bugGNU roff - Bugs: bug #61014, [man] should support refer(1)

 
 

bug #61014: [man] should support refer(1)

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Thu 05 Aug 2021 08:21:33 AM UTC
   
 
Category:  Macro man Severity:  1 - Wish
Item Group:  Feature change Status:  None
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Thu 05 Aug 2021 09:55:36 AM UTC, comment #1: 

You did not yet explain what the advantage of implementing this feature would be, for authors or users.

As far as i understand, the point of refer(1) is that authors writing many academic papers can keep the papers they cite repeatedly in a database file and refer to them from multiple of their own papers without re-typing each reference for each use, also keeping track of literature relevant to their personal work independently of individual papers they publish.

Using refer(1) that way is not possible in man(7) because because manual pages cannot use information from external files, and even if they could, there would be no way to transfer the database file to users' machines, and even worse, when installing a new package containing a manual page containing a reference, the package manager would have to edit an existing database file to add the new reference, rather than merely copying new files onto the system.

Even if you propose that manual pages should use the "fields" form of citations only and not the "keywords" form, which would seem to kind of defeat the purpose of refer(1), i'm not sure what the point is.  Are you proposing that software developers should be required to learn yet another language (hello John!) just to be able to maintain manual pages?  If refer(1) is supported, some pages sooner or later will start using it, which means that individual maintainers don't have a choice wehther they want to use it: they have to use it if someone else added refer(1) code to a page they bump into.

Yes, manual pages do occasionally refer to books and other external sources, but not really frequently.  For example, in OpenBSD, i see on average less than 15 such citations per 100 manual pages.  So formatting such references by hand does not look like an undue burden to me, in particular in a language that is more presentational than semantic.  Requiring knowledge of the refer(1) langauge, which has about 75 documented syntax elements according to the GNU refer(1) manual page, certainly looks like more of a burden.

So i'm not yet quite sure what the advantage would be, but i do see a few downsides:

  • Right now, i'm not aware of any current roff(1) or man(1) implementation supporting refer(1) in man(7).  So some compatibility issues are likely to be expected.
  • If i understand correctly, field names in refer(1) are not really standardized but up to individual macro sets or even individual users.  Such flexibility is good for writing academic papers, but less so for manual pages where standardization across a wide variety of operating systems is paramount.
  • Authors who don't use refer(1) for their own publications are unlikely to use the new feature even when it is supported, so no uniform pattern of usage can be expected, not even in the very long term.
  • Authors who are used to employing refer(1) for their own work almost certainly have their own bibliographic database and may feel annoyed that they cannot use that but - contrary to their usual practice - need to copy the database records into each manual page.  They may even accidentally use the "keyword" syntax out of sheer habit, and since refer(1) on their system is likely configured to use their database, they may not even notice their error.  The man(7) macros certainly cannot catch it because by the time the man(7) macros get to see the file, it looks right to them because the refer(1) preprocessor has already run.


So, what's the point, really?

Ingo Schwarze <schwarze>
Group Member
Thu 05 Aug 2021 08:21:33 AM UTC, original submission:  

Historically, man(7) implementations supported refer(1).

We should too.

Not a high priority, but perhaps an interesting exercise for me (or some enthusiastic volunteer).

G. Branden Robinson <gbranden>
Group administrator

 

(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
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by gbranden (Submitted the item)
  •  

    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 2 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-04-01 barx Carbon-Copy- Added barx
    2022-01-11 gbranden Item GroupNone Feature change

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code