[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [groff] groff as the basis for comprehensive documentation?
From: |
Ingo Schwarze |
Subject: |
Re: [groff] groff as the basis for comprehensive documentation? |
Date: |
Thu, 19 Apr 2018 02:28:36 +0200 |
User-agent: |
Mutt/1.8.0 (2017-02-23) |
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
- Re: [groff] groff as the basis for comprehensive documentation?, (continued)
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, Ingo Schwarze, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, G. Branden Robinson, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/16
Re: [groff] groff as the basis for comprehensive documentation?, Larry Kollar, 2018/04/18
Re: [groff] groff as the basis for comprehensive documentation?, Colin Watson, 2018/04/19
Re: [groff] groff as the basis for comprehensive documentation?, Ingo Schwarze, 2018/04/19
Re: [groff] groff as the basis for comprehensive documentation?, Colin Watson, 2018/04/20