Long ago, the Linux kernel started using 00-Index files to list the
contents of each documentation directory. This was intended to explain what
each of those files documented. Henrik Austad recently pointed out that
those files have been out of date for a very long time and were probably
not used by anyone anymore. This is nothing new. Henrik said in his post
that this had been discussed already for years, "and they have since then
grown further out of date, so perhaps it is time to just throw them out."
He counted hundreds of instances where the 00-index file was out of date or
not present when it should have been. He posted a patch to rip them all
unceremoniously out of the kernel.
Joe Perches was very pleased with this. He pointed out that .rst files
(the kernel's native documentation format) had largely taken over the
original purpose of those 00-index files. He said the oo-index files were
even misleading by now.
Jonathan Corbet was more reserved. He felt Henrik should distribute the
patch among a wider audience and see if it got any resistance. He added:
I've not yet decided whether I think this is a good idea or not. We
certainly don't need those files for stuff that's in the RST doctree,
that's what the index.rst files are for. But I suspect some people might
complain about losing them for the rest of the content. I do get patches
from people updating them, so some folks do indeed look at them.
Henrik told Jonathan he was happy to update the 00-index files if that
would be preferable. But he didn't want to do that if the right answer was
just to get rid of them.
Meanwhile, Josh Triplett saw no reason to keep the 00-index files around at
all. He remarked, "I was *briefly* tempted, reading through the files, to
suggest ensuring that the one-line descriptions from the 00-INDEX files end
up in the documents themselves, but the more I think about it, I don't
think even that is worth anyone's time to do."
Paul Moore also voiced his support for removing the 00-index files, at
least the ones for NetLabel, which was his area of interest.
The discussion ended there. It's nice that even for apparently obvious
patches, the developers still take the time to consider various
perspectives and try to retain any value from the old thing to the
new. It's especially nice to see this sort of attention given to
documentation patches, which tend to get left out in the cold when it comes
to coding projects.
Note: if you're mentioned above and want to post a response above the comment section, send a message with your response text to firstname.lastname@example.org.