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 <[email protected]>
Cc: [email protected]
Cc: Christoph Hellwig <[email protected]>
Cc: Peter Zijlstra <[email protected]>
Cc: Jani Nikula <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
---
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
On Wed, 7 Dec 2016 16:42:58 +0100
Daniel Vetter <[email protected]> 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
Em Wed, 7 Dec 2016 12:39:24 -0700
Jonathan Corbet <[email protected]> escreveu:
> On Wed, 7 Dec 2016 16:42:58 +0100
> Daniel Vetter <[email protected]> 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
On Thu, Dec 8, 2016 at 10:10 AM, Mauro Carvalho Chehab
<[email protected]> wrote:
> Em Wed, 7 Dec 2016 12:39:24 -0700
> Jonathan Corbet <[email protected]> escreveu:
>
>> On Wed, 7 Dec 2016 16:42:58 +0100
>> Daniel Vetter <[email protected]> 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
Em Thu, 8 Dec 2016 23:06:57 +0100
Daniel Vetter <[email protected]> escreveu:
> On Thu, Dec 8, 2016 at 10:10 AM, Mauro Carvalho Chehab
> <[email protected]> wrote:
> > Em Wed, 7 Dec 2016 12:39:24 -0700
> > Jonathan Corbet <[email protected]> escreveu:
> >
> >> On Wed, 7 Dec 2016 16:42:58 +0100
> >> Daniel Vetter <[email protected]> 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
On Thu, 8 Dec 2016 23:06:57 +0100
Daniel Vetter <[email protected]> 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