[bug #58946] [ms] adapt to use the facilities of pdfmark

[Keith Marshall]

Follow-up Comment #9, bug #58946 (project groff):

Ignoring those intended exclusively for internal use, (which I've elided from
the following), in spdf.tmac I see:

$ hg grep -r qparent '^\. *de ' spdf.tmac
contrib/pdfmark/spdf.tmac:5357:.de OMIT OMIT
contrib/pdfmark/spdf.tmac:5357:...
contrib/pdfmark/spdf.tmac:5357:.de XM
contrib/pdfmark/spdf.tmac:5357:.de XR
contrib/pdfmark/spdf.tmac:5357:.de XN
contrib/pdfmark/spdf.tmac:5357:...
contrib/pdfmark/spdf.tmac:5357:.de LU
contrib/pdfmark/spdf.tmac:5357:.de AN
contrib/pdfmark/spdf.tmac:5357:...
contrib/pdfmark/spdf.tmac:5357:.de OP
contrib/pdfmark/spdf.tmac:5357:.de NN
contrib/pdfmark/spdf.tmac:5357:...
contrib/pdfmark/spdf.tmac:5357:.de PXREF
contrib/pdfmark/spdf.tmac:5357:.de IS
contrib/pdfmark/spdf.tmac:5357:.de IE
contrib/pdfmark/spdf.tmac:5357:.de TC
contrib/pdfmark/spdf.tmac:5357:...

Of these, OMIT, OP, and TC are required to support the partitioned document
assembly mechanism of pdfroff.sh; as such, I would suggest that they should
remain in spdf.tmac.

Of the remainder, perhaps only XN, (with modification), is worthy of
consideration as a strictly necessary adjunct, and maybe XR as a convenient
addition.  All of the rest are essentially redundant, and may even be
worthless!  Here's what they do:

XN: sets its arguments as text, for use within the numbered heading following
NH, additionally using the same text as the content of a PDF document outline
entry, and within a TOC entry.  The modification, which I propose, is that
formatting of the TOC entry should be delegated to a user-defined callback
macro, (hence a document-local macro).  I also propose adding a complementary
XH macro, serving a similar purpose following SH.

XR: creates a ".pdfhref L" reference to a named destination, using semantics
similar to ms .B, or .I, with \$1 as the destination name, \$2 as argument to
the pdfhref "-A" option, and \$3 as argument to "-P"; reference text is
derived from the reference dictionary entry, created by ".pdfhref M".  If
deemed worthy of retention, maybe consider modification, to allow additional
arguments beyond \$3, to specify reference text.

XM: strict shorthand for ".pdfhref M -X".  Certainly not necessary.  If any
user wants such shorthand, I think it really should be defined locally to
their own document.

LU: surely not worthy of inclusion; it inserts an LP paragraph, stating — in
English — that content is to be added at some unspecified future time! 
Should be document-local, if wanted.

AN: inserts an SH heading, with default text "Note", but taking an optional
argument to override that.  It originates from my workplace documents, where I
used to introduce note, or warning annotations, or similar.  In hindsight, I
think I should have made it document-local.

NN: a contraction of NH, followed by XN, with some added bells and whistles. 
IIRC, I wrote this for one particular workplace document template; I
definitely should have kept it local.

PXREF: a parenthetical variation of XR; should be document-local.

IS:
IE: utterly useless.  Do much the same as QS...QE, which should be used
instead

    _______________________________________________________

Reply to this item at:

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

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