On Thu, 8 Feb 2018 06:45:07 -0800
Matthew Wilcox <willy@xxxxxxxxxxxxx> wrote:
> Jon asked me to redo the Context: patch on top of his current docs tree.
> Unfortunately, I was on a plane at the time, so I started fixing some
> other small things, and before I knew it, I'd completely restructured
> the entire doc-guide/kernel-doc.rst file.
>
> Feel free to not take it all, particularly the last 'Style Guide' patch.
OK, this all makes sense. Mostly. Here's my quibbles.
>
> Matthew Wilcox (6):
> Add documentation for Context section
> Minor fixes to kernel-doc.rst
> Add scripts/split-man.pl
I think this makes sense to do, but I really would like to see an intro
comment on the split-man.pl script itself. Somebody wandering through
the scripts directory should be able to look at the top of the file and
know what the script does without having to reverse-engineer delightful
stuff like:
> if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
> Fix whitespace in example
> Restructure kernel-doc.rst
> Add a Style Guide section
This last one worries me a bit because we're starting to impinge a bit on
the coding style document. If we're going to give guidance on things
like parameter names, I think that coding-style.rst is the right place
for it.
I'll go ahead and apply the first five. I'll try to get around to
putting a comment on scripts/split-man.pl, but I sure wouldn't mind if
somebody beat me to it...
Thanks,
jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
