linux-kernel - Re: [PATCH 03/11] docs: Clean up and organize the admin guide a bit

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: <20161026221825.55f42888@vento.lan>
Date:   Wed, 26 Oct 2016 22:18:25 -0200
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        Jani Nikula <jani.nikula@...el.com>
Subject: Re: [PATCH 03/11] docs: Clean up and organize the admin guide a bit

Em Wed, 26 Oct 2016 17:19:31 -0600
Jonathan Corbet <corbet@....net> escreveu:

> The admin guide is a good start, but it's time to turn it into something
> better than an unordered blob of files.  This is a first step in that
> direction.  The TOC has been split up and annotated, the guides have been
> reordered, and minor tweaks have been applied to a few of them.
> 
> One consequence of splitting up the TOC is that we don't really want to use
> :numbered: anymore, since the count resets every time and there doesn't
> seem to be a way to change that.  Eventually we probably want to group the
> documents into sub-books, at which point we can go back to a single TOC,
> but it's probably early to do that.
> 
> Signed-off-by: Jonathan Corbet <corbet@....net>
> ---
>  Documentation/admin-guide/index.rst             | 50 +++++++++++++++++++------
>  Documentation/admin-guide/kernel-parameters.rst |  4 +-
>  Documentation/admin-guide/sysfs-rules.rst       |  4 +-
>  Documentation/admin-guide/vga-softcursor.rst    |  4 +-
>  4 files changed, 45 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 4e5abbb4bbd5..2ce2bf02824b 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -1,22 +1,52 @@
> -Linux Kernel User's Documentation
> -=================================
> +The Linux kernel user's and administrator's guide
> +=================================================
>  
> -Contents:
> +The following is a collection of user-oriented documents that have been
> +added to the kernel over time.  There is, as yet, little overall order or
> +organization here — this material was not written to be a single, coherent
> +document!  With luck things will improve quickly over time.
> +
> +This initial section contains overall information, including the README
> +file describing the kernel as a whole, documentation on kernel parameters,
> +etc. 
>  
>  .. toctree::
> -   :maxdepth: 2
> -   :numbered:
> +   :maxdepth: 1
>  
>     README
> +   kernel-parameters
> +   devices
> +
> +Here is a set of documents aimed at users who are trying to track down
> +problems and bugs in particular.
> +
> +.. toctree::
> +   :maxdepth: 1
> +   
>     reporting-bugs
> +   security-bugs
>     bug-hunting
>     oops-tracing
>     ramoops
> -   initrd
> -   init
>     dynamic-debug-howto
> -   security-bugs
> -   kernel-parameters
> +   init
> +
> +This is the beginning of a section with information of interest to
> +application developers.  Documents covering various aspects of the kernel
> +ABI will be found here.
> +
> +.. toctree::
> +   :maxdepth: 1
> +   
> +   sysfs-rules
> +
> +The rest of this manual consists of various unordered guides on how to
> +configure specific aspects of kernel behavior to your liking.
> +
> +.. toctree::
> +   :maxdepth: 1
> +   
> +   initrd
>     serial-console
>     braille-console
>     parport
> @@ -25,8 +55,6 @@ Contents:
>     sysrq
>     unicode
>     vga-softcursor
> -   sysfs-rules
> -   devices
>     binfmt-misc
>     mono
>     java
> diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
> index d2f2725f032e..37105aedb2e4 100644
> --- a/Documentation/admin-guide/kernel-parameters.rst
> +++ b/Documentation/admin-guide/kernel-parameters.rst
> @@ -1,5 +1,5 @@
> -Kernel Parameters
> -~~~~~~~~~~~~~~~~~
> +The kernel's command-line parameters
> +====================================
>  
>  The following is a consolidated list of the kernel parameters as
>  implemented by the __setup(), core_param() and module_param() macros
> diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/admin-guide/sysfs-rules.rst
> index 04bdd52cba1d..8273bb1de105 100644
> --- a/Documentation/admin-guide/sysfs-rules.rst
> +++ b/Documentation/admin-guide/sysfs-rules.rst
> @@ -1,5 +1,5 @@
> -Rules on how to access information in the Linux kernel sysfs
> -============================================================
> +Rules on how to access information in  sysfs
> +============================================

There is an extra space in the above.

Except for that, the remaining looks OK on my eyes.

With that fixed, feel free to add:
	Reviewed-by: Mauro Carvalho Chehab <mchehab@...pensource.com>

Regards,
Mauro