groff(7): Add "Postprocessor access" section.

2 files changed, 178 insertions, 1 deletions

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
 .\" ====================================================================
 .