[TUHS] man-page style

[Theodore Y. Ts'o]

On Mon, Nov 19, 2018 at 10:35:05AM -0500, Clem Cole wrote:
> And Ted is not that I don't use the unix documents (full papers) - hey I
> do.   That is how I learned to use 'make' when it appeared (or C for that
> matter) from documents in /usr/doc. \
> 
> What started this whole thread was Doug's comment about how succinct and
> to the point man was.  If was a fine interface for >>UNIX<<.   Man (using
> roff) was what people expect.  It's not about better or worse -- it worked
> and worked well.

For what it's worth, that's a Debian packaging standard.  All
executables are supposed to have a man page.  In some cases it may be
no more than a short summary of the options and then a reference to
the info manual if you want to learn more.  If the upstream package
does not provide a man page, Debian maintainers are supposed to create
a man page, and hopefully contribute it back upstream.

This isn't always the case; but if there isn't a man page, that's
always grounds for filing a Debian bug report.

> As I said, if man had been maintained as the primary >>manual<< style
> interface and /usr/doc/<PROG>/foo.ms as the primary scheme (which >>IS<<
> what BSD did), then you don't fail the rule of least astonishment.  Then
> create a *roff -Tinfo | info_create backend, that produced the info files;
> those that want it, get it and love it.   Those that >>expect<< man to work
> because its UNIX, get what they expect.  No one is 'astonished.'

I'm not convinced the original BSD man page for, say, "make" is really
sufficient to learn how to use make effectively w/o the expanded,
non-man page write up in BSD Unix's Programmers Supplementary
Documents.  So I dare say the goal that the man page should be the
primary manual was a bit of an aspiration goal as well.

That being said, I'm not convinced nroff is powerful enough to be a
source language for info files and HTML files.  For one thing, it
doesn't have the ability to specify hyperlinks.  The GNU an-ext.tmac
extensions does define macros to provide *external* hyperlinks to WWW
URL's.  However, even that doesn't have the ability to specify
*internal* hyperlinks to other sections of the document.

Cheers,

						- Ted