Re: [PATCH] doc: Explain light-handed markup preference a bit better

[Daniel Vetter]

On Thu, Dec 8, 2016 at 10:10 AM, Mauro Carvalho Chehab
<mchehab@xxxxxxxxxxxxxxxx> wrote:
> Em Wed, 7 Dec 2016 12:39:24 -0700
> Jonathan Corbet <corbet@xxxxxxx> escreveu:
>
>> On Wed,  7 Dec 2016 16:42:58 +0100
>> Daniel Vetter <daniel.vetter@xxxxxxxx> 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:

Hm yeah, separate conversion section makes sense. In that case I'll
adopt Jani's suggestion for more terseness in overview document, and
we can merge Mauro's proposal (or something like it) on top. And I'll
try to rebase onto latest doc-next too ;-)

Does that sound like a plan, before I head of and respin v4?

Cheers, Daniel

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



-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch