Options, devices, hints - Documentation work needed ?

[Benedict Reuschling]

Hello Dirk,

sorry to keep you waiting.

The output looks interesting for further work. I think it would be great
for greater visibility (i.e., more eyes seeing it) to have it as a table
on the FreeBSD wiki. That way, we could mark each line of output with a
todo item, assign people to it, PRs or commits that adds the man page
reference, etc. During the process, we might discover that some items
don't warrant a man page (or even a reference) because they became
obsolete or are about to.

Do you have an account on the FreeBSD wiki yet to create and edit pages?
Would it be possible to modify your script to emit a wiki table which we
can then edit there?

Regards,
Benedict


Am 19.12.18 um 10:43 schrieb Dirk Schroetter:
> Hello Benedict,
> 
> I was wondering if you already had a chance to look over the output I sent a few days back and maybe already have a view on how to use that to the. Maximum benefit of the community.
> 
> Best Regards,
> 
> /Dirk
> 
>> 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"
>>>
>>
>>
> 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20181220/541477cf/attachment.sig>