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

[Rob Landley <rob@landley.net>]

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.