Re: [groff] mom manpage

[Ingo Schwarze]

Hi John,

John Gardner wrote on Sat, Dec 01, 2018 at 05:36:25PM +1100:
> Ingo Schwarze wrote:

>> Even moderately large systems can be beautifully documented in a
>> single manual page - for example, a shell

> It's amazing how true this is. Even with massive man-pages, it's still
> easier to find what I'm looking for in less(1) by hitting the `/` key and
> typing a search string.

Even better - on OpenBSD-current, i simply type

   $ man -O tag=wait ksh

and less(1) starts up like this:

   wait [job ...]
      Wait for the specified job(s) to finish.  The exit status of wait
      is that of the last specified job; if the last job is killed by a

then type ":tset" ENTER

   * set exit status.  In POSIX mode, the exit status of set is 0 if there
     are no errors; in non-POSIX mode, the exit status is that of any

then hit just "t"

   set [+-abCefhkmnpsuvXx] [+-o option] [+-A name] [--] [arg ...]
      The set command can be used to set (-) or clear (+) shell
      options, set the positional parameters, or set an array

Try that kind of hyperlinking with "/".

Just like   https://man.openbsd.org/ksh#wait
only at the console.  And no, it does *not* require the author to
say "i want an anchor here" in any special syntax.  It just works
from the normal manual page markup, without doing anything special.

> It's quite literally faster than the time it takes to load
> web-based documentation (especially on my crappy connection...)

Except when using groff, of course:

  address@hidden $ uname -a
    OpenBSD isnote.usta.de 6.4 GENERIC.MP#341 amd64
  address@hidden $ sysctl hw.model
    hw.model=Intel(R) Core(TM) i5-5300U CPU @ 2.30GHz
  address@hidden $ time man ksh | wc   
    2960   20284  165761
    0m00.06s real     0m00.06s user     0m00.01s system

  address@hidden [unstable11s]:~ > uname -a
    SunOS unstable11s 5.11 11.3 sun4u sparc SUNW,SPARC-Enterprise
  address@hidden [unstable11s]:~ > psrinfo -pv | tail -1
    SPARC64-VII (portid 1024 impl 0x7 ver 0x91 clock 2520 MHz)
  address@hidden [unstable11s]:~ > time man ksh | wc
    Reformatting page.  Please Wait... done
    3180   26718  227245
    real    0m0.549s
    user    0m0.952s
    sys     0m0.058s

And the comparison is not even fair: the OpenBSD page is mdoc(7),
while Solaris 11 has David Korn's old man(7) page from 1993, and
man(7) in general parses much faster than mdoc(7).

But that's OK.  Groff is a professional typesetting system, so
blaming it for being slow as a manual page formatter is not
reasonable, it just isn't what it is made for.

Yours,
  Ingo


P.S.
  address@hidden $ time lynx --dump http://man.openbsd.org/ksh.1 | wc 
    5172   21523  165576
    0m10.02s real     0m00.03s user     0m00.01s system