discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Yuri Pankov <yuripv@gmx.com>
Cc: discuss@mandoc.bsd.lv
Subject: Re: mandoc-1.14.2 released
Date: Sat, 29 Jul 2017 19:38:58 +0200	[thread overview]
Message-ID: <20170729173858.GH24945@athene.usta.de> (raw)
In-Reply-To: <de0c0c4f-3200-3efc-86c0-e9554ee3ced8@gmx.com>

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.


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

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

  reply	other threads:[~2017-07-29 17:39 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 [this message]
2017-07-29 20:09         ` Yuri Pankov
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=20170729173858.GH24945@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mandoc.bsd.lv \
    --cc=yuripv@gmx.com \
    --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).