Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1509942 > unrolled thread

[PATCH 00/11] Organize and clean up the admin and process guides

Started byJonathan Corbet <corbet@lwn.net>
First post2016-10-27 01:30 +0200
Last post2016-10-27 02:30 +0200
Articles 5 — 2 participants

Back to article view | Back to linux.kernel

Contents

  [PATCH 00/11] Organize and clean up the admin and process guides Jonathan Corbet <corbet@lwn.net> - 2016-10-27 01:30 +0200
    [PATCH 10/11] docs: add a warning to submitting-drivers.rst Jonathan Corbet <corbet@lwn.net> - 2016-10-27 01:30 +0200
      Re: [PATCH 10/11] docs: add a warning to submitting-drivers.rst Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-27 02:40 +0200
    [PATCH 03/11] docs: Clean up and organize the admin guide a bit Jonathan Corbet <corbet@lwn.net> - 2016-10-27 01:30 +0200
      Re: [PATCH 03/11] docs: Clean up and organize the admin guide a bit Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-27 02:30 +0200

#1509942 — [PATCH 00/11] Organize and clean up the admin and process guides

FromJonathan Corbet <corbet@lwn.net>
Date2016-10-27 01:30 +0200
Subject[PATCH 00/11] Organize and clean up the admin and process guides
Message-ID<swFNT-28S-5@gated-at.bofh.it>
The creation of the admin and process guides is a great thing, but, without
care, we risk replacing a messy docs directory with a few messy Sphinx
books.  In an attempt to head that off and show what I'm thinking, here's a
set of tweaks that, I think, make the existing Sphinx-formatted docs a bit
more accessible.

Hopefully none of this is too controversial.  That's probably too much to
hope for in the case of the deleted documents, though, since deleting
anything seems to be an uphill battle.

Jonathan Corbet (11):
  docs: Tweak the top-level Sphinx page
  docs: retitle the kernel-documentation.rst
  docs: Clean up and organize the admin guide a bit
  docs: Get rid of the badRAM guide
  docs: Get rid of the "basic profiling" guide
  docs: Get rid of the "bug-hunting" guide
  docs: Apply some basic organization to the process guide
  docs: Tweak submitting-patches.rst formatting
  docs: Collapse the process guide TOC
  docs: add a warning to submitting-drivers.rst
  docs: Add a warning to applying-patches.rst

 Documentation/admin-guide/bad-memory.rst        |  50 -----
 Documentation/admin-guide/basic-profiling.rst   |  68 -------
 Documentation/admin-guide/bug-hunting.rst       | 249 ------------------------
 Documentation/admin-guide/index.rst             |  53 +++--
 Documentation/admin-guide/kernel-parameters.rst |   4 +-
 Documentation/admin-guide/sysfs-rules.rst       |   4 +-
 Documentation/admin-guide/vga-softcursor.rst    |   4 +-
 Documentation/index.rst                         |  45 ++++-
 Documentation/kernel-documentation.rst          |   6 +-
 Documentation/process/applying-patches.rst      |   4 +
 Documentation/process/changes.rst               |   2 +-
 Documentation/process/index.rst                 |  39 +++-
 Documentation/process/submitting-drivers.rst    |   8 +
 Documentation/process/submitting-patches.rst    |  16 +-
 14 files changed, 137 insertions(+), 415 deletions(-)
 delete mode 100644 Documentation/admin-guide/bad-memory.rst
 delete mode 100644 Documentation/admin-guide/basic-profiling.rst
 delete mode 100644 Documentation/admin-guide/bug-hunting.rst

-- 
2.7.4

[toc] | [next] | [standalone]

#1509944 — [PATCH 10/11] docs: add a warning to submitting-drivers.rst

FromJonathan Corbet <corbet@lwn.net>
Date2016-10-27 01:30 +0200
Subject[PATCH 10/11] docs: add a warning to submitting-drivers.rst
Message-ID<swFNU-28S-45@gated-at.bofh.it>
In reply to#1509942
This is crufty stuff and should maybe just be deleted, but I'm not quite
ready to do that yet.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/process/submitting-drivers.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
index 0939d018c289..afb82ee0cbea 100644
--- a/Documentation/process/submitting-drivers.rst
+++ b/Documentation/process/submitting-drivers.rst
@@ -8,6 +8,14 @@ various kernel trees. Note that if you are interested in video card drivers
 you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
 (http://x.org/) instead.
 
+.. note::
+
+   This document is old and has seen little maintenance in recent years; it
+   should probably be updated or, perhaps better, just deleted.  Most of
+   what is here can be found in the other development documents anyway.
+
+   Oh, and we don't really recommend submitting changes to XFree86 :)
+
 Also read the Documentation/process/submitting-patches.rst document.
 
 
-- 
2.7.4

[toc] | [prev] | [next] | [standalone]

#1509994 — Re: [PATCH 10/11] docs: add a warning to submitting-drivers.rst

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2016-10-27 02:40 +0200
SubjectRe: [PATCH 10/11] docs: add a warning to submitting-drivers.rst
Message-ID<swGTD-2Pm-5@gated-at.bofh.it>
In reply to#1509944
Em Wed, 26 Oct 2016 17:19:38 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> This is crufty stuff and should maybe just be deleted, but I'm not quite
> ready to do that yet.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/process/submitting-drivers.rst | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
> index 0939d018c289..afb82ee0cbea 100644
> --- a/Documentation/process/submitting-drivers.rst
> +++ b/Documentation/process/submitting-drivers.rst
> @@ -8,6 +8,14 @@ various kernel trees. Note that if you are interested in video card drivers
>  you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
>  (http://x.org/) instead.
>  
> +.. note::
> +
> +   This document is old and has seen little maintenance in recent years; it
> +   should probably be updated or, perhaps better, just deleted.  Most of
> +   what is here can be found in the other development documents anyway.
> +
> +   Oh, and we don't really recommend submitting changes to XFree86 :)

Yeah, at least the XFree86 part should be stripped ;)

I guess the other parts should be verified if they're all there at the
process book before nuking this one.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

> +
>  Also read the Documentation/process/submitting-patches.rst document.
>  
>  



Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1509946 — [PATCH 03/11] docs: Clean up and organize the admin guide a bit

FromJonathan Corbet <corbet@lwn.net>
Date2016-10-27 01:30 +0200
Subject[PATCH 03/11] docs: Clean up and organize the admin guide a bit
Message-ID<swFNU-28S-47@gated-at.bofh.it>
In reply to#1509942
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
+============================================
 
 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::
 
-- 
2.7.4

[toc] | [prev] | [next] | [standalone]

#1509993 — Re: [PATCH 03/11] docs: Clean up and organize the admin guide a bit

FromMauro Carvalho Chehab <mchehab@s-opensource.com>
Date2016-10-27 02:30 +0200
SubjectRe: [PATCH 03/11] docs: Clean up and organize the admin guide a bit
Message-ID<swGJY-2Mc-31@gated-at.bofh.it>
In reply to#1509946
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

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web