[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/02: Rewrite/update some material.
From: |
G. Branden Robinson |
Subject: |
[groff] 01/02: Rewrite/update some material. |
Date: |
Thu, 21 May 2020 08:19:29 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit accca6a842cca84dd13e51fc3782b798b36af5fc
Author: G. Branden Robinson <address@hidden>
AuthorDate: Tue May 19 23:09:05 2020 +1000
Rewrite/update some material.
* man/groff_diff.7.man: Adopt "AT&T troff" nomenclature over "classical
troff" or "Unix troff".
* (groff Language): Rename section to just "Language".
* (Description, Language, Language/Long names): It's hard to summarize a
rewrite, but a few principles animate what I did here. (1) Use
idiomatic English. (2) Show, don't tell--I dislike self-referential
narratives in technical documentation; that is, "this manual page does
X", "this section is Y". Such stuff often comes across as
throat-clearing to me. (3) Supply the reader with concrete lists of
material to be discussed instead of making vague claims about the
breadth of one's scope.
* (Fractional point sizes): Rename to "Fractional point sizes and new
scale indicators". Relocate material about new scale indicators here.
* (Implementation Differences/Intermediate output format): Stop implying
that groff's output format is actively evolving.
* (Authors): Drop email addresses.
* (See Also): Rewrite. Eliminate novice-targeted instructions about how
to read man pages. Drop descriptions of groff man pages; simple
cross-references suffice. Update bibliographic entry for CSTR #54,
using the document's correct title, describe it briefly so the reader
might know why they want to go find a copy, and drop URL that has been
dead for years. Add bibliographic entry for CSTR #97, which seems
appropriate at the level of the detail this page gets into.
* My tone could be critiqued as verging on the promotional in the new
introductory paragraph of the "Language" section. This arose
primarily because I wanted to avoid repeating verbs. I almost feel
guilty, but still regard it as an improvement.
* Protect \! and \? escapes from end-of-sentence detection.
* Update internal cross-references to retitled subsections.
* doc/groff.texi (Fractional Type Sizes): Parallelize (where applicable)
with updated groff_diff(7) material.
---
doc/groff.texi | 56 +++----
man/groff_diff.7.man | 423 +++++++++++++++++++++++++++------------------------
2 files changed, 253 insertions(+), 226 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 91291c9..0d95e1d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10199,34 +10199,34 @@ post-vertical spacing; it is associated with the
current environment
@cindex @code{\H}, with fractional type sizes
@cindex @code{\s}, with fractional type sizes
A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, where
-@var{sizescale} is specified in the @file{DESC} file (1@tie{}by
-default). There is a new scale indicator @samp{z}, which has the effect
-of multiplying by @var{sizescale}. Requests and escape sequences in
-@code{gtroff} interpret arguments that represent a point size as being
-in units of scaled points, but they evaluate each such argument using a
-default scale indicator of @samp{z}. Arguments treated in this way are
-the argument to the @code{ps} request, the third argument to the
-@code{cs} request, the second and fourth arguments to the @code{tkf}
-request, the argument to the @code{\H} escape sequence, and those
-variants of the @code{\s} escape sequence that take a numeric expression
-as their argument (see below).
-
-For example, suppose @var{sizescale} is@tie{}1000; then a scaled point
-is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
-equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
-10250@tie{}scaled points, which is equal to 10.25@tie{}points.
-
-@code{gtroff} disallows the use of the @samp{z} scale indicator in
-instances where it would make no sense, such as a numeric expression
-whose default scale indicator was neither @samp{u} nor @samp{z}.
-Similarly it would make no sense to use a scaling indicator other than
-@samp{z} or @samp{u} in a numeric expression whose default scale
-indicator was @samp{z}, and so @code{gtroff} disallows this as well.
-
-There is also new scale indicator @samp{s}, which multiplies by the
-number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
-equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
-scale indicators.
+@var{sizescale} is specified in the device description file @file{DESC},
+and defaults to 1@tie{}. A new scale indicator @samp{z} has has the
+effect of multiplying by @var{sizescale}. Requests and escape sequences
+in GNU @code{troff} interpret arguments that represent a point size as
+being in units of scaled points; that is, they evaluate each such
+argument using a default scale indicator of @samp{z}. Arguments treated
+in this way those to @code{ps}, the third argument to the @code{cs},
+the second and fourth arguments to the @code{tkf}, and the arguments
+to @code{\H} and @code{\s}.
+
+For example, if @var{sizescale} is@tie{}1000, then a scaled point
+is one one-thousandth of a point. The request @samp{.ps 10.25} is
+synonymous with @samp{.ps 10.25z} and sets the point size to
+10250@tie{}scaled points, or 10.25@tie{}points.
+
+Consequently, in GNU @code{troff}, the number register @code{.s} can
+contain a non-integral point size.
+
+It makes no sense to use of the @samp{z} scale indicator in a numeric
+expression whose default scale indicator was neither @samp{u} nor
+@samp{z}, so GNU @code{troff} disallows this. Similarly, it is
+nonsensical to use a scaling indicator other than @samp{z} or @samp{u}
+in a numeric expression whose default scale indicator was @samp{z}, and
+so GNU @code{troff} disallows this as well.
+
+Another new scale indicator @samp{s} multiplies by the number of units
+in a scaled point. For instance, @samp{\n[.ps]s} is equal to @samp{1m}.
+Do not confuse the @samp{s} and @samp{z} scale indicators.
@Defreg {.ps}
A read-only number register returning the point size in scaled points.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 57e05a3..c42a8dc 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1,7 +1,7 @@
'\" e
.TH groff_diff @MAN7EXT@ "@MDATE@" "groff @VERSION@"
.SH Name
-groff_diff \- differences between GNU troff and classical troff
+groff_diff \- differences between GNU roff and AT&T troff
.
.
.\" ====================================================================
@@ -50,183 +50,215 @@ groff_diff \- differences between GNU troff and classical
troff
.SH Description
.\" ====================================================================
.
-This manual page describes the language differences between
-.IR groff ,
-the GNU
-.I roff
-text processing system, and the classical
+The GNU
.I roff
-formatter of the freely available Unix\~7 of the 1970s, documented in
-the
-.I Troff User's Manual
-by
-.I Ossanna
-and
-.IR Kernighan .
-.
-This includes the roff language as well as the intermediate output
-format (troff output).
-.
+text processing system,
+.IR groff ,
+is largely compatible with
+.RI AT&T\~ troff ,
+the typesetting system originating in Unix systems of the 1970s.
.
-.P
-Section \[lq]See Also\[rq] below gives pointers to both the classical
-.I roff
-and the modern
+At the same time,
.I groff
-documentation.
+removes many arbitrary limitations and adds features,
+both to the language and to the intermediate,
+device-independent output format.
+.
+Differences arising from
+.IR groff 's
+implementation of
+.RI AT&T\~ troff
+features are also noted.
.
.
.\" ====================================================================
-.SH "groff Language"
+.SH Language
.\" ====================================================================
.
-In this section, all additional features of
.I groff
-compared to the classical Unix\~7
-.I troff
-are described in detail.
+features identifiers of arbitrary length,
+supports non-integral point sizes,
+adds new escapes and requests,
+provides new conditional tests,
+recognizes additional scale indicators and numerical operators,
+and extends the function of some escapes and requests already present in
+.RI AT&T\~ troff .
.
.
.\" ====================================================================
.SS "Long names"
.\" ====================================================================
.
-The names of number registers, fonts, strings/\:macros/\:diversions,
-special characters (glyphs), and colors can be of any length.
-.
-In escape sequences, additionally to the classical
-\[oq]\fB(\fP\,\fIxx\/\fP\[cq]
-construction for a two-character glyph name,
-you can use
-\[oq]\fB[\fP\,\fIxxx\/\fP\fB]\fP\[cq]
-for a name of arbitrary length.
+.I groff
+introduces many new requests;
+with two exceptions,
+they all have names longer than two characters.
+.
+The names of number registers,
+fonts,
+strings/\:macros/\:diversions,
+environments,
+special characters (glyphs),
+and colors can be of any length.
+.
+Generally,
+anywhere
+.RI AT&T\~ troff
+supports an escape form that uses an opening parenthesis \[lq](\[rq]
+to introduce a two-character identifier name,
+.I groff
+supports a square-bracketed form \[lq][]\[rq] where the identifier
+within can be of arbitrary length.
.
.
.\" ====================================================================
-.SS "Fractional point sizes"
+.SS "Fractional point sizes and new scale indicators"
.\" ====================================================================
.
A
.I scaled point
is equal to
-.B 1/sizescale
-points, where
-.B sizescale
-is specified in the
-.I DESC
-file (1 by default).
+.RI 1/ sizescale
+points,
+where
+.I sizescale
+is a parameter specified in the device description file,
+.IR DESC ,
+and defaults to\~1.
.
-There is a new scale indicator\~\c
-.B z
-that has the effect of multiplying by sizescale.
+A new scale
+.RB indicator\~\[lq] z \[rq]
+has the effect of multiplying by
+.IR sizescale .
.
-Requests and escape sequences in troff interpret arguments that
-represent a point size as being in units of scaled points, but they
-evaluate each such argument using a default scale indicator of\~\c
-.BR z .
-Arguments treated in this way are the argument to the
-.B ps
-request, the third argument to the
-.B cs
-request, the second and fourth arguments to the
-.B tkf
-request, the argument to the
+Requests and escapes in
+.I groff
+interpret arguments that represent a point size as being in units of
+scaled points;
+that is,
+they evaluate such arguments using an implied default scale indicator
+.RB of\~\[lq] z \[rq].
+.
+Arguments treated in this way comprise those to
+.BR .ps ,
+the third argument to
+.BR .cs ,
+the second and fourth arguments to
+.BR .tkf ,
+and the arguments to
.B \[rs]H
-escape sequence, and those variants of the
-.B \[rs]s
-escape sequence that take a numeric expression as their argument.
+and
+.BR \[rs]s .
.
.
.P
-For example, suppose sizescale is 1000; then a scaled point is
-equivalent to a millipoint; the call
-.B .ps 10.25
-is equivalent to
-.B .ps 10.25z
-and so sets the point size to 10250 scaled points, which is equal to
-10.25 points.
+For example,
+if
+.I sizescale
+is\~1000,
+then a scaled point is one one-thousandth of a point.
+.
+The request
+.RB \[lq] ".ps 10.25" \[rq]
+is synonymous with
+.RB \[lq] ".ps 10.25z" \[rq]
+and sets the point size to 10250\~scaled points,
+or 10.25\~points.
.
.
.P
-The number register
+Consequently,
+in
+.IR groff ,
+the number register
.B \[rs]n[.s]
-returns the point size in points as decimal fraction.
+can contain a non-integral point size.
.
-There is also a new number register
+The new number register
.B \[rs]n[.ps]
-that returns the point size in scaled points.
+returns the point size in scaled points.
.
.
.P
-It would make no sense to use the
-.BR z \~\c
-scale indicator in a numeric expression whose default scale indicator
-was neither
-.B u
-nor\~\c
-.BR z ,
-and so
-.B troff
+It makes no sense to use the
+.RB \[lq] z \[rq]\~scale
+indicator in a numeric expression whose default scale indicator is
+neither
+.RB \[lq] u \[rq]
+.RB nor\~\[lq] z \[rq],
+so
+.I groff
disallows this.
.
-Similarly it would make no sense to use a scaling indicator other than
-.B z
-or\~\c
-.B u
-in a numeric expression whose default scale indicator was\~\c
-.BR z ,
-and so
-.B troff
+Similarly,
+it is nonsenical to use a scaling indicator other
+.RB than\~\[lq] z \[rq]
+.RB or\~\[lq] u \[rq]
+in a numeric expression whose default scale indicator
+.RB is\~\[lq] z \[rq],
+so
+.I groff
disallows this as well.
.
+.
.P
-There is also new scale indicator\~\c
-.B s
-which multiplies by the number of units in a scaled point.
+Another new scale indicator,
+.RB \[lq] s \[rq],
+multiplies by the number of basic units in a scaled point.
.
-So, for example,
-.B \[rs]n[.ps]s
+For instance,
+.RB \[lq] \[rs]n[.ps]s \[rq]
is equal to
.BR 1m .
-Be sure not to confuse the
-.B s
-and
-.BR z \~\c
+.
+Do not confuse
+.RB the\~\[lq] s \[rq]
+.RB and\~\[lq] z \[rq]
scale indicators.
.
.
+.P
+A further two new measurement units available in
+.I groff
+are
+.RB \[lq] M \[rq],
+which indicates hundredeths of an em,
+and
+.RB \[lq] f \[rq],
+which is defined as 65536 basic units.
+.
+The latter provides convenient fractions for color definitions with the
+.B .defcolor
+request.
+.
+For example, 0.5f equals 32768u.
+.
+.
.\" ====================================================================
.SS "Numeric expressions"
.\" ====================================================================
.
-Spaces are permitted in a number expression within parentheses.
+Spaces are permitted in a numeric expression within parentheses.
.
+Three new operators are available as well.
.
-.P
-.B M
-indicates a scale of 100ths of an em.
-.B f
-indicates a scale of 65536 units, providing fractions for color
-definitions with the
-.B defcolor
-request.
-.
-For example, 0.5f = 32768u.
.
.TP
.IB e1 >? e2
-The maximum of
+Compute the maximum of
.I e1
and
.IR e2 .
.
+.
.TP
.IB e1 <? e2
-The minimum of
+Compute the minimum of
.I e1
and
.IR e2 .
.
+.
.TP
.BI ( c ; e )
Evaluate
@@ -237,8 +269,9 @@ as the default scaling indicator.
.
If
.I c
-is missing, ignore scaling indicators in the evaluation of\~\c
-.IR e .
+is missing,
+ignore scaling indicators in the evaluation
+.RI of\~ e .
.
.
.\" ====================================================================
@@ -344,18 +377,18 @@ plotter as the output device).
.\" ====================================================================
.
.I groff
-introduces several new escape sequences,
+introduces several new escape sequences
and extends the syntax of a few
-.RB AT&T\~ troff
+.RI AT&T\~ troff
escapes
(namely,
.BR \[rs]D ,
.BR \[rs]f ,
.BR \[rs]k ,
.BR \[rs]n ,
-.BR \[rs]* ,
+.BR \[rs]$ ,
and
-.BR \[rs]$ ).
+.BR \[rs]* ).
.
In the following list,
escapes are collated alphabetically at first,
@@ -649,8 +682,10 @@ permitted for the argument to
.B \[rs]X
to contain newlines).
.
-The inclusion of newlines requires an extension to the Unix troff output
-format, and confuses drivers that do not know about this extension.
+The inclusion of newlines requires an extension to the
+.RI AT&T\~ troff
+output format,
+and confuses drivers that do not know about this extension.
.
.TP
.BI \[rs]Z' anything '
@@ -2735,11 +2770,13 @@ which, when reread, will cause the contents of
.I filename
to be transparently copied through to the output.
.
-In Unix troff, the contents of
+In
+.RI AT&T\~ troff,
+the contents of
.I filename
-is immediately copied through to the output regardless of whether
-there is a current diversion; this behaviour is so anomalous that it
-must be considered a bug.
+are immediately copied through to the output regardless of whether there
+is a current diversion;
+this behavior is so anomalous that it must be considered a bug.
.
.TP
.BI .de\~ xx\~yy
@@ -2795,8 +2832,8 @@ current font
.IR groff_font (@MAN5EXT@))
and default to \~12.
.
-Unlike AT&T
-.IR troff ,
+Unlike
+.RI AT&T\~ troff ,
.I groff
does not ignore the
.B .ss
@@ -3378,7 +3415,8 @@ is called with the
.B \-T
command-line option, and zero otherwise.
.
-This behaviour is different from Unix troff.
+This behavior is different from
+.RI AT&T\~ troff .
.
.P
Fonts not listed in the
@@ -3505,10 +3543,11 @@ Example:
.SH "Intermediate Output Format"
.\" ====================================================================
.
-This section describes the format output by GNU troff.
-.
-The output format used by GNU troff is very similar to that used
-by Unix device-independent troff.
+The output format of
+.I groff
+is modeled after that used
+.RI AT&T\~ troff
+once it adopted a device-independent approach in the early 1980s.
.
Only the differences are documented here.
.
@@ -3715,8 +3754,10 @@ Set the current line thickness to
.IR n \~\c
machine units.
.
-Traditionally Unix troff drivers use a line thickness proportional to
-the current point size; drivers should continue to do this if no
+Traditionally,
+.RI AT&T\~ troff
+drivers use a line thickness proportional to the current point size;
+drivers should continue to do this if no
.B Dt
command has been given, or if a
.B Dt
@@ -3748,7 +3789,8 @@ is not one of
.BR a ,
or\~\c
.BR \[ti] ,
-Unix troff treats each of the $x sub i$ as a horizontal quantity,
+.RI AT&T\~ troff
+treats each of the $x sub i$ as a horizontal quantity,
and each of the $y sub i$ as a vertical quantity and assumes that
the width of the drawn object is $sum from i=1 to n x sub i$,
and that the height is $sum from i=1 to n y sub i$.
@@ -4075,7 +4117,7 @@ does.
The
.B \[rs]A
escape sequence
-(see subsection \[lq]New escape sequences\[rq] above)
+(see subsection \[lq]Escape sequences\[rq] above)
may be helpful in avoiding use of these escape sequences in names.
.
.
@@ -4138,7 +4180,8 @@ whereas in
.I groff
it sets the point size to 10\~scaled points.
.
-See subsection \[lq]Fractional point sizes\[rq] above.
+See subsection \[lq]Fractional point sizes and new scale indicators\[rq]
+above.
.
.
.P
@@ -4268,15 +4311,15 @@ as of its 060716 release (June 2006).]
To store an escape sequence in a diversion that is interpreted when the
diversion is reread,
either use the traditional
-.B \[rs]!
+.B \[rs]!\&
transparent output facility,
or,
if this is unsuitable,
the new
-.B \[rs]?
+.B \[rs]?\&
escape sequence.
.
-See subsection \[lq]New escape sequences\[rq] above and sections
+See subsection \[lq]Escape sequences\[rq] above and sections
\[lq]Diversions\[rq] and \[lq]Gtroff Internals\[rq] in
.IR "Groff: The GNU Implementation of troff" ,
the
@@ -4285,40 +4328,39 @@ Texinfo manual.
.
.
.\" ====================================================================
-.SS "Intermediate output"
+.SS "Intermediate output format"
.\" ====================================================================
.
-The groff intermediate output format is in a state of evolution.
+Its extensions notwithstanding,
+the
+.I groff
+intermediate output format has some incompatibilities
+with that of
+.RI AT&T\~ troff ,
+but full compatibility is sought;
+problem reports and patches are welcome.
.
-So far it has some incompatibilities, but it is intended to establish
-a full compatibility to the classical troff output format.
+The following incompatibilities are known.
.
-Actually the following incompatibilities exist:
.
-.IP \[bu] 2m
-The positioning after the drawing of the polygons conflicts with the
-classical definition.
+.IP \[bu]
+The positioning after drawing polygons conflicts with the
+.RI AT&T\~ troff
+practice.
+.
.
-.IP \[bu] 2m
+.IP \[bu]
The intermediate output cannot be rescaled to other devices as
-classical \[oq]device-independent\[cq] troff did.
+.RI AT&T\~ troff 's
+could.
.
.
.\" ====================================================================
.SH Authors
.\" ====================================================================
-This document was written by
-.MT jjc@\:jclark.com
-James Clark
-.ME
-and modified by
-.MT wl@\:gnu.org
-Werner Lemberg
-.ME
-and
-.MT groff\-bernd.warken\-72@\:web.de
-Bernd Warken
-.ME .
+.
+This document was written by James Clark and modified by Werner Lemberg
+and Bernd Warken.
.
.
.\" ====================================================================
@@ -4334,55 +4376,40 @@ manual.
You can browse it interactively with \[lq]info groff\[rq].
.
.
-.TP
-.BR groff (@MAN1EXT@)
-A list of all documentation around
-.IR groff .
-.
-.TP
-.BR groff (@MAN7EXT@)
-A description of the
+.PP
+\[lq]Troff User's Manual\[rq]
+by Joseph F.\& Ossanna, 1976
+(revised by Brian W.\& Kernighan, 1992),
+AT&T Bell Laboratories Computing Science Techical Report No.\& 54,
+widely called simply \[lq]CSTR\~#54\[rq],
+documents the language,
+device and font description file formats,
+and device-independent output format
+referred to collectively in
.I groff
-language, including a short, but complete reference of all predefined
-requests, registers, and escapes of plain
-.IR groff .
-From the command line, this is called using
+documentation as
+.RI \[lq]AT&T\~ troff \[rq].
.
-.RS
-.IP
-.EX
-man 7 groff
-.EE
-.RE
.
-.TP
-.BR roff (@MAN7EXT@)
-A survey of
-.I roff
-systems, including pointers to further historical documentation.
+.PP
+\[lq]A Typesetter-independent TROFF\[rq]
+by Brian W.\& Kernighan, 1982,
+AT&T Bell Laboratories Computing Science Techical Report No.\& 97,
+provides additional insights into the
+device and font description file formats
+and device-independent output format.
.
-.TP
-.RI [ CSTR\~#54\/ ]
-The
-.I Nroff/\:Troff User's Manual
-by
-.I J.\& F.\& Ossanna
-of 1976 in the revision of
-.I Brian Kernighan
-of 1992, being the
-.UR http://\:cm.bell\-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
-classical troff documentation
-.UE .
+.
+.PP
+.IR groff (@MAN1EXT@),
+.IR groff (@MAN7EXT@),
+.IR roff (@MAN7EXT@)
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
.cp \n[*groff_groff_diff_7_man_C]
.
.
-.\" ====================================================================
-.\" Emacs variables
-.\" ====================================================================
-.
.\" Local Variables:
.\" mode: nroff
.\" fill-column: 72
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/02: Rewrite/update some material.,
G. Branden Robinson <=