[PATCH] Minor fix to Documentation/powerpc/00-INDEX

[PATCH] Minor fix to Documentation/powerpc/00-INDEX

[Rob Landley]

Signed-off-by: Rob Landley <rob@landley.net>

I have a python script to convert 00-INDEX files into index.html files, and a
second script to show 404 errors in the result as well as files/directories
nothing links to.   (It's not very useful yet, but in case you're wondering
http://kernel.org/doc/docdiridx.py and http://kernel.org/doc/doclinkcheck.py
.)

Anyway, my simple index.html generator breaks on the Documentation/powerpc
directory because one of the description lines is two lines long.  This
patch joins those two lines together into one line.  This is the only
instance (so far) of this problem.

---

In case you're wondering, here are the current the 404 errors in the
various 00-INDEX files.  Fixing all this is on my todo list:

Documentation/ecryptfs.txt
Documentation/time_interpolators.txt
Documentation/arm/SA1100
Documentation/arm/XScale
Documentation/arm/empeg
Documentation/arm/nwfpe
Documentation/isdn/README.eicon
Documentation/fb/clgenfb.txt
Documentation/networking/ethertap.txt
Documentation/filesystems/reiser4.txt
Documentation/scsi/AM53C974.txt
Documentation/scsi/ChangeLog

The "files and directories not linked to" list is 679 lines long.

diff -r /dev/null Documentation/powerpc/00-INDEX
--- a/Documentation/powerpc/00-INDEX	Thu Aug 09 08:40:21 2007 -0700
+++ b/Documentation/powerpc/00-INDEX	Thu Aug 09 20:49:03 2007 -0500
@@ -6,8 +6,7 @@ 00-INDEX
 00-INDEX
 	- this file
 cpu_features.txt
-	- info on how we support a variety of CPUs with minimal compile-time
-	options.
+	- info on how we support a variety of CPUs with minimal compile-time options.
 eeh-pci-error-recovery.txt
 	- info on PCI Bus EEH Error Recovery
 hvcs.txt

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

Re: [PATCH] Minor fix to Documentation/powerpc/00-INDEX

[Randy Dunlap]

On Thu, 9 Aug 2007 23:42:35 -0500 Rob Landley wrote:

> Signed-off-by: Rob Landley <rob@landley.net>
> 
> I have a python script to convert 00-INDEX files into index.html files, and a
> second script to show 404 errors in the result as well as files/directories
> nothing links to.   (It's not very useful yet, but in case you're wondering
> http://kernel.org/doc/docdiridx.py and http://kernel.org/doc/doclinkcheck.py
> .)
> 
> Anyway, my simple index.html generator breaks on the Documentation/powerpc
> directory because one of the description lines is two lines long.  This
> patch joins those two lines together into one line.  This is the only
> instance (so far) of this problem.

If Paul wants to merge this, then OK, but I'm not aware of any rule
that the file descriptions inside INDEX files must be only one line
long... is that documented somewhere?  (if so, where?)

Maybe the script should allow for this?

> ---
> 
> In case you're wondering, here are the current the 404 errors in the
> various 00-INDEX files.  Fixing all this is on my todo list:
> 
> Documentation/ecryptfs.txt
> Documentation/time_interpolators.txt
> Documentation/arm/SA1100
> Documentation/arm/XScale
> Documentation/arm/empeg
> Documentation/arm/nwfpe
> Documentation/isdn/README.eicon
> Documentation/fb/clgenfb.txt
> Documentation/networking/ethertap.txt
> Documentation/filesystems/reiser4.txt
> Documentation/scsi/AM53C974.txt
> Documentation/scsi/ChangeLog
> 
> The "files and directories not linked to" list is 679 lines long.
> 
> diff -r /dev/null Documentation/powerpc/00-INDEX
> --- a/Documentation/powerpc/00-INDEX	Thu Aug 09 08:40:21 2007 -0700
> +++ b/Documentation/powerpc/00-INDEX	Thu Aug 09 20:49:03 2007 -0500
> @@ -6,8 +6,7 @@ 00-INDEX
>  00-INDEX
>  	- this file
>  cpu_features.txt
> -	- info on how we support a variety of CPUs with minimal compile-time
> -	options.
> +	- info on how we support a variety of CPUs with minimal compile-time options.
>  eeh-pci-error-recovery.txt
>  	- info on PCI Bus EEH Error Recovery
>  hvcs.txt


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] Minor fix to Documentation/powerpc/00-INDEX

[Rob Landley]

