bugGNU roff - Bugs: bug #57667, rehabilitate refer(1)

 
 

bug #57667: rehabilitate refer(1)

Submitter:  None
Submitted:  Sun 26 Jan 2020 02:05:54 AM UTC
   
 
Category:  Preprocessor refer Severity:  3 - Normal
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 16 Aug 2023 05:59:43 AM UTC, comment #8: 

As Dave noted, we have a satisfied customer.

Per Oliver:

> The rephrased beginning to the refer man page communicates the key concept in a much more straightforward way than the old version --- thank you!


It looks like this commit was the main factor, though there were many subsequent ones.


commit 0ee49756cddc65f63363235513bfa194fc86aadb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Aug 3 00:19:35 2021 +1000

    [man pages]: Update preprocessor introductions.

    Make clarifications and parallelize discussions.  Try to require less
    troff foreknowledge.


I believe this is our first "fixed-in-1.23.0-but-we-didn't-know-that-at-the-time-of-release" ticket.

My beloved bugs-fixed statistic is now stale.  Oh no!

G. Branden Robinson <gbranden>
Group administrator
Sat 12 Aug 2023 07:15:00 PM UTC, comment #7: 

Oliver replied outside this bug but cc:ed to bug-groff: http://lists.gnu.org/r/bug-groff/2023-08/msg00149.html

> without the message to the mailing list the Savannah would have
> escaped my attention


Hmm, you should be on the cc list for this bug (as of June 29) and get automatic emails whenever it's updated.  There was a recent savannah bug with these autogenerated emails (sr #110918), but your cc entry doesn't seem to fall within that bug's problem space.  But if there's another savannah emailing bug, I'd like to chase it down.  On the other hand, if you didn't see the June 29 email when I posted comment #5, perhaps your spam filter ate it?

I presume you saw Branden's comment #6 email due to this cc entry, as the comment wasn't posted to the main groff list, and you're not subscribed to bug-groff.

Dave <barx>
Group Member
Sat 12 Aug 2023 06:43:19 AM UTC, comment #6: 

Oliver, can you respond to Dave's comment #5?

Is the refer(1) man page rehabilitated to a point of utility for you?

I'll add that I'm glad Piotr Piatrou found groff_mm(7) adequate as it existed four years ago; I found that I myself did not, so I whacked on it pretty good for groff 1.23.0.


$ COLUMNS=72 git di --stat 1.22.4 1.23.0 contrib/mm/groff_mm.7.man
 contrib/mm/groff_mm.7.man | 6049 +++++++++++++++++++++++--------------
 1 file changed, 3741 insertions(+), 2308 deletions(-)




G. Branden Robinson <gbranden>
Group administrator
Fri 30 Jun 2023 12:26:13 AM UTC, comment #5: 

Commit 0ee49756 polished the introduction of refer(1) (and other man pages).  It looks like this addresses the concern Oliver Corff raised in email (http://lists.gnu.org/r/groff/2021-05/msg00067.html); cc:ing him so he can provide feedback if he wishes.

Dave <barx>
Group Member
Wed 02 Mar 2022 07:37:42 PM UTC, comment #4: 

I'm not actively working on this.  Sorry.  :(

G. Branden Robinson <gbranden>
Group administrator
Wed 04 Aug 2021 07:54:47 AM UTC, comment #3: 

The bug's reporters should probably get email about its progress.  Adding them to its cc list.

Dave <barx>
Group Member
Mon 02 Aug 2021 02:51:10 PM UTC, comment #2: 

Some minor headway has been made here.


commit 9339aff304dd5206d77caf3fc06a097eb188c42d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Aug 3 00:10:02 2021 +1000

    refer(1): Fix content nit.

    groff man(7) doesn't support refer(1), but mom(7) does.

    troff: EXPERIMENTS/use-refer.man:7: warning: macro ']-' not defined
    troff: EXPERIMENTS/use-refer.man:15: warning: macro '][' not defined

    Addresses another point made in Savannah #57667.

commit 0db77de6a5e466ec506eee4b1e131f2bee8926df
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Aug 3 00:00:19 2021 +1000

    refer(1): Add "Examples" section.

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


G. Branden Robinson <gbranden>
Group administrator
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>
Group administrator
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 barx (commented in email)
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by barx (originally reported the bug)
  • -email is unavailable- added by barx (originally reported the bug)
  • -email is unavailable- added by gbranden (Posted a comment)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 13 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-08-16 gbranden StatusNeed Info Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
        Summaryrefer(1) rehab rehabilitate refer(1)
    2023-08-12 gbranden StatusNone Need Info
    2023-06-30 barx Carbon-Copy- Added -email is unavailable-
    2022-03-02 gbranden StatusIn Progress None
    2021-08-04 barx Carbon-Copy- Added ptpi
        Carbon-Copy- Added -email is unavailable-
    2021-08-02 gbranden StatusConfirmed In Progress
    2020-07-25 gbranden CategoryMacro - others/general Preprocessor refer
    2020-02-04 gbranden StatusNone Confirmed
        Assigned toNone gbranden

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code