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

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

[Daniel Vetter]

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@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Christoph Hellwig <hch@infradead.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 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

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

[Markus Heiser]

Am 29.11.2016 um 10:23 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:

> 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@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Christoph Hellwig <hch@infradead.org>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: Jani Nikula <jani.nikula@linux.intel.com>
> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
> Documentation/kernel-documentation.rst | 44 ++++++++++++++++++++++++++++++++--
> 1 file changed, 42 insertions(+), 2 deletions(-)

Sorry for my dump remarks ...

* shouldn't it on top of Jon's docs-next?
* should we lose a few words about tabs/indentation?

IMO indentation for reST markup should be 2 spaces, not
tabs (8 spaces). I know about CodeStyling but I think this doc
(markup) and not source-code. Code-examples should be indent
by tabs as usual. BTW here is what CodingStyle says:

 Outside of comments, documentation and except in Kconfig,
 spaces are never used for indentation, and the above example
 is deliberately broken.
 Get a decent editor and don't leave whitespace at the end of
 lines.

... encourages me to prefer spaces.

-- Markus --

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

[Mauro Carvalho Chehab]

Em Tue, 29 Nov 2016 11:28:12 +0100
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 29.11.2016 um 10:23 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
> 
> > 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@lwn.net>
> > Cc: linux-doc@vger.kernel.org
> > Cc: Christoph Hellwig <hch@infradead.org>
> > Cc: Peter Zijlstra <peterz@infradead.org>
> > Cc: Jani Nikula <jani.nikula@linux.intel.com>
> > Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> > ---
> > Documentation/kernel-documentation.rst | 44 ++++++++++++++++++++++++++++++++--
> > 1 file changed, 42 insertions(+), 2 deletions(-)  
> 
> Sorry for my dump remarks ...
> 
> * shouldn't it on top of Jon's docs-next?
> * should we lose a few words about tabs/indentation?
> 
> IMO indentation for reST markup should be 2 spaces, not
> tabs (8 spaces). I know about CodeStyling but I think this doc
> (markup) and not source-code. Code-examples should be indent
> by tabs as usual. BTW here is what CodingStyle says:
> 
>  Outside of comments, documentation and except in Kconfig,
>  spaces are never used for indentation, and the above example
>  is deliberately broken.
>  Get a decent editor and don't leave whitespace at the end of
>  lines.
> 
> ... encourages me to prefer spaces.

I agree that we should define the preferred spaces style.

Yet, I very much prefer that patches converting existing documents
to not touch whitespaces/tabs except when really needed.

>From my side, the editors I use to write documents are set to automatically 
convert 8 column alignments to tabs. I also have a script that I run when
needed, when I receive a patch with whitespaces at the end of lines.
It also converts spaces to tabs where needed.

So, whatever definition we use, IMO we should define that a tab has
8 spaces, and that tabs should be used if the alignment requires
more than 8 columns.

With regards of using indentation with 2 spaces, I don't have any
strong opinion.

>From what I remember, the scripts you used to convert the media
documents made a 4 spaces alignment for the media documentation
on several places, but I may be wrong.

Thanks,
Mauro

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

[Jani Nikula]

On Tue, 29 Nov 2016, 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.
>
> 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.

When I wrote most of the document originally, I put a lot of effort into
make it clear and consice. I don't approve of the changes here. This is
going to sound like bikeshedding, but I just couldn't make myself not
reply.

> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Christoph Hellwig <hch@infradead.org>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: Jani Nikula <jani.nikula@linux.intel.com>
> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
>  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.

I wrote that, and I left it short intentionally. I really don't think
prose will help here. This document is primarily a reference. Keep it as
concise as you possibly can.

I'd go with adding bullets along the lines of:

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

I think those capture the essence. Less is more.

Please note how I intentionally left out things like "core kernel
developers prefer plain text", "please align with the wishes of the
maintainer", "...would be rather harmful if the text itself is entirely
outdated". Personally, I simply do not think they have a place here.

> +* 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.

I don't think this hunk belongs under "the C domain" section. I'd just
stick it at the end of the earlier bullet list.

Condensing from my earlier mail [1], I'd go with just:

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

Again, I think this is a reference, not a tutorial. Please refer to
Sphinx/reStructuredText documentation for details instead of duplicating
the same information.


