[groff] 08/17: gropdf(1): Revise/recast.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 1829b10b2d3f05ae62a6b2b749109eb0893ea277
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Dec 3 01:23:48 2024 -0600

    gropdf(1): Revise/recast.
    
    Recast for attempted clarity and to get page breaks (in U.S. letter
    format) in more pleasant places.
    
    Use fewer single-sentence paragraphs.
    
    Favor present tense over future.
---
 src/devices/gropdf/gropdf.1.man | 177 +++++++++++++++++++++-------------------
 1 file changed, 92 insertions(+), 85 deletions(-)

diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index 637ae16ff..409a47ed0 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -271,68 +271,75 @@ Set the foundry to use for selecting fonts of the same 
name.
 .SH Usage
 .\" ====================================================================
 .
-The input to
-.I gropdf
-must be in the format output by
-.MR @g@troff @MAN1EXT@ .
-.
-This is described in
+.IR gropdf 's
+input must be in the format produced by
+.MR @g@troff @MAN1EXT@
+and described in
 .MR groff_out @MAN5EXT@ .
 .
-In addition, the device and font description files for the device used
-must meet certain requirements:
+Further,
+its device and font description files must meet certain requirements.
 .
-The resolution must be an integer multiple of\~72 times the
+The device
+.B resolution
+must be an integer multiple of\~72 times
 .BR sizescale .
 .
-The
-.B pdf
-device uses a resolution of 72000 and a sizescale of 1000.
-.
+By default,
+.I gropdf
+uses a
+.B resolution
+of 72000 and a
+.B sizescale
+of 1000.
 .
-.LP
-The device description file must contain a valid paper format;
+A valid paper format is mandatory;
 see
 .MR groff_font @MAN5EXT@ .
 .
+While the PDF standard allows several font file formats
+(like TrueType),
+at present
 .I gropdf
-uses the same Type\~1 Adobe PostScript fonts as the
-.B grops
-device driver.
-.
-Although the PDF Standard allows the use of other font types (like
-TrueType) this implementation only accepts the Type\~1 PostScript
-font.
+accepts only the same Type\~1 Adobe PostScript format as
+.MR grops @MAN1EXT@ .
 .
 Fewer Type\~1 fonts are supported natively in PDF documents than the
 standard 35 fonts supported by
-.B grops
-and all PostScript printers, but all the fonts are available since any
-which aren't supported natively are automatically embedded in the
-PDF.
+.I grops
+and PostScript printers, \" XXX: strictly, PostScript Level 2, right?
+but all are available since
+.I gropdf
+automatically embeds any that aren't specified by the PDF standard.
 .
 .
-.LP
+.P
 .I gropdf
-supports the concept of foundries,
-that is different versions of basically the same font.
-.
-During install a
-.I Foundry
-file controls where fonts are found and builds
+supports
+.I foundries
+that permit multiple providers to supply the same
 .I groff
-fonts from the files it discovers on your system.
-.
+font names.
 .
-.LP
-Each font description file must contain a command
+.IR groff 's
+compilation process
+attempts to locate Type\~ fonts on the system,
+populates a
+.I Foundry
+file with their locations,
+and generates font description files corresponding to them.
 .
-.IP
+Font description files can also be added after installation.
+Each such file must contain a directive
+.RS
 .BI internalname\  psname
-.
-.LP
-which says that the PostScript name of the font is
-.IR psname .
+.RE
+that maps the
+.I groff
+font name
+(such as \[lq]TR\[rq])
+to a PostScript name
+(such as \[lq]Times\-Roman\[rq]).
 .
 Lines starting with
 .B #
@@ -344,15 +351,16 @@ to the code in the default encoding for the font.
 This code can be used with the
 .B \[rs]N
 escape sequence in
-.B troff
-to select the character,
-even if the character does not have a
-.I groff
-name.
+.I @g@troff
+to select the character
+even if it lacks a special character name.
+.
+Every character in the font description must exist in the font file,
+and the widths given in the description must match those used in the
+font file.
 .
-Every character in the font file must exist in the PostScript font, and
-the widths given in the font file must match the widths used
-in the PostScript font.
+See
+.MR groff_font @MAN5EXT@ .
 .\" .
 .\" .
 .\" .LP
