From owner-freebsd-doc@freebsd.org Thu Dec 20 08:42:39 2018 Return-Path: Delivered-To: freebsd-doc@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 40621133C54F for ; Thu, 20 Dec 2018 08:42:39 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from mxout3bln1.prossl.de (mxout3bln1.prossl.de [91.233.87.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id ACA3D6D8E1 for ; Thu, 20 Dec 2018 08:42:38 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from fbipool-clients-45-156.fbi.h-da.de (fbipool-clients-45-156.fbi.h-da.de [141.100.45.156]) (authenticated bits=0) by mx1bln1.prossl.de (8.15.2/8.14.9) with ESMTPSA id wBK8ga8w083799 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Thu, 20 Dec 2018 09:42:36 +0100 To: Dirk Schroetter Cc: freebsd-doc@FreeBSD.org References: From: Benedict Reuschling Openpgp: preference=signencrypt Autocrypt: addr=bcr@FreeBSD.org; prefer-encrypt=mutual; keydata= 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 byRcKQ== Organization: The FreeBSD Project Subject: Re: Options, devices, hints - Documentation work needed ? Message-ID: Date: Thu, 20 Dec 2018 09:42:38 +0100 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:60.0) Gecko/20100101 Thunderbird/60.3.3 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="LuUHpzwvgJmaxmmylLJIJ6FV6glM2rdh1" X-Null-Tag: 969ed6f68aa343a17019002fe21fd793 X-Rspamd-Queue-Id: ACA3D6D8E1 X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-2.96 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-1.00)[-0.999,0]; NEURAL_HAM_SHORT(-0.96)[-0.964,0]; ASN(0.00)[asn:20647, ipnet:91.233.84.0/22, country:DE]; NEURAL_HAM_LONG(-1.00)[-1.000,0] X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 20 Dec 2018 08:42:39 -0000 This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --LuUHpzwvgJmaxmmylLJIJ6FV6glM2rdh1 Content-Type: multipart/mixed; boundary="431GblDjkeKGBO8P5lVOnCm3JuOrZ0i4w"; protected-headers="v1" From: Benedict Reuschling To: Dirk Schroetter Cc: freebsd-doc@FreeBSD.org Message-ID: Subject: Re: Options, devices, hints - Documentation work needed ? References: In-Reply-To: --431GblDjkeKGBO8P5lVOnCm3JuOrZ0i4w Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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, >=20 > I was wondering if you already had a chance to look over the output I s= ent a few days back and maybe already have a view on how to use that to t= he. Maximum benefit of the community. >=20 > Best Regards, >=20 > /Dirk >=20 >> Am 03.12.2018 um 18:57 schrieb Benedict Reuschling : >> >> 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 approp= riate) >> - 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 b= e >> 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 se= nse. >> >> 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 fin= d a comprehensive list of kernel options, I came up short. >>> >>> So I did fire up the editor and managed to get a python script runnin= g that looks at: >>> >>> * The =E2=80=9Aoptions=E2=80=98 files under /usr/src >>> * The =E2=80=9ANOTES=E2=80=98 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 o= f which around half do not have either an entry in NOTES or are not menti= oned 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 o= f these for my own personal use. Then I was wondering if the Documentatio= n 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=E2=80=99s errand and much to big for a = single person, but I would volunteer to at least get it started, if you f= olks 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@freebsd.org mailing list >>> https://lists.freebsd.org/mailman/listinfo/freebsd-doc >>> To unsubscribe, send any mail to "freebsd-doc-unsubscribe@freebsd.org= " >>> >> >> >=20 --431GblDjkeKGBO8P5lVOnCm3JuOrZ0i4w-- --LuUHpzwvgJmaxmmylLJIJ6FV6glM2rdh1 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- iQEzBAEBCgAdFiEEwXonQDvNfP/33IoBVXQ7/QHhjTUFAlwbVf4ACgkQVXQ7/QHh jTWCLAgAnVpDasylB2WHF/6gedHgP6de1Ct/XNNsTaTVWNOPpxAC5JJmcBLF42Tf YL67Fka89nJJU4T46kdgWDTlb6nYsxzYV9iHspjxWZD0VjbfFwMZy1cs0V2AisZA +iI7aG2doF86pDerK7OOXnYfs7NDPhukL/vgX4v8bdQYyywqpfKhwAlucYvXkjKi y/wuIYHd+iILHv24nwRASVPRdTudym+rpzLdTIFFiyX0OVYBZfWIPjZIj6QU3kSx /3yUy0xvyDxs+Y2CwDuKLIQVK3DvyYKPqsgm7N1Niaq5X4v2lzaB1Cot15LRkZux 5Bs85PY3+Y5r6jLgtIsrAKkOfUbn+g== =Fw9K -----END PGP SIGNATURE----- --LuUHpzwvgJmaxmmylLJIJ6FV6glM2rdh1--