linux-kernel - Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Tue, 23 Apr 2019 17:26:41 -0300
From:   Mauro Carvalho Chehab <mchehab@...radead.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     David Howells <dhowells@...hat.com>,
        Mike Snitzer <snitzer@...hat.com>,
        Peter Zijlstra <peterz@...radead.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org, linux-arch@...r.kernel.org
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST
 files to *.rst

Em Tue, 23 Apr 2019 10:54:15 -0600
Jonathan Corbet <corbet@....net> escreveu:

> On Tue, 23 Apr 2019 15:52:26 +0100
> David Howells <dhowells@...hat.com> wrote:
> 
> > There've been some changes that I've particularly objected to, such as
> > removing contents lists from files and replacing them with markup like:
> > 
> > 	.. contents:: :local:
> > 
> > This actually impedes use of the file.  It should not be necessary to build
> > the docs to get that for ordinary use.  
> 
> Usability of the text files versus that of the built docs is occasionally
> something that has to be traded off.  As a general rule, I want the text
> files to remain useful on their own.  There is a lot of value in the
> built docs for a lot of people, but that should not be the only, or even
> the primary, form of access
> 
> Tables of contents are certainly a place where that tradeoff makes itself
> felt.  Doing them by hand ensures that they are always present, but
> requires that people editing the docs also maintain the TOCS - something
> that experience has shown tends not to happen.  That's more of a pain
> than a little bit of markup, and people don't do it.  An automatically
> generated TOC, instead, is always correct and is linkable.
> 
> Few people complain about the biggest impediment to the readability of
> text files, though: the use of kerneldoc comments.  That splits the
> information between the text file and multiple random-seeming locations
> among tends of thousands of source files.  Sometimes the solution here is
> to move all of the documentation into the source, but that tends to
> fragment it and make it harder to find; it's certainly not the right
> place for many kinds of docs.  In general, it's hard to create a coherent
> story that way.
> 
> Suggestions / patches on how to improve things for *all* users of the
> docs are certainly welcome!
> 
> I am, incidentally, toying with the idea of trying to put together a
> documentation microconf at the Linux Plumbers Conference this year.  If
> anybody out there thinks that's a good idea and would like to
> participate, please let me know.

If you add a microconf to LPC, I'm in. 

IMO, we made big advances with documentation, but there's a lot more
to be done. Having a microconf to discuss those things may help us
to bring new ideas about how to keep improving it.

Thanks,
Mauro