From owner-freebsd-doc@freebsd.org Wed Jan 9 16:22:03 2019 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 517E7148608D for ; Wed, 9 Jan 2019 16:22:03 +0000 (UTC) (envelope-from dschroetter@gmail.com) Received: from mail-wm1-x32f.google.com (mail-wm1-x32f.google.com [IPv6:2a00:1450:4864:20::32f]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority G3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4BAB98F32C; Wed, 9 Jan 2019 16:22:02 +0000 (UTC) (envelope-from dschroetter@gmail.com) Received: by mail-wm1-x32f.google.com with SMTP id y139so8205523wmc.5; Wed, 09 Jan 2019 08:22:02 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=H7fIgxhVcXtmZBYT5rJ6bnXsbnhn6sDlAQOR317rKa0=; b=SWYTMC7boH8kjOnAjd+sifj5WBwqoM8mYZD3xXqDt/Eupf+yuCiV4reEomB3PjTCG7 sb20hLnHGVCVUUHreTYlhaO5oJQBQeEgBldHq2proz6kVWFKNv28OUifl1ozJVAl90Qb usR5+xk7rScvGA52m4eeK9wc5R8kFRD8j7ev52jm7omoRvjEjZu2ZSmUH9aufBrrXbEM tUEPquXu7iN5Srjw0+ES/AnbLgUE/aoGfv86RYrxSe4WGdkD/sCU+bDBmzUDQpiTTXzk 77Sb7pvVeNqe5i9/559aC9BQpBQOK3Y8yoCFMf748QTgIh/WIO4qiCpsyyDHkKOMg8TK KTfQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=H7fIgxhVcXtmZBYT5rJ6bnXsbnhn6sDlAQOR317rKa0=; b=dYAjl7VIGO6poMTGHCeOCuwm5p0tWlFuHJEm19OKyBDoKz+cRe+snoR79u4w8pQ/N8 PXCc95PgVT0pBwszY+jDRGf1ToRSdGocLl+yNtwjzY1Wnh+VxHomtaHRga/LFfaDMiJQ TpkNHc4+T1x6ChTRClr2BsCQyjZHoEUuW9dKD2WNKGpMN0buDfkVNYuRctTBvrrvyET3 4CZm/6Lpw9meP09xWVF32IWTBEaVLLDQIBl1y2yAT53RMPGTZLB0PI3p2Y1XqeScToTY 33HltauuiPjfAc7VhGamXAFvye/+TUaQIfXDNLZuLIeMauxou7bUZpfNIJok+idbPFqh cZWw== X-Gm-Message-State: AJcUukc+wZdWx3Zcqe/SqwXZnv6ZY57J/3ovegyflwo/3r3JMP1wJN7Z DWNow9uD85CYrvOziCa8QgpjAyoY X-Google-Smtp-Source: ALg8bN50CNsGPiqbPdvxjj6FPO9P5UucTIf1psjO269JBGdH19l32hlPHtoDzTJU0hZmfYTYyUdq3A== X-Received: by 2002:a1c:5892:: with SMTP id m140mr6358268wmb.60.1547050920624; Wed, 09 Jan 2019 08:22:00 -0800 (PST) Received: from [192.168.0.10] (p50973634.dip0.t-ipconnect.de. [80.151.54.52]) by smtp.gmail.com with ESMTPSA id z17sm49508739wrv.2.2019.01.09.08.21.59 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 09 Jan 2019 08:22:00 -0800 (PST) Content-Type: text/plain; charset=utf-8 Mime-Version: 1.0 (Mac OS X Mail 12.0 \(3445.100.39\)) Subject: Re: Options, devices, hints - Documentation work needed ? From: Dirk Schroetter In-Reply-To: Date: Wed, 9 Jan 2019 17:21:58 +0100 Cc: freebsd-doc@FreeBSD.org Content-Transfer-Encoding: quoted-printable Message-Id: <59490F3A-C748-44BE-86BB-8C54B8C469F2@gmail.com> References: To: Benedict Reuschling X-Mailer: Apple Mail (2.3445.100.39) X-Rspamd-Queue-Id: 4BAB98F32C X-Spamd-Bar: ---- Authentication-Results: mx1.freebsd.org; dkim=pass header.d=gmail.com header.s=20161025 header.b=SWYTMC7b; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (mx1.freebsd.org: domain of dschroetter@gmail.com designates 2a00:1450:4864:20::32f as permitted sender) smtp.mailfrom=dschroetter@gmail.com X-Spamd-Result: default: False [-4.86 / 15.00]; RCVD_VIA_SMTP_AUTH(0.00)[]; TO_DN_SOME(0.00)[]; FREEMAIL_FROM(0.00)[gmail.com]; R_SPF_ALLOW(-0.20)[+ip6:2a00:1450:4000::/36]; MV_CASE(0.50)[]; RCVD_COUNT_THREE(0.00)[3]; DKIM_TRACE(0.00)[gmail.com:+]; RCPT_COUNT_TWO(0.00)[2]; DMARC_POLICY_ALLOW(-0.50)[gmail.com,none]; MX_GOOD(-0.01)[cached: alt3.gmail-smtp-in.l.google.com]; NEURAL_HAM_SHORT(-0.92)[-0.916,0]; FROM_EQ_ENVFROM(0.00)[]; RCVD_TLS_LAST(0.00)[]; MIME_TRACE(0.00)[0:+]; FREEMAIL_ENVFROM(0.00)[gmail.com]; ASN(0.00)[asn:15169, ipnet:2a00:1450::/32, country:US]; MID_RHS_MATCH_FROM(0.00)[]; DWL_DNSWL_NONE(0.00)[gmail.com.dwl.dnswl.org : 127.0.5.0]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-1.000,0]; R_DKIM_ALLOW(-0.20)[gmail.com:s=20161025]; FROM_HAS_DN(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; NEURAL_HAM_LONG(-1.00)[-1.000,0]; MIME_GOOD(-0.10)[text/plain]; IP_SCORE(-2.44)[ip: (-8.44), ipnet: 2a00:1450::/32(-1.94), asn: 15169(-1.71), country: US(-0.08)]; SUBJECT_ENDS_QUESTION(1.00)[]; RCVD_IN_DNSWL_NONE(0.00)[f.2.3.0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.0.0.4.6.8.4.0.5.4.1.0.0.a.2.list.dnswl.org : 127.0.5.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: Wed, 09 Jan 2019 16:22:03 -0000 Hello Benedict, really no need to apologise at all - I took some =E2=80=9Edigital = detox=E2=80=9C myself as you can see.=20 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 : >=20 > Hello Dirk, >=20 > sorry to keep you waiting. >=20 > 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. >=20 > 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? >=20 > Regards, > Benedict >=20 >=20 > 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 = sent a few days back and maybe already have a view on how to use that to = the. Maximum benefit of the community. >>=20 >> Best Regards, >>=20 >> /Dirk >>=20 >>> Am 03.12.2018 um 18:57 schrieb Benedict Reuschling = : >>>=20 >>> Hello Dirk, >>>=20 >>> I think this is definitely valueable in multiple ways: >>>=20 >>> - 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 >>>=20 >>> Cross references will help developers understanding how things are >>> interconnected within the kernel and the source tree. >>>=20 >>> 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. >>>=20 >>> 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. >>>=20 >>> Thanks! >>>=20 >>> Cheers, >>> Benedict >>>=20 >>>=20 >>>=20 >>>> 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 = mentioned 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 single person, but I would volunteer to at least get it started, if = you folks 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 >>>=20 >>>=20 >>=20 >=20 >=20