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

[Ingo Schwarze]

Follow-up Comment #1, bug #61014 (project groff):

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?

    _______________________________________________________

Reply to this item at:

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

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