Update to http://kernel.org/doc

Now that I'm actually doing kernel development as my day job (containers stuff for Parallels), I've taken some time to brush up the old kernel documentation directory on kernel.org that I theoretically maintain.

It now includes:

1) Web versions of all the documentation I could find in the kernel source tarball, put on the web where Google can find it. (You can now link to the help text for menuconfig symbol, or refer to the output of "make htmldocs" via URL instead of telling people to build it themselves.)

2) Links to a bunch of standards documents applicable to the kernel.

3) Links to a bunch of other web pages containing kernel documentation (including broken-up copies of all the OLS papers dating back to 2001).

4) Other stuff.

I'm not saying it's complete. I'm just saying I exhumed it, gave it a good scrub, applied the interocitor to the bolts on its' neck, and sent it lurching towards the village...

Opinions?

Rob

P.S. Yes I know I still need to index the 2010 Ottawa Linux Symposium papers. I got 2009 properly indexed, though.

Now that I'm actually doing kernel development as my day job (containers stuff for Parallels), I've taken some time to brush up the old kernel documentation directory on kernel.org that I theoretically maintain.

It now includes:

1) Web versions of all the documentation I could find in the kernel source tarball, put on the web where Google can find it. (You can now link to the help text for menuconfig symbol, or refer to the output of "make htmldocs" via URL instead of telling people to build it themselves.)

2) Links to a bunch of standards documents applicable to the kernel.

3) Links to a bunch of other web pages containing kernel documentation (including broken-up copies of all the OLS papers dating back to 2001).

4) Other stuff.

I'm not saying it's complete. I'm just saying I exhumed it, gave it a good scrub, applied the interocitor to the bolts on its' neck, and sent it lurching towards the village...

Opinions?

Quoted 5 lines

I'm not saying it's complete. I'm just saying I exhumed it, gave it a good scrub, applied the interocitor to the bolts on its' neck, and sent it lurching towards the village...

Opinions?

Very useful if updated. I can now remove some portion of my kernel related bookmarks.

Quoted 8 lines · Mariusz Kozlowski

Quoted 5 lines

I'm not saying it's complete. I'm just saying I exhumed it, gave it a good scrub, applied the interocitor to the bolts on its' neck, and sent it lurching towards the village...

Opinions?

Very useful if updated. I can now remove some portion of my kernel related bookmarks.

Thanks. I can set up a cron job, but in reality it looks prettier than it actually is.

Part of the problem is that "make htmldocs" doesn't reliably build between about -rc1 and -rc4 or so. It's usually not part of anybody's regression testing, and when it DOES fail the output is usually crazy stuff like:

xmlto: /home/landley/linux/linux/Documentation/DocBook/80211.xml does not validate (status 3)
xmlto: Fix document syntax or use --skip-validation option /home/landley/linux/linux/Documentation/DocBook/80211.xml:13074: element
chapter: validity error : Element chapter content does not follow the DTD, expecting (chapterinfo? , (title , subtitle? , titleabbrev?) , (toc

| lot | index | glossary | bibliography)* , tocchap? , (((calloutlist |
glosslist | itemizedlist | orderedlist | segmentedlist | simplelist |
variablelist | caution | important | note | tip | warning |
literallayout | programlisting | programlistingco | screen | screenco |
screenshot | synopsis | cmdsynopsis | funcsynopsis | classsynopsis |
fieldsynopsis | constructorsynopsis | destructorsynopsis |
methodsynopsis | formalpara | para | simpara | address | blockquote |
graphic | graphicco | mediaobject | mediaobjectco | informalequation |
informalexample | informalfigure | informaltable | equation | example |
figure | table | msgset | procedure | sidebar | qandaset | anchor |
bridgehead | remark | highlights | abstract | authorblurb | epigraph |
indexterm | beginpage)+ , (sect1* | refentry* | simplesect* | section*))
| sect1+ | refentry+ | simplesect+ | section+) , (toc | lot | index |
glossary | bibliography)*), got (title sect1 sect1 refentry )

Document /home/landley/linux/linux/Documentation/DocBook/80211.xml does not validate

