groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

MR macro for man page cross references added to man(7)


From: G. Branden Robinson
Subject: MR macro for man page cross references added to man(7)
Date: Tue, 5 Oct 2021 22:38:28 +1100
User-agent: NeoMutt/20180716

Hi all,

I'm pleased to announce the addition, in discussion for over a year[1],
of a new semantic macro for the GNU implementation of man(7), prompted
by and compatible with Plan 9 troff, for man page cross references: MR.

The OSC 8 work on grotty(1), announced earlier this week, laid the
foundation for this work, enabling us to deliver true hyperlinked cross
references for output drivers other than grohtml, as opposed to mere
typeface changes.

Because man(7) culture is conservative, I have summarized the multiple
rationales for and expected benefits of this change in its NEWS item.

o The an (man) macro package supports a new macro, "MR", intended for
  use by man page cross references in preference to the font style
  alternation macros historically used.  Where before you would write
    .BR ls (1).
  or
    .IR ls (1).
  you should now write
    .MR ls 1 .
  (the third argument, typically used for trailing punctuation, is
  optional).  Because the macro semantically identifies a man page, it
  also creates a clickable hyperlink ("man:ls(1)" for the above example)
  on supporting devices.  A new string, MF, defines the font to be used
  for setting man page titles (the first argument to .MR and .TH),
  permitting its configuration by distributions, sites, and users.

  The MR macro is offered for compatibility with Plan 9 troff, which
  introduced it in August 2020, and to ameliorate several long-standing
  problems with man page cross references: (1) the package's lack of
  inherent hyperlink support for them; (2) false-positive identification
  of strings resembling man page cross references (as can happen with
  "exit(1)", "while(1)", "sleep(5)", "time(0)" and others) by terminal
  emulators and other programs; (3) the unwanted intrusion of hyphens in
  man page names, which frustrates copy-and-paste operations (this
  problem has always been avoidable through use of the \% escape
  sequence, but cross references are frequent in man pages and some page
  authors are inexpert *roff users); and (4) deep divisions in man page
  maintenance communities over which typeface should be used to set the
  man page title (italics, roman, or bold).

Here's the documentation of this feature in groff_man_style(7)
(groff_man(7) omits the examples and differs slightly in wording).

[...]
   Hyperlink macros
       Man page cross references like ls(1) are best presented with .MR.
       Email addresses are bracketed with .MT/.ME and other forms of hy‐
       perlink with .UR/.UE.  Hyperlinked text is supported on the  html
       and tty output devices; terminals and pager programs must support
       EMCA-48 OSC 8 escape sequences (see grotty(1)).  When device sup‐
       port  is unavailable or disabled with the U register (see section
       “Options” below), .MT and .UR URIs are rendered after the  linked
       text.

       .MT,  .ME, .UR, and .UE are GNU extensions not defined on systems
       running AT&T, Plan 9, or Solaris troff; see an-ext.tmac  in  sec‐
       tion “Files” below.  Plan 9 troff implements .MR.

       .MR page-title page-section [trailing-text]
              Set  a  man  page cross reference as “page-title(page-sec‐
              tion)”.  If trailing-text (typically punctuation) is spec‐
              ified, it follows the closing parenthesis  without  inter‐
              vening  space.   Hyphenation  is  disabled while the cross
              reference is set.  page-title is set in the font specified
              by the MF string.  The cross reference hyperlinks to a URI
              of the form “man:page-title(page-section)”.

                     The output driver
                     .MR grops 1
                     produces Postscript from
                     .I troff
                     output.
                     .
                     The Ghostscript program (\c
                     .MR gs 1)
                     interprets Postscript and PDF.
[...]
Options
       The following groff options set registers (with -r)  and  strings
       (with -d) recognized and used by the man macro package.
[...]
       -dMF=man-page-title-font
              Set the font used for man page titles named in .TH and .MR
              calls; the default is “I” (italic).  Any valid argument to
              groff’s “.ft” request may be used; see groff(7).   If  the
              MF  string  ends  in  “I”,  it is assumed to be an oblique
              typeface, and italic corrections are  applied  before  and
              after man page titles.
[...]
Files
[...]
       /usr/local/share/groff/1.23.0/tmac/an-ext.tmac
              The  extension  macro  definitions  for  .SY,  .YS,   .TQ,
              .EX/.EE,  .UR/.UE, and .MT/.ME are contained in this file;
              if the formatter is not GNU troff, it also provides an .MR
              implementation that does not attempt hyperlinking.   These
              macros  are  written  to be compatible with AT&T troff and
              permissively licensed—not copylefted.
[...]

I'll start migrating our own man pages from .BR and .IR to .MR in the
coming days.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2020-08/msg00068.html
    https://lists.gnu.org/archive/html/groff/2021-07/msg00132.html

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]