On Wed, Dec 06, 2017 at 11:23:25AM -0700, Jonathan Corbet wrote: > On Wed, 6 Dec 2017 12:45:29 +1100 > "Tobin C. Harding" <me@xxxxxxxx> wrote: > > > Documentation/printk-formats.txt is a candidate for conversion to > > ReStructuredText format. Some effort has already been made to do this > > conversion even thought the suffix is currently .txt > > > > Changes required to complete conversion > > > > - Add double backticks where needed. > > - Add entry to Documentation/index.rst > > - Use flat-table instead of ASCII table. > > - Fix minor grammatical errors. > > - Capitalize headers and correctly order heading adornments. > > - Use 'Passed by reference' uniformly. > > - Update pointer documentation around %px specifier. > > - Fix erroneous double backticks (to commas). > > - Simplify documentation for kobject. > > - Convert lib/vsnprintf.c function docs to use kernel-docs and > > include in Documentation/printk-formats.rst > > > > Signed-off-by: Tobin C. Harding <me@xxxxxxxx> > > Some comments from a quick review: > > - I would just put this into the core-api manual; we don't need to create > a separate section for printk formats. Cool, I was hoping you'd give some direction on this. thanks. > - I agree with Markus and others about the table. I think I would go a > little further and encourage observance of the "use minimal markup" > rule. Lots of ``double backticks`` make for slightly nicer HTML/PDF > output, but they come at the expense of plain-text readability, which > is something we really don't want to sacrifice. Great. I personally don't read docs in HTML/PDF so I like this ruling. > - The vsprintf.c part is probably not for me to take, so it should be > split out into a separate patch. I'm much less experienced than you Jon so please say if I am wrong but since the rst file depends on the changes to vsprintf.c wouldn't it be better if the changes went into the mainline together. I can split it into a two patch set if that is cleaner but putting the two patches through different trees seems like a bad idea because of the dependency. For what it's worth, I don't believe lib/vsprintf.c has a maintainer. Linus took changes to that file from my tree just recently. I don't know how this stuff works though in regards to merge conflicts. (Please take everything I say here with a pinch of salt since I have only maintained a tree for a few weeks now.) thanks, Tobin. -- 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
