[Bug] Apropos - Xr Child of Nd Rendering

[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

Apropos NAME limitations (was: [Bug] Apropos - Xr Child of Nd Rendering)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3166 bytes --]

Hi Ingo,

On Fri, Sep 13, 2024 at 05:49:49PM GMT, Ingo Schwarze wrote:
>   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.

Do you have similar limitations for the NAME section in man(7)?  I'm
wondering if some of the pages in the Linux man-pages would cause
problems.

(I'm not maintaining them at the moment[1], but I should have a look at
 this in case I come back to the project.)

[1]  <https://lore.kernel.org/linux-man/CACKs7VB_GEt_u463R4JvWveghBBscQeqaWtKrMmxNSQ2mn+-VA@mail.gmail.com/T/#t>


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Apropos NAME limitations (was: [Bug] Apropos - Xr Child of Nd Rendering)

[Ingo Schwarze]

Hello Alex,

Alejandro Colomar wrote on Fri, Sep 13, 2024 at 08:48:02PM +0200:
> On Fri, Sep 13, 2024 at 05:49:49PM GMT, Ingo Schwarze wrote:

>> .Sh NAME
>> .Nm name0 ,
>> .Nm name1 ,
>> .Nm name2
>> .Nd a one line description

> Do you have similar limitations for the NAME section in man(7)?

Similar limitations?

The mdoc(7) and man(7) languages are rather dissimilar in this respect
in the first place because a man(7) NAME section typically does not
contain any macros at all, and also because the man(7) language does
not generally support nesting of macros, not even outside the NMAE
section.  The exceptions where man(7) does support a very limited
amount of nesting are rare.

Consider this example to understand the typical case:

  .TH getent 1 (date) "Linux man-pages (unreleased)"
  .SH NAME
  getent \- get entries from Name Service Switch libraries
  .SH SYNOPSIS

> I'm wondering if some of the pages in the Linux man-pages would cause
> problems.

A very brief look into the linux-man-pages git repo gives me the
impression that what's in there is generally just fine.  That includes
pages like ioctl_eventpoll(2) where the NAME section is spread out
across multiple short input lines.

The command "makewhatis -p" (picky mode) form the mandoc toolbox
does find a few mismatches that look suspicious (not sure all of them
are really wrong), but nothing very alarming:

man2/getcwd.2: Section "3" manual in 2 directory
man2/mq_notify.2: Section "3" manual in 2 directory
man2/mq_open.2: Section "3" manual in 2 directory
man2/mq_unlink.2: Section "3" manual in 2 directory
man2const/PR_GET_SECCOMP.2const: Section "2" manual in 2const directory
man2const/PR_MPX_ENABLE_MANAGEMENT.2const: Section "2" manual in 2const directory
man2const/PR_MPX_DISABLE_MANAGEMENT.2const: Section "2" manual in 2const directory
man2const/PR_TASK_PERF_EVENTS_DISABLE.2const: Section "2" manual in 2const directory
man2/riscv_flush_icache.2: Section "3" manual in 2 directory
man2/mq_timedreceive.2: Section "3" manual in 2 directory
man2/mq_timedsend.2: Section "3" manual in 2 directory
man3/sigstack.3: Section "2" manual in 3 directory
man3/vlimit.3: Section "2" manual in 3 directory
man3/vtimes.3: Section "2" manual in 3 directory
man3const/PA_WSTRING.3const: Section "3head" manual in 3const directory
man3const/PA_WCHAR.3const: Section "3head" manual in 3const directory
man3const/PA_STRING.3const: Section "3head" manual in 3const directory
man3const/PA_POINTER.3const: Section "3head" manual in 3const directory
man3const/PA_LAST.3const: Section "3head" manual in 3const directory
man3const/PA_INT.3const: Section "3head" manual in 3const directory
man3const/PA_FLOAT.3const: Section "3head" manual in 3const directory
man3const/PA_FLAG_SHORT.3const: Section "3head" manual in 3const directory
man3const/PA_FLAG_PTR.3const: Section "3head" manual in 3const directory
man3const/PA_FLAG_LONG_LONG.3const: Section "3head" manual in 3const directory
man3const/PA_FLAG_LONG_DOUBLE.3const: Section "3head" manual in 3const directory
man3const/PA_FLAG_LONG.3const: Section "3head" manual in 3const directory
man3const/PA_DOUBLE.3const: Section "3head" manual in 3const directory
man3const/PA_CHAR.3const: Section "3head" manual in 3const directory
man3/register_printf_type.3: Section "3head" manual in 3 directory
man3/register_printf_specifier.3: Section "3head" manual in 3 directory
man3/register_printf_modifier.3: Section "3head" manual in 3 directory
man4/console_ioctl.4: Section "2" manual in 4 directory
man4/tty_ioctl.4: Section "2" manual in 4 directory
man3/S_ISSOCK.3: Section "7" manual in 3 directory
man3/S_ISREG.3: Section "7" manual in 3 directory
man3/S_ISLNK.3: Section "7" manual in 3 directory
man3/S_ISFIFO.3: Section "7" manual in 3 directory
man3/S_ISDIR.3: Section "7" manual in 3 directory
man3/S_ISCHR.3: Section "7" manual in 3 directory
man3/S_ISBLK.3: Section "7" manual in 3 directory
man7/man.7: No one-line description, using filename "man"
man3/queue.3: Section "7" manual in 3 directory
man3type/sigset_t.3type: Section "7" manual in 3type directory
man3type/siginfo_t.3type: Section "7" manual in 3type directory

