From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mout.gmx.net (mout.gmx.net [212.227.17.21]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 16092c90 for ; Sat, 29 Jul 2017 15:15:22 -0500 (EST) Received: from [192.168.1.2] ([188.170.202.126]) by mail.gmx.com (mrgmx103 [212.227.17.174]) with ESMTPSA (Nemesis) id 0LzKQf-1dfzxQ0mLR-014Pn7 for ; Sat, 29 Jul 2017 22:09:53 +0200 Subject: Re: mandoc-1.14.2 released To: discuss@mandoc.bsd.lv References: <20170728181244.GD58985@athene.usta.de> <69d1d7f2-ce86-62e1-7623-e1a4c05f6f4d@gmx.com> <20170729142827.GF24945@athene.usta.de> <20170729173858.GH24945@athene.usta.de> From: Yuri Pankov Message-ID: <30365e38-be1c-0d36-99c8-b3a50804ed21@gmx.com> Date: Sat, 29 Jul 2017 23:09:50 +0300 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.2.1 X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 In-Reply-To: <20170729173858.GH24945@athene.usta.de> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:TihwZhOixCkka+dnCMlV/h+IgSfrt2QZ9Mf96wldIAOSLGi6xzD BOJkkmidaX7CPCw1974o2iqg5tPxzKQpsT84xk6PHyuU2NkeTxBbfKmRspLx8vtqf0IR5wd iEJm7ojzewm39uUCFnP8+HOvl0TIT3Maol6swpTFklCfu8K/X1rjyAWyUleuVVNiygSF6dD YmIjzK5AVZ9YHNtIFV91Q== X-UI-Out-Filterresults: notjunk:1;V01:K0:zDJ2USW8bm8=:BmWg8w6w2C/7yfzioJvzvK EOICZh7ZmSoWefC4hhhXMQfJCPMDXuZAQbHmt92rxSZxkcC4pk4n9hHRQKjiPIvyzuvb8+RwP 5ahVqwFLcSO18VZCZWUx1jFqOGsfLB103N8diYxZuH5rHdWqvZOS6rRm+gmC1qTWoQVE0fWM6 GmKx57tTYWE7lCUgM3a+opaW6W5PXtE26o0lG8nlgwlfopHKX7ta3oSCzWXExwAGTA86VA6lK cx0J4r9KkhItK0fLDNM2aBH0HAV+tBrL6aNw0EacYs3tWVdwu+BDZCKjddFdSnw/IVuAAlVK7 3NRiJgpgoRSRmN0mhTZq/x+paDiH9CoxVA/7kH7Ax91fA81Tei/5pATJXGNsvxyTHX3Taixg9 LAFvN8m2KX0i+Xu+gnrRL3nDNhl/zuZDGdi086DKytEo9b1CCyUbBRU4MhzXiDD0lBgZUgjB4 iLMz8QKvFZk/JyfW4foW5IuAMrXYBVN+tkqH8cpJJFxGhvdC6zKiqhuj8dBr0pPLP7QWadSS8 UbuwNF9yyfhKWKkNu32tktDVF55ekbOuN0kWQHnGBEbMC6h1tFY5FurRCuFa9ere+1Bv0y1VY 33ptMCNmOeU94+xlMK7wINCqDt/3a9oAKApOHDQmKuRR5HHtwnuJDbberiTkfTY+dkJT1wjtG oXpYRgs/Eyt9PcYgQlnK8bSJatcQfNpprYSVLriCVbQMTp1/2dxjuEif1Taa4DWrIzaf/LjFs uDWTwoiEtAPXyWh41kQ1V4x6WgSqlOgPGYpLd1ToLi+qGG4W01qA7msLie2oJzQLtjCdCFdAE Ard/SlpYC8WvcGb2d+akaTT23vq9VIfcyld829S1LTAym+RCso9lhirj0V8KdbXi5pEUr5Z 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