[groff] 27/31: groff(1) (Preprocessors): Revise.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 647bb68d842119a064c904862cbd05a8fe26b5c9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jul 25 15:07:11 2021 +1000

    groff(1) (Preprocessors): Revise.
    
    * Explain what a (roff) preprocessor is and what it (typically) does.
    * Recast to recognize that much of GNU roff is a reimplementation of
      older programs.
    * Recast for clarity.
    * Drop language about preprocessors that "aren't visible to the user".
      That's out of scope for this man page.  It is not a manifest, though
      it does somewhat resemble one in places.  :-/
---
 src/roff/groff/groff.1.man | 76 ++++++++++++++++++++++++++++++----------------
 1 file changed, 49 insertions(+), 27 deletions(-)

diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 1713249..6f01c1a 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -856,68 +856,90 @@ command line to format a document.
 .SS Preprocessors
 .\" ====================================================================
 .
-The
-.I groff
-preprocessors are reimplementations of the classical preprocessors
-with moderate extensions.
+A preprocessor is an interpreter of a domain-specific language that
+produces
+.I roff
+language output.
 .
-The standard preprocessors distributed with the
-.I groff
-package are
+Frequently,
+such input is confined to sections or regions of a
+.I roff
+input file
+(bracketed with macro calls specific to each preprocessor),
+which it replaces.
+.
+Preprocessors therefore often interpret a subset of
+.I roff
+syntax along with their own language.
 .
+GNU
+.I roff
+provides reimplementations of most preprocessors familiar to users of
+AT&T
+.IR troff ; \" AT&T
+these routinely have extended features and/or require GNU
+.I troff \" GNU
+to format their output.
+.
+Preprocessors distributed with GNU
+.I roff
+include
+.
+.
+.RS
 .TP
 .IR \%@g@eqn (@MAN1EXT@)
 for mathematical formulae,
 .
+.
 .TP
 .IR \%@g@grn (@MAN1EXT@)
-for including
+for pictures in
 .IR gremlin (1)
-pictures,
+format,
+.
 .
 .TP
 .IR \%@g@pic (@MAN1EXT@)
-for drawing diagrams,
+for diagrams,
+.
 .
 .TP
 .IR \%@g@chem (@MAN1EXT@)
 for chemical structure diagrams,
 .
+.
 .TP
 .IR \%@g@refer (@MAN1EXT@)
 for bibliographic references,
 .
+.
 .TP
 .IR \%@g@soelim (@MAN1EXT@)
 to preprocess files included with
-.I groff \" language
+.I roff \" language
 .B .so
-requests.
-.
-.P
+requests,
 and
 .
+.
 .TP
 .IR \%@g@tbl (@MAN1EXT@)
 for tables.
+.RE
+.
 .
 .P
-A new preprocessor not available in classical
-.I troff
+A preprocessor unique to GNU
+.I roff
 is
-.IR \%preconv (@MAN1EXT@)
-which converts various input encodings to something
-.I groff
+.IR \%preconv (@MAN1EXT@),
+which converts various input encodings to something GNU
+.I troff \" GNU
 can understand.
 .
-It is always run first before any other preprocessor.
-.
-.P
-Besides these,
-there are some internal preprocessors that are
-automatically run with some devices.
-.
-These aren't visible to the user.
+When used,
+it is run before any other preprocessors.
 .
 .
 .\" ====================================================================