[PATCH 1/6] doc: Explain light-handed markup preference a bit better
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 Cc: linux-doc@vger.kernel.org Cc: Christoph Hellwig Cc: Peter Zijlstra Cc: Jani Nikula Cc: Mauro Carvalho Chehab Signed-off-by: Daniel Vetter --- 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:: `` for longer code blocks that benefit + from highlighting. + the C domain -- 2.11.0 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 1/6] doc: Explain light-handed markup preference a bit better
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 Cc: linux-doc@vger.kernel.org Cc: Christoph Hellwig Cc: Peter Zijlstra Cc: Jani Nikula Cc: Mauro Carvalho Chehab Signed-off-by: Daniel Vetter --- 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:: `` for longer code blocks that benefit + from highlighting. + the C domain -- 2.11.0 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/6] doc: Explain light-handed markup preference a bit better
On Tue, 7 Mar 2017 17:40:35 +0100 Daniel Vetter wrote: > Jon, can you pls pick this one up, or want me to resend stand-alone? I got it; I should get both applied before too long. jon -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 1/6] doc: Explain light-handed markup preference a bit better
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 > Cc: linux-doc@vger.kernel.org > Cc: Christoph Hellwig > Cc: Peter Zijlstra > Cc: Jani Nikula > Cc: Mauro Carvalho Chehab > Signed-off-by: Daniel Vetter 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:: `` 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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
