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

[Nate Bargmann]

* On 2018 18 Apr 19:30 -0500, Ingo Schwarze wrote:
> 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.

Yes, indeed.
> 
> > 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

Well, I am doing a simple 'man ./foo.1' in the project directory and I
get the page displayed through less.  Been doing it that way for years
on Debian and now Slackware.

The default man in Slackware complains there is no option '-l' available
and gives me the usage screen.

> 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

I now looked at mandoc's man(1) page again and the '-l' option is
explained as you have used it here.  Somehow I missed that the other day
and had tried '-m' and '-M' to no avail.  Then I managed to construct a
directory local .db and could read my test file.

Perhaps an example would be a benefit.  I often check the EXAMPLE
section of pages as I'm the sort that gets more out of working example
than even a good explanation.

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

One thing I have learned, a user will try all sorts of permutations the
developer never considered!  A user will also read the manual very
differently than the developer or its author.  I try to keep these
points in mind as I work with the project.

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

Thanks, Ingo.

I'll admit to not being a 'man' power user.  I use it to quickly pull up
a page and don't even think of 'apropos' or the other command line
options.  Like a lot of us, I'm probably lazy in all the wrong areas.
;-)

I know we're veering off topic for this list.

- Nate

-- 

"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."

Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB

signature.asc
Description: PGP signature