From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-1.sys.kth.se (smtp-1.sys.kth.se [130.237.32.175]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id pASKbtV7016580 for ; Mon, 28 Nov 2011 15:37:56 -0500 (EST) Received: from mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) by smtp-1.sys.kth.se (Postfix) with ESMTP id A2C74155920 for ; Mon, 28 Nov 2011 21:37:49 +0100 (CET) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-1.sys.kth.se ([130.237.32.175]) by mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) (amavisd-new, port 10024) with LMTP id jzNiDWVUbr0n for ; Mon, 28 Nov 2011 21:37:48 +0100 (CET) X-KTH-Auth: kristaps [83.250.6.251] X-KTH-mail-from: kristaps@bsd.lv X-KTH-rcpt-to: tech@mdocml.bsd.lv Received: from macky.local (c83-250-6-251.bredband.comhem.se [83.250.6.251]) by smtp-1.sys.kth.se (Postfix) with ESMTP id 19F5E1563D3 for ; Mon, 28 Nov 2011 21:37:46 +0100 (CET) Message-ID: <4ED3F11A.6080201@bsd.lv> Date: Mon, 28 Nov 2011 21:37:46 +0100 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:8.0) Gecko/20111105 Thunderbird/8.0 X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 To: tech@mdocml.bsd.lv Subject: Re: Showing all possible apropls keys. References: <4ECA86C8.1030100@bsd.lv> <20111121223702.GA22285@iris.usta.de> <4ECB6446.4090201@bsd.lv> <20111126122125.GD13912@iris.usta.de> In-Reply-To: <20111126122125.GD13912@iris.usta.de> Content-Type: multipart/mixed; boundary="------------070409090507090008060609" This is a multi-part message in MIME format. --------------070409090507090008060609 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit >> 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. Ingo, Getting the ball rolling with this... thoughts on the enclosed patch? It's more or less what appears above, with most verbiage snatched directly from mdoc(7). Thoughts? Kristaps --------------070409090507090008060609 Content-Type: text/plain; name="patch.txt" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="patch.txt" Index: apropos.1 =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/apropos.1,v retrieving revision 1.9 diff -u -r1.9 apropos.1 --- apropos.1 26 Nov 2011 22:38:11 -0000 1.9 +++ apropos.1 28 Nov 2011 20:36:47 -0000 @@ -103,6 +103,9 @@ macro to query and .Li val is its value. +See +.Sx Macro Keys +for a list of available terms. Operator .Li \&= evaluates a substring, while @@ -125,7 +128,7 @@ parses terms as case-sensitive regular expressions .Pq the Li \&~ operator over manual names and descriptions -.Pq the Li \&Nm No and Li \&Nd No macros . +.Pq the Li \&Nm No and Li \&Nd No macro keys . Multiple terms imply pairwise .Fl o . Results are sorted by manual title, with output formatted as @@ -151,6 +154,81 @@ If an architecture is specified in the output, use .Pp .Dl $ man \-s sec \-S arch title +.Ss Macro Keys +Queries evaluate over a subset of +.Xr mdoc 7 +macros indexed by +.Xr mandocdb 8 . +These may be any of the following or +.Li any +for any macro key. +.Pp +Names and description: +.Bl -offset indent -compact -column "Brq, Bro, Brc" description +.It Li \&Nm Ta manual name +.It Li \&Nd Ta one-line manual description +.El +.Pp +Sections and cross references: +.Bl -offset indent -compact -column "Brq, Bro, Brc" description +.It Li \&Sh Ta section header (excluding standard sections) +.It Li \&Ss Ta subsection header +.It Li \&Xr Ta cross reference to another manual page +.It Li \&Rs Ta bibliographic references +.El +.Pp +Semantic markup for command line utilities: +.Bl -offset indent -compact -column "Brq, Bro, Brc" description +.It Li \&Fl Ta command line options (flags) +.It Li \&Cm Ta command modifier +.It Li \&Ar Ta command arguments +.It Li \&Ic Ta internal or interactive command +.It Li \&Ev Ta environmental variable +.It Li \&Pa Ta file system path +.El +.Pp +Semantic markup for function libraries: +.Bl -offset indent -compact -column "Brq, Bro, Brc" description +.It Li \&Lb Ta function library name +.It Li \&In Ta include file +.It Li \&Ft Ta function return type +.It Li \&Fn Ta function name +.It Li \&Fa Ta function argument type and name +.It Li \&Vt Ta variable type +.It Li \&Va Ta variable name +.It Li \&Dv Ta defined variable or preprocessor constant +.It Li \&Er Ta error constant +.It Li \&Ev Ta environmental variable +.El +.Pp +Various semantic markup: +.Bl -offset indent -compact -column "Brq, Bro, Brc" description +.It Li \&An Ta author name +.It Li \&Lk Ta hyperlink +.It Li \&Mt Ta Do mailto Dc hyperlink +.It Li \&Cd Ta kernel configuration declaration +.It Li \&Ms Ta mathematical symbol +.It Li \&Tn Ta tradename +.El +.Pp +Physical markup: +.Bl -offset indent -compact -column "Brq, Bro, Brc" description +.It Li \&Em Ta italic font or underline +.It Li \&Sy Ta boldface font +.It Li \&Li Ta typewriter font +.El +.Pp +Text production: +.Bl -offset indent -compact -column "Brq, Bro, Brc" description +.It Li \&St Ta reference to a standards document +.It Li \&At Ta At No version reference +.It Li \&Bx Ta Bx No version reference +.It Li \&Bsx Ta Bsx No version reference +.It Li \&Nx Ta Nx No version reference +.It Li \&Fx Ta Fx No version reference +.It Li \&Ox Ta Ox No version reference +.It Li \&Dx Ta Dx No version reference +.El .Sh ENVIRONMENT .Bl -tag -width Ds .It Ev MANPATH --------------070409090507090008060609-- -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv