Add some missing Documentation/*/00-INDEX files
Subsystems (2)
cover Add some missing Documentation/*/00-INDEX files
Hi,
Rob Landley is trying to organize Linux kernel documentation. One thing he is doing is generating index.html files based on our 00-INDEX files in the Documentation directory. He has met with a small problem however, since not all subdirectories inside Documentation contain such a file, nor are all the files that do exist up to date, his index.html files turn up rather incomplete.
In a reply to a recent post to linux-doc, where Rob also posted his script for generating the index.html files, I offered to help out with that situation and create (at least some of) the missing 00-INDEX files. These patches represent the first five files I've created.
The reason I'm not submitting more files at this time is simply that I want to get some feedback before wasting too much time creating these files if it turns out that for some reason they are not wanted. This is also the reason why I'm cross posting to LKML at this time, since I suspect that not very many people currently read linux-doc.
So please do the ACK/NACK/Merge dance with these patches and let me know if more are wanted or not. :-)
Kind regards,
Jesper Juhl <[email protected]>
PATCH 1/5 Add a 00-INDEX file to Documentation/auxdisplay/
Add a 00-INDEX file to Documentation/auxdisplay/
---
00-INDEX | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/auxdisplay/00-INDEX new file +8 -0
@@ -0,0 +1,8 @@ +00-INDEX + - this file. +cfag12864b + - documentation for the cfag12864b LCD driver. +cfag12864b-example.c + - cfag12864b LCD userspace example program. +ks0108 + - documentation for the ks0108 LCD controller driver.
Re: [PATCH 1/5] Add a 00-INDEX file to Documentation/auxdisplay/
Quoted 16 lines · Jesper Juhl
Add a 00-INDEX file to
Documentation/auxdisplay/Signed-off-by Jesper Juhl <[email protected]>---
00-INDEX | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/auxdisplay/00-INDEX 2007-08-11 23:58:49.000000000 +0200 line 8
Quoted 8 lines
Documentation/auxdisplay/00-INDEX 2007-08-11 23:58:49.000000000 +0200 renamed from dev/null 2005-11-21 04:22:37.000000000 +0100 +8
-0@@ -0,0 +1,8 @@ +00-INDEX + - this file. +cfag12864b + - documentation for the cfag12864b LCD driver. +cfag12864b-example.c + - cfag12864b LCD userspace example program. +ks0108 + - documentation for the ks0108 LCD controller driver.
Thank you for the patch.
Signature · 2 lines
Miguel Ojeda http://maxextreme.googlepages.com/index.htm
PATCH 2/5 Add a 00-INDEX file to Documentation/mips/
In reply to Jesper JuhlAdd a 00-INDEX file to Documentation/mips/
---
00-INDEX | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/mips/00-INDEX new file +8 -0
@@ -0,0 +1,8 @@ +00-INDEX + - this file. +AU1xxx_IDE.README + - README for MIPS AU1XXX IDE driver. +GT64120.README + - README for dir with info on MIPS boards using GT-64120 or GT-64120A. +time.README + - README for MIPS time services.
PATCH RESEND 2/5 Add a 00-INDEX file to Documentation/mips/
In reply to Jesper JuhlAdd a 00-INDEX file to Documentation/mips/
---
00-INDEX | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/mips/00-INDEX new file +8 -0
@@ -0,0 +1,8 @@ +00-INDEX + - this file. +AU1xxx_IDE.README + - README for MIPS AU1XXX IDE driver. +GT64120.README + - README for dir with info on MIPS boards using GT-64120 or GT-64120A. +time.README + - README for MIPS time services.
PATCH 3/5 Add a 00-INDEX file to Documentation/sysctl/
In reply to Jesper JuhlAdd a 00-INDEX file to Documentation/sysctl/
---
00-INDEX | 16 ++++++++++++++++ 1 file changed, 16 insertions(+)
Documentation/sysctl/00-INDEX new file +16 -0
@@ -0,0 +1,16 @@ +00-INDEX + - this file. +README + - general information about /proc/sys/ sysctl files. +abi.txt + - documentation for /proc/sys/abi/*. +ctl_unnumbered.txt + - explanation of why one should not add new binary sysctl numbers. +fs.txt + - documentation for /proc/sys/fs/*. +kernel.txt + - documentation for /proc/sys/kernel/*. +sunrpc.txt + - documentation for /proc/sys/sunrpc/*. +vm.txt + - documentation for /proc/sys/vm/*.
PATCH RESEND 3/5 Add a 00-INDEX file to Documentation/sysctl/
In reply to Jesper JuhlAdd a 00-INDEX file to Documentation/sysctl/
---
00-INDEX | 16 ++++++++++++++++ 1 file changed, 16 insertions(+)
Documentation/sysctl/00-INDEX new file +16 -0
@@ -0,0 +1,16 @@ +00-INDEX + - this file. +README + - general information about /proc/sys/ sysctl files. +abi.txt + - documentation for /proc/sys/abi/*. +ctl_unnumbered.txt + - explanation of why one should not add new binary sysctl numbers. +fs.txt + - documentation for /proc/sys/fs/*. +kernel.txt + - documentation for /proc/sys/kernel/*. +sunrpc.txt + - documentation for /proc/sys/sunrpc/*. +vm.txt + - documentation for /proc/sys/vm/*.
Quoted 6 lines · Jesper Juhl
Rob Landley is trying to organize Linux kernel documentation. One thing he is doing is generating index.html files based on our 00-INDEX files in the Documentation directory. He has met with a small problem however, since not all subdirectories inside Documentation contain such a file, nor are all the files that do exist up to date, his index.html files turn up rather incomplete.
[...]
Quoted 2 lines
I want to get some feedback before wasting too much time creating these files
[...]
Isn't it with 00-INDEX just like with the "Last Updated:" footers in documentation texts?
They are metadata which will be almost always out of date.
Signature · 3 lines
Stefan Richter -=====-=-=== =--- -==-- http://arcgraph.de/sr/
Quoted 7 lines · Stefan Richter
Quoted 6 lines · Jesper Juhl
Rob Landley is trying to organize Linux kernel documentation. One thing he is doing is generating index.html files based on our 00-INDEX files in the Documentation directory. He has met with a small problem however, since not all subdirectories inside Documentation contain such a file, nor are all the files that do exist up to date, his index.html files turn up rather incomplete.
Quoted 8 lines
[...]
Quoted 2 lines
I want to get some feedback before wasting too much time creating these files
[...]
Isn't it with 00-INDEX just like with the "Last Updated:" footers in documentation texts?
That is certainly a risk, yes. But it shouldn't be hard to write a small script to check if the 00-INDEX files are up-to-date, that will make it pretty simple to update them once in a while if people forget.
Signature · 3 lines
Jesper Juhl <[email protected]> Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html Plain text mails only, please http://www.expita.com/nomime.html
Quoted 7 lines · Jesper Juhl
Quoted 3 lines · Stefan Richter
Isn't it with 00-INDEX just like with the "Last Updated:" footers in documentation texts?
That is certainly a risk, yes. But it shouldn't be hard to write a small script to check if the 00-INDEX files are up-to-date, that will make it pretty simple to update them once in a while if people forget.
Or use the first line of each text file to describe what the file is about.
And BTW, if authors insist on "Last Updated:", make it a header rather than a footer. Increases the chance that submitters remember to update it.
Signature · 3 lines
Stefan Richter -=====-=-=== =--- -==-- http://arcgraph.de/sr/
Quoted 10 lines · Stefan Richter
Quoted 7 lines · Jesper Juhl
Quoted 2 lines · Stefan Richter
Isn't it with 00-INDEX just like with the "Last Updated:" footers in documentation texts?
That is certainly a risk, yes. But it shouldn't be hard to write a small script to check if the 00-INDEX files are up-to-date, that will make it pretty simple to update them once in a while if people forget.
Or use the first line of each text file to describe what the file is about.
The first line of "unicode.txt" is:
Last update: 2005-01-17, version 1.4
The first line of "keys.txt" (and keys-request-key.txt) is:
============================
The first line of sx.txt is blank, although that's easy enough to work around.
Lots of first lines redundantly have the filename in them, others have trailing information like the first nonblank line of kref.txt:
Quoted 1 line
krefs allow you to add reference counters to your objects. If you
This heuristic seems to need about as much cleanup as just fixing 00-INDEX.txt in all the directories.
Quoted 2 lines
And BTW, if authors insist on "Last Updated:", make it a header rather than a footer. Increases the chance that submitters remember to update it.
Why not just use the source control system to review the actual revision history of the file?
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 2 lines · Rob Landley
Quoted 1 line · Stefan Richter
Or use the first line of each text file to describe what the file is about.
...
Quoted 2 lines
This heuristic seems to need about as much cleanup as just fixing 00-INDEX.txt in all the directories.
I didn't think of heuristics but rather of a style guideline. Maybe prepend this metadata line with "Subject: " or so to distinguish it from data.
What's the difference to 00-INDEX? It's inline. Hence,
- as soon as a majority of files have that header, authors of new files will start to provide that header automatically. Or am I too optimistic?
- it's a little bit faster to create these headers than to add them to 00-INDEX: Just move the existing title to the top.
There could also be "From: " and/or "Cc: " headers for authorship and maintainership metadata. (Of course maintainership metadata could also go into extra files like 00-INDEX or MAINTAINERS. Authorship metadata of more recent documentation files is actually available in the source control system.)
Quoted 5 lines
Quoted 2 lines
And BTW, if authors insist on "Last Updated:", make it a header rather than a footer. Increases the chance that submitters remember to update it.
Why not just use the source control system to review the actual revision history of the file?
Just to clarify: I'm *not* one of those who want the date in there.
Signature · 3 lines
Stefan Richter -=====-=-=== =--- -==-- http://arcgraph.de/sr/
Quoted 6 lines · Stefan Richter
Quoted 2 lines
This heuristic seems to need about as much cleanup as just fixing 00-INDEX.txt in all the directories.
I didn't think of heuristics but rather of a style guideline. Maybe prepend this metadata line with "Subject: " or so to distinguish it from data.
That's just extra markup for me to filter out. Either the first line nonblank has a special meaning or it doesn't. Currently, it doesn't.
Quoted 4 lines
What's the difference to 00-INDEX? It's inline. Hence,
- as soon as a majority of files have that header, authors of new files will start to provide that header automatically. Or am I too optimistic?
You're too optimistic, but if it's something we can check automatically we can find and fix instances that don't. (Although in this case "automatic" means we generate the index, put it on the web, and either we notice mistakes or people point them out to us.)
Quoted 2 lines
- it's a little bit faster to create these headers than to add them to 00-INDEX: Just move the existing title to the top.
You are aware that some of the files in Documentation aren't text, right? There's example code in C, there's docbook, there's a gif and an xpm...
What variant of "fast" do you mean? Processing the entire directory takes a fraction of a second on my laptop.
I'm not really invested in 00-INDEX, but I point out that it currently exists and I've indicated a willingness to do work to update it. If you want to do your own work to update something else, be my guest. I'll be over here.
Quoted 2 lines
There could also be "From: " and/or "Cc: " headers for authorship and maintainership metadata.
You're adding complexity again. Why are you adding complexity?
Quoted 2 lines
(Of course maintainership metadata could also
go into extra files like 00-INDEX orMAINTAINERS.
00-INDEX is a bad place for it, and MAINTAINERS hasn't go the granularity.
Quoted 3 lines
Authorship metadata
of more recent documentation files is actually available in the source control system.)
I was wondering if this would be noticed...
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 3 lines · Rob Landley
Quoted 2 lines · Stefan Richter
- it's a little bit faster to create these headers than to add them to 00-INDEX: Just move the existing title to the top.
...
Quoted 2 lines
What variant of "fast" do you mean? Processing the entire directory takes a fraction of a second on my laptop.
I meant the speed of people, not the speed of text processors.
Signature · 3 lines
Stefan Richter -=====-=-=== =--- -==-- http://arcgraph.de/sr/
Quoted 11 lines · Stefan Richter
Quoted 3 lines · Rob Landley
Quoted 2 lines · Stefan Richter
- it's a little bit faster to create these headers than to add them to 00-INDEX: Just move the existing title to the top.
...
Quoted 2 lines
What variant of "fast" do you mean? Processing the entire directory takes a fraction of a second on my laptop.
I meant the speed of people, not the speed of text processors.
Gotcha.
Populating 00-INDEX from the first nonblank line of each file, skipping lines that are entirely punctuation, is a good suggestion. A human has to go clean up the result, but I could do this thing... :)
Thanks for the suggestion.
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 6 lines · Jesper Juhl
Quoted 2 lines
Isn't it with 00-INDEX just like with the "Last Updated:" footers in documentation texts?
That is certainly a risk, yes. But it shouldn't be hard to write a small script to check if the 00-INDEX files are up-to-date, that will make it pretty simple to update them once in a while if people forget.
Already done:
http://marc.info/?l=linux-doc&m=118671778606001&w=2
It checks the index.html files so you have to run
http://kernel.org/doc/make/docdiridx.py and then run
http://kernel.org/doc/make/doclinkcheck.py afterwards. It shows you the files 00-index links to which aren't there (the 404 errors), and then the files that nothing links to.
I notice that I'm not filtering out the generated index.html files, but oh well. I'll fix that... :)
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 4 lines · Stefan Richter
Isn't it with 00-INDEX just like with the "Last Updated:" footers in documentation texts?
They are metadata which will be almost always out of date.
If nothing is using them, they'll bit-rot, yes. Way of the world. But I've found a use for them. Therefore, I'm interested in getting them up to date and then keeping them there. I already wrote an automatic checker to tell me how they differ from reality, which is half the battle. (It won't help if the file contents change so much the description needs to be updated, but that's not a common event.)
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 9 lines · Rob Landley
Quoted 4 lines · Stefan Richter
Isn't it with 00-INDEX just like with the "Last Updated:" footers in documentation texts?
They are metadata which will be almost always out of date.
If nothing is using them, they'll bit-rot, yes. Way of the world. But I've found a use for them. Therefore, I'm interested in getting them up to date and then keeping them there.
So, do you want me to create more of these?
If you want them, could you perhaps start by ACK'ing the first 5 patches to help me get them merged?
Once I see the first 5 merged I'll start creating more, but I don't want to waste time doing so before that.
Quoted 2 lines
I already wrote an automatic checker to tell me how they differ from reality, which is half the battle.
I started writing such a script myself yesterday, but it's not done yet. If you already have one that works could I have a copy please? That would make my life easier if I'm to help you with this.
Signature · 3 lines
Jesper Juhl <[email protected]> Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html Plain text mails only, please http://www.expita.com/nomime.html
Quoted 5 lines · Jesper Juhl
Quoted 4 lines · Rob Landley
Quoted 3 lines · Stefan Richter
Isn't it with 00-INDEX just like with the "Last Updated:" footers in documentation texts?
Quoted 7 lines
Quoted 5 lines
Quoted 1 line
They are metadata which will be almost always out of date.
If nothing is using them, they'll bit-rot, yes. Way of the world. But I've found a use for them. Therefore, I'm interested in getting them up to date and then keeping them there.
So, do you want me to create more of these?
Yes please.
Quoted 2 lines
If you want them, could you perhaps start by ACK'ing the first 5 patches to help me get them merged?
Just did. :)
Quoted 2 lines
Once I see the first 5 merged I'll start creating more, but I don't want to waste time doing so before that.
Sorry it took so long, but my net access is still a touch intermittent just now. I recently moved back to Austin and we haven't unpacked the wireless router yet. (So although there's internet at home my wife is usually the one using it. I'm out at a wireless laundromat at the moment. Yes, Austin has such things.)
Quoted 6 lines
Quoted 2 lines
I already wrote an automatic checker to tell me how they differ from reality, which is half the battle.
I started writing such a script myself yesterday, but it's not done yet. If you already have one that works could I have a copy please? That would make my life easier if I'm to help you with this.
I posted a link to it in the message at the start of this thread:
http://lkml.org/lkml/2007/8/9/584
Here's the release announcement for it:
http://marc.info/?l=linux-doc&m=118671778606001&w=2
Here's the source control for it:
http://landley.net/hg/kdocs/file/tip/make/
You need to run the index.html generator first, because the link checker works on the html and not on 00-INDEX itself. Both scripts expect Documentation to be a subdirectory of the current directory, and do the whole directory.
And I need to update it so it filters out index.html, but my laundry's done. :)
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
Quoted 2 lines · Jesper Juhl
So please do the ACK/NACK/Merge dance with these patches and let me know if more are wanted or not. :-)
Just tried 'em: they worked for me. :)
Thanks,
Rob
Signature · 2 lines
"One of my most productive days was throwing away 1000 lines of code." - Ken Thompson.
PATCH 4/5 Add a 00-INDEX file to Documentation/telephony/
In reply to Jesper JuhlAdd a 00-INDEX file to Documentation/telephony/
---
00-INDEX | 4 ++++ 1 file changed, 4 insertions(+)
Documentation/telephony/00-INDEX new file +4 -0
@@ -0,0 +1,4 @@ +00-INDEX + - this file. +ixj.txt + - document describing the Quicknet drivers.
PATCH RESEND 4/5 Add a 00-INDEX file to Documentation/telephony/
In reply to Jesper JuhlAdd a 00-INDEX file to Documentation/telephony/
---
00-INDEX | 4 ++++ 1 file changed, 4 insertions(+)
Documentation/telephony/00-INDEX new file +4 -0
@@ -0,0 +1,4 @@ +00-INDEX + - this file. +ixj.txt + - document describing the Quicknet drivers.
PATCH 5/5 Add a 00-INDEX file to Documentation/watchdog/
In reply to Jesper JuhlAdd a 00-INDEX file to Documentation/watchdog/
---
00-INDEX | 10 ++++++++++ 1 file changed, 10 insertions(+)
Documentation/watchdog/00-INDEX new file +10 -0
@@ -0,0 +1,10 @@ +00-INDEX + - this file. +pcwd-watchdog.txt + - documentation for Berkshire Products PC Watchdog ISA cards. +src/ + - directory holding watchdog related example programs. +watchdog-api.txt + - description of the Linux Watchdog driver API. +wdt.txt + - description of the Watchdog Timer Interfaces for Linux.
Re: [PATCH 5/5] Add a 00-INDEX file to Documentation/watchdog/
Hi Jesper,
Quoted 3 lines
Add a 00-INDEX file to
Documentation/watchdog/Signed-off-by Jesper Juhl <[email protected]>
Added this to the linux-2.6-watchdog trees.
Greetings,
Wim.