Date: Thu, 8 Dec 2016 07:10:21 -0200
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Jonathan Corbet <corbet@lwn.net>,
        Jani Nikula <jani.nikula@linux.intel.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>,
        LKML <linux-kernel@vger.kernel.org>, linux-doc@vger.kernel.org,
        Christoph Hellwig <hch@infradead.org>,
        Peter Zijlstra <peterz@infradead.org>,
        Daniel Vetter <daniel.vetter@intel.com>
Subject: Re: [PATCH] doc: Explain light-handed markup preference a bit
 better
Message-ID: <20161208071021.5cd73ec8@vento.lan>
In-Reply-To: <20161207123924.4a47d777@lwn.net>
References: <20161207154258.23333-1-daniel.vetter@ffwll.ch>
        <20161207123924.4a47d777@lwn.net>
Organization: Samsung
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 6688
Lines: 165

Em Wed, 7 Dec 2016 12:39:24 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Wed,  7 Dec 2016 16:42:58 +0100
> Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> 
> > We already had a super-short blurb, but worth extending it I think:
> > We're still pretty far away from anything like a consensus, but
> > there's clearly a lot of people who prefer an as-light as possible
> > approach to converting existing .txt files to .rst. Make sure this is
> > properly taken into account and clear.
> > 
> > Motivated by discussions with Peter and Christoph and others.  
> 
> I do think we should put something in to guide people in the right
> direction.  And yes, it should, itself, be light-handed and minimal.
> 
> [...]
> 
> >  Documentation/kernel-documentation.rst | 28 ++++++++++++++++++++++++++--
> >  1 file changed, 26 insertions(+), 2 deletions(-)  
> 
> I do, however, also believe that it should apply to relatively recent
> docs-next :)
> 
> > diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
> > index 0dd17069bc0b..5bffe5a418aa 100644
> > --- a/Documentation/kernel-documentation.rst
> > +++ b/Documentation/kernel-documentation.rst
> > @@ -77,9 +77,27 @@ Specific guidelines for the kernel documentation
> >  
> >  Here are some specific guidelines for the kernel documentation:
> >  
> > -* Please don't go overboard with reStructuredText markup. Keep it simple.
> > +* Please don't go overboard with reStructuredText markup. Keep it simple. A lot
> > +  of core kernel developers prefer plain text, with a big emphasis on plain. In
> > +  the end if we have pretty generated docs which the subject experts don't
> > +  like to edit and keep up-to-date everyone loses.
> >  
> > -* Please stick to this order of heading adornments:
> > +  Be especially considerate when converting existing documentation. There's a
> > +  wide scale from annotating every little bit with in-line styles to only
> > +  touching up the bare minimum needed to integrate an existing file into the
> > +  larger documentation. Please align with the wishes of the maintainer to make
> > +  sure that documentations stays useful for everyone.  
> 
> I think this is about where I figured out why I'm not 100% ready to jump on
> this.  What we're doing here is mixing two things: information on how to
> write documents, and information on how to convert existing documents.
> 
> I'm not really opposed to applying the patch as-is, but I do wonder if what
> we really need is a new section aimed specifically at people doing
> conversions?  The concerns *are* a bit different, and there's more
> information we could put into a conversion section that isn't relevant to
> others.  Plus we could remove it some day far in the future when
> everything's converted :)

Yeah, a "conversion guide" section seems interesting. In the case of
media, for example, we prefer to use as much as ReST provides, as nobody
cares that the doc source would be as readable as the html/pdf output.
So, we want to be sure that the enriched text output would look better
to the ones using the documentation.

In that case, I would go for something close to the text I wrote to Peter
sometime ago:

<ReST>
Conversion guide
================

Be especially considerate when converting existing documentation. There's a
wide scale from annotating every little bit with in-line styles to only
touching up the bare minimum needed to integrate an existing file into the
larger documentation. Please align with the wishes of the maintainer to make
sure that documentations stays useful for everyone.  

Usually, all it takes to convert a text document to ReST is:

- adjust the chapter/section headers, as they all start on column 1,
  and all have a line below with a symbol (like "=", "-", "~", ...), E. g::

	Foo chapter
	===========

	bar section
	-----------

  It will automatically assign the first symbol to chapter, the
  next one to section and so on. Avoid touch the symbols used on
  the text, if possible

- use *foo* (for italics) instead of _foo_;

- if you need to use cross-references, use :ref:`path <id>`, e. g::

	:ref:`Documentation/admin-guide/serial-console.rst <serial_console>`

- if it contains source examples or ascii artwork diagrams, use "::"
  on the previous line to create a literal block, e. g.::

	this is an example::

		// whatever I do here, Sphinx will display as-is
		foo(bar);

- adjust whitespaces/new lines where needed, as Sphinx identifies
  continuation lines if the text is at the same column as the
  previous line, and blank lines break paragraphs.

- if you have something that you want to use a monotonic font on
  PDF/LaTeX/HTML output, use ``foo``. Please note, however, that some
  maintainers prefer to use "foo" instead, with makes better when
  reading the document in plain text.

- if you use special characters like '*' in the middle of the text
  (outsize a literal block), prepend with a \ in order to escape
  parsing it.
</ReST>


> 
> > +* Don't just blindly convert documents, also carefully review them and fix up
> > +  any issues in the text itself. Updated docs might trick readers into believing
> > +  they're accurately reflecting current best practice, which would be rather
> > +  harmful if the text itself is entirely outdated.
> > +
> > +* When converting existing documents, please try to retain the existing heading
> > +  styles as much as possible. Sphinx accept almost anything, as long as it's  
> 
> accept*s*  (or "will accept")
> 
> > +  consistent and headings all start in column 1.
> > +
> > +  For new documents please stick to this order of heading adornments:
> >  
> >    1. ``=`` with overline for document title::
> >  
> > @@ -107,6 +125,12 @@ Here are some specific guidelines for the kernel documentation:
> >    the order as encountered."), having the higher levels the same overall makes
> >    it easier to follow the documents.
> >  
> > +* For inserting fixed width text blocks (for code examples, use case
> > +  examples, etc.), use ``::`` for anything that doesn't really benefit
> > +  from syntax highlighting, especially short snippets. Use
> > +  ``.. code-block:: <language>`` for longer code blocks that benefit
> > +  from highlighting.
> > +  
> 
> I think we should add a sentence somewhere saying:
> 
>   Note that, if the sentence before the block ends with ":", you can simply
>   add a second colon rather than putting in a separate "::" line.
> 
> I've had to tell a few people that.  It's a tiny detail, but one that does
> improve the readability of the resulting documents and reduce the
> intrusiveness of conversions.
> 
> Thanks,
> 
> jon


Thanks,
Mauro