[groff] 05/05: man/groff_diff.7.man: Resynchronize with Texinfo.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e74f90e5c888db8ad8c68c80fe304bd7d85355fd
Author: G. Branden Robinson <address@hidden>
AuthorDate: Thu Apr 16 21:27:51 2020 +1000

    man/groff_diff.7.man: Resynchronize with Texinfo.
    
    Rename section from "Incompatibilities" to "Implementation Differences"
    to match Texinfo manual.
    
    Drop subsection heading "groff language".  It wasn't doing much real
    work, as the only other subsection, "Intermediate output", is not very
    developed (and contains some stale forward-looking comments).
    
    The synchrony was not slavish.  I have the following observations:
    
    * The term "groff" is used in man pages; the Texinfo manual uses "GNU
      troff".  (Interestingly, "GNU" is never wrapped in an @acronym{} macro
      despite the relentless consistency of its application to other
      acronyms, and even initialisms that are not pronounceable words--i.e.,
      non-acronyms.)
    
    * The man pages use the term "roff" to refer to the family of
      languages devised at Bell Labs in descent from Jerome Saltzer's
      "runoff"; the Texinfo manual does not follow this practice.
    
    * Organizational distinctions are retained.  The Texinfo manual arranges
      material about requests and escapes thematically by function; the man
      pages tend to organize such material lexicographically by syntactical
      category.
    
    * Different quotation conventions arise from Texinfo's use of semantic
      markup and assumption of the availability of different font families
      versus man pages' limitation to one font family and three face styles.
    
    * Similarly, in man pages, references to roff requests and escapes tend
      to be prefixed with the appropriate sigil, and string and number
      registers by the syntactic expression used to dereference them.  In
      Texinfo the former are generally "naked", marked up only with @code{}.
      @samp{}s or examples are used for multi-term expressions, however.
    
    * Texinfo supports footnotes and man pages don't.  Parenthetical asides
      are used in man pages instead.
    
    My preference would be to migrate the Texinfo manual to the established
    man page conventions for the first two items and leave the rest alone.
---
 man/groff_diff.7.man | 389 +++++++++++++++++++++++++++++----------------------
 1 file changed, 225 insertions(+), 164 deletions(-)

diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index c9b49c0..79e0345 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3726,118 +3726,151 @@ The first three output commands are guaranteed to be:
 .
 .
 .\" ====================================================================
-.SH Incompatibilities
-.\" ====================================================================
-.
-In spite of the many extensions, groff has retained compatibility to
-classical troff to a large degree.
-.
-For the cases where the extensions lead to collisions, a special
-compatibility mode with the restricted, old functionality was created
-for groff.
-.
-.
-.\" ====================================================================
-.SS "groff language"
+.SH "Implementation Differences"
 .\" ====================================================================
 .
 .I groff
-provides a
-.B compatibility mode
-that allows the processing of roff code written for classical
-.B troff
-or for other implementations of roff in a consistent way.
+has a number of features that cause incompatibilities with documents
+written using old versions of
+.IR roff .
 .
-.P
-Compatibility mode can be turned on with the
-.B \-C
-command-line option, and turned on or off with the
-.B .cp
-request.
+Some GNU extensions to
+.I roff
+have become supported by other implementations.
 .
