コミット: 7fb941487470b7d236080e148971ecf149d072d2 - groff-pdfmark (hg)

Reference Documentation: PDF Publishing with GNU Troff

コミットメタ情報

• リビジョン: 7fb941487470b7d236080e148971ecf149d072d2 (tree)
• 日時: 2024-10-08 03:30:51
• 作者: Keith Marshall <keith@user...>
• コミッター: Keith Marshall

ログメッセージ

Improve filtering of groff special tokens from sanitized text.

* tmac/sanitize.tmac (sanitize:scan.reject): New string; with
default value of "'\&\%\:'", it specifies a list of groff special
tokens, enclosed within a matching pair of arbitrary delimiting
tokens, ("'" in this default case), which are to be filtered out
of sanitized text, and thus discarded from this context.
(sanitize:scan.subst): New string; with default value comprising
the space-separated list of quoted macro arguments, "'\-'-'",
and "'\ \~' '", this specifies a collection of special token
substitution groups, arbitrarily delimited by the "'" token.
(sanitize:scan.filter): New macro; called by...
(sanitize): ...this, it interprets, and applies the effect of...
(sanitize:scan.reject, sanitize:scan.subst): ...these filters.

変更サマリ

• modified: tmac/sanitize.tmac

差分

diff -r c2eeb7bfb7e2 -r 7fb941487470 tmac/sanitize.tmac
--- a/tmac/sanitize.tmac	Thu Oct 03 23:25:46 2024 +0100
+++ b/tmac/sanitize.tmac	Mon Oct 07 19:30:51 2024 +0100
@@ -29,6 +29,12 @@
 with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ..
+.\" Package Entry Point
+.\" -------------------
+.\"
+.\" All access to the capabilities of this package should be directed
+.\" through the sanitize macro; implement it.
+.\"
 .de sanitize
 .\" Usage: .sanitize name text ...
 .\"
