[PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Jesper Juhl]

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 <jesper.juhl@gmail.com>

[PATCH 1/5] Add a 00-INDEX file to Documentation/auxdisplay/

[Jesper Juhl]

Add a 00-INDEX file to Documentation/auxdisplay/


Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
---

 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.

[PATCH 2/5] Add a 00-INDEX file to Documentation/mips/

[Jesper Juhl]

Add a 00-INDEX file to Documentation/mips/


Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
---

 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.

[PATCH 3/5] Add a 00-INDEX file to Documentation/sysctl/

[Jesper Juhl]

Add a 00-INDEX file to Documentation/sysctl/


Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
---

 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/*.

[PATCH 4/5] Add a 00-INDEX file to Documentation/telephony/

[Jesper Juhl]

Add a 00-INDEX file to Documentation/telephony/


Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
---

 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.

[PATCH 5/5] Add a 00-INDEX file to Documentation/watchdog/

[Jesper Juhl]

Add a 00-INDEX file to Documentation/watchdog/


Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
---

 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.

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Stefan Richter]

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/

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Jesper Juhl]

On 12/08/07, Stefan Richter <stefanr@s5r6.in-berlin.de> 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 <jesper.juhl@gmail.com>
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

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Stefan Richter]

Jesper Juhl wrote:
> On 12/08/07, Stefan Richter <stefanr@s5r6.in-berlin.de> 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/

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Rob Landley]

On Sunday 12 August 2007 12:34:30 pm Stefan Richter wrote:
> Jesper Juhl wrote:
> > On 12/08/07, Stefan Richter <stefanr@s5r6.in-berlin.de> 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.

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Rob Landley]

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.

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Jesper Juhl]

On 12/08/07, Rob Landley <rob@landley.net> 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 <jesper.juhl@gmail.com>
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

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Stefan Richter]

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/

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Rob Landley]

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.

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Rob Landley]

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 <rob@landley.net>

Just tried 'em: they worked for me. :)

Thanks,

Rob
-- 
"One of my most productive days was throwing away 1000 lines of code."
  - Ken Thompson.

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Rob Landley]

On Sunday 12 August 2007 3:11:06 pm Jesper Juhl wrote:
> On 12/08/07, Rob Landley <rob@landley.net> 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.

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Rob Landley]

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.

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Stefan Richter]

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/

Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files

[Rob Landley]

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.

Re: [PATCH 5/5] Add a 00-INDEX file to Documentation/watchdog/

[Wim Van Sebroeck]

Hi Jesper,

> Add a 00-INDEX file to Documentation/watchdog/
> 
> Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>

Added this to the linux-2.6-watchdog trees.

Greetings,
Wim.

Re: [PATCH 1/5] Add a 00-INDEX file to Documentation/auxdisplay/

[Miguel Ojeda]

On 8/12/07, Jesper Juhl <jesper.juhl@gmail.com> wrote:
>
> Add a 00-INDEX file to Documentation/auxdisplay/
>
>
> Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
> ---
>
>  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 <maxextreme@gmail.com>

-- 
Miguel Ojeda
http://maxextreme.googlepages.com/index.htm

[PATCH 2/5][resend] Add a 00-INDEX file to Documentation/mips/

[Jesper Juhl]

Add a 00-INDEX file to Documentation/mips/


Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
---

 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.

[PATCH 3/5][resend] Add a 00-INDEX file to Documentation/sysctl/

[Jesper Juhl]

Add a 00-INDEX file to Documentation/sysctl/


Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
---

 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/*.

[PATCH 4/5][resend] Add a 00-INDEX file to Documentation/telephony/

[Jesper Juhl]

Add a 00-INDEX file to Documentation/telephony/


Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
---

 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.