-The number register
-.B \[rs]n(.C
-is\~1 if compatibility mode is on, 0\~otherwise.
 .
 .P
-This became necessary because the GNU concept for long names causes
-some incompatibilities.
-.I Classical troff
-interprets
-.IP
-.B .dsabcd
+Long names may be the most obvious innovation.
 .
-.P
+.RI AT&T\~ troff
+interprets
+.RB \[lq] .dsabcd \[rq]
 as defining a string
-.B ab
+.RB \[lq] ab \[rq]
 with contents
-.BR cd .
-In
+.RB \[lq] cd \[rq].
+.
+Normally,
 .I groff
-mode, this is considered as a call of a macro named
-.BR dsabcd .
+interprets this as a call of a macro named
+.RB \[lq] dsabcd \[rq].
 .
-.P
-Also
-.I classical troff
-interprets
+.RI AT&T\~ troff
+also interprets
 .B \[rs]*[
-or
+and
 .B \[rs]n[
-as references to a string or number register called\~\c
-.B [
-while
+as a reference to a string or number register,
+respectively,
+called
+.RB \[lq] [ \[rq].
+.
+In
+.IR groff ,
+however,
+the
+.RB \[lq] [ \[rq]
+is normally interpreted as delimiting a long name.
+.
+In compatibility mode,
 .I groff
-takes this as the start of a long name.
+interprets names in the traditional way,
+which means that they are limited to one or two characters.
+.
 .
 .P
-In
-.IR "compatibility mode" ,
-groff interprets these things in the traditional way; so long
-names are not recognized.
+See the
+.B \-C
+option in
+.IR groff (@MAN1EXT@)
+and,
+above,
+the
+.B .C
+register
+and
+.B .cp
+and
+.B .do
+requests for more on compatibility mode.
+.
 .
 .P
-On the other hand, groff in
-.I GNU native mode
-does not allow to use the single-character escapes
-.B \[rs]\[rs]
-(backslash),
-.B \[rs]|
-(vertical bar),
-.B \[rs]\[ha]
-(caret),
-.B \[rs]&
-(ampersand),
-.B \[rs]{
-(opening brace),
-.B \[rs]}
-(closing brace),
-.RB \[oq] \[rs]\  \[cq]
-(space),
-.B \[rs]\[aq]
-(single quote),
-.B \[rs]\[ga]
-(backquote),
-.B \[rs]\-
-(minus),
-.B \[rs]_
-(underline),
-.B \[rs]!\&
-(bang),
-.B \[rs]%
-(percent),
+Normally,
+.I groff
+preserves the input level in delimited arguments,
+but not in compatibility mode.
+.
+For example,
+on terminal devices,
+.RS
+.EX
+\&.ds xx \[aq]
+\&\[rs]w\[aq]abc\[rs]*(xxdef\[aq]
+.EE
+.RE
+produces \[lq]168\[rq] ordinarily,
+but \[lq]72def\[aq]\[rq] in compatibility mode.
+.
+.
+.P
+Furthermore,
+the escapes
+.BR \[rs]f ,
+.BR \[rs]H ,
+.BR \[rs]m ,
+.BR \[rs]M ,
+.BR \[rs]R ,
+.BR \[rs]s ,
 and
-.B \[rs]c
-(character\~c) in names of strings, macros, diversions, number
-registers, fonts or environments, whereas
-.I classical troff
-does.
+.BR \[rs]S
+transparent for recognizing the beginning of a line only in
+compatibility mode.
+.
+For example,
+this code produces bold output in both cases,
+but the text differs,
+.RS
+.EX
+\&.de xx \[aq]
+Hello!
+\&..
+\&\[rs]fB.xx\[rs]fP
+.EE
+.RE
+producing \[lq].xx\[rq] in normal mode and \[lq]Hello!\[rq] in
+compatibility mode.
+.
 .
 .P
+.I groff
+does not allow the use of the escape sequences
+.BR \[rs]| ,
+.BR \[rs]\[ha] ,
+.BR \[rs]& ,
+.BR \[rs]{ ,
+.BR \[rs]} ,
+.RB \[lq] \[rs]\~ \[rq] ,
+.BR \[rs]\[aq] ,
+.BR \[rs]\[ga] ,
+.BR \[rs]\- ,
+.BR \[rs]_ ,
+.BR \[rs]! ,
+.BR \[rs]% ,
+.BR \[rs]c ,
+in names of strings,
+macros,
+diversions,
+number registers,
+fonts, or environments;
+.RI AT&T\~ troff
+does.
+.
 The
 .B \[rs]A
-escape sequence can be helpful in avoiding these escape sequences in
-names.
+escape sequence
+(see subsection \[lq]New escape sequences\[rq] above)
+may be helpful in avoiding use of these escape sequences in names.
 .
 .
 .P
@@ -3889,19 +3922,17 @@ McIlroy referred to it as a \[lq]living fossil\[rq].]
 Fractional point sizes cause one noteworthy incompatibility.
 .
 In
-.I classical
-.IR troff ,
+.RI AT&T\~ troff
 the
-.B ps
-request ignores scale indicators and so
-.RS
-.P
-.B .ps\~10u
-.RE
+.B .ps
+request ignores scale indicators and thus
+.RB \[lq] .ps\~10u \[rq]
+sets the point size to 10\~points,
+whereas in
+.I groff
+it sets the point size to 10\~scaled points.
 .
-.P
-sets the point size to 10\~points, whereas in groff native mode the
-point size is set to 10\~scaled points.
+See subsection \[lq]Fractional point sizes\[rq] above.
 .
 .
 .P
@@ -3910,93 +3941,123 @@ In
 there is a fundamental difference between unformatted input
 characters, and formatted output characters (glyphs).
 .
-Everything that affects how a glyph is output is
-stored with the glyph; once a glyph has been
-constructed it is unaffected by any subsequent requests that are
-executed, including the
-.BR bd ,
-.BR cs ,
-.BR tkf ,
-.BR tr ,
+Everything that affects how a glyph is output is stored with the glyph;
+once a glyph has been constructed,
+it is unaffected by any subsequent requests that are executed,
+including the
+.BR .bd ,
+.BR .cs ,
+.BR .tkf ,
+.BR .tr ,
 or
-.B fp
+.B .fp
 requests.
 .
-.P
-Normally glyphs are constructed from input characters at
-the moment immediately before the glyph is added to the current
-output line.
+Normally,
+glyphs are constructed from input characters immediately before the
+glyph is added to the current output line.
 .
-Macros, diversions and strings are all, in fact, the same type of
-object; they contain lists of input characters and glyphs
-in any combination.
+Macros,
+diversions,
+and strings are all,
+in fact,
+the same type of object;
+they contain lists of input characters and glyphs in any combination.
 .
-.P
-Special characters can be both; before being added to the output, they
-act as input entities, afterwards they denote glyphs.
+Special characters can be both: before being added to the output,
+they act as input entities;
+afterwards,
+they denote glyphs.
 .
-.P
-A glyph does not behave like an input character for the
-purposes of macro processing; it does not inherit any of the special
-properties that the input character from which it was constructed
-might have had.
+A glyph does not behave like an input character for the purposes of
+macro processing;
+it does not inherit any of the special properties that the input
+character from which it was constructed might have had.
 .
-The following example makes things clearer.
+The following example,
 .
-.P
 .RS
 .EX
-\&.di x
-\[rs]\[rs]\[rs]\[rs]
-\&.br
-\&.di
-\&.x
+.B .di x
+.B \[rs]\[rs]\[rs]\[rs]
+.B .br
+.B .di
+.BR .x ,\" Only mathematical typographers will appreciate this comma.
 .EE
 .RE
 .
-.P
-With
-.I GNU troff
-this is printed as
-.BR \[rs]\[rs] .
-So each pair of input backslashes \[oq]\[rs]\[rs]\[cq] is turned
-into a single output backslash glyph \[oq]\[rs]\[cq] and the
-resulting output backslashes are not interpreted as escape characters
-when they are reread.
+prints
+.RB \[lq] \[rs]\[rs] \[rq]
+in
+.IR groff ;
+each pair of input backslashes is turned into one output backslash and
+the resulting output backslashes are not interpreted as escape
+characters when they are reread.
 .
-.P
-.I Classical troff
+.RI AT&T\~ troff
 would interpret them as escape characters when they were reread and
-would end up printing a single backslash \[oq]\[rs]\[cq].
+would end up printing one
+.RB \[lq] \[rs] \[rq].
+.
 .
 .P
-In GNU, the correct way to get a printable version of the backslash
-character \[cq]\[rs]\[cq]
-is the
+One correct way to obtain a printable backslash in most documents is to
+use the
+.B \[rs]e
+escape sequence;
+this always prints a single instance of the current escape character,
+regardless of whether or not it is used in a diversion;
+it also works in both
+.I groff
+and
+.RI AT&T\~ troff .
+.
+(Naturally,
+if you've changed the escape character,
+you need to prefix the
+.RB \[lq] e \[rq]
+with whatever it is\[em]and you'll likely get something other than a
+backslash in the output.)
+.
+.
+.P
+The other correct way,
+appropriate in contexts independent of the backslash's common use as a
+.I roff
+escape character\[em]perhaps in discussion of character sets or other
+programming languages\[em]is the character escape
 .B \[rs](rs
-escape sequence, but classical troff does not provide a clean feature
-for getting a non-syntactical backslash.
+or
+.BR \[rs][rs] ,
+for \[lq]reverse solidus\[rq],
+from its name in the ECMA-6 (ISO/IEC\~646) standard.
 .
-A close method is the printable version of the current escape
-character using the
-.B \[rs]e
-escape sequence; this works if the current escape character is not
-redefined.
+[This character escape is not portable to
+.RI AT&T\~ troff ,
+but is to its lineal descendant,
+Heirloom Doctools
+.IR troff ,
+as of its 060716 release (June 2006).]
 .
-It works in both GNU mode and compatibility mode, while dirty tricks
-like specifying a sequence of multiple backslashes do not work
-reliably; for the different handling in diversions, macro definitions,
-or text mode quickly leads to a confusion about the necessary number of
-backslashes.
 .
 .P
-To store an escape sequence in a diversion that is interpreted
-when the diversion is reread, either the traditional
-.B \[rs]!\&
-transparent output facility or the
-new
-.B \[rs]?\&
-escape sequence can be used.
+To store an escape sequence in a diversion that is interpreted when the
+diversion is reread,
+either use the traditional
+.B \[rs]!
+transparent output facility,
+or,
+if this is unsuitable,
+the new
+.B \[rs]?
+escape sequence.
+.
+See subsection \[lq]New escape sequences\[rq] above and sections
+\[lq]Diversions\[rq] and \[lq]Gtroff Internals\[rq] in
+.IR "Groff: The GNU Implementation of troff" ,
+the
+.I groff
+Texinfo manual.
 .
 .
 .\" ====================================================================