BR,
Jani.


[1] http://mid.mail-archive.com/87y407tyvv.fsf@intel.com


> +
> +
>  list tables
>  -----------

-- 
Jani Nikula, Intel Open Source Technology Center

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

[Mauro Carvalho Chehab]

Em Tue, 29 Nov 2016 12:38:55 +0200
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

> On Tue, 29 Nov 2016, 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.
> >
> > 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.  
> 
> When I wrote most of the document originally, I put a lot of effort into
> make it clear and consice. I don't approve of the changes here. This is
> going to sound like bikeshedding, but I just couldn't make myself not
> reply.

Sorry, but I agree with Daniel here: we should provide a guide
for those people that will be helping with the document conversion.

I expect that ReST conversion will attract kernel newbies, and having
a chapter or section with a guideline for them will help a lot to
avoid us to review things that would be otherwise be refused by
the subsystem maintainer.

Yet, we could eventually separate the guidelines for text->ReST
conversions on a separate chapter (or even on a separate file),
in order to avoid mixing a general thumb of rules for the Kernel
documentation from a set of guidelines for documents conversion.

> 
> > Cc: Jonathan Corbet <corbet@lwn.net>
> > Cc: linux-doc@vger.kernel.org
> > Cc: Christoph Hellwig <hch@infradead.org>
> > Cc: Peter Zijlstra <peterz@infradead.org>
> > Cc: Jani Nikula <jani.nikula@linux.intel.com>
> > Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> > ---
> >  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.  
> 
> I wrote that, and I left it short intentionally. I really don't think
> prose will help here. This document is primarily a reference. Keep it as
> concise as you possibly can.
> 
> I'd go with adding bullets along the lines of:
> 
> ---
> * 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.

The above sounds OK to me, but for a newbie the above may not be
enough. While both your text and Daniel's version says about the
same, my personal preference would be to stick with the Daniel's one,
as it make things clearer, IMHO.

> ---
> 
> I think those capture the essence. Less is more.
> 
> Please note how I intentionally left out things like "core kernel
> developers prefer plain text", "please align with the wishes of the
> maintainer", "...would be rather harmful if the text itself is entirely
> outdated". Personally, I simply do not think they have a place here.
> 
> > +* 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.  
> 
> I don't think this hunk belongs under "the C domain" section. I'd just
> stick it at the end of the earlier bullet list.

Agreed.

> Condensing from my earlier mail [1], I'd go with just:
> 
> ---
> * 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 would stick with Daniel's text here. The problem with the above is
that "code blocks that benefit from highlighting" is a very abstract
concept. Also, we know by experience that pygments have bugs with
highlight. I had to use ".. code-block:: none" on some media blocks
where it was doing the wrong thing. So, I prefer Daniel's text:
"But that should only be used when really necessary". That should be
scary enough for a newbie to not use code-blocks, while keeping the
decision of using it to senior developers, who knows better
"when really necessary".

> Again, I think this is a reference, not a tutorial. Please refer to
> Sphinx/reStructuredText documentation for details instead of duplicating
> the same information.

We're not following any specific Sphinx/ReST tutorial.

IMHO, it is better to define the "ReST style" (just like we have a coding
style) that we want to be followed by the Kernel's documentation than 
letting the user use a random reference that may or may not follow
the current style.

So, I would add a tutorial somewhere, eventually pointing to the
external selected places that use the convention we're defining
at the Kernel.

Thanks,
Mauro

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

[Jani Nikula]

On Tue, 29 Nov 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> Sorry, but I agree with Daniel here: we should provide a guide
> for those people that will be helping with the document conversion.

That goal is not mutually exclusive with keeping this document concise.

That is all.

Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

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

[Daniel Vetter]

On Tue, Nov 29, 2016 at 05:08:30PM +0200, Jani Nikula wrote:
> On Tue, 29 Nov 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> > Sorry, but I agree with Daniel here: we should provide a guide
> > for those people that will be helping with the document conversion.
> 
> That goal is not mutually exclusive with keeping this document concise.
> 
> That is all.

Opted for some comprimise-y thing, going with Jani's proposal for the
fixed-width quoting (since mine was definitely too wordy), but opted to
keep the others unchanged. Still feels like overall a concise and balanced
expose, but happy to change if folks object.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

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