These seem mostly caused by use of .so, which is fragile anyway,
so maybe this isn't such a big deal.

A very quick and dirty perl(1) script i just wrote to find macros
in the NAME sections in linux-man-pages came up with exactly
one instance, in hosts.equiv(5) - btw., is hosts.equiv(5) really
still supported in Linux?  It's so horribly insecure that the whole
mechanism was removed from OpenBSD many years ago.

  .SH NAME
  hosts.equiv \- list of hosts and users that are granted "trusted"
  .B r
  command access to your system

I wouldn't call that "great wording", but makewhatis(8) doesn't
choke on it:

   $ makewhatis -DDt man/man5/hosts.equiv.5
  man/man5/hosts.equiv.5: Adding name hosts.equiv, bits=0x6
  man/man5/hosts.equiv.5: Adding name hosts.equiv, bits=0x8
  man/man5/hosts.equiv.5: Adding name hosts.equiv, bits=0x10
  hosts.equiv(5) - list of hosts and users that are granted "trusted" r command access to your system

   $ man -k -M man hosts
  hosts(5) - static table lookup for hostnames
  hosts.equiv(5) - list of hosts and users that are granted "trusted" r command access to your system

Of course, the letter "r" will not be bold in apropos(1) output, but
that's not the worst downside of that particular one-line description.

So, i think your are almost completely fine in this respect, Alex.

Is the first sentence of

  https://www.kernel.org/doc/man-pages/maintaining.html

outdated?  It says:

  The current man-pages maintainer is (since 2004) Michael Kerrisk
  (mtk.manpages@gmail.com; blog); starting in 2020, Alejandro Colomar
  (alx.manpages@gmail.com) has joined as comaintainer. 

If that is outdated and there is currently a shortage of maintainers,
that's a pity.  :-(

All the best for you,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

Re: Apropos NAME limitations (was: [Bug] Apropos - Xr Child of Nd Rendering)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 9787 bytes --]

On Fri, Sep 13, 2024 at 10:23:48PM GMT, Ingo Schwarze wrote:
> Hello Alex,

Hello Ingo,

> Alejandro Colomar wrote on Fri, Sep 13, 2024 at 08:48:02PM +0200:
> > On Fri, Sep 13, 2024 at 05:49:49PM GMT, Ingo Schwarze wrote:
> 
> >> .Sh NAME
> >> .Nm name0 ,
> >> .Nm name1 ,
> >> .Nm name2
> >> .Nd a one line description
> 
> > Do you have similar limitations for the NAME section in man(7)?
> 
> Similar limitations?
> 
> The mdoc(7) and man(7) languages are rather dissimilar in this respect
> in the first place because a man(7) NAME section typically does not
> contain any macros at all, and also because the man(7) language does
> not generally support nesting of macros, not even outside the NMAE
> section.  The exceptions where man(7) does support a very limited
> amount of nesting are rare.
> 
> Consider this example to understand the typical case:
> 
>   .TH getent 1 (date) "Linux man-pages (unreleased)"
>   .SH NAME
>   getent \- get entries from Name Service Switch libraries
>   .SH SYNOPSIS
> 
> > I'm wondering if some of the pages in the Linux man-pages would cause
> > problems.
> 
> A very brief look into the linux-man-pages git repo gives me the
> impression that what's in there is generally just fine.  That includes
> pages like ioctl_eventpoll(2) where the NAME section is spread out
> across multiple short input lines.

It's good to know that spreading into several lines is ok.  That was one
of the things I was worried about.

