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/
