Date: Thu, 7 Dec 2017 08:30:13 +1100
From: "Tobin C. Harding" <me@tobin.cc>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Randy Dunlap <rdunlap@infradead.org>,
        Andrew Murray <amurray@mpc-data.co.uk>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
Subject: Re: [PATCH] doc: convert printk-formats.txt to rst
Message-ID: <20171206213013.GE11835@eros>
References: <1512524729-16051-1-git-send-email-me@tobin.cc>
 <20171206112325.1a76727b@lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20171206112325.1a76727b@lwn.net>
User-Agent: Mutt/1.5.24 (2015-08-30)
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 2444
Lines: 55

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

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.