From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout.scc.kit.edu (scc-mailout.scc.kit.edu [129.13.185.202]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id pAQCLPgS002309 for ; Sat, 26 Nov 2011 07:21:26 -0500 (EST) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-02.scc.kit.edu with esmtp (Exim 4.72 #1) id 1RUHG1-0005vJ-E6; Sat, 26 Nov 2011 13:21:25 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1RUHG1-0007PQ-Fi for tech@mdocml.bsd.lv; Sat, 26 Nov 2011 13:21:25 +0100 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1RUHG1-0005Jc-Ec for tech@mdocml.bsd.lv; Sat, 26 Nov 2011 13:21:25 +0100 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1RUHG1-0003u5-Dd for tech@mdocml.bsd.lv; Sat, 26 Nov 2011 13:21:25 +0100 Date: Sat, 26 Nov 2011 13:21:25 +0100 From: Ingo Schwarze To: tech@mdocml.bsd.lv Subject: Re: Showing all possible apropls keys. Message-ID: <20111126122125.GD13912@iris.usta.de> References: <4ECA86C8.1030100@bsd.lv> <20111121223702.GA22285@iris.usta.de> <4ECB6446.4090201@bsd.lv> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4ECB6446.4090201@bsd.lv> User-Agent: Mutt/1.5.21 (2010-09-15) Hi Kristaps, Kristaps Dzonsons wrote on Tue, Nov 22, 2011 at 09:58:46AM +0100: > My initial thought, however, was just to cut out parts of your macro > synopsis documentation for a two-column display, e.g., > > Accepted keywords are as follows: > > Nd description of manual page > Nm name of manual page > Fn a function name > ... > > Better? Yes. I'd probably try to help people by giving acronyms as much as possible, then pointing to mdoc(7) afterwards. A bit like: The following search keywords are available: NAME section content: Nm name of the manual page (defined in each page) Nd one-line description (defined in each page) Information about command line utilities: Nm name of the command Fl flag (command line option) Cm command modifier Ar argument on the command line Ic internal or interactive command Ev environment variable Pa path name in the file system Information about function libraries: Lb library name In include file Ft function return type Fn function name Fa function argument type and argument name Vt variable type Va variable name Dv defined variable or preprocessor constant Er error constant Various information: An author name Lk hyperlink Mt mailto hyperlink Cd configuration declaration for kernel devices Ms mathematical symbol Tn tradename Physical markup: Em emphasised text (italic or underlined) Li literal text (constant width) Sy symbolic text (bold face) Section headers and cross references: Sh section header (standard section headers are not indexed) Ss subsection header Xr cross reference to another manual page Rs reference start (bibliographic block) St standards reference At AT&T UNIX version reference Bx BSD version reference Bsx BSD/OS version reference Nx NetBSD version reference Fx FreeBSD version reference Ox OpenBSD version reference Dx DragonFly version reference These search keywords follow mdoc(7) macro names, even when the manual page is written using the man(7) language and even when only a formatted version of the manual is available. Even in the latter two cases, searching by `Nm' and `Nd' is possible, but most other search keys are not going to return the page. Well, something like that. Note that in some places, i deliberately chose a different wording compared to mdoc(7), for two reasons: The audience is different, people reading apropos(1) will use these keys less often than people using mdoc(7), so acronyms are more important. And the purpose is slightly different, people using apropos(1) just need a rough understanding what the keys will probably return, while people reading mdoc(7) are manual authors or maintainers and have to understand some finer points about when and how to use individual macros. Yours, Ingo -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv