Re: [PATCH] doc: memory-barriers: reStructure Text

[Markus Heiser]

> Am 05.01.2018 um 04:52 schrieb afzal mohammed <afzal.mohd.ma@xxxxxxxxx>:

[...]

> Initially i was sceptical of rst & once instead of hitting the fly,
> hit "make htmldocs" on the keyboard :), and the opinion about it was
> changed.

Yes, I understand that some of us have a (reasonable) doubt about
the reST markup.  It is not perfect in any matter, e.g. I don't like
the ``monospace`` markup.  But this is my home opinion.

    My hope is, that those of us who have a doubt give reST
    a chance ... it is a compromise, not as bad as you might
    think first ... your cooperation and your criticism is
    needed and welcome. Please let me invite you / read on:

There are other plain-text markups e.g. AsciiDoc or Markdown. The
reST markup and the Sphinx-builder is a compromise from a evaluation
in 2016 (see linux-doc ML subject "muddying the waters" [1]).

Jani wrote an article about the evaluation and it results [2]. And
there are other articles documenting all the various aspects.

- A report from the documentation maintainer [3]
- Kernel documentation with Sphinx, part 2: how it works [4]
- Kernel documentation update [5]

To summarize it with my words:

The old DocBook-based toolchain was hard to maintain and of course
who want's to write XML? A consistent plain-text markup for
articles in /Documentation/* and source-code comments (kernel-doc)
was needed.

The markup: IMO reST wins that race, because it has a extendable
markup specification while others plain-text markups like Markdown
have various (HTML) builders with various markup dialects[7] (which
is more a mess than a definition).

The builder: IMO Sphinx-Doc wins that race, since it is (well)
maintained, widely used and has a interface for extensions.
I.e. the one extension we wrote: 'kernel-doc' to parse kernel-doc
comments from source code and include them in the articles.
Perspective: Sphinx-Doc also offers solutions we might use in the
future (e.g. building man-pages). Not to end in a mess, extensions
should be implemented cautiously and deliberately (be patient).

But that should not fool you; yes we have known problems with our
toolchain and it is not yet ;) perfect in any matter (e.g. the
highlighting in kernel-doc comments or the PDF generation or the
sphinx-doc versions shipped with various distributions or ..) 

Anyway, today we have more than before: The reST learning curve is
(compared to DocBook) not hard for newbees and our toolchain is
flexible for all the requirements wich might come up in the future.

IMO the actual challenge is the content and the organization
of the doc-tree and for this 

[1] https://www.mail-archive.com/search?q=muddying+the+waters&l=linux-doc%40vger.kernel.org
[2] https://lwn.net/Articles/692704/
[3] https://lwn.net/Articles/704613/
[4] https://lwn.net/Articles/692705/
[5] https://lwn.net/Articles/705224/
[6] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
[7] http://pandoc.org/MANUAL.html#markdown-variants

> It was easy to navigate through various docs & the realized
> that various topics (& many) were present (yes, it was there earlier
> also, but had to dive inside Documentation & search, while viewing the
> toplevel index.html made them standout). It was like earlier you had
> to go after docs, but now it was docs coming after you, that is my
> opinion.
> 
> Later while fighting with memory-barriers.txt, felt that it might be
> good for it as well as to be in that company.
> 
> And the readability as a text is not hurt as well.
> 
> It was thought that rst conversion could be done quickly, but since
> this was my first attempt with rst, had to put some effort to get a
> not so bad output, even if this patch dies, i am happy to have learnt
> rst conversion to some extent.

Thats exactly what I mean: give reST a chance :)

-- Markus --