Date:   Sat, 22 Oct 2016 02:57:45 +0900
From:   SeongJae Park <sj38.park@...il.com>
To:     Mauro Carvalho Chehab <mchehab@...pensource.com>
Cc:     Jonathan Corbet <corbet@....net>, Minchan Kim <minchan@...nel.org>,
        linux-doc <linux-doc@...r.kernel.org>,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH 01/12] Documentation/HOWTO: Mark subsection in rst format

On Sat, Oct 22, 2016 at 2:25 AM, Mauro Carvalho Chehab
<mchehab@...pensource.com> wrote:
> Em Sat, 22 Oct 2016 01:42:00 +0900
> SeongJae Park <sj38.park@...il.com> escreveu:
>
>> On Sat, Oct 22, 2016 at 12:45 AM, Mauro Carvalho Chehab
>> <mchehab@...pensource.com> wrote:
>> > Em Sat, 22 Oct 2016 00:19:46 +0900
>> > SeongJae Park <sj38.park@...il.com> escreveu:
>> >
>> >> Subsections in HOWTO is not marked in rst format.  This commit specifies
>> >> them in rst format.
>> >>
>> >> Signed-off-by: SeongJae Park <sj38.park@...il.com>
>> >> ---
>> >>  Documentation/HOWTO | 15 ++++++++++-----
>> >>  1 file changed, 10 insertions(+), 5 deletions(-)
>> >
>> > There are already patches converting HOWTO to ReST applied upstream:
>>
>> This patchset is not to replace the patches but to be applied on top of the
>> patches.
>>
>> >
>> > commit 1b49ecf2f3be358882bb97652ba50ae808c0ba8f
>> > Author: Jonathan Corbet <corbet@....net>
>> > Date:   Tue Sep 20 18:46:36 2016 -0600
>> >
>> >     docs: Clean up bare :: lines
>> >
>> >     Mauro's patch set introduced some bare :: lines; these can be represented
>> >     by a double colon at the end of the preceding text line.  The result looks
>> >     a little less weird and is less verbose.
>> >
>> >     Signed-off-by: Jonathan Corbet <corbet@....net>
>> >
>> > commit f1eebe92c2653e8fc3760577e53befdc9b62ef26
>> > Author: Mauro Carvalho Chehab <mchehab@...pensource.com>
>> > Date:   Mon Sep 19 08:07:59 2016 -0300
>> >
>> >     Documentation/HOWTO: adjust external link references
>> >
>> >     - A few link references were missing http://
>> >     - Several sites are now redirecting to https protocol. On such
>> >       cases, just use the https URL.
>> >
>> >     NOTE: all URLs were checked and they're pointing to the right places.
>> >
>> >     Signed-off-by: Mauro Carvalho Chehab <mchehab@...pensource.com>
>> >     Signed-off-by: Jonathan Corbet <corbet@....net>
>> >
>> > commit 34fed7e7e0e56f885f309e8892a3571400072e37
>> > Author: Mauro Carvalho Chehab <mchehab@...pensource.com>
>> > Date:   Mon Sep 19 08:07:58 2016 -0300
>> >
>> >     Documentation/HOWTO: improve some markups to make it visually better
>> >
>> >     Do a series of minor improvements at the ReST output format:
>> >
>> >     - Instead of using the quote blocks (::) for quotes, use
>> >     italics. That looks nicer on epub (and html) output, as
>> >     no scroll bar will be added. Also, it will adjust line
>> >     breaks on the text automatically.
>> >
>> >     - Add a missing reference to SubmittingPatches.rst and use
>> >     **foo** instead of _foo_.
>> >
>> >     - use bold for "The Perfect Patch" by removing a newline.
>> >
>> >     Signed-off-by: Mauro Carvalho Chehab <mchehab@...pensource.com>
>> >     Signed-off-by: Jonathan Corbet <corbet@....net>
>> >
>> > commit 43fb67a5258c0f3d1d869cb7d72617d87b257c62
>> > Author: Mauro Carvalho Chehab <mchehab@...pensource.com>
>> > Date:   Mon Sep 19 08:07:57 2016 -0300
>> >
>> >     Documentation/HOWTO: update information about generating documentation
>> >
>> >     The description there are pre-Sphinx. Update it to cover the
>> >     new way.
>> >
>> >     Signed-off-by: Mauro Carvalho Chehab <mchehab@...pensource.com>
>> >     Signed-off-by: Jonathan Corbet <corbet@....net>
>> >
>> >
>> > There's also a series of patches pending merge that moves it
>> > Documentation/process/howto.rst and add to this book:
>> >
>> >         https://mchehab.fedorapeople.org/kernel_docs/process/howto.html
>>
>> AFAIU, `The development process` section has subsections but they are marked as
>> sections.  That's what this patchset is trying to solve.  Looks like the
>> problem is still in the pending patches, too.  If you would like, I will resend
>> this patch after merging of the pending patches, though it would be no big
>> problem to merge this little patch before it.
>
> There's no real difference on using something like:
>
>         foo
>         ===
>
>         bar
>         ---
>
> or
>
>         foo
>         ~~~
>
>         bar
>         ===
>
> Sphinx just gets the first tag and use it for level 1 indentation, the
> next one for level 2, etc.
>
> See:
>         http://www.sphinx-doc.org/en/stable/rest.html
>
>         "Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings.
>
>         ...
>
>         "Of course, you are free to use your own marker characters
>         (see the reST documentation), and use a deeper nesting level,
>         but keep in mind that most target formats (HTML, LaTeX) have
>         a limited supported nesting depth."
>
>
> So, the only real limit is the number of indentation levels that the
> document can have.
>
> It proposes an style guide, but I don't see any sense on enforcing
> an specific style here. Actually, not enforcing one is, IMHO, a
> good thing, because we can always switch the indentation level
> by simply including a document on a TOC. So, it is easy to promote
> or to demote a document, by just changing the .. toctable:: where it
> belongs.

Well... `kernel-documentation.rst`, the document that I considered, says as
below:

```
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 stick to this order of heading adornments:

  1. ``=`` with overline for document title::

       ==============
       Document title
       ==============

  2. ``=`` for chapters::

       Chapters
       ========

  3. ``-`` for sections::

       Section
       -------

  4. ``~`` for subsections::

       Subsection
       ~~~~~~~~~~

  Although RST doesn't mandate a specific order ("Rather than imposing a fixed
  number and order of section title adornment styles, the order enforced will be
  the order as encountered."), having the higher levels the same overall makes
  it easier to follow the documents.
```

In short, it provides clear guideline though it also awares the meaningless of
tags order in rst.  That's why I thought it would be better to use `~~~~` for
subsections in this case.  After all, the sections in this case seems obviously
intended to be subsection of `The development process` section.   If I am
missing something, please let me know.


Thanks,
SeongJae Park


>
> Thanks,
> Mauro

Powered by blists - more mailing lists