Re: Better Help Docs Searching?

[Roman Neuhauser <neuhauser@xxxxxxxxxx>]

# zachriggle@xxxxxxxxx / 2021-08-01 05:44:52 -0500:
> A good example is the builtin 'read'.  Even knowing it's a builtin,
> and searching the docs [1] / man pages for builtins, it's still not
> very straightforward to find the docs on 'read'.  (There are 91
> matches for "read" on the online docs and 82 in zshbuiltins).

"/^ *read \[" (without the quotes) followed by ^J or ^M will get you
there, but boy, the ergonomy of three consecutive key presses with a
stretched out pinky finger... :(


# zachriggle@xxxxxxxxx / 2021-08-03 00:45:22 -0500:
> One thing that I really like / prefer about man pages is the $MANPAGER
> variable, which I have configured to use bat(3) [1] as my pager, which
> gives syntax highlighting, highlights command names, and flag names.
> Is there an equivalent for "info" pages?

that's an impossible task, metadata in info files only goes as far as
^L preceding menus from what i've seen...  man pages can be styled by
your pager because the file you're viewing in the pager includes the
style info.  roff is a cumbersome markup language, but it's what you
make it to be.  while most man pages you'll find on linux are written
using the man(7) macro set, mdoc(7) provides a semantic marup language.

man(7) from https://mandoc.bsd.lv/ (found in many BSDs and Linux
distros):

  The man language was the standard formatting language for AT&T UNIX
  manual pages from 1979 to 1989.  Do not use it to write new manual
  pages: it is a purely presentational language and lacks support for
  semantic markup.  Use the mdoc(7) language, instead.

just to clarify, this is not about abandoning man pages.  man(7) and
mdoc(7) are "just" different markups to write man pages in.

btw, zsh's man pages use man(7), as is usual with generated man pages.
man(7) gives you this level of info:

  .PD 0
  \fBcd\fP [ \fB\-qsLP\fP ] [ \fIarg\fP ]
  .TP
  .PD 0
  \fBcd\fP [ \fB\-qsLP\fP ] \fIold\fP \fInew\fP
  .TP

.PD = vertical margin
\fB = bold font
\fI = italic font
\fP = previous font
.TP = "tagged paragraph", normally term + definition in a list
      of definitions.  not here though.

they're on different levels, and i can see why someone writing
manuals for linux would find man pages pointless.

this could have been (in mdoc(7)):

  .Ic cd
  .Op Fl qsLP
  .Op Ar arg
  .
  .Ic cd
  .Op Fl qsLP
  .Ar old
  .Ar new

.Ic = interactive command, .Op = optional, .Ar argument.
the Op macro generates the brackets around its argument.
totally different level of discourse.

two more examples; these three are entirely different and
perfectly distinguishable:

  .\" optional flag to the program
  .Op Fl n
  .\" optional flag to the program, requires an argument
  .Op Fl n Ar DIR
  .\" mandatory operand to the program
  .Ar DIR

environment variables don't get mixed up with syntax non-terminals:

  .Ev TERM
  .Sy TERM

and if i go looking for all parts of git which accept --origin,
i won't drown in all the passing mentions of the flag elsewhere.
cooking with gas!  meanwhile...

as long as our software vendors deliver man pages marked up in
man(7) we're out of luck: their pages may be pretty (if you ever
bothered to print one) but otherwise quite useless.  it's different
with mdoc(7), tools to mine the data don't exist yet afaik, but at
they are feasible.

mdoc(7) is better than man(7) but still quite unpleasant to write
(better than docbook!  low standard, i know), and certainly not
sufficient for things like finegrained links (all you get is semantic
markup for a list of references at the bottom, and intra-document
links targeting other *sections*).  but it's already here and people
seem unwilling to give man pages up.

a good way forward imo is to deprecate the current man+pager model,
this coupling is too loose, man/whatis/apropos simply sucks, and
the pager can't fill the shoes either.  there's no reason we shouldn't
be able to follow links between man pages or have ad-hoc indexes
generated from our in-viewer queries.  info is not magic.

i believe that GNU could have spent a fraction of the effort they put
into texinfo on man instead, and we'd all be much happier today.


anyway, if your software vendors provide you with man(7)-based pages,
demand better! (you may have to roll up your sleeves though. :)

-- 
roman