From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,HEADER_FROM_DIFFERENT_DOMAINS, UNPARSEABLE_RELAY autolearn=no autolearn_force=no version=3.4.4 Received: from mandoc.bsd.lv (bsd.lv [66.111.2.12]) by inbox.vuxu.org (Postfix) with ESMTP id D59292F752 for ; Sun, 15 Sep 2024 01:45:39 +0200 (CEST) Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 007b0d5b for ; Sat, 14 Sep 2024 23:45:37 +0000 (UTC) Received: from mailtransmit04.runbox.com (mailtransmit04.runbox.com [185.226.149.37]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id cb74d333 for ; Sat, 14 Sep 2024 23:45:37 +0000 (UTC) Received: from mailtransmit03.runbox ([10.9.9.163] helo=aibo.runbox.com) by mailtransmit04.runbox.com with esmtps (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.93) (envelope-from ) id 1spcSO-009Jun-4N for tech@mandoc.bsd.lv; Sun, 15 Sep 2024 01:45:36 +0200 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=runbox.com; s=selector1; h=Message-Id:Date:Subject:To:From:MIME-Version: Content-Transfer-Encoding:Content-Type; bh=+mMcWedJ2NA1Hx5ytrNCB4jc2EjZ2cH2kLTa6Aj3k/k=; b=HzSYYqhD8FxtI8cChTi/aPHCre J4m1G19trdXszwxx29Sng56mWIzIh4/s/tIzh4DIUMA9n95jpNCyyc9DvcO8+m89j26AX4jqnlti7 0sNAsZaMG1m36G+PRZ3TMkz3uYJgM+ppjVviDwhVJXK7Wpb2sbZbdT1cm0hPPcchgIj6GK68oodkH VuAVZmJaHrOpgbCL4nvZJVPuS+bycziTDaB2JuF/Q69XAfp2jBJpeKHvrAW1IEcq43pwotDak00AF TOB2jldPIQaqxXkpaAOdtELmRMnQX4AI9J/VlO0zv7KKdAIEJaLMvj35+MO0nNmM9Byym507SQFjW 37SbMp7A==; Received: from [10.9.9.128] (helo=rmmprod06.runbox) by mailtransmit03.runbox with esmtp (Exim 4.86_2) (envelope-from ) id 1spcSN-0000SD-Ig for tech@mandoc.bsd.lv; Sun, 15 Sep 2024 01:45:35 +0200 Received: from mail by rmmprod06.runbox with local (Exim 4.86_2) (envelope-from ) id 1spcSN-0000PH-Hj for tech@mandoc.bsd.lv; Sun, 15 Sep 2024 01:45:35 +0200 Content-Type: text/plain; charset="utf-8" Content-Disposition: inline Content-Transfer-Encoding: quoted-printable X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Received: from [Authenticated alias (960610)] by runbox.com with http (RMM6); for ; Sat, 14 Sep 2024 23:45:35 GMT From: "Alexander Ziaee" To: "tech" Subject: Re: [Bug] Apropos - Xr Child of Nd Rendering Date: Sat, 14 Sep 2024 23:45:35 +0000 (UTC) X-RMM-Aliasid: 960610 X-Mailer: RMM6 Message-Id: Hello, On 2024-09-13 16:58 -04:00 EDT, "Alexander Ziaee" = wrote: > On 2024-09-13 11:49 -04:00 EDT, "Ingo Schwarze" wrote: >> Alexander Ziaee wrote on Mon, Sep 02, 2024 at 05:01:57PM +0000: >>> [0] https://man-dev.freebsd.org/jail.conf >> >> I recommend making this >> >> .Sh NAME >> .Nm jail.conf >> .Nd configuration file for system jails >> .Sh DESCRIPTION >> The >> .Nm >> file consists of one or more jail definitions statements >> for use by the >> .Xr jail 8 >> management program. >> >> The phrase "and parameter or variable statements within those jail >> definitions" is misplaced in the first sentence. Not only is the >> first sentence supposed to be as clear and concise as possible >> without going down any rabbit holes; this phrase also requires >> the basic syntax of a definition statement to be established first. >> >> The second sentence is also quite bad: "looks something like a C >> compound statement" is just vague. A manual page needs to define >> syntax and semantics with precision, not wave its hands around >> hoping the reader might guess what the actual rules are. >> >> Maybe something like >> >> A jail definition statement consists of a single word, the >> name of the jail, an opening curly brace, a list of at least >> (insert the minimum number here) parameter assignments, >> and a closing curly brace. >> A parameter assignment consists of a single word, the parameter >> name, an equal sign, a value enclosed in double quotes, >> and a terminating semicolon. >> >> For people who speak C, seeing the similarity is trivial; for >> people who don't, mentioning it is nothing but a distraction, >> so do not mention it. Also, saying "similar" in a manual page >> is very bad unless you exhaustive explain the commonalities >> and differences - but then the text usually becomes excessively >> verbose. >> >> Alternatively, the second sentence could simply be: >> >> The syntax of a jail definitions statement is as follows: >> .Bd -unfilled >> .Ar jail_name Cm \&{ >> .Bd -unfilled -offset indent -compact >> .Ar parameter_name Cm =3D Qq Ar value ; >> \&... >> .Ed >> .Cm \&} >> .Ed >> >> I tend to prefer a through description though, optionally >> followed by a syntax display - but visualization of the >> syntax can also wait for the EXAMPLES section if desired. >> >> The rest of the first paragraph also looks disorganized. >> The sentence "Each jail is required to have a name at the front >> of its definition." is a gratuitious repetition of what was >> already said. In general, this manual seems of low quality and >> in dire need of a lot of basic editorial work. Here is the PR [0] in case you are interested sir, thank you again. [0] : https://github.com/freebsd/freebsd-src/pull/1422 Best, Alex= -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv