linux-kernel - Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format

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]

Message-ID: <20190416080024.7fb65682@lwn.net>
Date:   Tue, 16 Apr 2019 08:00:24 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Mike Snitzer <snitzer@...hat.com>
Cc:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org, Alasdair Kergon <agk@...hat.com>,
        dm-devel@...hat.com
Subject: Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format

On Tue, 16 Apr 2019 09:28:52 -0400
Mike Snitzer <snitzer@...hat.com> wrote:

> Can you help me understand why this is the direction text based
> Documenation is taking in the Linux kernel?  All I see is markup, and
> escaping of characters, that is a chore to administer over time.

This is a discussion that was mostly resolved some years ago...

Classic Documentation/ is a jumbled collection of unorganized text files,
some of which contain highly useful information and others of which
haven't had much to offer since about 1996.  We are working to turn it
into an organized collection where, hopefully, some thought has actually
been given to the people who will be reading it.

The ReST conversion, in particular, allows us to link documents into a
larger structure, create indexes and cross references, and produce output
in formats like HTML and PDF.  It lets us present the documentation like
this:

	https://www.kernel.org/doc/html/latest/

Among other things, making the documentation more accessible in this way
makes it easier and more rewarding for developers to improve it, and I
believe we are seeing the results of that.  Linus called out the
documentation work in the 5.1-rc1 announcement, for example.

Nobody has complained about the maintenance burden of RST docs - so far as
I have heard, anyway.  Things do break occasionally, but problems in the
docs build almost always result from code changes that mess up the
kerneldoc comments rather than RST changes, and it's been that way for as
long as I've been paying attention.

Thanks,

jon