コミット: 1dd113b9870ccdebd88207f30ee752b67f5bde3c - groff-pdfmark (hg)

Reference Documentation: PDF Publishing with GNU Troff

コミットメタ情報

• リビジョン: 1dd113b9870ccdebd88207f30ee752b67f5bde3c (tree)
• 日時: 2024-10-11 04:38:50
• 作者: Keith Marshall <keith@user...>
• コミッター: Keith Marshall

ログメッセージ

Improve handling of groff special characters in sanitized text.

* tmac/sanitize.tmac (sanitize:esc-(hy): Redefine as a string, with
value equivalent to a single ASCII hyphen-minus; now used by...
(sanitize:esc(??.subst): ...this new macro; it handles substitutions
for two-character escapes of the form "\(??", on behalf of...
(sanitize:esc-(): ...this; add a sanity check, to ensure that the
input text residual comprises no fewer than two characters, as needed
to complete the "\(??" escape sequence; otherwise simplify, delegating
handling of the entire substitution operation to...
(sanitize:esc-(??.subst): ...this; it is also used by...
(sanitize:esc-[): ...this new macro; it also performs two-character
escape substitution, for the alternative groff "\[??]" form, such that
escapes of both "\(??" and "\[??]" forms are substituted congruently.
(sanitize:esc-(mi, sanitize:esc-(en): New strings; they define
substitutions for "\(mi" and "\(en", respectively; both are aliases...
(sanitize:esc-(hy): ...for this; thus all three result in substitution
of a single ASCII hyphen-minus glyph.
(sanitize:esc-(em): New string; it defines a substitution for the
"\(em" escape, such that it is replaced by a conjoined pair of ASCII
hyphen-minus glyphs.

変更サマリ

• modified: tmac/sanitize.tmac

差分

diff -r 7fb941487470 -r 1dd113b9870c tmac/sanitize.tmac
--- a/tmac/sanitize.tmac	Mon Oct 07 19:30:51 2024 +0100
+++ b/tmac/sanitize.tmac	Thu Oct 10 20:38:50 2024 +0100
@@ -81,12 +81,11 @@
 .      \"
 .         rn sanitize:scan.char sanitize:hold
 .         sanitize:scan.execute
-.         ie d sanitize:esc-\\*[sanitize:scan.char] \{\
-.         \"
-.         \" ...which we delegate to its appropriate handler, to skip...
-.         \"
-.            sanitize:esc-\\*[sanitize:scan.char]
-.         \}
+.
+.      \" ...to check for an identifiable escape sequence, which may be
+.      \" delegated to its appropriate handler...
+.      \"
+.         ie d \\*[sanitize:esc-handler] .\\*[sanitize:esc-handler]
 .
 .      \" ...but, in the case of an unrecognized escape sequence, we copy
 .      \" its backed-up content, followed by the character retrieved from
@@ -138,6 +137,11 @@
 .   if '!*[sanitize:scan.char]'\\' .ds sanitize:scan.char "^[\"
 .   ec
 ..
+.\" Define a shorthand notation for identification of the internal entry
+.\" point names of available escape sequence handlers.
+.\"
+.ds sanitize:esc-handler "sanitize:esc-\E*[sanitize:scan.char]\"
+.
 .
 .\" Filters for Removal and Substitution of Special Tokens
 .\" ------------------------------------------------------
@@ -357,6 +361,122 @@
 .      el .if '\\*[\\$1.try]'\\*[sanitize:scan.char]' .nr \\$1.matched 1
 .   \}
 ..
+.
+.\" Special Character Substitutions in Sanitized Text
+.\" -------------------------------------------------
+.\"
+.\" Special characters, as defined in groff_char(7), will usually not
+.\" be rendered reliably within sanitized text; thus, the sanitize macro
+.\" supports a simple substitution mechanism, for any speecial character
+.\" which is represented by a two-character escape name.  Specifically,
+.\" any such special character may be mapped, using a notation in the
+.\" style derived from their traditional troff "\(cc" representation,
+.\" similar the the sanitize:esc-(cc defaults, below.
+.\"
+.\" Define sanitized substitutions for "\(hy" and "\(em"; map them to
+.\" a single ASCII hyphen-minus, and a conjoined pair of hyphen-minus
+.\" glyphs, respectively.
+.\"
+.ds sanitize:esc-(hy -
+.ds sanitize:esc-(em --
+.
+.\" Translate "\(en" and "\(mi" as equivalents for "\(hy".
+.\"
+.als sanitize:esc-(en sanitize:esc-(hy
+.als sanitize:esc-(mi sanitize:esc-(hy
+.
+.\" Each of these substitutions is linked into the sanitize macro
+.\" processing sequence by one or other of two sanitize:esc-handler
+.\" conformantly named macros, sanitize:esc-( and sanitize:esc-[
+.\"
+.de sanitize:esc-(
+.\" Usage (internal): .sanitize:esc-(
+.\"
+.\" Handler for interpretation of special character escape sequences
+.\" which are expressed in the form "\(??"; the residual MUST comprise
+.\" at least two characters, to match this escape sequence format, or
+.\" the call is handled as a no-op.
+.\"
+.   if 2>\\n[sanitize:residual.length] .return
+.\"
+.\" Only when there are sufficient characters available, do we
+.\" attempt to interpret the escape sequence; when a substitution
+.\" has been defined, for the current input escape sequence, it
+.\" replaces the initial two characters of the residual.
+.\"
+.   \\$0??.subst \\$0 2
+.\"
+.\" Regardless of whether a substitution occurred, or not, the
+.\" preceding call will have created a local look-ahead buffer;
+.\" it may be safely discarded.
+.\"
+.   rm \\$0:look-ahead
+..
+.de sanitize:esc-[
+.\" Usage (internal): .sanitize:esc-[
+.\"
+.\" An analogue for sanitize:esc-(, this handles "\(??" two-character
+.\" escapes, which have been expressed in groff's alternative "\[??]"
+.\" format; just as sanitize:esc-( requires no fewer than two residual
+,\" characters, this requires no fewer than three of them, (one extra,
+.\" to match the closing "]"), or it becomes a no-op.
+.\"
+.   if 3>\\n[sanitize:residual.length] .return
+.\"
+.\" Only when there are sufficient characters available, do we attempt
+.\" to interpret the escape sequence; in this case, the third residual
+.\" character must be the closing "]"...
+.\"
+.   ds \\$0:look-ahead \\*[sanitize:residual]
+.   substring \\$0:look-ahead 2 2
+.\"
+.\" ...in which case, we may process any substitution which has been
+.\" defined, replacing the initial three characters of the residual,
+.\" while retaining any which extend beyond this initial three...
+.\"
+.   if '\\*[\\$0:look-ahead]']' .sanitize:esc-(??.subst \\$0 3
+.\"
+.\" ...and ultimately, discarding the local look-ahead buffer.
+.\"
+.   rm \\$0:look-ahead
+..
+.\" Each of this pair of sanitize:esc-handler macros delegates the
+.\" actual substitution to the sanitize:esc-(??.subst macro.
+.\"
+.de sanitize:esc-(??.subst
+.\" Usage (internal): .sanitize:esc-(??.subst caller count
+.\"
+.\" Perform substitution, if any is specified, for a two-character
+.\" escape, which has been expressed in either troff "\(??", or the
+.\" groff alternative "\[??]" format; in either case, a substitution
+.\" is available, only if a string named sanitize:esc-(?? has been
+.\" defined, with its actual "??" suffix matching the first two
+.\" characters of the sanitize:residual string.
+.\"
+.   ds \\$1:look-ahead \\*[sanitize:residual]
+.   substring \\$1:look-ahead 0 1
+.   if !d sanitize:esc-(\\*[\\$1:look-ahead] .return
+.
+.\" If we are still here, then a substitution has been identified;
+.\" process it, collecting an updated residual into the designated
+.\" look-ahead buffer...
+.\"
+.   ds \\$1:look-ahead \\*[sanitize:esc-(\\*[\\$1:look-ahead]]
+.   if \\n[sanitize:residual.length]>\\$2 \{\
+.   \" ...appending any part of the input residual, which extends
+.   \" beyond the end of the escape secuence...
+.   \"
+.      substring sanitize:residual \\$2
+.      as \\$1:look-ahead \\*[sanitize:residual]
+.   \}
+.
+.\" ...then ultimately, replacing the original residual with this
+.\" updated string value, and recomputing its length.
+.\"
+.   als sanitize:residual \\$1:look-ahead
+.   length sanitize:residual.length \\*[sanitize:residual]
+..
+.
 .de sanitize:skip-(
 .\" Usage (internal): .sanitize:skip-(
 .\"
@@ -388,28 +508,6 @@
 .      el .nr sanitize:skip.count 0
 .   \}
 ..
-.de sanitize:esc-(
-.\" Usage (internal): .sanitize:esc-(
-.\"
-.\" Handler for interpretation special character escape sequences,
-.\" which are expressed in the form "\(xx".
-.\"
-.   ds sanitize:look-ahead \\*[sanitize:residual]
-.   substring sanitize:look-ahead 0 1
-.   if d \\$0\\*[sanitize:look-ahead] .\\$0\\*[sanitize:look-ahead]
-.   rm sanitize:look-ahead
-..
-.de sanitize:esc-(hy
-.\" Usage (internal): .sanitize:esc-(hy
-.\"
-.\" Handler for translation of "\(hy" special character escapes
-.\" within sanitized PDF outline entries; each is replaced by an
-.\" (approximately) equivalent ASCII "-" character.
-.\"
-.   substring sanitize:residual 2
-.   ds sanitize:residual -\\*[sanitize:residual]
-.   nr sanitize:residual.length -1
-..
 .de sanitize:esc-generic
 .\" Usage (internal): .sanitize:esc-X
 .\"