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

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

Hello,

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:
>
>> 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 stronger terms.

+1...ish. More defined spec makes more consistency and less room for arguments, but I don't like repetative verbose doc either. "one line about what it does" does seem pretty obvious, but I still do sometimes end up feeling like 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 = 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 to submit these recommendations on the freebsd github, and set you as the author 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