Options, devices, hints - Documentation work needed ?

[Dirk Schroetter]

Hello Benedict,

really no need to apologise at all - I took some „digital detox“ myself as you can see. 

I like the idea of multiplying the number of eyes fro sure and I am happy to share all of the information in a table as well. I have not yet an account t edit the wiki pages, but I will try to get one now.

Will keep you posted.

Best Regards,

/Dirk

> Am 20.12.2018 um 09:42 schrieb Benedict Reuschling <bcr at FreeBSD.org>:
> 
> 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"
>>>> 
>>> 
>>> 
>> 
> 
>