Options, devices, hints - Documentation work needed ?

[Dirk Schroetter]

Hello Benedict,

thanks for your reply and your encouragement. I could not get myself to send you quite the hacked output I was operating on, so here a somewhat ‚improved‘ version of the output. When you see the file, you can imagine my optimism when I sent the earlier mail ;-)

The list essentially just lists the option, any NOTES files it occurred in, the option header files for the option, then the architectures, possible default values encountered and the man-pages this option was seen in.

So that is where I am at right now and I am looking forward to your feedback.

Best Regards,

/Dirk
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: options_raw.txt
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20181204/dd2d96f2/attachment-0001.txt>
-------------- next part --------------


> Am 03.12.2018 um 18:57 schrieb Benedict Reuschling <bcr at FreeBSD.org>:
> 
> Hello Dirk,
> 
> I think this is definitely valueable in multiple ways:
> 
> - finding missing entries in NOTES or lacking a man page (as you noted)
> - adding cross references and notes to existing man pages (when appropriate)
> - checking if all these options are needed or are included implicitly
> during kernel builds
> - identifying outdated information or obsolete entries
> 
> Cross references will help developers understanding how things are
> interconnected within the kernel and the source tree.
> 
> I'm just wondering what kind of format would be appropriate for the
> table. It could be a big table on the FreeBSD wiki, but it could also be
> part of the developers handbook or a separate article. Can you send us
> an excerpt so that we can see how it looks like? It does not have to be
> fancy, just to get a feel for the information in it.
> 
> I could help out from the doc side of things and we should definitely
> find someone from the kernel side to confirm that the findings make sense.
> 
> Thanks!
> 
> Cheers,
> Benedict
> 
> 
> 
> Am 03.12.18 um 17:52 schrieb Dirk Schroetter:
>> Hello there,
>> 
>> I am just working on my kernel and its config and after trying to find a comprehensive list of kernel options, I came up short.
>> 
>> So I did fire up the editor and managed to get a python script running that looks at:
>> 
>> * The ‚options‘ files under /usr/src
>> * The ‚NOTES‘ files
>> * The manual pages
>> 
>> all this being dumped into a table and cross-referenced.
>> 
>> My current stat on a FreeBSD 11.2 AMD64: Around 1000 kernel options of which around half do not have either an entry in NOTES or are not mentioned on a man page (e.g. ACPI_MAX_TAKS or ADA_TEST_FAILURE)
>> 
>> So I was going to try to compile some form of documentation for all of these for my own personal use. Then I was wondering if the Documentation project had any use for this kind of information. My idea was:
>> 
>> 1. Try to get the information into the respective NOTES files.
>> 2. Make sure the options, devices, hints get into the option.h files
>> 3. Updating the man pages.
>> 
>> It may be that this is a fool’s errand and much to big for a single person, but I would volunteer to at least get it started, if you folks think that there is any merit to it.
>> 
>> So that would be my proposal and I would love to hear back from you.
>> 
>> Best Regards,
>> 
>> /Dirk
>> _______________________________________________
>> freebsd-doc at freebsd.org mailing list
>> https://lists.freebsd.org/mailman/listinfo/freebsd-doc
>> To unsubscribe, send any mail to "freebsd-doc-unsubscribe at freebsd.org"
>> 
> 
>