On Saturday 11 August 2007 4:33:34 pm Randy Dunlap wrote:
> On Thu, 9 Aug 2007 23:42:35 -0500 Rob Landley wrote:
> > Signed-off-by: Rob Landley <rob@landley.net>
> >
> > I have a python script to convert 00-INDEX files into index.html files,
> > and a second script to show 404 errors in the result as well as
> > files/directories nothing links to.   (It's not very useful yet, but in
> > case you're wondering http://kernel.org/doc/docdiridx.py and
> > http://kernel.org/doc/doclinkcheck.py .)
> >
> > Anyway, my simple index.html generator breaks on the
> > Documentation/powerpc directory because one of the description lines is
> > two lines long.  This patch joins those two lines together into one line.
> >  This is the only instance (so far) of this problem.
>
> If Paul wants to merge this, then OK, but I'm not aware of any rule
> that the file descriptions inside INDEX files must be only one line
> long... is that documented somewhere?  (if so, where?)

Documentation/00-INDEX line 5:

> Please try and keep the descriptions small enough to fit on one line.

There was only one instance of it not being the case.  I can use indentation 
level instead (which is what Kconfig uses to identify help text, so I'm not 
leaking pythonisms into the kernel that aren't already there), but the one 
line thing seemed to be an existing standard.

I'm also relying on the first file in the list being documentation for 
00-INDEX itself.  (If it breaks, I'll either try to derive a new heuristic 
and change the script, or submit a patch to change the index.  That one would 
be a more difficult heuristic to replace, though.)

> Maybe the script should allow for this?

*shrug*  I can go either way on that, but people get all funny about 
whitespace being significant and the one line thing wasn't my idea. :)

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

Re: [PATCH] Minor fix to Documentation/powerpc/00-INDEX

[Jesper Juhl]

On 12/08/07, Rob Landley <rob@landley.net> wrote:
> On Saturday 11 August 2007 4:33:34 pm Randy Dunlap wrote:
> > On Thu, 9 Aug 2007 23:42:35 -0500 Rob Landley wrote:
> > > Signed-off-by: Rob Landley <rob@landley.net>
> > >
> > > I have a python script to convert 00-INDEX files into index.html files,
> > > and a second script to show 404 errors in the result as well as
> > > files/directories nothing links to.   (It's not very useful yet, but in
> > > case you're wondering http://kernel.org/doc/docdiridx.py and
> > > http://kernel.org/doc/doclinkcheck.py .)
> > >
> > > Anyway, my simple index.html generator breaks on the
> > > Documentation/powerpc directory because one of the description lines is
> > > two lines long.  This patch joins those two lines together into one line.
> > >  This is the only instance (so far) of this problem.
> >
> > If Paul wants to merge this, then OK, but I'm not aware of any rule
> > that the file descriptions inside INDEX files must be only one line
> > long... is that documented somewhere?  (if so, where?)
>
> Documentation/00-INDEX line 5:
>
> > Please try and keep the descriptions small enough to fit on one line.
>
> There was only one instance of it not being the case.  I can use indentation
> level instead (which is what Kconfig uses to identify help text, so I'm not
> leaking pythonisms into the kernel that aren't already there), but the one
> line thing seemed to be an existing standard.
>
The two times that I've done some big updates to
Documentation/00-INDEX I've also stuck to one line for each
description since that was the only form I'd ever seen - I didn't know
if it was a rule or not, but it seemed pretty sensible for an index.
It's also the form I've stuck to for the new files I send patches for recently.

So for whatever my oppinion is worth; I think we may as well make it a
rule for the 00-INDEX files.


-- 
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] Minor fix to Documentation/powerpc/00-INDEX

[Randy Dunlap]

On Sun, 12 Aug 2007 22:16:43 +0200 Jesper Juhl wrote:

> On 12/08/07, Rob Landley <rob@landley.net> wrote:
> > On Saturday 11 August 2007 4:33:34 pm Randy Dunlap wrote:
> > > On Thu, 9 Aug 2007 23:42:35 -0500 Rob Landley wrote:
> > > > Signed-off-by: Rob Landley <rob@landley.net>
> > > >
> > > > I have a python script to convert 00-INDEX files into index.html files,
> > > > and a second script to show 404 errors in the result as well as
> > > > files/directories nothing links to.   (It's not very useful yet, but in
> > > > case you're wondering http://kernel.org/doc/docdiridx.py and
> > > > http://kernel.org/doc/doclinkcheck.py .)
> > > >
> > > > Anyway, my simple index.html generator breaks on the
> > > > Documentation/powerpc directory because one of the description lines is
> > > > two lines long.  This patch joins those two lines together into one line.
> > > >  This is the only instance (so far) of this problem.
> > >
> > > If Paul wants to merge this, then OK, but I'm not aware of any rule
> > > that the file descriptions inside INDEX files must be only one line
> > > long... is that documented somewhere?  (if so, where?)
> >
> > Documentation/00-INDEX line 5:
> >
> > > Please try and keep the descriptions small enough to fit on one line.

OK :)

> > There was only one instance of it not being the case.  I can use indentation
> > level instead (which is what Kconfig uses to identify help text, so I'm not
> > leaking pythonisms into the kernel that aren't already there), but the one
> > line thing seemed to be an existing standard.
> >
> The two times that I've done some big updates to
> Documentation/00-INDEX I've also stuck to one line for each
> description since that was the only form I'd ever seen - I didn't know
> if it was a rule or not, but it seemed pretty sensible for an index.
> It's also the form I've stuck to for the new files I send patches for recently.
> 
> So for whatever my oppinion is worth; I think we may as well make it a
> rule for the 00-INDEX files.

I think that it's a reasonable rule.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***