From owner-freebsd-doc@freebsd.org Mon Dec 3 17:57:24 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 513DE132E44B for ; Mon, 3 Dec 2018 17:57:24 +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 BC16A8CE34 for ; Mon, 3 Dec 2018 17:57:23 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from Voyager.fritz.box (p4FE9A7EE.dip0.t-ipconnect.de [79.233.167.238]) (authenticated bits=0) by mx1bln1.prossl.de (8.15.2/8.14.9) with ESMTPSA id wB3HvL8c008539 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Mon, 3 Dec 2018 18:57:21 +0100 Subject: Re: Options, devices, hints - Documentation work needed ? To: Dirk Schroetter , freebsd-doc@FreeBSD.org References: From: Benedict Reuschling Openpgp: preference=signencrypt Autocrypt: addr=bcr@FreeBSD.org; prefer-encrypt=mutual; keydata= xsBNBFr4feYBCACdrnRpuvW/d/PeKuFu54ifaGhG+yFf3wnWaQX8hTCvySbv6A24Owot6cyU vhjdsifZ9iRQ82Likl+6OxI9qBXR9N+WCv1ut46q+mL50YLnYRejRCz8vEmVunlyVDKjsBY5 DtjsaRXMJ/D56wh3ROd9VYjrDHWobu+bg9D7RIv0kCyoPd0JsYRFXISgt4IocWVLT8ciWqiT Pp3m37BPrtXhR3EDOnHmGWPf6SuolvveqyOlpdguD3LAkFJDLeq3isnMaLXUhcsTqBTBLdOT 6EJHBYCcq39izNVC88JsVBmEuByhpb0LaXrBFQWhUG5RyecROAqrx+DWhcZnxayCtr3NABEB AAHNLUJlbmVkaWN0IFJldXNjaGxpbmcgPGJlbmVkaWN0QHJldXNjaGxpbmcub3JnPsLAlAQT AQoAPgIbAwULCQgHAwUVCgkICwUWAgMBAAIeAQIXgBYhBFNCdm1t64Tl0+Pc9qHQwdMFhdFY BQJa+I6nBQkDwnfBAAoJEKHQwdMFhdFYxh0H/2jE6At35/G9bgNC8BqMb6OlZmOZoAdLyuai 6cVW1SssB4NSd89gB3rTBJJCI2rMozu5t/mm/x0xL2sgNl9C3sscW6KtQDvYAwEom/Wa07dP FOIUyznfwO5PakiI1t3HM0EBWiIF+Zd04nUL8EGdfNQ4QIIxmo+DQxcTcnC4RjOh7QOmNmjK dxZQn90O0friMr27Q72FvFeqSAO8xu8dauYHEsnn1FmoFqL5zfwzLXq5fdSF7IdbyQjOsOyI dlk3XjakCLgn1h4lKb3rhkF+xsfU9ZqjOOCri+raRoFwGtc8WSJsD5bd1vTCCmvdXbtrKCqY 7fK/1FJvH3EpDarLbrrOwE0EWviAUAEIANhFdCBVIHCRKc580sUYSmo4C1Jj/wiZFK10YqUa 0dD6nlxB9nRdfk/CTmw1QTd96F8G13yLwVIRMNrlrABw1vDqs1LAk1MXct3oVR5MR8NXXl37 2H+VU7UpYkLFSBCdC2bQ91dInQ53xgIVqmzLmwbRdrY9SOj9j8vkZVNaTA+AeIPM3FlPh+B9 /baS5HfXP5E3pml+kMETVuNi/PrQ4y+KVKIH/P7cHjDo/SwzllU6hNpYqVsQh9LkxI/BvJEj CwshoI8Z4jBQ6YyS7txEwWTHrwPhzVkvNERm09m8rtBW3ql3UVd//jy9zFGN5jrPdW1YMaVC xt2g3BJlnSCczYEAEQEAAcLAfAQYAQoAJgIbDBYhBFNCdm1t64Tl0+Pc9qHQwdMFhdFYBQJa +I7ABQkDwnVwAAoJEKHQwdMFhdFYJ1EH/09WdEgY/GHXqRfdU00J7x9tVErshLFgiF/Hdsa1 KhnVZ8JSEn5ZUt0ik2UCXRYakLRBGKykYVAx6z7eUptDQYrIg/pS3EWo7+7IuF4/P2WP4BY7 e0a62mL+Q2G9QY0s7GOGBLaueYw5Jxrn5gaWp54ZyxRZZbbddkmvsVYGTDpd4PMzI0JIjzLX rMNQzA8vTZTwdlpWwVUJZMzRzIn6SBIqnPnJGSWr2Gm5fzbL/5GzBRk4s3SJZTdhDC+pffyl AtyMNDlgfaZ4Hu493F+/urL+MqbuuQf1zG+If+B717OA9jVtByCFrTwOdH44z0ibNiRybfal ZCO/6zTTS28kXCk= Organization: The FreeBSD Project Message-ID: Date: Mon, 3 Dec 2018 18:57:20 +0100 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:60.0) Gecko/20100101 Thunderbird/60.3.1 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="QP1FNOW1PL8O9BwwL6vtJuIT5CXecrPO9" X-Null-Tag: 435d73d9795413b3d9014b976c91a196 X-Rspamd-Queue-Id: BC16A8CE34 X-Spamd-Result: default: False [-1.30 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-0.61)[-0.610,0]; NEURAL_HAM_SHORT(-0.15)[-0.147,0]; ASN(0.00)[asn:20647, ipnet:91.233.84.0/22, country:DE]; NEURAL_HAM_LONG(-0.54)[-0.539,0] X-Rspamd-Server: mx1.freebsd.org 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: Mon, 03 Dec 2018 17:57:24 -0000 This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --QP1FNOW1PL8O9BwwL6vtJuIT5CXecrPO9 Content-Type: multipart/mixed; boundary="SFaD9LH97nTCkDMJxWXWCGqzc9QnoJ6tI"; protected-headers="v1" From: Benedict Reuschling To: Dirk Schroetter , freebsd-doc@FreeBSD.org Message-ID: Subject: Re: Options, devices, hints - Documentation work needed ? References: In-Reply-To: --SFaD9LH97nTCkDMJxWXWCGqzc9QnoJ6tI Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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 appropria= te) - 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= =2E Thanks! Cheers, Benedict Am 03.12.18 um 17:52 schrieb Dirk Schroetter: > Hello there, >=20 > 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. >=20 > So I did fire up the editor and managed to get a python script running = that looks at: >=20 > * The =E2=80=9Aoptions=E2=80=98 files under /usr/src > * The =E2=80=9ANOTES=E2=80=98 files > * The manual pages >=20 > all this being dumped into a table and cross-referenced. >=20 > 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 mention= ed on a man page (e.g. ACPI_MAX_TAKS or ADA_TEST_FAILURE) >=20 > 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: >=20 > 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. >=20 > It may be that this is a fool=E2=80=99s errand and much to big for a si= ngle person, but I would volunteer to at least get it started, if you fol= ks think that there is any merit to it. >=20 > So that would be my proposal and I would love to hear back from you. >=20 > Best Regards, >=20 > /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 --SFaD9LH97nTCkDMJxWXWCGqzc9QnoJ6tI-- --QP1FNOW1PL8O9BwwL6vtJuIT5CXecrPO9 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- iQEzBAEBCgAdFiEEwXonQDvNfP/33IoBVXQ7/QHhjTUFAlwFboAACgkQVXQ7/QHh jTVgEAf/TnC02kY+P1qYForeD2Aae19ToT4R/4h+TQ+xAWCHqJjoUj3WEc4Ua0UI QTy75ehqNsvxKJxLZYp0KPS3KoXxmKw+e9cGym27xKORAc3aF8iaX5DrQpgOCg0S LZuYnESsg+KHiFvvGkalpLaGPGAymyr2ISsZ4scCaV4xNr5ALC5a37WeHu/1QXIz 20bIgNcQEtjauyB76vJ7//4EXiZa7KgJKersMN+xv1JHWpUiPsHHj8mjFlC6FzBu 7EYZ2C6pGwVLBqOf3kEFOlJoNm3CwJN1mqoTBiXAnfDPLTbWe4tVdGDabka4Wr/x DgV1NmOsO6O2M68L+T7TYuMIZ3E6gg== =khO4 -----END PGP SIGNATURE----- --QP1FNOW1PL8O9BwwL6vtJuIT5CXecrPO9--