Re: mandoc-1.14.2 released

[Yuri Pankov <yuripv@gmx.com>]

On Sat, 29 Jul 2017 19:38:58 +0200, Ingo Schwarze wrote:
> Hi Yuri,
> 
> Yuri Pankov Illumos wrote on Sat, Jul 29, 2017 at 06:12:54PM +0300:
> 
>> There's another issue though which doesn't look entirely correct,
>> sorry, I didn't check the lint, only formatted output previously.
> 
> No problem, nobody can be expected to find everything at once.
> 
>> We have a man page that looks like this (and should stay like that):
>>
>> $ cat foo_bar.1
>> .Dd July 29, 2017
>> .Dt FOO_BAR 1
>> .Os
>> .Sh NAME
>> .Nm foo_bar
>> .Nd baz
>> .Sh SYNOPSIS
>> .Nm foo
>> .Fl F Sy bar
> 
> That should probably be ".Fl F Cm bar", but that's unrelated.
> 
>> .Sh DESCRIPTION
>> baz
>> .Sh SEE ALSO
>> .Xr foo 1
> 
> Oh.  You mean like git-commit(1)?
> 
>> and here's the warning:
>>
>> $ mandoc -Tlint -Wwarning foo_bar.1
>> mandoc: foo_bar.1:13:5: WARNING: cross reference to self: Xr foo 1
>>
>> Shouldn't we look only at the NAME section for this check?
> 
> Very good question.
> 
> My first impulse was to say "your manual page is broken".
> But that is maybe not the right answer.
> 
> We don't have that problem in OpenBSD because we do not build
> tools so large that they can't be described in a single page.
> Not so much out of lack of time to write that much code, but
> more out of pity on the poor users who would have to read all
> that documentation and spend so much time trying to learn using
> such large tools.
> 
> But opinions on good software design and sane limits on complexity
> and bloat aside, documentation tools probably shouldn't make it
> impossible to document seriously bloated software like git(1).  It's
> OK if documentation tools make documentating such bloat seriously
> harder, because maintaining and using such bloated tools is extremely
> difficult anyway.  But it shouldn't be outright impossible.

It's not about bloat.  We have mount(1M) and share(1M), documenting 
generic options, and e.g. mount_nfs(1M) and share_nfs(1M), documenting 
NFS protocol specific ones, along with lots of protocol specific notes. 
Dumping all that in mount(1M) and share(1M) would actually be bloating 
them IMO :-)

For example, share_nfs.1m:

.Dd March 23, 2017
.Dt SHARE_NFS 1M
.Os
.Sh NAME
.Nm share_nfs
.Nd make local NFS file systems available for mounting by remote systems
.Sh SYNOPSIS
.Nm share
.Fl F Cm nfs
.Op Fl d Ar description
.Op Fl o Ar specific_options
.Ar pathname

> That said, the technical problem here is that mandoc(1) uses -
> slightly simplifying the algorithm and not describing priorities -
>   1. the filename(s) of of manual page files
>   2. the .Nm arguments in the NAME section
>   3. the .Nm HEAD arguments in the SYNOPSIS section
> as names of the manual page.  Item 3 is useful because some authors
> neglect putting all the names in the NAME section - even though they
> should.
> 
> Using "foo" as a name of the manual page has many implications:
> 
> Try "man -w foo".  You will probably see both foo(1) and foo_bar(1).
> 
> Try "man -a foo".  You will probably get shown foo(1), foo_bar(1),
> and possibly quite some other pages, too.  Which may actually be
> useful for searching through all these pages at once, inside less(1).
> Such searching is even more important for large than for small tools.
> 
> Try "man -k Nm~'^foo$'".  You will probably see something like
> 
>    foo(1) - top-level description of the foo utility
>    foo(1), foo_bar(1) - baz
> 
> Delete foo.1 from the system and run "makewhatis", then try "man foo".
> You will probably be shown foo_bar(1) or some similar page.
> 
> So this is not just about the warning that may seem annoying at first.
> That warning actually indicates that there are real, deeper issues.
> 
> 
> What can we do?
> 
>   a) Stop harvesting names in the SYNOPSIS section.
>      Instead, more forcefully tell people to fix their NAME sections.
> 
>   b) Somehow provide a way to say, in the SYNOPSIS section,
>      "This name is not topical."
>      In the case of git, you could already do that by saying
>      .Nm "git commit"
>      rather than
>      .Nm git Cm commit
>      in the SYNOPSIS.
> 
>      In your case, with the nasty flag in between, that's less obvious.
>      .Nm "foo \-F bar"
>      seems to be what the page documents, but it sure looks ugly.
> 
>      I'm very hesitant to introduce new syntax just to mark a name
>      as "not topical".
> 
>   c) Not warn about .Xr to names only found in the SYNOPSIS.
>      I'm not enthusiastic because that hides potential problems
>      with the aspects described above even for legitimate use,
>      and it can also hide actual bugs, namely, pages that *do*
>      reference themselves but have an incomplete NAME section.
> 
>   d) Something else?
> 
> Maybe i'm leaning towards a).  It's the simplest to understand for
> users and authors.
> 
> But i'm not really sure yet...

I'd say a) as well, but looking for a solution in the mean time -- this 
is the only one left for the moment :-)

TIA
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv