linux-kernel - Re: [PATCH v3 13/21] Documentation/SecurityBugs: convert it 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: <20160916175311.620e480c@vento.lan>
Date:   Fri, 16 Sep 2016 17:53:11 -0300
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Jonathan Corbet <corbet@....net>
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 13/21] Documentation/SecurityBugs: convert it to ReST
 markup

Em Fri, 16 Sep 2016 11:17:33 -0600
Jonathan Corbet <corbet@....net> escreveu:

> On Wed, 14 Sep 2016 08:06:42 -0300
> Mauro Carvalho Chehab <mchehab@...pensource.com> wrote:
> 
> > Add a name for the document and convert the sections to
> > ReST markups.  
> 
> No objection to the changes (modulo the discussion on section numbers),
> but I do wonder whether this one belongs with the process documentation.
> This is here for users as much as anybody.  We haven't really begun to
> organize user-level docs, but, when we do, I think this maybe belongs
> there.

Agreed. I moved it to the dev-process just because it was mentioned at
the HOWTO, but yeah, it would fit more on a doc/user book, together
with README, kernel-parameters.txt, etc.

We can certainly move it to there, and enable intersphinx extension,
to avoid warnings when just one book is compiled.

I guess the big problem with a user book is what should we do with
the top README file. It is the main user book, but it is also something
that a Kernel developer needs.

If you want, I can find some time to work on an user book, but,
before that, I guess we need to define what should we do with the
README file.

My suggestion would be to move its contents to the doc/user/intro.rst
file, and, on its place, add a simple README file that would just
point to the main books inside Documentation, like:

        Linux kernel release 4.x <http://kernel.org/>

For the main Kernel user documentation, please see:
	Documentation/user

For development documentation, please see:
	Documentation/process

For the several API documentation files, please see:
	Documentation/media
	Documentation/kernel-drivers
	Documentation/gpu
	...

If you want, I can prepare such patches, but I prefer if we can merge
those two series before that, in order to avoid dependencies between
each patch series.

> 
> Just a thought...
> 
> jon

Thanks,
Mauro