anonymous
2020-01-26 02:05:56 UTC
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/
<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/