[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 15/15: troff(1): Revise.
From: |
G. Branden Robinson |
Subject: |
[groff] 15/15: troff(1): Revise. |
Date: |
Tue, 20 Jul 2021 18:13:16 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 60edc83593ed792bb5924824914f295d4ae846a9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jul 21 07:22:17 2021 +1000
troff(1): Revise.
* Update apropos line to mention typesetting.
* Recast introductory paragraph. Stop assuming that the reader already
knows what a program named "troff" does; describe it instead.
* Make description of -b option more accessible.
* Add space between option letter and its argument in paragraph tags.
* Say "escape sequences", not "escapes".
* Use \~ to prevent breaks inside very short phrases.
* Describe files (potentially) loaded by command more carefully.
* Revamp "See also" section to front our Texinfo manual. Elaborate man
pages referred to more carefully. Drop superfluous example of how
to view a man page. Add entries for groff_char(7), groff_font(5), and
groff_out(5), relating each directly to the topic.
* Use idiomatic English.
* Add a page authorship credit for myself; I've stunk it up enough.
---
src/roff/troff/troff.1.man | 215 +++++++++++++++++++++++++++------------------
1 file changed, 130 insertions(+), 85 deletions(-)
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index a77d4e2..f7ba2cc 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -1,14 +1,14 @@
'\" t
.TH @g@troff @MAN1EXT@ "@MDATE@" "groff @VERSION@"
.SH Name
-@g@troff \- GNU troff document formatter
+@g@troff \- GNU roff typesetter and document formatter
.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
-.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2021 Free Software Foundation, Inc.
.\"
.\" This file is part of groff, the GNU roff type-setting system.
.\"
@@ -85,26 +85,35 @@
.SH Description
.\" ====================================================================
.
-This manual page describes the GNU version of
-.BR troff .
+The GNU version of
+.I troff \" generic
+is the heart of the
+.I groff
+document formatting system.
.
-It is part of the groff document formatting system.
+.I \%@g@troff
+is the
+.I groff
+system's formatter,
+the program that transforms
+.I roff
+language input into a device-independent output format.
.
-It is functionally compatible with Unix troff, but has many
-extensions, see
-.BR \%groff_diff (@MAN7EXT@).
+It is functionally compatible with the AT&T
+.I troff \" AT&T
+typesetter and features numerous extensions.
.
-Usually it should be invoked using the
-.BR groff (@MAN1EXT@)
-command which will also run preprocessors and postprocessors in the
-appropriate order and with the appropriate options.
+Many people prefer to use the
+.IR groff (@MAN1EXT@)
+command,
+a front end which also runs preprocessors and output drivers in the
+appropriate order and with appropriate options.
.
.
.\" ====================================================================
.SH Options
.\" ====================================================================
.
-.
.TP
.B \-a
Generate a plain text approximation of the typeset output.
@@ -160,17 +169,15 @@ output are subject to change.
.
.TP
.B \-b
-Write an input stack backtrace to the standard error stream with each
-.I \%@g@troff
-diagnostic message.
+Write a backtrace reporting the state of
+.IR \%@g@troff 's
+input parser to the standard error stream with each diagnostic message.
.
-The line numbers given in the backtrace might not always be correct;
+The line numbers given in the backtrace might not always be correct,
+because
.IR \%@g@troff 's
-idea of line numbers can be confused by
-.B .as
-or
-.B .am
-requests.
+idea of line numbers can be confused by requests that append to strings
+or macros.
.
.
.TP
@@ -231,14 +238,14 @@ or related requests.
.
.
.TP
-.BI \-f fam
+.BI \-f\~ fam
Use
.I fam
as the default font family.
.
.
.TP
-.BI \-F dir
+.BI \-F\~ dir
Search in directory
.I dir
for the selected output device's directory of device and font
@@ -255,6 +262,7 @@ and ordering.
Read the standard input after all the named input files have been
processed.
.
+.
.TP
.BI \-I\~ dir
Search
@@ -273,7 +281,7 @@ those named in
.RB \[lq] "\[rs]X\[aq]ps: file\[aq]" \[rq],
and
.RB \[lq] "\[rs]X\[aq]pdf: pdfpic\[aq]" \[rq]
-escapes).
+escape sequences).
.
This option may be specified more than once;
the directories are then searched in the order specified.
@@ -296,7 +304,7 @@ file name.
.
.
.TP
-.BI \-m name
+.BI \-m\~ name
Process
.RI name .tmac
before any input files.
@@ -317,7 +325,7 @@ and ordering.
.
.
.TP
-.BI \-M dir
+.BI \-M\~ dir
Search directory
.I dir
for macro files.
@@ -329,12 +337,13 @@ and ordering.
.
.
.TP
-.BI \-n num
+.BI \-n\~ num
Number the first page
.IR num .
.
+.
.TP
-.BI \-o list
+.BI \-o\~ list
Output only pages in
.IR list ,
which is a comma-separated list of page ranges;
@@ -342,19 +351,21 @@ which is a comma-separated list of page ranges;
means print page
.IR n ,
.IB m \- n
-means print every page between
-.I m
-and
+means print every page
+.RI between\~ m
+.RI and\~ n ,
.IR n ,
.BI \- n
-means print every page up to
-.IR n ,
+means print every page up
+.RI to\~ n ,
+and
.IB n \-
means print every page from
-.IR n .
+.IR n \~on.
.
.I \%@g@troff
-will exit after printing the last page in the list.
+stops processing and exits after formatting the last page enumerated in
+.IR list .
.
.
.TP
@@ -396,7 +407,7 @@ and
.
.
.TP
-.BI \-T dev
+.BI \-T\~ dev
Prepare output for device
.IR dev ,
rather than the default,
@@ -429,9 +440,9 @@ option above.
.
.
.TP
-.BI \-w name
+.BI \-w\~ name
.TQ
-.BI \-W name
+.BI \-W\~ name
Enable
.RB ( \-w )
or inhibit
@@ -439,7 +450,8 @@ or inhibit
emission of warnings in category
.IR name .
.
-See subsection \[lq]Warnings\[rq] below.
+See section \[lq]Warnings\[rq] below.
+.
.
.
.TP
@@ -818,26 +830,37 @@ see
.
.TP
.I @MACRODIR@/troffrc
-Initialization file (called before any other macro package).
+is an initialization macro file loaded before any macro packages
+specified with
+.B \-m
+options.
+.
.
.TP
.I @MACRODIR@/troffrc\-end
-Initialization file (called after any other macro package).
+is an initialization macro file loaded after all macro packages
+specified with
+.B \-m
+options.
+.
.
.TP
.IR @MACRODIR@/ name .tmac
.TQ
.IR @MACRODIR@/tmac. name
-Macro files
+are macro files distributed with
+.IR groff .
+.
.
.TP
.IR @FONTDIR@/dev name /DESC
-Device description file for device
+describes the output device
.IR name .
.
+.
.TP
.IR @FONTDIR@/dev name / F
-Font file for font
+describes the font
.I F
of device
.IR name .
@@ -848,10 +871,10 @@ of device
and
.I troffrc\-end
are sought neither in the current nor the home directory by default for
-security reasons
-(even if the
+security reasons,
+even if the
.B \-U
-option is given).
+option is specified.
.
Use the
.B \-M
@@ -869,13 +892,16 @@ The GNU version of
.I troff \" generic
was originally written by James Clark;
he also wrote the original version of this document,
-which was modified by
+which was updated by
.MT wl@\:gnu\:.org
Werner Lemberg
-.ME
-and
+.ME ,
.MT groff\-bernd\:.warken\-72@\:web\:.de
Bernd Warken
+.ME ,
+and
+.MT g.branden\:.robinson@\:gmail\:.com
+G.\& Branden Robinson
.ME .
.
.
@@ -883,57 +909,76 @@ Bernd Warken
.SH "See also"
.\" ====================================================================
.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
+.
+You can browse it interactively with \[lq]info groff\[rq].
+.
+.
.TP
-.BR groff (@MAN1EXT@)
-The main program of the
+.IR groff (@MAN1EXT@)
+offers an overview of the GNU
+.I roff
+system
+and describes its front end executable.
+.
+.
+.TP
+.IR groff (@MAN7EXT@)
+details the
.I groff
-system, a wrapper around
-.IR @g@troff .
+language,
+including a short but complete reference of all predefined requests,
+registers,
+and escape sequences.
.
.
.TP
-.BR groff (@MAN7EXT@)
-A description of the
+.IR groff_char (@MAN7EXT@)
+explains the syntax of
.I groff
-language, including a short but complete reference of all predefined
-requests, registers, and escapes of plain
-.IR groff .
+special character escape sequences,
+and lists all special characters predefined by the language.
.
-From the command line, this is called by
-.RS
-.IP
-.B man 7 groff
-.RE
.
.TP
.IR groff_diff (@MAN7EXT@)
-The differences of the
-.I groff
-language and the
-.I classical troff
-language.
+enumerates the differences between
+AT&T device-independent
+.I troff \" AT&T
+and
+.IR groff .
.
-Currently, this is the most actual document of the
-.I groff
-system.
.
.TP
-.IR roff (@MAN7EXT@)
-An overview over
+.IR groff_font (@MAN5EXT@)
+covers the format of
.I groff
-and other
-.I roff
-systems, including pointers to further related documentation.
+device and font description files.
.
.
-.P
-.IR "Groff: The GNU Implementation of troff" ,
-by Trent A.\& Fisher and Werner Lemberg,
-is the primary
-.I groff
-manual.
+.TP
+.IR groff_out (@MAN5EXT@)
+describes the format of
+.IR \%@g@troff 's
+output.
.
-You can browse it interactively with \(lqinfo groff\(rq.
+.
+.TP
+.IR groff_tmac (@MAN5EXT@)
+includes information about macro files that ship with
+.IR groff .
+.
+.
+.TP
+.IR roff (@MAN7EXT@)
+supplies background on
+.I roff
+systems in general,
+including pointers to further related documentation.
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 15/15: troff(1): Revise.,
G. Branden Robinson <=