Re: [PATCH] Documentation: update top level 00-INDEX file with newadditions

From: Rob Landley
Date: Thu Feb 21 2013 - 13:42:39 EST


On 02/19/2013 08:53:14 AM, Paul Gortmaker wrote:
On 13-02-18 10:57 AM, Randy Dunlap wrote:
> On 02/18/13 01:39, Jiri Kosina wrote:
>> On Thu, 14 Feb 2013, Paul Gortmaker wrote:
>>
>>> It seems there are about 80 new, but undocumented addtions at
>>> the top level Documentation directory. This fixes up the top
>>> level 00-INDEX by adding new entries and deleting a couple orphans.
>>> Some subdirs could probably still use a check/cleanup too though.
>
> After this patch, I would prefer to see a requirement that each Documentation/
> file contain a "topic" line and then generate INDEX files from those automatically...

1) Have you tried running make htmldocs recently? Notice how much cleanup needs to be done there? (Yes, it's on my todo list.)

2) How many people know that make htmldocs exists? The advantage of 00-INDEX is you don't need to be that familiar with the kernel documentation to notice it _exists_. If you have to run a step to generate it, half the point goes away.

>
> comments?

Rules can sometimes be so inflexible as to prevent additions.
I think I'd rather see a makefile target that does some sanity
checks, so that kernel janitors and the like are more apt to
send trivial patches before it falls behind by 80+ entries like
it was just recently. Just my $0.02 opinion.

P.

Ran my doclinkcheck.py against the "lying around" snapshot I have (less than a week old). The attached file is the output. I need to add filters. (I should break down and add an X: rule for Documentation/devicetree because that's maintained separately by domain experts and is a huge source of churn rending the linux-doc list nearly unusable. And burying my personal mailbox a bit.)

Also, this doesn't catch stuff like:

cd Documentation; for i in $(find zh_CN -type f); do X="$(echo $i | sed 's@^zh_CN/@@')"; find $X -newer $i; done

(I.E. are any translated files older than the file that got translated...)

Today, Greg KH signed my pgp key at CELF, meaning I can start the process of getting my kernel.org account back, which gets me unblocked on a lot of this. (I always have the todo list of doom, but all I've been able to do since the breakin is forward patches to -trivial, and sending big stuff through that seems inappropriate somehow...)

Rob--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/