Which means what, exactly? (That particular example was from last week, it's been fixed since upstream. I added --skip-validation to my xmlto invocation because more stuff built. There are still two blank entries in http://kernel.org/doc/htmldocs/ are because their builds broke. I should pull and run it again and see if those build now...)

Oh, another fun thing is that my Documentation index is created from the 00-INDEX files when those exist, and there's usually version skew between that file and the directory contents.

I have a http://kernel.org/doc/make/doclinkcheck.py which finds the files it lists which don't exist and the files which exist but aren't listed. The current list of files 00-INDEX says exist, but aren't at that location, is:

404 errors:
Documentation/time_interpolators.txt Documentation/voyager.txt Documentation/powerpc/booting-without-of.txt Documentation/powerpc/mpc52xx-device-tree-bindings.txt Documentation/arm/msm Documentation/arm/Samsung-S3C24XX Documentation/arm/Sharp-LH Documentation/arm/SPEAr Documentation/arm/empeg/ Documentation/PCI/PCI-DMA-mapping.txt Documentation/networking/dgrs.txt Documentation/networking/ethertap.txt Documentation/networking/wavelan.txt Documentation/w1/masters/mxc_w1 Documentation/vm/slabinfo.c Documentation/serial/hayes-esp.txt Documentation/filesystems/dentry-locking.txt Documentation/filesystems/reiser4.txt Documentation/s390/zfcpdump

The list of files which exist but aren't in a 00-INDEX is crazy long so I won't post it here. (I can if you're interested...)

I'll probably get around to chipping away at some of that, but first I need to do a proper 2010 OLS paper index. (And that's just a chronological index. A _topic_ index is a huge undertaking. I did a quick search for the NFS guys last night and came up with 7 papers, and I haven't even checked 2010 yet. I'm only even considering an OLS paper topic index because I'd only have to _update_ it once a year, so the work involved is at least finite...)

Quoted 4 lines

I have a http://kernel.org/doc/make/doclinkcheck.py which finds the files it lists which don't exist and the files which exist but aren't listed. The current list of files 00-INDEX says exist, but aren't at that location, is:

I'll fix some of these (or accept patches to do so). Thanks.

Quoted 7 lines · Randy Dunlap

Quoted 4 lines

I have a http://kernel.org/doc/make/doclinkcheck.py which finds the files it lists which don't exist and the files which exist but aren't listed. The current list of files 00-INDEX says exist, but aren't at that location, is:

I'll fix some of these (or accept patches to do so). Thanks.

Let's see...

From: Rob Landley <[email protected]>

Time interpolators were removed in git 1f564ad6d41828 Voyager support went away in git b6b6e2b112caf

Signed-off-by Rob Landley <[email protected]>

---

 Documentation/00-INDEX |    4 ----
 1 file changed, 4 deletions(-)

Documentation/00-INDEX +0 -2

index 8dfc670..f607367 100644
@@ -328,8 +328,6 @@ sysrq.txt
 	- info on the magic SysRq key.
 telephony/
 	- directory with info on telephony (e.g. voice over IP) support.
-time_interpolators.txt
-	- info on time interpolators.
 uml/
 	- directory with information about User Mode Linux.
 unicode.txt

From: Rob Landley <[email protected]>

The device tree infrastructure is being genericized so its documentation moved out of the PowerPC directory.

Signed-off-by Rob Landley <[email protected]>

---

 Documentation/devicetree/00-INDEX |    8 ++++++++
 Documentation/powerpc/00-INDEX    |    4 ----
 2 files changed, 8 insertions(+), 4 deletions(-)

Documentation/devicetree/00-INDEX new file +8 -0

@@ -0,0 +1,8 @@
+Documentation for device trees, a data structure by which bootloaders pass
+hardware layout to Linux in a device-independent manner, simplifying hardware
+probing.  This subsystem is maintained by Grant Likely
+<[email protected]> and has a mailing list at
+https://lists.ozlabs.org/listinfo/devicetree-discuss
+
+booting-without-of.txt
+        - Booting Linux without Open Firmware, describes history and format of device trees.

Documentation/powerpc/00-INDEX +0 -2

index e3960b8..5620fb5 100644
@@ -5,8 +5,6 @@ please mail me.
 
 00-INDEX
 	- this file
-booting-without-of.txt
-	- Booting the Linux/ppc kernel without Open Firmware
 cpu_features.txt
 	- info on how we support a variety of CPUs with minimal compile-time
 	options.

Quoted 11 lines · On Mon, 21 Feb 2011 14:34:51 -0600 Rob Landley wrote:

Quoted 7 lines · Randy Dunlap

Quoted 4 lines

I have a http://kernel.org/doc/make/doclinkcheck.py which finds the files it lists which don't exist and the files which exist but aren't listed.  The current list of files 00-INDEX says exist, but aren't at that location, is:

I'll fix some of these (or accept patches to do so). Thanks.

Let's see...

Quoted 7 lines

From: Rob Landley <[email protected]>

Time interpolators were removed in git 1f564ad6d41828 Voyager support went away in git b6b6e2b112caf

Signed-off-by Rob Landley <[email protected]>

---

Thanks, added to my patch queue.

Quoted 18 lines

 Documentation/00-INDEX |    4 ----

 1 file changed, 4 deletions(-)

Documentation/00-INDEX +0 -0

index 8dfc670..f607367 100644
@@ -328,8 +328,6 @@ sysrq.txt

      - info on the magic SysRq key.
 telephony/
      - directory with info on telephony (e.g. voice over IP) support. -time_interpolators.txt
-     - info on time interpolators.
 uml/
      - directory with information about User Mode Linux. unicode.txt

Documentation/00-INDEX +0 -0

@@ -346,8 +344,6 @@ vm/

Quoted 8 lines

      - directory with info on the Linux vm code. volatile-considered-harmful.txt
      - Why the "volatile" type class should not be used -voyager.txt
-     - guide to running Linux on the Voyager architecture. w1/
      - directory with documents regarding the 1-wire (w1) subsystem. watchdog/

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code *** --
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Now that I'm actually doing kernel development as my day job (containers stuff for Parallels), I've taken some time to brush up the old kernel documentation directory on kernel.org that I theoretically maintain.

It now includes:

3) Links to a bunch of other web pages containing kernel documentation (including broken-up copies of all the OLS papers dating back to 2001).

There also have many doc located in Documentation directory, but not in 00-INDEX file, like
apparmor.txt
bad_memory.txt
braille-console.txt
bt8xxgpio.txt
circular-buffers.txt
coccinelle.txt
credentials.txt
debugging-via-ohci1394.txt
devicetree/
dmaengine.txt
dynamic-debug-howto.txt
email-clients.txt
flexible-arrays.txt
futex-requeue-pi.txt
gcov.txt
...

Also there have some entry not list as alphabetical order.

Quoted 19 lines · Jovi Zhang

There also have many doc located in Documentation directory, but not in 00-INDEX file, like
apparmor.txt
bad_memory.txt
braille-console.txt
bt8xxgpio.txt
circular-buffers.txt
coccinelle.txt
credentials.txt
debugging-via-ohci1394.txt
devicetree/
dmaengine.txt
dynamic-debug-howto.txt
email-clients.txt
flexible-arrays.txt
futex-requeue-pi.txt
gcov.txt
...

Quoted 1 line

Also there have some entry not list as alphabetical order.

My script lists those as well: it finds a little over 1100 of them, which is why I didn't post the list.  (Here it is gzipped and attached.) But that's also listing files for directories that have no 00-INDEX, so I should probably filter that better...

Is alphabetical order a requirement?

Rob

Quoted 1 line

Quoted 1 line

Quoted 1 line

Quoted 22 lines · Rob Landley

Quoted 19 lines · Jovi Zhang

There also have many doc located in Documentation directory, but not in 00-INDEX file, like
apparmor.txt
bad_memory.txt
braille-console.txt
bt8xxgpio.txt
circular-buffers.txt
coccinelle.txt
credentials.txt
debugging-via-ohci1394.txt
devicetree/
dmaengine.txt
dynamic-debug-howto.txt
email-clients.txt
flexible-arrays.txt
futex-requeue-pi.txt
gcov.txt
...

Quoted 1 line

Also there have some entry not list as alphabetical order.

Quoted 9 lines

My script lists those as well: it finds a little over 1100 of them, which is why I didn't post the list.  (Here it is gzipped and attached.) But that's also listing files for directories that have no 00-INDEX, so I should probably filter that better...

Is alphabetical order a requirement?

Rob

Hmm, not sure..., The header of 00-INDEX is like this:

Quoted 1 line

Quoted 1 line

Quoted 1 line

Quoted 1 line

This is a brief list of all the files in ./linux/Documentation and what they contain. If you add a documentation file, please list it here in alphabetical order as well, or risk being hunted down like a rabid dog. Please try and keep the descriptions small enough to fit on one line. Thanks -- Paul G. <<<

From: Randy Dunlap <[email protected]>

Clean up entries in 00-INDEX: drop files that have been removed.

Reported-by Rob Landley <[email protected]>

Signed-off-by Randy Dunlap <[email protected]>

Quoted 6 lines · On Mon, 21 Feb 2011 15:34:09 -0600 Rob Landley wrote:

From: Rob Landley <[email protected]>

The device tree infrastructure is being genericized so its documentation moved out of the PowerPC directory.

Signed-off-by Rob Landley <[email protected]>

Added to my patch queue. Thanks.

Quoted 6 lines

---

 Documentation/devicetree/00-INDEX |    8 ++++++++
 Documentation/powerpc/00-INDEX    |    4 ----
 2 files changed, 8 insertions(+), 4 deletions(-)

Documentation/devicetree/00-INDEX line 8

Quoted 11 lines

Documentation/devicetree/00-INDEX new file +8 -0

@@ -0,0 +1,8 @@
+Documentation for device trees, a data structure by which bootloaders pass
+hardware layout to Linux in a device-independent manner, simplifying hardware
+probing.  This subsystem is maintained by Grant Likely
+<[email protected]> and has a mailing list at
+https://lists.ozlabs.org/listinfo/devicetree-discuss
+
+booting-without-of.txt
+        - Booting Linux without Open Firmware, describes history and format of device trees.

Documentation/powerpc/00-INDEX please mail me. · line 9

Quoted 10 lines

Documentation/powerpc/00-INDEX +0 -2

index e3960b8..5620fb5 100644
@@ -5,8 +5,6 @@ please mail me.
 
 00-INDEX
 	- this file
-booting-without-of.txt
-	- Booting the Linux/ppc kernel without Open Firmware

Quoted 17 lines · Randy Dunlap

Quoted 6 lines · On Mon, 21 Feb 2011 15:34:09 -0600 Rob Landley wrote:

From: Rob Landley <[email protected]>

The device tree infrastructure is being genericized so its documentation moved out of the PowerPC directory.

Signed-off-by Rob Landley <[email protected]>

Added to my patch queue. Thanks.

Quoted 6 lines

---

 Documentation/devicetree/00-INDEX |    8 ++++++++
 Documentation/powerpc/00-INDEX    |    4 ----
 2 files changed, 8 insertions(+), 4 deletions(-)

Quoted 11 lines

Documentation/devicetree/00-INDEX line 8

Quoted 11 lines

Documentation/devicetree/00-INDEX new file +8 -0

@@ -0,0 +1,8 @@
+Documentation for device trees, a data structure by which bootloaders pass
+hardware layout to Linux in a device-independent manner, simplifying hardware
+probing.  This subsystem is maintained by Grant Likely
+<[email protected]> and has a mailing list at
+https://lists.ozlabs.org/listinfo/devicetree-discuss
+
+booting-without-of.txt
+        - Booting Linux without Open Firmware, describes history and format of device trees.

Gah, I screwed this one up. All the other 00-INDEX files list themselves as the first entry, ala:

Quoted 10 lines

Documentation/powerpc/00-INDEX please mail me. · line 9

Quoted 10 lines

Documentation/powerpc/00-INDEX +0 -2

index e3960b8..5620fb5 100644
@@ -5,8 +5,6 @@ please mail me.
 
 00-INDEX
 	- this file
-booting-without-of.txt
-	- Booting the Linux/ppc kernel without Open Firmware

See?

(This broke my index.html generator script, which uses the 00-INDEX line to split "header info that does not contain files you link to" from "alternating file/description lines" which come after it. Yes, I broke my own script.)

Sorry I didn't catch this quickly, I had to get on a plane and come to Scale. (Handing out flyers at the OpenVZ booth.)

Let me know if you want a replacement patch or a patch on top of this one.

Quoted 6 lines

From: Randy Dunlap <[email protected]>

Clean up entries in 00-INDEX: drop files that have been removed.

Reported-by Rob Landley <[email protected]>

Signed-off-by Randy Dunlap <[email protected]>

Acked-by Rob Landley <[email protected]>

Quoted 1 line

Let me know if you want a replacement patch or a patch on top of this one.

Thanks for catching that.
A replacement patch, please.

Quoted 4 lines · Randy Dunlap

Quoted 1 line

Let me know if you want a replacement patch or a patch on top of this one.

Thanks for catching that.
A replacement patch, please.

Here you go:

From: Rob Landley <[email protected]>

The device tree infrastructure is being genericized so its documentation moved out of the PowerPC directory.

Signed-off-by Rob Landley <[email protected]>

---

Documentation/devicetree/00-INDEX | 10 ++++++++++
Documentation/powerpc/00-INDEX | 4 ----

2 files changed, 10 insertions(+), 4 deletions(-)

Documentation/devicetree/00-INDEX new file +10 -0

@@ -0,0 +1,10 @@
+Documentation for device trees, a data structure by which bootloaders pass
+hardware layout to Linux in a device-independent manner, simplifying hardware
+probing.  This subsystem is maintained by Grant Likely
+<[email protected]> and has a mailing list at
+https://lists.ozlabs.org/listinfo/devicetree-discuss
+
+00-INDEX
+	- this file
+booting-without-of.txt
+	- Booting Linux without Open Firmware, describes history and format of device trees.

Documentation/powerpc/00-INDEX +0 -0

index e3960b8..5620fb5 100644
@@ -5,8 +5,6 @@ please mail me.
 

00-INDEX
- this file

Documentation/powerpc/00-INDEX +0 -2

-booting-without-of.txt
-	- Booting the Linux/ppc kernel without Open Firmware

cpu_features.txt
- info on how we support a variety of CPUs with minimal compile-time options.

Documentation/powerpc/00-INDEX +0 -0

@@ -16,8 +14,6 @@ hvcs.txt
 	- IBM "Hypervisor Virtual Console Server" Installation Guide

mpc52xx.txt
- Linux 2.6.x on MPC52xx family

Documentation/powerpc/00-INDEX +0 -2

-mpc52xx-device-tree-bindings.txt
-	- MPC5200 Device Tree Bindings

sound.txt
- info on sound support under Linux/PPC
zImage_layout.txt