On Thu, Mar 02, 2017 at 04:16:33PM +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. > > v3: Make the explanations around fixed-width quoting more concise > (Jani). > > v4: > - Rebase onto docs-4.10. > - Go with the more terse recommendation from Jani, defer to the much > more detailed conversion guide Mauro is working on for details. > > 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> Jon, can you pls pick this one up, or want me to resend stand-alone? Thanks, Daniel > --- > Documentation/doc-guide/sphinx.rst | 17 ++++++++++++++++- > 1 file changed, 16 insertions(+), 1 deletion(-) > > diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst > index 96fe7ccb2c67..532d65b70500 100644 > --- a/Documentation/doc-guide/sphinx.rst > +++ b/Documentation/doc-guide/sphinx.rst > @@ -73,7 +73,16 @@ 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. For the most part the documentation should be plain text with > + just enough consistency in formatting that it can be converted to > + other formats. > + > +* Please keep the formatting changes minimal when converting existing > + documentation to reStructuredText. > + > +* Also update the content, not just the formatting, when converting > + documentation. > > * Please stick to this order of heading adornments: > > @@ -103,6 +112,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. > + > > the C domain > ------------ > -- > 2.11.0 > -- 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
