| Message ID | 1477523979-5837-4-git-send-email-corbet@lwn.net |
|---|---|
| State | New |
| Headers | show |
Em Wed, 26 Oct 2016 17:19:31 -0600 Jonathan Corbet <corbet@lwn.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@lwn.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@s-opensource.com> Regards, Mauro
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 +============================================ The kernel-exported sysfs exports internal kernel implementation details and depends on internal kernel structures and layout. It is agreed upon diff --git a/Documentation/admin-guide/vga-softcursor.rst b/Documentation/admin-guide/vga-softcursor.rst index 9eac6744b3a1..a663a745cff4 100644 --- a/Documentation/admin-guide/vga-softcursor.rst +++ b/Documentation/admin-guide/vga-softcursor.rst @@ -50,8 +50,8 @@ third parameter .. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. -Examples: -========= +Examples +-------- To get normal blinking underline, use::
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@lwn.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(-) -- 2.7.4