@@ -367,36 +375,30 @@ in the PostScript font.
 .\" produces on the fly.
 .
 .
-.LP
+.P
 .I gropdf
-can automatically include the downloadable fonts necessary
-to print the document.
-.
-Fonts may be in PFA or PFB format.
-.LP
+can automatically
+.I embed
+any downloadable fonts necessary to print the document.
 .
-Any downloadable fonts which should, when required, be included by
-.I gropdf
-must be listed in the file
-.IR @FONTDIR@/\:\%devpdf/\:\%download ;
-this should consist of lines of the form
+Any fonts thus required must be listed in the file
+.IR @FONTDIR@/\:\%devpdf/\:\%download ,
+which should comprise lines of the form
 .
-.IP
-.I
-foundry font filename
+.RS
+.I "foundry font file-name"
+.RE
 .
-.LP
 where
 .I foundry
-is the foundry name or blank for the default foundry.
-.
+is the foundry name, or blank for the default foundry;
 .I font
 is the PostScript name of the font,
 and
-.I filename
-is the name of the file containing the font.
-.
-It can also contain a pathname to the font.
+.I file-name
+is the name of the PFA or PFB font file,
+and can be a pathname
+(can contain slashes).
 .
 Any lines beginning with
 .B #
@@ -405,12 +407,15 @@ fields must be separated by tabs
 (spaces are
 .B not
 allowed);
-.I filename
-is searched for using the same mechanism that is used
-for
-.I groff
-font metric files,
-unless a path is also present.
+if
+.I file-name
+is not a pathname,
+it is sought using the same mechanism as that used for
+font metric files.
+.\" XXX: This may be underspecified; do we mean groff font description
+.\" files, or AFM files?  Also, gropdf does its own path searches rather
+.\" than the stuff in libgroff so I'm not sure what "the same mechanism"
+.\" means.  --GBR
 .
 The
 .I download
@@ -421,7 +426,7 @@ Foundry names are usually a single character
 or empty for the default foundry.
 .
 This default uses the same fonts as
-.I ghostscript
+.I Ghostscript
 uses when it embeds fonts in a PDF file.
 .
 .
@@ -1018,6 +1023,8 @@ To restore the normal glyph orientation,
 repeat the command.
 .
 .
+.br
+.ne 5v
 .TP
 .BI "\[rs]X\[aq]pdf: markstart " "/ANN-definition" \[aq]
 .TQ
@@ -1145,7 +1152,7 @@ entry, revealing the new page.
 - The old page dissolves gradually to reveal the new one.
 .br
 .B Glitter
-- Similar to Dissolve,
+- As Dissolve,
 except that the effect sweeps across the page in a wide band moving from
 one side of the screen to the other in the direction specified by the
 .I direction
@@ -1303,7 +1310,7 @@ not all PDF Readers support any or all these transitions.
 produces a background rectangle on the page,
 where
 .RS
-.TP
+.TP 8n \" "bottom" + 2n
 .I cmd
 is the command,
 which can be any of
@@ -1322,12 +1329,12 @@ requires the given dimensions to place the box.
 .
 Including
 .RB \[lq] fill \[rq]
-in the command will paint the rectangle with the current fill colour
+in the command paints the rectangle with the current fill colour
 (as with
 .BR \[rs]M[] )
 and including
 .RB \[lq] box \[rq]
-will give the rectangle a border in the current stroke colour
+gives the rectangle a border in the current stroke colour
 (as with
 .BR \[rs]m[] ).
 .
@@ -1337,13 +1344,13 @@ will give the rectangle a border in the current stroke 
colour
 may also be
 .RB \[lq] off \[rq]
 on its own,
-which will terminate drawing the current box.
+which terminates drawing the current box.
 .
 If you have specified a page colour with
 .RB \[lq] pagefill \[rq],
 it is always the first box in the stack,
 and if you specify it again,
-it will replace the first entry.
+it replaces the first entry.
 .
 Be aware that the
 .RB \[lq]  pagefill \[rq]
@@ -1364,7 +1371,7 @@ may be
 .RB \[lq] footnote \[rq]
 followed by a new value for
 .IR bottom ,
-which will be used for all open boxes on the current page.
+which is used for all open boxes on the current page.
 This is to allow room for footnote areas that grow while a page is
 processed
 (to accommodate multiple footnotes,