> The command "makewhatis -p" (picky mode) form the mandoc toolbox
> does find a few mismatches that look suspicious (not sure all of them
> are really wrong), but nothing very alarming:
> 
> man2/getcwd.2: Section "3" manual in 2 directory

Nah, that's fine.

$ head man2/getcwd.2 
.so man3/getcwd.3
.\" Because getcwd(3) is layered on a system call of the same name

> man2/mq_notify.2: Section "3" manual in 2 directory
> man2/mq_open.2: Section "3" manual in 2 directory
> man2/mq_unlink.2: Section "3" manual in 2 directory
> man2const/PR_GET_SECCOMP.2const: Section "2" manual in 2const directory
> man2const/PR_MPX_ENABLE_MANAGEMENT.2const: Section "2" manual in 2const directory
> man2const/PR_MPX_DISABLE_MANAGEMENT.2const: Section "2" manual in 2const directory
> man2const/PR_TASK_PERF_EVENTS_DISABLE.2const: Section "2" manual in 2const directory
> man2/riscv_flush_icache.2: Section "3" manual in 2 directory
> man2/mq_timedreceive.2: Section "3" manual in 2 directory
> man2/mq_timedsend.2: Section "3" manual in 2 directory
> man3/sigstack.3: Section "2" manual in 3 directory
> man3/vlimit.3: Section "2" manual in 3 directory
> man3/vtimes.3: Section "2" manual in 3 directory
> man3const/PA_WSTRING.3const: Section "3head" manual in 3const directory
> man3const/PA_WCHAR.3const: Section "3head" manual in 3const directory
> man3const/PA_STRING.3const: Section "3head" manual in 3const directory
> man3const/PA_POINTER.3const: Section "3head" manual in 3const directory
> man3const/PA_LAST.3const: Section "3head" manual in 3const directory
> man3const/PA_INT.3const: Section "3head" manual in 3const directory
> man3const/PA_FLOAT.3const: Section "3head" manual in 3const directory
> man3const/PA_FLAG_SHORT.3const: Section "3head" manual in 3const directory
> man3const/PA_FLAG_PTR.3const: Section "3head" manual in 3const directory
> man3const/PA_FLAG_LONG_LONG.3const: Section "3head" manual in 3const directory
> man3const/PA_FLAG_LONG_DOUBLE.3const: Section "3head" manual in 3const directory
> man3const/PA_FLAG_LONG.3const: Section "3head" manual in 3const directory
> man3const/PA_DOUBLE.3const: Section "3head" manual in 3const directory
> man3const/PA_CHAR.3const: Section "3head" manual in 3const directory
> man3/register_printf_type.3: Section "3head" manual in 3 directory
> man3/register_printf_specifier.3: Section "3head" manual in 3 directory
> man3/register_printf_modifier.3: Section "3head" manual in 3 directory
> man4/console_ioctl.4: Section "2" manual in 4 directory
> man4/tty_ioctl.4: Section "2" manual in 4 directory
> man3/S_ISSOCK.3: Section "7" manual in 3 directory
> man3/S_ISREG.3: Section "7" manual in 3 directory
> man3/S_ISLNK.3: Section "7" manual in 3 directory
> man3/S_ISFIFO.3: Section "7" manual in 3 directory
> man3/S_ISDIR.3: Section "7" manual in 3 directory
> man3/S_ISCHR.3: Section "7" manual in 3 directory
> man3/S_ISBLK.3: Section "7" manual in 3 directory
> man7/man.7: No one-line description, using filename "man"
> man3/queue.3: Section "7" manual in 3 directory
> man3type/sigset_t.3type: Section "7" manual in 3type directory
> man3type/siginfo_t.3type: Section "7" manual in 3type directory
> 
> These seem mostly caused by use of .so, which is fragile anyway,
> so maybe this isn't such a big deal.
> 
> A very quick and dirty perl(1) script i just wrote to find macros
> in the NAME sections in linux-man-pages came up with exactly
> one instance,

	$ find -type f \
		| xargs sed -n '/^\.SH NAME/,/^\.SH/p' \
		| grep '^\.[A-RT-Z]' -C2;
	.SH NAME
	hosts.equiv \- list of hosts and users that are granted "trusted"
	.B r
	command access to your system
	.SH DESCRIPTION

Yup, this is the kind of corner case I had in mind.

> in hosts.equiv(5) - btw., is hosts.equiv(5) really
> still supported in Linux?

I don't know.  I removed support for rlogind(8) in shadow utils
recently:

