Re: [PATCH] doc: convert printk-formats.txt to rst

[Jonathan Corbet <corbet@lwn.net>]

On Wed,  6 Dec 2017 12:45:29 +1100
"Tobin C. Harding" <me@tobin.cc> 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@tobin.cc>

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.

 - 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.

 - The vsprintf.c part is probably not for me to take, so it should be
   split out into a separate patch.

Thanks for working on this,

jon