Messages in this thread | | | Date | Wed, 14 Oct 1998 17:11:11 +0100 (GMT) | From | Riley Williams <> | Subject | Re: Kernel Config documentation |
| |
Hi Alan, Mark.
On Tue, 13 Oct 1998, Alan Cox wrote:
>> 1) Is there a list of people working on documenting those options. I'd >> rather not duplicate work, etc.
> Not that I know of. You might want to submit entries to matching > MAINTAINERS people if there are any first. The file itself has Axel > Boldt as its primary maintainer. Most of the recent work on it for > 2.0.x has been from other folk (Stepan Kasal especially)
>> 2) The text for the help seems to come straight from >> ./Documentation/Configure.help. What are the formatting rules >> for this file?
>> What delineates one topic from the next and what marks a >> section as belonging to the option? (Does the CONFIG_ define >> match the text in the help file?)
> It is (where [ ] is just for clarity)
> [Text of Config.in prompt] > [CONFIG_WHATEVER] > [2 spaces]text > [2 spaces]text > [2 spaces]text > [blank line]
> for each entry. And 77 column width maximum (I think thats the > right magic number). That allows menuconfig room for borders
Memory says 76 columns is the preferred number, but I could easily be wrong...
I've been looking into modifying the various scripts to auto-format this text, but have come across too many problems since there are several types of text to be dealt with:
1. The majority of the text can be regarded as free format, but some of it is in the form of preformatted tables which need to be retained.
2. Most of the help texts are written as a single paragraph, and as a result are extremely hard to understand. However, I can't see any simple automatic way to break the text up into digestable paragraphs...
3. Certain paragraphs occur in just about every help block, but with slightly different phraseology. For reference, here's two such texts taken from the 2.0.35 helpfile:
From CONFIX_IPX we see:
This driver is also available as a module ( = code which can be inserted and removed from the running kernel whenever you want). If you want to compile it as a module, say M here and read Documentation/modules.txt.
From CONFIG_SCSI_EATA_PIO we see:
If you want to compile this as a module ( = code which can be inserted in and removed from the running kernel whenever you want), say M here and read Documentation/modules.txt.
Perhaps somebody could explain the difference in meaning that is intended, since I can't find any !!!
My preference would be to give the help system enough intelligence to know that if the option in question allowed an 'M' selection to be made, it should automagically append the appropriate paragraph to the end of the help text, rather than have it repeated several hundred times in the file where it just causes unnecessary bloat.
4. Some paragraphs just don't have a text line before them, others have a text line that is too long for display, and yet others have a text line that does not match the option text displayed earlier. How should these be dealt with?
Personally, I would like to take the header line out of there and have the config programs use the text from the relevant config.in file, but that's not up to me...
>> 3) Are there any tools to make this process easier? Is the text read at >> run-time, or do I need to force a recompile of, say, the >> lxdialog code?
> Run time
Thankfully...
>> 4) Alan, is it worth doing anything for the 2.0.x kernel at this point?
> If there are any and someone does the work I will take them without > hesitation. Missing help is a bug in my book.
>> 5) What else do I need to know?
> I think thats it.
One thing I'd like to know is when either 2.0.36 or 2.2.0 (whichever is chosen) is likely to appear, but that's probably still a trade secret at this point...
Best wishes from Riley.
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/
| |