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 6D3AF2EAB4 for ; Fri, 13 Sep 2024 22:58:53 +0200 (CEST) Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 8da81bdb for ; Fri, 13 Sep 2024 20:58:53 +0000 (UTC) Received: from mailtransmit04.runbox.com (mailtransmit04.runbox.com [185.226.149.37]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id b0d186b1 for ; Fri, 13 Sep 2024 20:58:52 +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 1spDNT-006CIO-ST for tech@mandoc.bsd.lv; Fri, 13 Sep 2024 22:58:51 +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=XFrTCNhBZFpQqiHQzTxQt40OuETFWajnNa4xAOgliW8=; b=TO1j0vRDnIZgKMh1Q6q0Lo31hP rG5nTtgdN9TrQO9uL/ZIk6/IYlbSSI8s/1V6PVH+c3Ps4+RUBo+gq6GxYlc/aq/cmptSBRusq9vY5 udXkaIorNhvzPvE9Hg1LM7v7b/Q5DkOQ6ss4UHm0nIO5iXVitWrPs02Hmoy5tLIOYEm9OepcF7ABj gXbNhlZ1CTnS+RVeCbIXM0EfW9EmvLI8bkM8MHjfa9My5PbFtgTlY52c3FyPfcsDfqRBlcEq0GkBk bZmApVWGidlepetIt0eifHZotaZ8Q0pDn6du0RPRSmnMqXoGhKxvzjbVT2lfABUQGDe7mT4xMQIYT G8ojucmQ==; Received: from [10.9.9.129] (helo=rmmprod07.runbox) by mailtransmit03.runbox with esmtp (Exim 4.86_2) (envelope-from ) id 1spDNT-0000gX-CX for tech@mandoc.bsd.lv; Fri, 13 Sep 2024 22:58:51 +0200 Received: from mail by rmmprod07.runbox with local (Exim 4.86_2) (envelope-from ) id 1spDNT-0000Bd-Ba for tech@mandoc.bsd.lv; Fri, 13 Sep 2024 22:58:51 +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 ; Fri, 13 Sep 2024 20:58:51 GMT From: "Alexander Ziaee" To: "tech" Subject: Re: [Bug] Apropos - Xr Child of Nd Rendering Date: Fri, 13 Sep 2024 20:58:51 +0000 (UTC) X-RMM-Aliasid: 960610 X-Mailer: RMM6 Message-Id: Hello, 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: > >> In jail.conf(5) on FreeBSD we have lines like this: >> >> .Nm jail.conf >> .Nd configuration file for >> .Xr jail 8 >> .Sh DESCRIPTION >> >> This works beautifully in man(1) and man.cgi [0], but in apropos >> renders without parenthesis like this: >> >> jail.conf(5) - configuration file for jail 8 > > I classify this as "not a bug - garbage in, garbage out" Okay, sounds reasonable to me. > Maybe the manual should discourage child macros below .Nd in even stronge= r terms. +1...ish. More defined spec makes more consistency and less room for argume= nts, but I don't like repetative verbose doc either. "one line about what i= t does" does seem pretty obvious, but I still do sometimes end up feeling l= ike I'm getting petit-flamed in the discussions. >> [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. Thank you so much for such a detailed explanation and suggestions! I think = these suggestions are a wonderful improvement to the platform! I am going t= o submit these recommendations on the freebsd github, and set you as the au= thor of course. > https://man-dev.freebsd.org/jail.8 also looks defective to me. > For example, the first sentence of the DESCRIPTION ought to provide > a concise definition of the topic to a person who never heard the > NAME of the page before. In this case, in one short sentence, > what is the basic idea of a jail? (With going into any detail, > of course). > > The SYNOPSIS of jail(8) looks incredibly confusing. Even staring > at it for quite some time and comparing it to the option lists below, > it still remains a mystery to me what the defining characteristic > of each of the many SYNOPSIS lines is. I'm not sure what the > problem is: maybe the material is just badly organized into > multiple SYNOPSIS lines, or maybe there should be a table explaining > either relatively early, after the first few introductory sentences, > or maybe after the definition of the fundamental options -cemr, > what the purpose and defining characteristic of each SYNOPSIS line > is? As it stands, it's just looks utterly confusing. Hmm, I'll give that a go too. Thank you! Alex= -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv