bugGNU troff - Bugs: bug #57667, refer(1) rehab

 
 

bug #57667: refer(1) rehab

Submitted by:  None
Submitted on:  Sun 26 Jan 2020 02:05:54 AM UTC  
 
Category:  Preprocessor refer Severity:  3 - Normal
Item Group:  Documentation Status:  Confirmed
Privacy:  Public Assigned to:  G. Branden Robinson <gbranden>
Open/Closed:  Open Planned Release:  None

Add a New Comment (Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

Tue 04 Feb 2020 07:29:32 AM UTC, comment #1: 

Thank you for the report.  I think most or all of your observations and suggestions are sound.

"It would be of enormous help if, at the very least, the SEE ALSO section pointed readers to Lesk's paper"

This part is already done, for refer(1) and related pages:

commit c913e9c5c2ae0958876426754b4eb85d9efe0049
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Fri Jan 17 19:47:34 2020 +1100

    man pages: note origins of refer(1) and friends

    * src/preproc/refer/refer.1.man:
    * src/utils/indxbib/indxbib.1.man:
    * src/utils/lkbib/lkbib.1.man:
    * src/utils/lookbib/lookbib.1.man: To "See Also" section of "refer" and
    related tools, add bibliographic reference to the original Bell Labs
    "refer" paper by Mike Lesk.

G. Branden Robinson <gbranden>
Project AdministratorIn charge of this item.
Sun 26 Jan 2020 02:05:54 AM UTC, original submission:  

Peter Schaffter says of refer(1):

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:

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):

  1. descriptions of internal strings like [A, [B, ... and registers generated by refer,
  2. mention of the citations formatting being taken care of by refer-ms.tmac, etc., if one uses the standard macro sets,
  3. 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.

Anonymous

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

     

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2020-07-25 gbranden CategoryMacro - others => Preprocessor refer
    2020-02-04 gbranden StatusNone => Confirmed
        Assigned toNone => gbranden

    Back to the top


    Powered by Savane 3.5