Re: Showing all possible apropls keys.

[Ingo Schwarze <schwarze@usta.de>]

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