[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 08/15: grodvi(1): Fix style problems.
From: |
G. Branden Robinson |
Subject: |
[groff] 08/15: grodvi(1): Fix style problems. |
Date: |
Tue, 20 Oct 2020 14:00:30 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 930216c1b6d706368422a750e40134f8c1e34b46
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Oct 19 02:43:28 2020 +1100
grodvi(1): Fix style problems.
* Set program names in italics.
* Use groff-style string escapes.
* Quote multi-word in-line code examples so that they are clear even if
the rendering device doesn't support bold.
* Break input lines after commas and semicolons.
* Use two empty requests where inter-paragraph space is expected.
* Set macro names with a leading dot.
* Set the abbreviation TFM (Tex Font Metrics) in full capitals. It is
the file extension that is normally lowercase.
* Recast to avoid implication that the \N escape is a groffism.
* Set multi-word parentheticals on their own input line(s).
* Set the "hcode" request in bold and with a leading dot.
* Set the abbreviation DVI in full capitals.
* Suppress hyphenation of configurably-prefixed command name in-line
code example and man page cross-references.
* Suppress hyphenation of "tfm·todit" in man page cross-reference.
* Add hyphenation points before dots in file names.
---
src/devices/grodvi/grodvi.1.man | 202 ++++++++++++++++++++++++++--------------
1 file changed, 130 insertions(+), 72 deletions(-)
diff --git a/src/devices/grodvi/grodvi.1.man b/src/devices/grodvi/grodvi.1.man
index 073dd34..387e78b 100644
--- a/src/devices/grodvi/grodvi.1.man
+++ b/src/devices/grodvi/grodvi.1.man
@@ -73,39 +73,48 @@ grodvi \- convert groff output to TeX DVI format
.SH Description
.\" ====================================================================
.
-.B grodvi
+.I grodvi
is a driver for
-.B groff
-that produces \*(tx DVI format.
+.I groff
+that produces \*[tx] DVI format.
.
-Normally it should be run by
-.BR "groff \-Tdvi" .
+Normally it should be run via
+.RB \[lq] "groff \-Tdvi" \[rq].
.
This will run
-.BR "@g@troff \-Tdvi" ;
-it will also input the macros in
-.IR \%@MACRODIR@/\:dvi.tmac .
+.BR \[lq] "\%@g@troff \-Tdvi" \[rq],
+read the macros in
+.IR \%@MACRODIR@/\:dvi\:.tmac ,
+and pipe the output to
+.IR grodvi .
+.
.
.LP
The DVI file generated by
-.B grodvi
+.I grodvi
can be printed by any correctly-written DVI driver.
.
-The troff drawing primitives are implemented
-using the tpic version\~2 specials.
+.I troff
+drawing primitives are implemented using
+.I tpic
+version\~2 specials.
.
-If the driver does not support these, the
+If the driver does not support these,
+the
.B \[rs]D
commands will not produce any output.
.
+.
.LP
There is an additional drawing command available:
.
+.
.TP
.BI \[rs]D\[aq]R\~ "dh dv" \[aq]
-Draw a rule (solid black rectangle), with one corner
-at the current position, and the diagonally opposite corner
-at the current position
+Draw a rule
+(solid black rectangle),
+with one corner at the current position,
+and the diagonally opposite corner at the current position
.RI +( dh , dv ).
.
Afterwards the current position will be at the opposite corner.
@@ -115,58 +124,72 @@ driver that does not support the tpic specials unlike the
other
.B \[rs]D
commands.
.
+.
.LP
-The groff command
+The
+.I groff
+command
.BI \[rs]X\[aq] anything \[aq]
is translated into the same command in the DVI file as would be
produced by
.BI \%\[rs]special{ anything }
-in \*(tx;
+in \*[tx];
.I anything
may not contain a newline.
.
+.
.LP
For inclusion of EPS image files,
.B \-Tdvi
loads
.I pspic.tmac
-automatically, providing the
-.B PSPIC
+automatically,
+providing the
+.B .PSPIC
macro.
.
-Please check
-.BR groff_tmac (@MAN5EXT@)
+See
+.IR groff_tmac (@MAN5EXT@)
for a detailed description.
.
+.
.LP
Font files for
-.B grodvi
-can be created from tfm files using
-.BR tfmtodit (@MAN1EXT@).
+.I grodvi
+can be created from TFM
+(\*[tx] font metrics)
+files using
+.IR tfmtodit (@MAN1EXT@).
.
The font description file should contain the following
additional commands:
.
+.
.TP
.BI internalname\~ name
-The name of the tfm file (without the
+The name of the TFM file
+(without the
.I .tfm
extension) is
.IR name .
.
+.
.TP
.BI checksum\~ n
-The checksum in the tfm file is
+The checksum in the TFM file is
.IR n .
.
+.
.TP
.BI designsize\~ n
-The designsize in the tfm file is
+The designsize in the TFM file is
.IR n .
.
+.
.LP
These are automatically generated by
-.B tfmtodit.
+.I tfmtodit.
+.
.
.LP
The default color for
@@ -175,33 +198,43 @@ and
.B \[rs]M
is black.
.
-Currently, the drawing color for
+Currently,
+the drawing color for
.B \[rs]D
-commands is always black, and fill color values are translated to gray.
+commands is always black,
+and fill color values are translated to gray.
+.
.
.LP
In
-.B troff
+.IR groff ,
+as in AT&T
+.IR troff , \" AT&T
the
.B \[rs]N
escape sequence can be used to access characters by their position
-in the corresponding tfm file;
-all characters in the tfm file can be accessed this way.
+in the corresponding TFM file;
+all characters in the TFM file can be accessed this way.
+.
.
.LP
-By design, the DVI format doesn't care about physical dimensions of the
-output medium.
+By design,
+the DVI format doesn't care about physical dimensions of the output
+medium.
.
Instead,
-.B grodvi
+.I grodvi
emits the equivalent to \*[tx]'s
.BI \%\[rs]special{\:\%papersize= width , length }
on the first page;
-.B dvips
-(and possibly other DVI drivers) then sets the page size accordingly.
+.I dvips
+(and possibly other DVI drivers)
+then sets the page size accordingly.
.
-If either the page width or length is not positive, no papersize special
-is output.
+If either the page width or length is not positive,
+no
+.B papersize
+special is output.
.
.
.\" ====================================================================
@@ -226,19 +259,23 @@ Horizontal and vertical lines will be implemented by
rules.
.
Other drawing commands will be ignored.
.
+.
.TP
.BI \-F dir
Prepend directory
.RI dir /dev name
to the search path for font and device description files;
.I name
-is the name of the device, usually
+is the name of the device,
+usually
.BR dvi .
.
+.
.TP
.B \-l
Specify landscape orientation.
.
+.
.TP
.BI \-p papersize
Specify paper dimensions.
@@ -250,20 +287,23 @@ and
.B paperwidth
commands in the
.I DESC
-file; it accepts the same arguments as the
+file;
+it accepts the same arguments as the
.B papersize
-command (see
-.BR groff_font (@MAN5EXT@)
+command
+(see
+.IR groff_font (@MAN5EXT@)
for details).
.
+.
.TP
.BI \-w n
Set the default line thickness to
.I n
thousandths of an em.
.
-If this option isn't specified, the line thickness defaults to
-0.04\~em.
+If this option isn't specified,
+the line thickness defaults to 0.04\~em.
.
.
.\" ====================================================================
@@ -284,6 +324,7 @@ and
.B H
having members in each of these styles:
.
+.
.RS
.TP
.B TR
@@ -334,9 +375,11 @@ CM Slanted Sans Serif Bold Extended (cmssbxo10)
.FT
.RE
.
+.
.LP
There are also the following fonts which are not members of a family:
.
+.
.RS
.TP
.B CW
@@ -351,6 +394,7 @@ CM Italic Typewriter Text (cmitt10)
.FT
.RE
.
+.
.LP
Special fonts are
.B MI
@@ -360,9 +404,11 @@ Special fonts are
.B EX
(cmex10),
.B SC
-(cmtex10, only for
+(cmtex10,
+only for
.BR CW ),
-and, perhaps surprisingly,
+and,
+perhaps surprisingly,
.BR TR ,
.BR TI ,
and
@@ -374,6 +420,7 @@ For italic fonts,
is used instead of
.BR CW .
.
+.
.LP
Finally,
the symbol fonts of the American Mathematical Society are available as
@@ -385,6 +432,7 @@ special fonts
.
These two fonts are not mounted by default.
.
+.
.LP
Using the option
.B \-mec
@@ -393,12 +441,17 @@ Using the option
provides the EC and TC fonts.
.
The design of the EC family is very similar to that of the CM fonts;
-additionally, they give a much better coverage of groff symbols.
+additionally,
+they give a much better coverage of
+.I groff
+symbols.
.
Note that
.I ec.tmac
-must be called before any language-specific files; it doesn't take
-care of hcode values.
+must be called before any language-specific files;
+it doesn't take care of
+.B .hcode
+values.
.
.
.\" ====================================================================
@@ -412,9 +465,9 @@ A list of directories in which to search for the
directory in addition to the default ones.
.
See
-.BR @g@troff (@MAN1EXT@)
+.IR \%@g@troff (@MAN1EXT@)
and
-.BR \%groff_font (@MAN5EXT@)
+.IR \%groff_font (@MAN5EXT@)
for more details.
.
.
@@ -423,21 +476,24 @@ for more details.
.\" ====================================================================
.
.TP
-.I \%@FONTDIR@/devdvi/DESC
+.I \%@FONTDIR@/\:\%devdvi/\:DESC
Device description file.
.
+.
.TP
-.IR \%@FONTDIR@/devdvi/ F
+.IR \%@FONTDIR@/\:\%devdvi/ F
Font description file for font
.IR F .
.
+.
.TP
-.I \%@MACRODIR@/dvi.tmac
+.I \%@MACRODIR@/\:dvi\:.tmac
Macros for use with
-.BR grodvi .
+.IR grodvi .
+.
.
.TP
-.I \%@MACRODIR@/ec.tmac
+.I \%@MACRODIR@/\:ec\:.tmac
Macros to switch to EC fonts.
.
.
@@ -445,15 +501,17 @@ Macros to switch to EC fonts.
.SH Bugs
.\" ====================================================================
.
-Dvi files produced by
-.B grodvi
-use a different resolution (57816 units per inch) from those produced by
-\*(tx.
+DVI files produced by
+.I grodvi
+use a different resolution
+(57816 units per inch)
+from those produced by \*[tx].
.
-Incorrectly written drivers which assume the resolution used by \*(tx,
+Incorrectly written drivers which assume the resolution used by \*[tx],
rather than using the resolution specified in the DVI file will not
work with
-.BR grodvi .
+.IR grodvi .
+.
.
.LP
When using the
@@ -461,7 +519,7 @@ When using the
option with boxed tables,
vertical and horizontal lines can sometimes protrude by one pixel.
.
-This is a consequence of the way \*(tx requires that the heights
+This is a consequence of the way \*[tx] requires that the heights
and widths of rules be rounded.
.
.
@@ -469,13 +527,13 @@ and widths of rules be rounded.
.SH "See Also"
.\" ====================================================================
.
-.BR tfmtodit (@MAN1EXT@),
-.BR groff (@MAN1EXT@),
-.BR @g@troff (@MAN1EXT@),
-.BR groff_out (@MAN5EXT@),
-.BR groff_font (@MAN5EXT@),
-.BR groff_char (@MAN7EXT@),
-.BR groff_tmac (@MAN5EXT@)
+.IR \%tfmtodit (@MAN1EXT@),
+.IR groff (@MAN1EXT@),
+.IR \%@g@troff (@MAN1EXT@),
+.IR groff_out (@MAN5EXT@),
+.IR groff_font (@MAN5EXT@),
+.IR groff_char (@MAN7EXT@),
+.IR groff_tmac (@MAN5EXT@)
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 08/15: grodvi(1): Fix style problems.,
G. Branden Robinson <=