Re: [PATCH v3 13/21] Documentation/SecurityBugs: convert it to ReST markup

[Mauro Carvalho Chehab]

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

> On Wed, 14 Sep 2016 08:06:42 -0300
> Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> 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