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

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

[Alexander Ziaee]

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

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

[Alexander Ziaee]

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

[Bug] Apropos - Xr Child of Nd Rendering

[Alexander Ziaee]

Hello,

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

Would anyone be willing to share a hint?

[0] https://man-dev.freebsd.org/jail.conf

Thanks,
Alex--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Ingo Schwarze]

Hello Alexander,

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".

> Would anyone be willing to share a hint?

The mdoc(7) manual page says:

  MANUAL STRUCTURE
  [...]
           NAME
           The name(s) and a one line description of the documented material.
           The syntax for this as follows:

                 .Nm name0 ,
                 .Nm name1 ,
                 .Nm name2
                 .Nd a one line description
  [...]
  MACRO REFERENCE
  [...]
     Nd line
          A one line description of the manual's content.  This is the
          mandatory last macro of the NAME section and not appropriate
          for other sections.

          Examples:
                .Nd mdoc language reference
                .Nd format and display UNIX manuals

          The Nd macro technically accepts child macros and terminates with
          a subsequent Sh invocation.  Do not assume this behaviour: some
          whatis(1) database generators are not smart enough to parse more
          than the line arguments and will display macros verbatim.

So the behaviour is more or less documented to be undefined for your
input.  Maybe the manual should discourage child macros below .Nd in
even stronger terms.

The decision to not attempt formatting in the apropos(1) output module
but simply print the one-line strings verbatim is deliberate.  There are
two reasons for this decision.

First, simplicity and maintainability.  The database lookup code in
apropos(1) is already quite complex.  Hooking into the full mdoc(7)
and man(7) formatting modules, which are even more complex, would
send complexity through the roof.  In general, for a small UNIX-style
program, its a good idea to have no more than one source of complexity
to not risk losing track of what is going on.  Besides, fancy
formatting is really beside the point of the apropos(1) program,
it's all about providing a simple, straighforward index.

Second point, robustness.  A small number of crazy piople do all
kinds of crazy stuff below the .Nd macro.  In extreme cases, i
have even seen paragraph breaks and the like in there.  If apropos(1)
would try to honour such madness in formatting, that might utterly
mess up the formatting of the apropos(1) output, which is supposed
to be a simple list of one-line entries.  Where to draw the line?
Which macros should be honoured here, which shouldn't?  Even if you
make such set of a decisions, it is very hard to implement because
the renderes are recursive and you will have a hard time passing in
information from the outside where to stop processing at which lower
level.

On top of all that, i believe including an .Xr reference in a
document title is bad typographical and bad editorial style.
Have you ever seen a title on the cover of a printed book that
included a hyperlink to a website, or a reference to another printed
book?  I think even for the main <h1> title of a webpage, it
is very rare to include a hyperlink to another page.

The reason is that the job of the main title of a document is to
describe the topic of the document as concisely as possible,
requiring as little context as possible.  Pointing to additional,
external content is then a job for the content of the document,
but not for the title.

> [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.

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.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv