Re: How to use refer macros-agnostic way?

[Peter Schaffter]

On Wed, Jan 08, 2020, Tadziu Hoffmann wrote:
> In my opinion, the manual page [refer(1)] is perfectly adequate,
> if you accept that it is not a tutorial but rather a reference
> manual that you refer to for particular details of implementation
> or invocation.

The caveat is significant: you must accept that manpages aren't
instruction manuals, which term I prefer to "tutorial," which has
a whiff of condescension.  They're more like abstracts with cheat
sheets.

> In fact, all of the manual pages for troff-related utilities
> assume that you're already familiar (at least in very broad
> terms) with the basic ideas of how the utilities are meant to be
> used.

A classic manpage Catch-22: useful only after you already know what
you turned to the manpage to learn.

I disagree that refer(1) is perfectly adequate:

  * there's no mention that the mom macros, which have been part of
    groff for close to twenty years, are suitable for use with refer;

  * the wording of the preamble to the list of field identifiers
    creates the impression that they are the only ones available;

  * there is no mention that the number of reference types can be
    extended beyond the four that are listed;

  * sections dealing with accent strings in bibliographic databases
    need to be updated to state first that accented characters
    should be entered as named glyphs, reflecting contemporary
    usage, and only secondarily that accent strings, if preferred,
    should come after the affected character.

I thoroughly sympathise with the OP's frustration with the refer
manpage, even if there's nothing to be done about it.  It's complete
and accurate, but communicates its substance poorly to all but the
initiated.  It would be of enormous help if, at the very least, the
SEE ALSO section pointed readers to Lesk's paper so they don't have
to plough through the whole manpage only to discover that they're as
befuddled and befogged as before, with no clue where to find the
kind of helpful information they were seeking.

-- 
Peter Schaffter
http://www.schaffter.ca