linux-kernel - Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup

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: <20160916111314.5baa4f97@lwn.net>
Date:   Fri, 16 Sep 2016 11:13:14 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Mauro Carvalho Chehab <mchehab@...pensource.com>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Markus Heiser <markus.heiser@...marit.de>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        LKML <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST
 markup

On Wed, 14 Sep 2016 08:06:36 -0300
Mauro Carvalho Chehab <mchehab@...pensource.com> wrote:

> - Fix all chapter identation;
> - add c blocks where needed;

Here is where I think we need a bit of a philosophical discussion...

> -		Chapter 1: Indentation
> +Indentation
> +-----------

You're a fan of having sphinx do the numbering, and I have no problem
understanding why.  But this will defeat people who say "look in chapter 3
of Documentation/CodingStyle".  We're removing a bit of information from
the plain-text file and reserving it for the formatted version.  If we're
really going to do that, we should do it consciously, with the knowledge
that there is a cost involved.

We'll see this even more with SubmittingPatches, where it is quite common
for people to cite the number of the section they think is being violated
in any given situation.

jon