Re: [Bug] Apropos - Xr Child of Nd Rendering

["Alexander Ziaee" <concussious@runbox.com>]

Hello,

On 2024-09-13 16:58 -04:00 EDT, "Alexander Ziaee" <concussious@runbox.com> wrote:
> On 2024-09-13 11:49 -04:00 EDT, "Ingo Schwarze" <schwarze@usta.de> 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 = 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