[bug #57667] refer(1) rehab

[anonymous]

URL:
  <https://savannah.gnu.org/bugs/?57667>

                 Summary: refer(1) rehab
                 Project: GNU troff
            Submitted by: None
            Submitted on: Sun 26 Jan 2020 02:05:54 AM UTC
                Category: Macro - others
                Severity: 3 - Normal
              Item Group: Documentation
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None

    _______________________________________________________

Details:

Peter Schaffter says of refer(1)
<http://lists.gnu.org/archive/html/groff/2020-01/msg00024.html>:

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.

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

Piotr Piatrou adds
<http://lists.gnu.org/archive/html/groff/2020-01/msg00027.html>:

Take, for instance, groff_mm(1), which can indeed be called ADEQUATE man page
because, with all its conciseness, it gave me enough information to start
using the mm macros.  What was crucial to me, the descriptions of internal
strings and registers, and also the interaction with mm of the user-defined
macros. This is exactly what a user needs but does not find in refer(1).
Namely, what could be added to refer(1):

0 descriptions of internal strings like [A, [B, ... and registers generated by
refer,
0 mention of the citations formatting being taken care of by refer-ms.tmac,
etc., if one uses the standard macro sets,
0 if one does not use the standard macro sets, there should be a brief
description of how a user is to arrange the .[-, ... macros.

Maybe a couple of paragraphs, it does not break anything, and should be enough
as a newbuy's staring point.

I agree that all this information is already scattered among refer(1),
refer.tmac and the Lesk's paper. I even agree that the information is kind of
ample. I am complaining about the way of its presentation, which DOES NOT work
for an average user.




    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?57667>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/