Updating 00-INDEX in Documentation/*

Updating 00-INDEX in Documentation/*

[Henrik Austad]

[-- Attachment #1: Type: text/plain, Size: 2031 bytes --]

Hi Rob, Jiri

If this email goes the wrong place, my sincere apologies, my asbestos 
underwear can be quickly donned!

I've been reading through some of the docs and one thing that has struct 
me, is that there is a certain degree of bitrot (textrot?). Almost every 
category has an outdated 00-INDEX. A couple of indexes has been updated 
(thanks for applying Jiri!), but more remains.

This is obviously not the most important job to undertake, but it 
serves as a very convenient starting-point when exploring a given topic.

Hacking away at python shows me that of the 254 subfolders 57 has outdated 
00-INDEX, either with missing files, or files that has been removed. (see 
list below)

Now, I'm quite happy to start fixing this, but what I would like to know 
before I start:

- is it considered a waste of time? i.e. will it be worth the time
- what is best, a single, big patch, or a series of one patch per 
  directory?
- or should someone(tm) kick whoever caused 00-INDEX to be outdated, to fix 
  it?

thanks!

List of filesystems with outdated index

  name of dir: (index_not_folder / in_folder_not_index)

filesystems: (5/17)
filesystems/nfs: (1/2)
m68k: (0/1)
serial: (1/2)
leds: (0/4)
arm: (10/7)
blackfin: (0/2)
ide: (1/1)
fb: (3/3)
networking: (3/12)
scsi: (0/8)
power: (1/2)
filesystems: (5/17)
filesystems/nfs: (1/2)
arm: (10/7)
RCU: (0/1)
mmc: (4/0)
fmc: (4/0)
w1: (2/0)
w1/masters: (1/2)
w1/slaves: (0/1)
timers: (0/3)
devicetree: (5/1)
serial: (1/2)
leds: (0/4)
arm: (10/7)
fb: (3/3)
power: (1/2)
mmc: (4/0)
w1: (2/0)
w1/masters: (1/2)
w1/slaves: (0/1)
powerpc: (4/0)
x86: (0/8)
PCI: (1/1)
isdn: (1/0)
powerpc: (4/0)
laptops: (1/2)
vm: (4/7)
virtual: (3/0)
scheduler: (0/1)
x86: (0/8)
s390: (2/2)
filesystems: (5/17)
filesystems/nfs: (1/2)
arm: (10/7)
serial: (1/2)
leds: (0/4)
arm: (10/7)
fb: (3/3)
power: (1/2)
mmc: (4/0)
w1: (2/0)
w1/masters: (1/2)
w1/slaves: (0/1)
powerpc: (4/0)
x86: (0/8)

-- 
Henrik Austad

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Updating 00-INDEX in Documentation/*

[Jiri Kosina]

On Mon, 28 Oct 2013, Henrik Austad wrote:

> Hi Rob, Jiri
> 
> If this email goes the wrong place, my sincere apologies, my asbestos 
> underwear can be quickly donned!
> 
> I've been reading through some of the docs and one thing that has struct 
> me, is that there is a certain degree of bitrot (textrot?). Almost every 
> category has an outdated 00-INDEX. A couple of indexes has been updated 
> (thanks for applying Jiri!), but more remains.
> 
> This is obviously not the most important job to undertake, but it 
> serves as a very convenient starting-point when exploring a given topic.
> 
> Hacking away at python shows me that of the 254 subfolders 57 has outdated 
> 00-INDEX, either with missing files, or files that has been removed. (see 
> list below)
> 
> Now, I'm quite happy to start fixing this, but what I would like to know 
> before I start:
> 
> - is it considered a waste of time? i.e. will it be worth the time

That definitely depends purely on you, as you are the sole owner of your 
own time :)

I'd be happy to apply the fixes if you decide to produce them, as keeping 
the references broken isn't really nice.

> - what is best, a single, big patch, or a series of one patch per 
>   directory?

For this particular thing, I'd prefer single big patch. I can handle the 
(very unlikely) conflict cases.

> - or should someone(tm) kick whoever caused 00-INDEX to be outdated, to fix 
>   it?

That's probably more effort than actually fixing it :)

Thanks,

-- 
Jiri Kosina
SUSE Labs

Re: Updating 00-INDEX in Documentation/*

[Rob Landley]

On 10/28/2013 08:05:11 AM, Henrik Austad wrote:
> Hi Rob, Jiri
> Hacking away at python shows me that of the 254 subfolders 57 has  
> outdated
> 00-INDEX, either with missing files, or files that has been removed.  
> (see
> list below)

I'm a bit behind on my email just now. (Started a new job last month,  
everything else got derailed for a bit.)

> Now, I'm quite happy to start fixing this, but what I would like to  
> know
> before I start:
> 
> - is it considered a waste of time? i.e. will it be worth the time
> - what is best, a single, big patch, or a series of one patch per
>   directory?
> - or should someone(tm) kick whoever caused 00-INDEX to be outdated,  
> to fix
>   it?

Go for it.

I've had a script that does this since 2007, but it's in the context of  
creating html indexes for the kernel.org/doc/Documentation directory,  
and after the kernel.org breakin they never gave me rsync access back  
(because it's not built into git and all any server ever does is run  
git, right?) so I couldn't update it anymore. Then they decided that  
the Documentation directory should just be a raw checkout from git with  
no html indexes (because git), and presumably they'll be doing the same  
for
http://kernel.org/doc/menuconfig any day now (how, I couldn't tell you,  
but it's apparently no longer my problem)...

So it's kinda hard to get enthused about it these days. I wanted to  
revive my old push to reorganize the documentation directory  
(https://lkml.org/lkml/2007/5/22/473 and such) but if the word from on  
high is that a giant raw pile of unsorted files is the optimal way to  
organize things, who am I to argue?

Same problem for kernel.org/doc/htmldocs: the ones I did way back when  
(https://web.archive.org/web/20090327025639/http://www.kernel.org/doc/htmldocs/)  
had both the "one big html file" version and the lots of little files  
version and I'd watch the build logs and send patches to get the  
warnings down, but they took that away and replaced it without even  
letting me know they were doing that, so I've fallen out of the habit.  
(My understanding was that the kernel.org guys officially don't care  
about any data that isn't accessed through git, and a web browser isn't  
git, so...)

*shrug* I suppose all it's still on the todo list somewhere. Maybe  
somewhere after reviving http://landley.net/qemu and catching that up  
to current, but it's in there...

Rob

Re: Updating 00-INDEX in Documentation/*

[Henrik Austad]

On Thu, Nov 14, 2013 at 11:09:03PM -0600, Rob Landley wrote:
> On 10/28/2013 08:05:11 AM, Henrik Austad wrote:
> >Hi Rob, Jiri
> >Hacking away at python shows me that of the 254 subfolders 57 has
> >outdated
> >00-INDEX, either with missing files, or files that has been
> >removed. (see
> >list below)
> 
> I'm a bit behind on my email just now. (Started a new job last
> month, everything else got derailed for a bit.)
> 
> >Now, I'm quite happy to start fixing this, but what I would like
> >to know
> >before I start:
> >
> >- is it considered a waste of time? i.e. will it be worth the time
> >- what is best, a single, big patch, or a series of one patch per
> >  directory?
> >- or should someone(tm) kick whoever caused 00-INDEX to be
> >outdated, to fix
> >  it?
> 
> Go for it.

Ok, I'll work my way through the list then.

> I've had a script that does this since 2007, but it's in the context of 
> creating html indexes for the kernel.org/doc/Documentation directory

Hmm, ok, I was just planning to get the 00-INDEX files up to speed, 
anything beyond that was not on my plan.

> , and after the kernel.org breakin they never gave me rsync access back 
> (because it's not built into git and all any server ever does is run git, 
> right?) so I couldn't update it anymore. Then they decided that the 
> Documentation directory should just be a raw checkout from git with no 
> html indexes (because git), and presumably they'll be doing the same for 
> http://kernel.org/doc/menuconfig any day now (how, I couldn't tell you, 
> but it's apparently no longer my problem)...
> 
> So it's kinda hard to get enthused about it these days. I wanted to
> revive my old push to reorganize the documentation directory
> (https://lkml.org/lkml/2007/5/22/473 and such) but if the word from
> on high is that a giant raw pile of unsorted files is the optimal
> way to organize things, who am I to argue?
> 
> Same problem for kernel.org/doc/htmldocs: the ones I did way back when 
> (https://web.archive.org/web/20090327025639/http://www.kernel.org/doc/htmldocs/) 
> had both the "one big html file" version and the lots of little files 
> version and I'd watch the build logs and send patches to get the warnings 
> down, but they took that away and replaced it without even letting me 
> know they were doing that, so I've fallen out of the habit. (My 
> understanding was that the kernel.org guys officially don't care about 
> any data that isn't accessed through git, and a web browser isn't git, 
> so...)
> 
> *shrug* I suppose all it's still on the todo list somewhere. Maybe
> somewhere after reviving http://landley.net/qemu and catching that
> up to current, but it's in there...
> 
> Rob

-- 
Henrik Austad