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]>
Add a 00-INDEX file to Documentation/auxdisplay/
Signed-off-by: Jesper Juhl <[email protected]>
---
00-INDEX | 8 ++++++++
1 file changed, 8 insertions(+)
--- /dev/null 2005-11-21 04:22:37.000000000 +0100
+++ linux-2.6/Documentation/auxdisplay/00-INDEX 2007-08-11 23:58:49.000000000 +0200
@@ -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.
Add a 00-INDEX file to Documentation/mips/
Signed-off-by: Jesper Juhl <[email protected]>
---
00-INDEX | 8 ++++++++
1 file changed, 8 insertions(+)
--- /dev/null 2005-11-21 04:22:37.000000000 +0100
+++ linux-2.6/Documentation/mips/00-INDEX 2007-08-11 22:56:26.000000000 +0200
@@ -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.
Add a 00-INDEX file to Documentation/sysctl/
Signed-off-by: Jesper Juhl <[email protected]>
---
00-INDEX | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
--- /dev/null 2005-11-21 04:22:37.000000000 +0100
+++ linux-2.6/Documentation/sysctl/00-INDEX 2007-08-11 23:52:50.000000000 +0200
@@ -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/*.
Add a 00-INDEX file to Documentation/telephony/
Signed-off-by: Jesper Juhl <[email protected]>
---
00-INDEX | 4 ++++
1 file changed, 4 insertions(+)
--- /dev/null 2005-11-21 04:22:37.000000000 +0100
+++ linux-2.6/Documentation/telephony/00-INDEX 2007-08-11 23:55:54.000000000 +0200
@@ -0,0 +1,4 @@
+00-INDEX
+ - this file.
+ixj.txt
+ - document describing the Quicknet drivers.
Add a 00-INDEX file to Documentation/watchdog/
Signed-off-by: Jesper Juhl <[email protected]>
---
00-INDEX | 10 ++++++++++
1 file changed, 10 insertions(+)
--- /dev/null 2005-11-21 04:22:37.000000000 +0100
+++ linux-2.6/Documentation/watchdog/00-INDEX 2007-08-12 00:06:01.000000000 +0200
@@ -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.
Jesper Juhl wrote:
> 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.
[...]
> 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.
--
Stefan Richter
-=====-=-=== =--- -==--
http://arcgraph.de/sr/
On 12/08/07, Stefan Richter <[email protected]> wrote:
> Jesper Juhl wrote:
> > 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.
> [...]
> > 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.
--
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
Jesper Juhl wrote:
> On 12/08/07, Stefan Richter <[email protected]> wrote:
>> 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.
--
Stefan Richter
-=====-=-=== =--- -==--
http://arcgraph.de/sr/
On Sunday 12 August 2007 12:34:30 pm Stefan Richter wrote:
> Jesper Juhl wrote:
> > On 12/08/07, Stefan Richter <[email protected]> wrote:
> >> 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:
> 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.
> 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
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
On Sunday 12 August 2007 7:48:37 am Stefan Richter wrote:
> 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
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
On 12/08/07, Rob Landley <[email protected]> wrote:
> On Sunday 12 August 2007 7:48:37 am Stefan Richter wrote:
> > 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.
>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.
--
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
Rob Landley wrote:
> On Sunday 12 August 2007 12:34:30 pm Stefan Richter wrote:
>> Or use the first line of each text file to describe what the file is about.
...
> 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.)
>> 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.
--
Stefan Richter
-=====-=-=== =--- -==--
http://arcgraph.de/sr/
On Sunday 12 August 2007 12:10:56 pm Jesper Juhl wrote:
> > 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
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
On Saturday 11 August 2007 5:45:02 pm Jesper Juhl wrote:
> So please do the ACK/NACK/Merge dance with these patches and
> let me know if more are wanted or not. :-)
Acked-by: Rob Landley <[email protected]>
Just tried 'em: they worked for me. :)
Thanks,
Rob
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
On Sunday 12 August 2007 3:11:06 pm Jesper Juhl wrote:
> On 12/08/07, Rob Landley <[email protected]> wrote:
> > On Sunday 12 August 2007 7:48:37 am Stefan Richter wrote:
> > > 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?
Yes please.
> If you want them, could you perhaps start by ACK'ing the first 5
> patches to help me get them merged?
Just did. :)
> 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.)
> >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
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
On Sunday 12 August 2007 3:17:38 pm Stefan Richter wrote:
> > 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.
> 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.)
> - 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.
> There could also be "From: " and/or "Cc: " headers for authorship and
> maintainership metadata.
You're adding complexity again. Why are you adding complexity?
> (Of course maintainership metadata could also
> go into extra files like 00-INDEX or MAINTAINERS.
00-INDEX is a bad place for it, and MAINTAINERS hasn't go the granularity.
> Authorship metadata
> of more recent documentation files is actually available in the source
> control system.)
I was wondering if this would be noticed...
Rob
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
Rob Landley wrote:
> On Sunday 12 August 2007 3:17:38 pm Stefan Richter wrote:
>> - 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.
...
> 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.
--
Stefan Richter
-=====-=-=== =--- -==--
http://arcgraph.de/sr/
On Sunday 12 August 2007 4:47:17 pm Stefan Richter wrote:
> Rob Landley wrote:
> > On Sunday 12 August 2007 3:17:38 pm Stefan Richter wrote:
> >> - 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.
>
> ...
>
> > 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
--
"One of my most productive days was throwing away 1000 lines of code."
- Ken Thompson.
Hi Jesper,
> 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.
On 8/12/07, Jesper Juhl <[email protected]> wrote:
>
> Add a 00-INDEX file to Documentation/auxdisplay/
>
>
> Signed-off-by: Jesper Juhl <[email protected]>
> ---
>
> 00-INDEX | 8 ++++++++
> 1 file changed, 8 insertions(+)
>
> --- /dev/null 2005-11-21 04:22:37.000000000 +0100
> +++ linux-2.6/Documentation/auxdisplay/00-INDEX 2007-08-11 23:58:49.000000000 +0200
> @@ -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.
Signed-off-by: Miguel Ojeda <[email protected]>
--
Miguel Ojeda
http://maxextreme.googlepages.com/index.htm
Add a 00-INDEX file to Documentation/mips/
Signed-off-by: Jesper Juhl <[email protected]>
---
00-INDEX | 8 ++++++++
1 file changed, 8 insertions(+)
--- /dev/null 2005-11-21 04:22:37.000000000 +0100
+++ linux-2.6/Documentation/mips/00-INDEX 2007-08-11 22:56:26.000000000 +0200
@@ -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.
Add a 00-INDEX file to Documentation/sysctl/
Signed-off-by: Jesper Juhl <[email protected]>
---
00-INDEX | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
--- /dev/null 2005-11-21 04:22:37.000000000 +0100
+++ linux-2.6/Documentation/sysctl/00-INDEX 2007-08-11 23:52:50.000000000 +0200
@@ -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/*.
Add a 00-INDEX file to Documentation/telephony/
Signed-off-by: Jesper Juhl <[email protected]>
---
00-INDEX | 4 ++++
1 file changed, 4 insertions(+)
--- /dev/null 2005-11-21 04:22:37.000000000 +0100
+++ linux-2.6/Documentation/telephony/00-INDEX 2007-08-11 23:55:54.000000000 +0200
@@ -0,0 +1,4 @@
+00-INDEX
+ - this file.
+ixj.txt
+ - document describing the Quicknet drivers.