Re: [groff] groff as the basis for comprehensive documentation?

[Ingo Schwarze]

Hi Nate,

Nate Bargmann wrote on Wed, Apr 18, 2018 at 06:52:44PM -0500:

> After reading a bit about mdoc,

I'm sure here you mean mandoc(1), the program, not mdoc(7), the
markup language.

> I was disappointed that unlike "man" that I find on Slackware or
> Debian, I had to add an uninstalled man page into the db in order
> for "mandoc" to open it.  Perhaps I missed an option, but the "man"
> I'm familiar with is capable of opening a file simply by giving it
> a path name.

That is non-standard behaviour even on GNU/Linux:

   $ lsb_release -d
  Description:    Debian GNU/Linux 8.10 (jessie)
   $ dpkg-query -l man-db | tail -n 1
  ii  man-db         2.7.0.2-5    i386         on-line manual pager
   $ ls *.1
  apropos.1  demandoc.1  man.1  man.options.1  mandoc.1  soelim.1
   $ man apropos.1        # the man-db man(1) implementation
  No manual entry for apropos.1
   $ ./Bin/man apropos.1  # the mandoc man(1) implementation
  man: No entry for apropos.1 in the manual.

However:

   $ man -l apropos.1 | grep 'search manual'
     apropos, whatis - search manual page databases
   $ ./Bin/man -l apropos.1 | grep 'search manual'
     apropos, whatis - search manual page databases

As a matter of fact, the inspiration for the -l option came from
Linux, and the person who asked me to implement it in mandoc several
years ago was an Alpine Linux developer.  Classical BSD man(1) did
not have the -l option, but i agree that it is useful, and i use it
many times every day.

I think it is good that the '-l' ("local") option is required when
giving a file name in the local directory, or an absolute path.
The program has many different ways to specify which page to display:

 * by full page name as in man(1)
 * by whole word search as in whatis(1) = man -f
 * by substring or regexp search as in apropos(1) = man -k
 * by file name as in man -l

With so many different semantics of a command line, guessing
what the user meant will only cause confusion.


Besides, with the mandoc implementation of man(1), it is not
absolutely required to update the database even after installing a
new page into /usr/share/man/.  The man(1) program will find the
new page at once even if it is not yet in the database - but of
course, apropos(1) cannot find it, so always keeping the database
up to date still makes sense.  A good package manager will do that
for you, so it is no hassle.

Yours,
  Ingo