From ba8b06a9d78f844cbdda4990545e3351bc06f4ca Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Sat, 13 Jan 2024 09:29:53 -0600 Subject: groff(7): Add "Postprocessor access" section. --- doc/groff.texi | 5 +- man/groff.7.man | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 178 insertions(+), 1 deletion(-) diff --git a/doc/groff.texi b/doc/groff.texi index 6e2e1cc3e..4ffb9cc20 100644 --- a/doc/groff.texi +++ b/doc/groff.texi @@ -16414,7 +16414,8 @@ returned by the function @cite{getenv@r{(3)}}. @c ===================================================================== -@c TODO: Add a corresponding section to groff(7). +@c BEGIN Keep (roughly) parallel with section "Postprocessor access" of +@c groff(7). @node Postprocessor Access, Miscellaneous, I/O, GNU troff Reference @section Postprocessor Access @cindex postprocessor access @@ -16505,6 +16506,8 @@ output format; their presence confuses drivers that do not know about it @DefreqListEndx {taga, name} Reserved for internal use. @endDefreq +@c END Keep (roughly) parallel with section "Postprocessor access" of +@c groff(7). @c ===================================================================== diff --git a/man/groff.7.man b/man/groff.7.man index 8bb3bfd84..63652fb63 100644 --- a/man/groff.7.man +++ b/man/groff.7.man @@ -7789,6 +7789,180 @@ copies a named environment's contents to the current one. . . .\" ==================================================================== +.SH "Postprocessor access" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Postprocessor +.\" Access". +Two escape sequences and two requests enable documents to pass +information directly to an output driver or other postprocessor. +. +These are useful for exercising device-specific capabilities that the +.I groff +language does not abstract or generalize; +examples include the embedding of hyperlinks and image files. +. +Device-specific functions are documented in each output driver's man +page, +such as +.MR gropdf @MAN1EXT@ , +.MR grops @MAN1EXT@ , +or +.MR grotty @MAN1EXT@ . +. +. +.P +The +.RB \[lq] device \[rq] +request and +.B \[rs]X +escape sequence embed their arguments into GNU +.I troff \" GNU +output as parameters to an +.RB \[lq] "x X" \[rq] +device control command +(see +.MR groff_out @MAN5EXT@ ). +. +The meaning and interpretation of such parameters is determined by the +output driver or other postprocessor. +. +. +.P +Within a device control command, +the escape sequences +.BR \[rs]& , +.BR \[rs]) , +.BR \[rs]% , +and +.B \[rs]: +are ignored; +.BI \[rs] space +and +.B \[rs]\[ti] +are converted to single space characters; +and @code{\\} has +.B \[rs]\[rs] +its escape character stripped. +. +So that the basic Latin subset of the Unicode character set +(that is, +ISO\~646:1991-IRV or, +popularly, +\[lq]US-ASCII\[rq]) +can be reliably encoded in device control commands, +seven special character escape sequences +.RB (\[lq] \[rs]\- \[rq], +.RB \[lq] \[rs][aq] \[rq], +.RB \[lq] \[rs][dq] \[rq], +.RB \[lq] \[rs][ga] \[rq], +.RB \[lq] \[rs][ha] \[rq], +.RB \[lq] \[rs][rs] \[rq], +and +.RB \[lq] \[rs][ti] \[rq]) +are mapped to basic Latin characters; +see +.MR groff_char @MAN7EXT@ . +. +For this transformation, +character translations and special character definitions are +ignored. +. +(They are bypassed because these parameters are not rendered as glyphs +in the output; +instead, +they remain abstract characters\[em]in a PDF bookmark or a URL, +for example.) +. +. +.P +Escape sequences other than the foregoing in device control command +may be ignored, +or produce an error. +. +. +.P +A device control command issued with the +.RB \[lq] device \[rq] +request will not be reflected in the output unless a partially collected +line exists at least once in the top-level diversion +(recall section \[lq]Diversions\[rq] above). +. +When experimenting with such device controls in minimal documents, +a +.B br +request +will ensure this to be the case. +. +. +.P +If the +.B use_charnames_in_special +directive appears in the output device's +.I DESC +file, +the use of special character escape sequences is +.I not +an error; +they are simply output verbatim +(with the exception of the seven mapped to Unicode basic Latin +characters, +discussed above). +. +.B use_charnames_in_special +is currently employed only by +.MR grohtml @MAN1EXT@ . +. +. +.P +GNU +.I troff \" GNU +also permits the interpolatation of macro contents as a device control +command. +. +The +.B devicem +request +and +.B \[rs]Y +escape sequence are approximately equivalent to +.RB \[lq] \[rs]X\[aq]\c +.IB name \[aq]\c +\[rq]. +. +However, +the contents of the string or macro +.I name +are not interpreted; +it is also permitted for +.I name +to have been defined as a macro and thus contain newlines. +. +(There is no way to embed a newline +in the arguments to +.RB \[lq] device \[rq] +or +.BR \[rs]X .) +. +The inclusion of newlines requires an extension to the AT&T +.I troff \" AT&T +output format; +their presence confuses drivers that do not know about it +(see subsection \[lq]Device control commands\[rq] of +.MR groff_out @MAN5EXT@ ). +. +. +.P +The +.B tag +and +.B taga +requests are reserved for internal use. +.\" END Keep (roughly) parallel with groff.texi node "Postprocessor +.\" Access". +. +. +.\" ==================================================================== .SH Underlining .\" ==================================================================== . -- cgit v1.2.3