Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
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/ - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
On Sunday 12 August 2007 3:11:06 pm Jesper Juhl wrote: > On 12/08/07, Rob Landley <[EMAIL PROTECTED]> 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
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 <[EMAIL PROTECTED]> Just tried 'em: they worked for me. :) Thanks, Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
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/ - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
On 12/08/07, Rob Landley <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
On Sunday 12 August 2007 12:34:30 pm Stefan Richter wrote: > Jesper Juhl wrote: > > On 12/08/07, Stefan Richter <[EMAIL PROTECTED]> 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
Jesper Juhl wrote: > On 12/08/07, Stefan Richter <[EMAIL PROTECTED]> 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/ - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
On 12/08/07, Stefan Richter <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [PATCH 0/5] Add some missing Documentation/*/00-INDEX files
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/ - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
[PATCH 0/5] Add some missing Documentation/*/00-INDEX files
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 <[EMAIL PROTECTED]> - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
