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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20171206112325.1a76727b@lwn.net>
Date:   Wed, 6 Dec 2017 11:23:25 -0700
From:   Jonathan Corbet <corbet@....net>
To:     "Tobin C. Harding" <me@...in.cc>
Cc:     Randy Dunlap <rdunlap@...radead.org>,
        Andrew Murray <amurray@...-data.co.uk>,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] doc: convert printk-formats.txt to rst

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