[PATCH] Documentation: kernel-docs: Move vfs.txt under "Docs at the Linux Kernel tree"

[PATCH] Documentation: kernel-docs: Move vfs.txt under "Docs at the Linux Kernel tree"

[Jonathan Neuschäfer]

It's unnecessary to point to an external mirror of the Documentation
directory. Also, drop the date field, because in-kernel documentation is
continually updated.

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
---

Alternatively, we might drop this entry of the list entirely, because
Documentation/ is already covered.
---
 Documentation/process/kernel-docs.rst | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
index ab12dddc773e..92488e59943d 100644
--- a/Documentation/process/kernel-docs.rst
+++ b/Documentation/process/kernel-docs.rst
@@ -52,6 +52,17 @@ The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
         (including this document itself) have been moved there, and might
         be more up to date than the web version.

+    * Title: **Overview of the Virtual File System**
+
+      :Author: Richard Gooch.
+      :Location: Documentation/filesystems/vfs.txt
+      :Keywords: VFS, File System, mounting filesystems, opening files,
+        dentries, dcache.
+      :Description: Brief introduction to the Linux Virtual File System.
+        What is it, how it works, operations taken when opening a file or
+        mounting a file system and description of important data
+        structures explaining the purpose of each of their entries.
+
 On-line docs
 ------------

@@ -95,18 +106,6 @@ On-line docs
         [...]. This paper examines some common problems for
         submitting larger changes and some strategies to avoid problems.

-    * Title: **Overview of the Virtual File System**
-
-      :Author: Richard Gooch.
-      :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
-      :Date: 2007
-      :Keywords: VFS, File System, mounting filesystems, opening files,
-        dentries, dcache.
-      :Description: Brief introduction to the Linux Virtual File System.
-        What is it, how it works, operations taken when opening a file or
-        mounting a file system and description of important data
-        structures explaining the purpose of each of their entries.
-
     * Title: **Linux Device Drivers, Third Edition**

       :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
--
2.20.1

Re: [PATCH] Documentation: kernel-docs: Move vfs.txt under "Docs at the Linux Kernel tree"

[Martin Kepplinger]

Am 01.04.2019 00:14 schrieb Jonathan Neuschäfer:
> It's unnecessary to point to an external mirror of the Documentation
> directory. Also, drop the date field, because in-kernel documentation 
> is
> continually updated.
> 
> Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
> ---
> 
> Alternatively, we might drop this entry of the list entirely, because
> Documentation/ is already covered.
> ---
>  Documentation/process/kernel-docs.rst | 23 +++++++++++------------
>  1 file changed, 11 insertions(+), 12 deletions(-)
> 
> diff --git a/Documentation/process/kernel-docs.rst
> b/Documentation/process/kernel-docs.rst
> index ab12dddc773e..92488e59943d 100644
> --- a/Documentation/process/kernel-docs.rst
> +++ b/Documentation/process/kernel-docs.rst
> @@ -52,6 +52,17 @@ The Sphinx books should be built with ``make
> {htmldocs | pdfdocs | epubdocs}``.
>          (including this document itself) have been moved there, and 
> might
>          be more up to date than the web version.
> 
> +    * Title: **Overview of the Virtual File System**
> +
> +      :Author: Richard Gooch.
> +      :Location: Documentation/filesystems/vfs.txt
> +      :Keywords: VFS, File System, mounting filesystems, opening 
> files,
> +        dentries, dcache.
> +      :Description: Brief introduction to the Linux Virtual File 
> System.
> +        What is it, how it works, operations taken when opening a file 
> or
> +        mounting a file system and description of important data
> +        structures explaining the purpose of each of their entries.
> +
>  On-line docs
>  ------------
> 
> @@ -95,18 +106,6 @@ On-line docs
>          [...]. This paper examines some common problems for
>          submitting larger changes and some strategies to avoid 
> problems.
> 
> -    * Title: **Overview of the Virtual File System**
> -
> -      :Author: Richard Gooch.
> -      :URL: 
> http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
> -      :Date: 2007
> -      :Keywords: VFS, File System, mounting filesystems, opening 
> files,
> -        dentries, dcache.
> -      :Description: Brief introduction to the Linux Virtual File 
> System.
> -        What is it, how it works, operations taken when opening a file 
> or
> -        mounting a file system and description of important data
> -        structures explaining the purpose of each of their entries.
> -
>      * Title: **Linux Device Drivers, Third Edition**
> 
>        :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
> --
> 2.20.1

Reviewed-by: Martin Kepplinger <martink@posteo.de>

thanks

Re: [PATCH] Documentation: kernel-docs: Move vfs.txt under "Docs at the Linux Kernel tree"

[Jonathan Corbet]

On Mon,  1 Apr 2019 00:14:37 +0200
Jonathan Neuschäfer <j.neuschaefer@gmx.net> wrote:

> It's unnecessary to point to an external mirror of the Documentation
> directory. Also, drop the date field, because in-kernel documentation is
> continually updated.

So I had to ponder on this one a bit...saying "continually updated" is
pretty amusing for a document that leads off with:

		  Last updated on June 24, 2007.

> Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
> ---
> 
> Alternatively, we might drop this entry of the list entirely, because
> Documentation/ is already covered.

In the end, I think this alternative option is the better one.  We don't
want to turn kernel-docs.rst into yet another out-of-date index for the
rest of Documentation/, and the removal of the external URL takes away the
only bit of additional information that this entry offers.

Thanks,

jon

Re: [PATCH] Documentation: kernel-docs: Move vfs.txt under "Docs at the Linux Kernel tree"

[Jonathan Neuschäfer]

[-- Attachment #1: Type: text/plain, Size: 1497 bytes --]

On Tue, Apr 02, 2019 at 09:43:58AM -0600, Jonathan Corbet wrote:
> On Mon,  1 Apr 2019 00:14:37 +0200
> Jonathan Neuschäfer <j.neuschaefer@gmx.net> wrote:
> 
> > It's unnecessary to point to an external mirror of the Documentation
> > directory. Also, drop the date field, because in-kernel documentation is
> > continually updated.
> 
> So I had to ponder on this one a bit...saying "continually updated" is
> pretty amusing for a document that leads off with:
> 
> 		  Last updated on June 24, 2007.

Ok, I should have been more explicit with what I meant and written "(in
principle) continually update"; compared to journal articles or sections
of a specific edition of a book, that's what files in Git are.

However, looking at the Git history for vfs.txt, it has indeed been
updated multiple times per year, and not just with typo fixes, so I
think this line should simply be removed to avoid further confusion.

> 
> > Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
> > ---
> > 
> > Alternatively, we might drop this entry of the list entirely, because
> > Documentation/ is already covered.
> 
> In the end, I think this alternative option is the better one.  We don't
> want to turn kernel-docs.rst into yet another out-of-date index for the
> rest of Documentation/, and the removal of the external URL takes away the
> only bit of additional information that this entry offers.

Good points, I'll do that for v2.


Jonathan Neuschäfer

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]