[Daniel Vetter]

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@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Christoph Hellwig <hch@infradead.org>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: Jani Nikula <jani.nikula@linux.intel.com>
> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>

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

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

[Peter Zijlstra]

On Tue, Nov 29, 2016 at 02:17:52PM +0100, Daniel Vetter wrote:
> 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@lwn.net>
> > Cc: linux-doc@vger.kernel.org
> > Cc: Christoph Hellwig <hch@infradead.org>
> > Cc: Peter Zijlstra <peterz@infradead.org>
> > Cc: Jani Nikula <jani.nikula@linux.intel.com>
> > Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> 
> 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?

Seems OK to me, but there's already a bunch of bike-shedding in this
thread.

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

[Daniel Vetter]

On Tue, Dec 06, 2016 at 08:52:41AM +0100, Peter Zijlstra wrote:
> On Tue, Nov 29, 2016 at 02:17:52PM +0100, Daniel Vetter wrote:
> > 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@lwn.net>
> > > Cc: linux-doc@vger.kernel.org
> > > Cc: Christoph Hellwig <hch@infradead.org>
> > > Cc: Peter Zijlstra <peterz@infradead.org>
> > > Cc: Jani Nikula <jani.nikula@linux.intel.com>
> > > Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> > 
> > 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?
> 
> Seems OK to me, but there's already a bunch of bike-shedding in this
> thread.

Thanks for taking a look, I'll resend trying to address the other feedback
and make everyone happy.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

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

[Daniel Vetter]

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@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Christoph Hellwig <hch@infradead.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 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

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

[Daniel Vetter]

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

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Christoph Hellwig <hch@infradead.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 Documentation/kernel-documentation.rst | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

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.
+
+* 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::
 
@@ -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.
+
 
 the C domain
 ------------
-- 
2.10.2

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

[Jonathan Corbet]

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

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

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

[Mauro Carvalho Chehab]

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

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@s-opensource.com> wrote:
> 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:

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

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

[Mauro Carvalho Chehab]

Em Thu, 8 Dec 2016 23:06:57 +0100
Daniel Vetter <daniel.vetter@ffwll.ch> escreveu:

> On Thu, Dec 8, 2016 at 10:10 AM, Mauro Carvalho Chehab
> <mchehab@s-opensource.com> wrote:
> > 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:  
> 
> 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?

Sounds like a plan to me :-)

Regards,
Mauro

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

[Jonathan Corbet]

On Thu, 8 Dec 2016 23:06:57 +0100
Daniel Vetter <daniel.vetter@ffwll.ch> wrote:

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

It sounds like a good plan to me.

jon

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

[Daniel Vetter]

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.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Christoph Hellwig <hch@infradead.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 Documentation/kernel-documentation.rst | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index 0dd17069bc0b..ceb17d428278 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -77,7 +77,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. A lot
+  of core kernel developers prefer plain text, with a big emphasis on plain. And
+  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.
+
+  Be especially considerate when converting existing .txt 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.
 
 * Please stick to this order of heading adornments:
 
-- 
2.10.2

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

[Mauro Carvalho Chehab]

Em Mon, 28 Nov 2016 17:16:22 +0100
Daniel Vetter <daniel.vetter@ffwll.ch> escreveu:

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

Good idea! Please see below for some suggestions.

> 
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Christoph Hellwig <hch@infradead.org>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: Jani Nikula <jani.nikula@linux.intel.com>
> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
>  Documentation/kernel-documentation.rst | 11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
> index 0dd17069bc0b..ceb17d428278 100644
> --- a/Documentation/kernel-documentation.rst
> +++ b/Documentation/kernel-documentation.rst
> @@ -77,7 +77,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. A lot
> +  of core kernel developers prefer plain text, with a big emphasis on plain. And
> +  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.
> +
> +  Be especially considerate when converting existing .txt 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.

Looks good to me.

>  * Please stick to this order of heading adornments:

I would actually relax the heading adornments order. IMHO, if a
document to be converted has already some adornments order, the
best is to just keep using them.

So, IMHO, I would be changing the above to:

	* Please stick to the heading adornments that are already
	  present on a document, if you're converting it to ReST. If you're
	  writing it from scratch, please prefer this order of heading adornments:

I would also mention to prefer using "::" over ".. code-block::" when
converting existing documents.

Thanks,
Mauro