help / color / mirror / code / Atom feed
From: Roman Neuhauser <neuhauser@sigpipe.cz>
To: Zach Riggle <zachriggle@gmail.com>, Zsh Users <zsh-users@zsh.org>
Subject: Re: Better Help Docs Searching?
Date: Wed, 4 Aug 2021 08:30:08 +0200	[thread overview]
Message-ID: <YQoz8OLqrCJjRXSI@isis.sigpipe.cz> (raw)
In-Reply-To: <CAMP9c5ng8Hf5A+sVSfnO5ZfAXRTXdzi5JX3bKgGKfMoH8VV7Kw@mail.gmail.com> <20210801163314.toawcsrtj6eqydxr@chazelas.org> <CAN=4vMoaurtxQJXvmd2SsDDRhZ74RwKmsvCbseHC9z-utdSwTA@mail.gmail.com> <CAMP9c5m=oOwSvEaqVF62GF0=BjjMnS8fBEmbcWz9ydxqx=tvZQ@mail.gmail.com>

# zachriggle@gmail.com / 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@gmail.com / 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

  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 ]
  .PD 0
  \fBcd\fP [ \fB\-qsLP\fP ] \fIold\fP \fInew\fP

.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. :)


  parent reply	other threads:[~2021-08-04  6:31 UTC|newest]

Thread overview: 26+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-08-01 10:44 Zach Riggle
2021-08-01 11:01 ` Roman Perepelitsa
2021-08-01 16:21 ` Mikael Magnusson
2021-08-01 16:33   ` Stephane Chazelas
2021-08-01 18:52     ` Bart Schaefer
2021-08-01 20:11       ` Ray Andrews
2021-08-03  5:45         ` Zach Riggle
2021-08-03  8:03           ` Zach Riggle
2021-08-03  8:09             ` Zach Riggle
2021-08-03  8:44               ` Peter Stephenson
2021-08-03  9:40                 ` Zach Riggle
2021-08-03  9:57                   ` Peter Stephenson
2021-08-03 16:47                   ` Bart Schaefer
2021-08-03 11:28             ` david rayner
2021-08-05 15:31             ` Vincent Lefevre
2021-08-03 16:52           ` Bart Schaefer
2021-08-01 16:25 ` Bart Schaefer
2021-08-05  9:56   ` Vincent Lefevre
2021-08-04  6:30 ` Roman Neuhauser [this message]
2021-08-04 14:56   ` Ray Andrews
2021-08-04 16:08     ` Bart Schaefer
2021-08-05 12:00       ` Ray Andrews
2021-08-04 16:38     ` Roman Neuhauser
2021-08-04 16:05   ` Bart Schaefer
2021-08-04 16:45     ` Roman Neuhauser
2021-08-14 15:41 ` Daniel Shahaf

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YQoz8OLqrCJjRXSI@isis.sigpipe.cz \
    --to=neuhauser@sigpipe.cz \
    --cc=zachriggle@gmail.com \
    --cc=zsh-users@zsh.org \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox


This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).