From: Ingo Schwarze <email@example.com> To: Yuri Pankov <firstname.lastname@example.org> Cc: email@example.com 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: <firstname.lastname@example.org> 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 email@example.com
next prev parent 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 \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --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).