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 c5dcce6f for ; Wed, 2 Aug 2017 08:50:55 -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 1dcu33-0003Qj-PS; Wed, 02 Aug 2017 15:50:54 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1dcu33-0004KO-IV; Wed, 02 Aug 2017 15:50:53 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1dcu33-0002ZS-C9; Wed, 02 Aug 2017 15:50:53 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 98cbca7e; Wed, 2 Aug 2017 15:50:53 +0200 (CEST) Date: Wed, 2 Aug 2017 15:50:53 +0200 From: Ingo Schwarze To: Yuri Pankov Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc-1.14.2 released Message-ID: <20170802135053.GC27589@athene.usta.de> References: <20170728181244.GD58985@athene.usta.de> <69d1d7f2-ce86-62e1-7623-e1a4c05f6f4d@gmx.com> <20170729142827.GF24945@athene.usta.de> <20170729173858.GH24945@athene.usta.de> <30365e38-be1c-0d36-99c8-b3a50804ed21@gmx.com> 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: <30365e38-be1c-0d36-99c8-b3a50804ed21@gmx.com> User-Agent: Mutt/1.8.0 (2017-02-23) Hi Yuri, Yuri Pankov Illumos wrote on Sat, Jul 29, 2017 at 11:09:50PM +0300: > 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 Interesting. On OpenBSD, mount_nfs(8) is an actual command /sbin/mount_nfs, and documented as such, with .Sh SYNOPSIS .Nm mount_nfs ... Of course, you can also invoke it as "mount -t nfs", which is documented in mount(8). But that implies the clash doesn't occur here. > Ingo Schwarze wrote: >> What can we do? >> >> a) Stop harvesting names in the SYNOPSIS section. >> c) Not warn about .Xr to names only found in the SYNOPSIS. I just committed a fix doing that, see below. > I'd say a) as well, but looking for a solution in the mean time -- > this is the only one left for the moment :-) Since Markus Waldner and Leah Neukirchen found a very serious regression in 1.14.2 right after release, i'm going to follow up with a pure bug fix release 1.14.3 shortly. It will also contain the fix below. Yours, Ingo Log Message: ----------- No longer use names that only occur in the SYNOPSIS section as names for man(1) lookup. For OpenBSD base and Xenocara, that functionality was never intended to be required, and i just fixed the last handful of offenders using it - not counting the horribly ill-designed interfaces engine(3) and lh_new(3) which are impossible to properly document in the first place. Of course, apropos(1) and whatis(1) continue to use SYNOPSIS .Nm, .Fn, and .Fo macros, so "man -k ENGINE_get_load_privkey_function" still works. This change also gets rid of a few bogus warnings "cross reference to self" which actually are *not* to self, like in yp(8). This former functionality was intended to help third-party software in the ports tree and on non-OpenBSD systems containing manual pages with incomplete or corrupt NAME sections. But it turned out it did more harm than good, and caused more confusion than relief, specifically for third party manuals and for maintainers of mandoc-portable on other operating systems. So kill it. Problems reported, among others, by Yuri Pankov (illumos). OK jmc@ Modified Files: -------------- mandoc: mansearch.c mdoc_validate.c Revision Data ------------- Index: mdoc_validate.c =================================================================== RCS file: /home/cvs/mandoc/mandoc/mdoc_validate.c,v retrieving revision 1.351 retrieving revision 1.352 diff -Lmdoc_validate.c -Lmdoc_validate.c -u -p -r1.351 -r1.352 --- mdoc_validate.c +++ mdoc_validate.c @@ -1137,8 +1137,6 @@ post_fname(POST_ARGS) if ( ! (cp[0] == '\0' || (cp[0] == '(' && cp[1] == '*'))) mandoc_msg(MANDOCERR_FN_PAREN, mdoc->parse, n->line, n->pos + pos, n->string); - if (n->sec == SEC_SYNOPSIS && mdoc->meta.msec != NULL) - mandoc_xr_add(mdoc->meta.msec, n->string, -1, -1); } static void @@ -1205,9 +1203,8 @@ post_nm(POST_ARGS) n = mdoc->last; - if ((n->sec == SEC_NAME || n->sec == SEC_SYNOPSIS) && - n->child != NULL && n->child->type == ROFFT_TEXT && - mdoc->meta.msec != NULL) + if (n->sec == SEC_NAME && n->child != NULL && + n->child->type == ROFFT_TEXT && mdoc->meta.msec != NULL) mandoc_xr_add(mdoc->meta.msec, n->child->string, -1, -1); if (n->last != NULL && Index: mansearch.c =================================================================== RCS file: /home/cvs/mandoc/mandoc/mansearch.c,v retrieving revision 1.75 retrieving revision 1.76 diff -Lmansearch.c -Lmansearch.c -u -p -r1.75 -r1.76 --- mansearch.c +++ mansearch.c @@ -171,7 +171,9 @@ mansearch(const struct mansearch *search page = dbm_page_get(rp->page); if (lstmatch(search->sec, page->sect) == 0 || - lstmatch(search->arch, page->arch) == 0) + lstmatch(search->arch, page->arch) == 0 || + (search->argmode == ARG_NAME && + rp->bits <= (int32_t)(NAME_SYN & NAME_MASK))) continue; if (res == NULL) { @@ -452,14 +454,28 @@ lstlen(const char *cp, size_t sep) { size_t sz; - for (sz = 0;; sz++) { - if (cp[0] == '\0') { - if (cp[1] == '\0') - break; - sz += sep - 1; - } else if (cp[0] < ' ') - sz--; - cp++; + for (sz = 0; *cp != '\0'; cp++) { + + /* Skip names appearing only in the SYNOPSIS. */ + if (*cp <= (char)(NAME_SYN & NAME_MASK)) { + while (*cp != '\0') + cp++; + continue; + } + + /* Skip name class markers. */ + if (*cp < ' ') + cp++; + + /* Print a separator before each but the first string. */ + if (sz) + sz += sep; + + /* Copy one string. */ + while (*cp != '\0') { + sz++; + cp++; + } } return sz; } @@ -471,19 +487,34 @@ lstlen(const char *cp, size_t sep) static void lstcat(char *buf, size_t *i, const char *cp, const char *sep) { - const char *s; + const char *s; + size_t i_start; - for (;;) { - if (cp[0] == '\0') { - if (cp[1] == '\0') - break; + for (i_start = *i; *cp != '\0'; cp++) { + + /* Skip names appearing only in the SYNOPSIS. */ + if (*cp <= (char)(NAME_SYN & NAME_MASK)) { + while (*cp != '\0') + cp++; + continue; + } + + /* Skip name class markers. */ + if (*cp < ' ') + cp++; + + /* Print a separator before each but the first string. */ + if (*i > i_start) { s = sep; while (*s != '\0') buf[(*i)++] = *s++; - } else if (cp[0] >= ' ') - buf[(*i)++] = cp[0]; - cp++; + } + + /* Copy one string. */ + while (*cp != '\0') + buf[(*i)++] = *cp++; } + } /* -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv