From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 292ef97a for ; Sat, 29 Jul 2017 12:39:02 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1dbVhc-0000iH-Jk; Sat, 29 Jul 2017 19:39:01 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1dbVha-0004tP-BS; Sat, 29 Jul 2017 19:38:58 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1dbVha-0003dY-8G; Sat, 29 Jul 2017 19:38:58 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 3ac86056; Sat, 29 Jul 2017 19:38:58 +0200 (CEST) Date: Sat, 29 Jul 2017 19:38:58 +0200 From: Ingo Schwarze To: Yuri Pankov Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc-1.14.2 released Message-ID: <20170729173858.GH24945@athene.usta.de> References: <20170728181244.GD58985@athene.usta.de> <69d1d7f2-ce86-62e1-7623-e1a4c05f6f4d@gmx.com> <20170729142827.GF24945@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.8.0 (2017-02-23) 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