<https://github.com/shadow-maint/shadow/commit/ca046af5d976e9eb835772997ffd594b9ee979aa>

	commit ca046af5d976e9eb835772997ffd594b9ee979aa
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Sat May 18 01:57:40 2024 +0200

	    Remove support for rlogind in login(1), that is, remove the '-r' flag
	    
	    The "quick hack" finally disappeared.  Probably nobody noticed.  ;)
	    (See the changes in <configure.ac> for the context of this pun.)
	    
	    Probably everybody uses SSH these days for remote login.  Let's remove
	    this insecure method.
	    
	    Closes: <https://github.com/shadow-maint/shadow/issues/992>
	    Reviewed-by: dkwo <nicolopiazzalunga@gmail.com>
	    Reviewed-by: Iker Pedrosa <ipedrosa@redhat.com>
	    Cc: "Serge E. Hallyn" <serge@hallyn.com>
	    Cc: Michael Vetter <jubalh@iodoru.org>
	    Cc: Sam James <sam@gentoo.org>
	    Cc: Benedikt Brinkmann <datacobra@thinkbot.de>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

But that's the closest I've been to that.  I don't know if it's in use
by anyone.

> It's so horribly insecure that the whole
> mechanism was removed from OpenBSD many years ago.
> 
>   .SH NAME
>   hosts.equiv \- list of hosts and users that are granted "trusted"
>   .B r
>   command access to your system
> 
> I wouldn't call that "great wording", but makewhatis(8) doesn't
> choke on it:
> 
>    $ makewhatis -DDt man/man5/hosts.equiv.5
>   man/man5/hosts.equiv.5: Adding name hosts.equiv, bits=0x6
>   man/man5/hosts.equiv.5: Adding name hosts.equiv, bits=0x8
>   man/man5/hosts.equiv.5: Adding name hosts.equiv, bits=0x10
>   hosts.equiv(5) - list of hosts and users that are granted "trusted" r command access to your system
> 
>    $ man -k -M man hosts
>   hosts(5) - static table lookup for hostnames
>   hosts.equiv(5) - list of hosts and users that are granted "trusted" r command access to your system
> 
> Of course, the letter "r" will not be bold in apropos(1) output, but
> that's not the worst downside of that particular one-line description.
> 
> So, i think your are almost completely fine in this respect, Alex.

Yup, that's good.  :)

> Is the first sentence of
> 
>   https://www.kernel.org/doc/man-pages/maintaining.html
> 
> outdated?  It says:

Very much.

> 
>   The current man-pages maintainer is (since 2004) Michael Kerrisk
>   (mtk.manpages@gmail.com; blog); starting in 2020, Alejandro Colomar
>   (alx.manpages@gmail.com) has joined as comaintainer. 

It was outdated 3 years ago.  I moved most of the website to the git
repository: <./CONTRIBUTING>, <./CONTRIBUTING.d/*>, <./README>,
<./RELEASE>, <./INSTALL>, <./LICENSES/*>.  But I didn't find time to
move that one page, and it remains there.

The README says:

	History
	   Tarballs
	       Tarballs of man-pages-1.* releases are available at:
	       <https://www.win.tue.nl/~aeb/ftpdocs/linux-local/manpages.archive/>

	   Maintainers
	       Alejandro Colomar <alx@kernel.org> <https://www.alejandro-colomar.es/>
		     2020 - present (5.09 - HEAD)
	       Michael Kerrisk <mtk.manpages@gmail.com> <https://man7.org/>
		     2004 - 2021    (2.00 - 5.13)
	       Andries Brouwer <aeb@cwi.nl> <https://www.win.tue.nl/~aeb>
		     1995 - 2004    (1.6  - 1.70)
	       Rik Faith <https://www.cs.unc.edu/~faith/>
		     1993 - 1995    (1.0  - 1.5)

The rationale was that for 1 year I was the only maintainer of the
project and still didn't have access to kernel.org, so the project lived
in a small server at my home.  I couldn't update the website for a year,
and the only source of truth was my git repository.  I've decommissioned
most of the website when I've had access to it, since it didn't make
sense to update it when everything was already in git.  I just added
some links to the files in the repo.

> If that is outdated and there is currently a shortage of maintainers,
> that's a pity.  :-(

There's shortage of maintainers, but because there's shortage of food in
my table.  If companies --cough, Red Hat, cough-- scratch their pockets,
I'd be more than happy to come back (and if they scratch enough, maybe I
get Michael to come back too).

> 
> All the best for you,

Thanks!

>   Ingo

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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