Hi Peter, On Tue, Nov 29, 2016 at 10:23:14AM +0100, Daniel Vetter 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. > > v2: > - Mention that existing headings should be kept when converting > existing .txt files (Mauro). > - Explain that we prefer :: for quoting code, it's easier on the > eyes (Mauro). > - Explain that blindly converting outdated docs is harmful. Motived > by comments Peter did in our discussion. > > Cc: Jonathan Corbet <corbet@xxxxxxx> > Cc: linux-doc@xxxxxxxxxxxxxxx > Cc: Christoph Hellwig <hch@xxxxxxxxxxxxx> > Cc: Peter Zijlstra <peterz@xxxxxxxxxxxxx> > Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> > Cc: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> > Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx> Since this was motivated by a discussion you've (re)started, does this sufficiently address your concerns for conversion from plain text .txt to plain text .rst of existing documents? Anything you'd want to see changed? Thanks, Daniel > --- > Documentation/kernel-documentation.rst | 44 ++++++++++++++++++++++++++++++++-- > 1 file changed, 42 insertions(+), 2 deletions(-) > > diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst > index 0dd17069bc0b..d04cecdb498d 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. > + > +* 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 > + 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:: > > @@ -136,6 +154,28 @@ changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by: > :c:func:`VIDIOC_LOG_STATUS` > > > +For inserting code examples and use-cases use the simple fixed-width quoting > +style ``::`` which can either be on a line of it's own, or at the end of a > +preceeding paragraph. If there's no space before the double-colon it will be > +converted to a normal ``:``, which makes the overall text flow fairly reasonable > + > +.. code-block:: rst > + > + Some text explaing what you need to do:: > + > + code_example() > + > + More text explaining the next step:: > + > + if (condition) > + more_function_calls(); > + > + > +Sphinx also supports ``.. code-block::`` annotations, which also allow you to > +specify the language used for hightlight. But that should only be used when > +really necessary. > + > + > list tables > ----------- > > -- > 2.10.2 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
