discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Yuri Pankov <yuripv@gmx.com>
To: discuss@mandoc.bsd.lv
Subject: Re: mandoc-1.14.2 released
Date: Sat, 29 Jul 2017 23:09:50 +0300	[thread overview]
Message-ID: <30365e38-be1c-0d36-99c8-b3a50804ed21@gmx.com> (raw)
In-Reply-To: <20170729173858.GH24945@athene.usta.de>

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

  reply	other threads:[~2017-07-29 20:15 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-07-28 18:12 Ingo Schwarze
2017-07-29 13:35 ` Yuri Pankov
2017-07-29 14:28   ` Ingo Schwarze
2017-07-29 15:12     ` Yuri Pankov
2017-07-29 17:38       ` Ingo Schwarze
2017-07-29 20:09         ` Yuri Pankov [this message]
2017-08-02 13:50           ` Ingo Schwarze

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=30365e38-be1c-0d36-99c8-b3a50804ed21@gmx.com \
    --to=yuripv@gmx.com \
    --cc=discuss@mandoc.bsd.lv \
    --subject='Re: mandoc-1.14.2 released' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).