@@ -66,23 +72,12 @@
 .   \" have been replaced by the string "^["; if this string has been
 .   \" returned, we prepare to handle an escape sequence...
 .   \"
-.      ie '\\*[sanitize:scan.char]'^[' .nr sanitize:skip.count 1
-.      el .if '\\*[sanitize:scan.char]'\%' \{\
-.          \" The "\%" escape requires special handling; assuming
-.          \" that it will never be used to introduce a hyphen into
-.          \" a PDF outline entry, it may simply be discarded, by
-.          \" the expedient of handling it as if it is equivalent
-.          \" to an artificial "\F%" escape sequence.
-.          \"
-.             ds sanitize:residual F%\\*[sanitize:residual]
-.             nr sanitize:residual.length +2
-.             nr sanitize:skip.count 1
-.         \}
-.      ie \\n[sanitize:skip.count] \{\
+.      ie '\\*[sanitize:scan.char]'^[' \{\
+.         nr sanitize:skip.count 1
+.
 .      \" When a possible escape sequence has been detected, we back it
 .      \" up, (in case it isn't recognized, and we need to reinstate its
-.      \" content into the result string), then scan ahead to check for
-.      \" an identifiable escape sequence...
+.      \" content into the result string), then scan ahead...
 .      \"
 .         rn sanitize:scan.char sanitize:hold
 .         sanitize:scan.execute
@@ -102,14 +97,10 @@
 .
 .   \" When the current scan cycle has retrieved a character, which isn't
 .   \" part of any possible escape sequence, we simply copy that character
-.   \" to the result string; map escapes such as "\ ", "\~", and "\0" to
-.   \" simple ASCII SP, and "\-" to ASCII hyphen-minus, as we go.
+.   \" to the result string, while processing any special token removals,
+.   \" or substitutions, as we go.
 .   \"
-.      el \{\
-.         ie '\\*[sanitize:scan.char]'\-' .ds sanitize:scan.char "-\"
-.         el .sanitize:scan-space-token.remap "\ " "\~" "\0"
-.         as sanitize:result "\\*[sanitize:scan.char]\"
-.      \}
+.      el .sanitize:scan.filter \\*[sanitize:scan.reject]
 .   \}
 .
 .\" Clean up the register space, by deleting all of the string registers,
@@ -147,21 +138,223 @@
 .   if '!*[sanitize:scan.char]'\\' .ds sanitize:scan.char "^[\"
 .   ec
 ..
-.de sanitize:scan-space-token.remap
-.\" Usage (internal): .sanitize:scan-space-token.remap space-token ...
+.
+.\" Filters for Removal and Substitution of Special Tokens
+.\" ------------------------------------------------------
 .\"
-.\" This internal helper macro maps any groff escape token which becomes
-.\" a space, within formatted output, to an ASCII SP in sanitized text.
+.ds sanitize:scan.reject "'\&\%\:'\"
+.ds sanitize:scan.subst ""'\-'-'" "'\ \~' '"\"
+.
+.\" Note that both of these are handled by a common filter processing
+.\" macro, with the REJECT filters being converted to their equivalent
+.\" SUBST filters, each with an empty substitution field.
+.\"
+.de sanitize:scan.filter
+.\" Usage (internal): .sanitize:scan.filter <reject-list> ...
+.\"
+.\" Handler for processing of any input token, when the sanitize
+.\" macro has determined that it does contribute to any part of a
+.\" normal escape sequence; (it may, however, represent any of the
+.\" special escape sequences, which is encoded in copy mode, as a
+.\" single input token).
 .\"
 .   while \\n(.$ \{\
-.      if '\\$1'\\*[sanitize:scan.char]' \{\
-.      \" The current input character matches one of the specified
-.      \" space tokens; substitute and return a simple ASCII SP.
+.   \" Each passed <reject-list> argument must comprise a string
+.   \" of individual tokens, enclosed in a matching pair of other
+.   \" arbitrary tokens, which do not otherwise appear in the list;
+.   \" convert each to a token substitution group specification,
+.   \" in which the substitute text is an empty string.
+.   \"
+.      length \\$0.arglen \\$1
+.      if \\n[\\$0.arglen]>2 \{\
+.      \" Note that any valid <reject-list> argument MUST comprise
+.      \" AT LEAST two delimiter tokens, and ONE OR MORE additional
+.      \" tokens, which form the <reject-list> content; beyond this
+.      \" minimum length limitation, the integrity of <reject-list>
+.      \" arguments is NOT verified at this stage; the integrity of
+.      \" each WILL be checked, only on subsequent evaluation of
+.      \" its corresponding substitution group specification.
 .      \"
-.         ds sanitize:scan.char " \"
-.         return
+.         ie d \\$0.arglist .as \\$0.arglist "\\*[\\$0.delimiter]" "\\$1\"
+.         el .ds \\$0.arglist ""\\$1\"
+.
+.      \" The delimiter token, for the current <reject-list> string,
+.      \" is the first token in this specification string; capture
+.      \" it, so that it may subsequently be duplicated at the end
+.      \" of a copy of the string, so completing the correspondingly
+.      \" generated substitution group specification.
+.      \"
+.         ds \\$0.delimiter "\\$1\"
+.         substring \\$0.delimiter 0 0
 .      \}
-.      shift    \" try matching the next specified escape, if any.
+.   \" Repeat for the next <reject-list> argument, if any.
+.   \"
+.      shift
+.   \}
+.\" When finished conversion of <reject-list> arguments, we have no
+.\" further use for the argument length check...
+.\"
+.   rr \\$0.arglen
+.
+.\" ...but we do still need to properly terminate the last of any
+.\" substitution group specifications, which were generated, or if
+.\" none were, then define an empty set of substitution groups.
+.\"
+.   ie d \\$0.arglist .as \\$0.arglist "\\*[\\$0.delimiter]"
+.   el .ds \\$0.arglist "\"
+.
+.\" Ultimately, hand off the filter activity to the designated
+.\" sub-handler, and clean up the local namespace.
+.\"
+.   \\$0.execute \\*[\\$0.arglist] \\*[sanitize:scan.subst]
+.   rm \\$0.arglist \\$0.delimiter
+..
+.de sanitize:scan.filter.execute
+.\" Usage (internal): .sanitize:scan.filter.execute <subst-group> ...
+.\"
+.\" Sub-handler, called by sanitize:scan:filter, to complete matching
+.\" of the current sanitize:scan.char, in the context of all specified
+.\" substitution group arguments.
+.\"
+.\" Initially assuming that no filter specification is applicable...
+.\"
+.   nr \\$0.matched 0
+.
+.\" ...check each given filter specification in turn, until we either
+.\" identify one which matches sanitize:scan.char, or we exhaust ALL
+.\" of those given, without finding any match.
+.\"
+.   while \\n(.$ \{\
+.   \" For each given filter specification, begin by performing a
+.   \" rudimentary check, to ensure that it comprises no fewer than
+.   \" the minimum number of tokens required for validity.
+.   \"
+.      length \\$0.arglen \\$1
+.      if \\n[\\$0.arglen]>3 \{\
+.      \" Any valid substitution group specification MUST comprise
+.      \" EXACTLY THREE identical delimiter tokens, and AT LEAST ONE
+.      \" additional token, to be matched as a substitution candidate;
+.      \" when this minimum length requirement is satisfied, capture
+.      \" the delimiter, (which is the first token specified), for
+.      \" subsequent matching...
+.      \"
+.         ds \\$0.delimiter "\\$1\"
+.         substring \\$0.delimiter 0 0
+.
+.      \" ...and remove it from the specification, the length of which
+.      \" must consequently be reduced by one, prior to initiation of a
+.      \" progressive scan for a substitutable token match, (which may
+.      \" be identified by a phase ZERO invocation of the associated
+.      \" evaluation sub-handler macro).
+.      \"
+.         nr \\$0.arglen -1
+.         ds \\$0.specification "\\$1\"
+.         \\$0.eval \\$0 0
+.
+.      \" Regardless of the resulting phase ZERO evaluation state, a
+.      \" further phase ONE evaluation is required, to completely scan
+.      \" the filter specification, and subsequently check that it is
+.      \" well-formed; to facilitate this, we must clear the residual
+.      \" delimiter match indication, (remaining after matching the
+.      \" delimiter between the token list and substitution fields),
+.      \" so that we may subsequently confirm that a substitution
+.      \" field is both present, and properly terminated.
+.      \"
+.      \" Additionally, when an applicable specification has been
+.      \" identified, the original content of sanitize:scan.char MUST
+.      \" be cleared, to prepare it for accumulation of the substitute
+.      \" text, during the phase ONE scan.
+.      \"
+.         ds \\$0.try "\"
+.         if \\n[\\$0.matched] .ds sanitize:scan.char "\"
+.         \\$0.eval \\$0 1
+.
+.      \" After completing this phase ONE evaluation, we should again
+.      \" have identified a closing delimiter token, with NO residual
+.      \" content in the specification string; if this isn't the case,
+.      \" then the specification is malformed, so diagnose it.
+.      \"
+.         ds \\$0.warn "tm sanitize:warning:\\$1: \\\\$* delimiter\"
+.         if !'\\*[\\$0.try]'\\*[\\$0.delimiter]' .\\*[\\$0.warn missing]
+.         if \\n[\\$0.arglen] .\\*[\\$0.warn junk after closing]
+.
+.      \" After evaluation of each specification, as necessary, clean
+.      \" up the local namespace temporary storage.
+.      \"
+.         rm \\$0.specification \\$0.delimiter \\$0.try \\$0.warn
+.      \}
+.
+.   \" As soon as we have identified an applicable filter specification,
+.   \" then that applies, to the exclusion of all others, so there is no
+.   \" need to consider any more...
+.   \"
+.      ie \\n[\\$0.matched] .shift \\n(.$
+.
+.   \" ...but until such a filter has been identifed, simply discard the
+.   \" most recently evaluated, and proceed to evaluate the next given,
+.   \" if any remain.
+.   \"
+.      el .shift
+.   \}
+.
+.\" When ALL necessary specifications have been evaluated, we may also
+.\" clean up the local namespace temporary counters, and flags.
+.\"
+.   rr \\$0.arglen \\$0.matched
+.
+.\" Regardless of whether a substitution has been performed, (even if it
+.\" has been derived from a malformed specification), or not, whatever
+.\" content remains in sanitize:scan.char must be appended to the result
+.\" string, which is to be returned by the sanitize macro.
+.\"
+.   as sanitize:result "\\*[sanitize:scan.char]\"
+..
+.de sanitize:scan.filter.execute.eval
+.\" Usage (internal): .sanitize:scan.filter.execute.eval <caller> <phase>
+.\"
+.\" Internal sub-handler for parsing of substitution filter specifications;
+.\" the <caller> argument specifies the name of the calling macro, (which is
+.\" nominally ALWAYS sanitize:scan.filter.execute), while the <phase> value
+.\" is ZERO when scanning the initial token list field, within each filter
+.\" specification, and ONE when parsing the substitution field.
+.\"
+.\" On entry, the caller's ".arglen" property specifies the number of tokens,
+.\" within the active filter specification, which remain to be parsed; the
+.\" caller has already evaluated the first of these, while assigning it to
+.\" its ".delimiter" property...
+.\"
+.   while \\n[\\$1.arglen] \{\
+.   \"
+.   \" ...so, immediately discard it...
+.   \"
+.      nr \\$1.arglen -1
+.      substring \\$1.specification 1
+.   \"
+.   \" ...and move on, capturing the next available token for evaluation...
+.   \"
+.      ds \\$1.try "\\*[\\$1.specification]\"
+.      substring \\$1.try 0 0
+.   \"
+.   \" ...terminating this evaluation phase, as soon as a token match for
+.   \" the caller's ".delimiter" property is encounered.
+.   \"
+.      if '\\*[\\$1.try]'\\*[\\$1.delimiter]' .return
+.
+.   \" If we're still here, then we have an new non-delimiter token which
+.   \" is to be evaluated; if this is in phase ONE, and the current filter
+.   \" has been activated by a prior token match in phase ZERO, then this
+.   \" token must be appended to the current sanitize:result...
+.   \"
+.      ie \\$2 .if \\n[\\$1.matched] .as sanitize:scan.char "\\*[\\$1.try]\"
+.
+.   \" ...otherwise, while in evaluation phase ZERO, we check for a token
+.   \" match to the current sanitize:scan.char, setting the active state
+.   \" for the current filter, on finding such a match, and then continue
+.   \" to scan ahead, until a delimiter match terminates the scan, or (in
+.   \" the case of a malformed filter specification), no tokens remain to
+.   \" be evaluated.
+.   \"
+.      el .if '\\*[\\$1.try]'\\*[sanitize:scan.char]' .nr \\$1.matched 1
 .   \}
 ..
 .de sanitize:skip-(