Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1532034 > unrolled thread

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

Back to article view | Back to linux.kernel

Contents

  [PATCH] doc: Explain light-handed markup preference a bit better Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-11-29 10:30 +0100
    Re: [PATCH] doc: Explain light-handed markup preference a bit better Markus Heiser <markus.heiser@darmarit.de> - 2016-11-29 11:30 +0100
      Re: [PATCH] doc: Explain light-handed markup preference a bit  better Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-29 13:00 +0100
    Re: [PATCH] doc: Explain light-handed markup preference a bit better Jani Nikula <jani.nikula@linux.intel.com> - 2016-11-29 11:40 +0100
      Re: [PATCH] doc: Explain light-handed markup preference a bit  better Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-11-29 12:50 +0100
        Re: [PATCH] doc: Explain light-handed markup preference a bit better Jani Nikula <jani.nikula@linux.intel.com> - 2016-11-29 16:20 +0100
          Re: [PATCH] doc: Explain light-handed markup preference a bit better Daniel Vetter <daniel@ffwll.ch> - 2016-12-07 16:50 +0100
    Re: [PATCH] doc: Explain light-handed markup preference a bit better Daniel Vetter <daniel@ffwll.ch> - 2016-11-29 14:20 +0100
      Re: [PATCH] doc: Explain light-handed markup preference a bit better Peter Zijlstra <peterz@infradead.org> - 2016-12-06 09:00 +0100
        Re: [PATCH] doc: Explain light-handed markup preference a bit better Daniel Vetter <daniel@ffwll.ch> - 2016-12-07 16:50 +0100

#1532034 — [PATCH] 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.

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

[toc] | [next] | [standalone]

#1532104

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

[toc] | [prev] | [next] | [standalone]

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

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

[toc] | [prev] | [next] | [standalone]

#1532113

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

[toc] | [prev] | [next] | [standalone]

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

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

[toc] | [prev] | [next] | [standalone]

#1532400

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

[toc] | [prev] | [next] | [standalone]

#1537851

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

[toc] | [prev] | [next] | [standalone]

#1532271

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

[toc] | [prev] | [next] | [standalone]

#1536730

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.

[toc] | [prev] | [next] | [standalone]

#1537849

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

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web