[groff] 29/32: grolj4(1): Fix content, style, and markup nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c6f514e0c4372573d7a81820a3e0b52852755e47
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Oct 6 02:19:18 2022 -0500

    grolj4(1): Fix content, style, and markup nits.
    
    * Set "groff" in italics in summary-description (Savannah #63150).
    * Add subsection "Paper format and device description file"; relocate
      list of supported paper formats here from the "Options" section.
    * Add subsection "Font description files"; relocate the discussion of
      bespoke directives supported by this driver here from an unmotivated
      appendix to the "Options" section.  Try to improve the description of
      the directives' meanings.
    * Move discussion of bespoke drawing command supported by this driver
      into a new subsection, "Drawing commands".
    * Speak of "drawing position", not "current position".  This is groff,
      not PostScript.
    * Sort options into English lexicographic order.
    * Add cross reference to online copy of HP PCL 5 reference document,
      necessary if one is to make any sense of the custom directives above.
    * Tighten wording.
    * Adjust dead-tree pagination.
---
 src/devices/grolj4/grolj4.1.man | 189 ++++++++++++++++++++++++++--------------
 1 file changed, 122 insertions(+), 67 deletions(-)

diff --git a/src/devices/grolj4/grolj4.1.man b/src/devices/grolj4/grolj4.1.man
index 25552e4e9..e976c4104 100644
--- a/src/devices/grolj4/grolj4.1.man
+++ b/src/devices/grolj4/grolj4.1.man
@@ -1,6 +1,8 @@
 .TH grolj4 @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH Name
-grolj4 \- groff output driver for HP LaserJet 4 family printers
+grolj4 \-
+.I groff
+output driver for HP LaserJet 4 family printers
 .
 .
 .\" ====================================================================
@@ -67,9 +69,9 @@ grolj4 \- groff output driver for HP LaserJet 4 family 
printers
 .SH Description
 .\" ====================================================================
 .
-The GNU
+This GNU
 .I roff
-LJ4 output driver translates the output of
+output driver translates the output of
 .MR @g@troff @MAN1EXT@
 into a PCL5 format suitable for an HP LaserJet 4 printer.
 .
@@ -103,22 +105,98 @@ reads the standard input stream.
 Output is written to the standard output stream.
 .
 .
-.P
-An additional drawing command is available beyond those documented in
-.MR groff @MAN7EXT@ .
+.\" ====================================================================
+.SS "Paper format and device description file"
+.\" ====================================================================
+.
+.I grolj4
+supports paper formats
+.RB \[lq] A4 \[rq],
+.RB \[lq] B5 \[rq],
+.RB \[lq] C5 \[rq],
+.RB \[lq] com10 \[rq],
+.RB \[lq] DL \[rq],
+.RB \[lq] executive \[rq],
+.RB \[lq] legal \[rq],
+.RB \[lq] letter \[rq],
+and
+.RB \[lq] monarch \[rq].
+.
+These are matched case-insensitively.
+.
+The
+.B \-p
+option overrides any setting in the device description file
+.IR DESC .
+.
+If neither specifies a paper format,
+\[lq]letter\[rq] is assumed.
+.
+.
+.\" ====================================================================
+.SS "Font description files"
+.\" ====================================================================
+.
+.I grolj4
+recognizes four font description file directives in addition to those
+documented in
+.MR groff_font @MAN5EXT@ ,
 .
 .
 .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
-.RI +( dh , dv ).
+.BI pclweight\~ n
+Set the stroke weight to
+.IR n ,
+an integer in the range \-7 to +7;
+the default is\~0.
 .
-Afterwards the current position will be at the opposite corner.
 .
-This generates a PCL fill rectangle command, and so will work on
-printers that do not support HPGL/2 unlike the other
-.B \eD
+.TP
+.BI pclstyle\~ n
+Set the style to
+.IR n ,
+an integer in the range 0 to 32767;
+the default is\~0.
+.
+.
+.TP
+.BI pclproportional\~ n
+Set the proportional spacing Boolean flag to
+.IR n ,
+which can be either 0 or\~1;
+the default is\~0.
+.
+.
+.TP
+.BI pcltypeface\~ n
+Set the typeface family to
+.IR n ,
+an integer in the range 0 to 65535;
+the default is\~0.
+.
+.
+.\" ====================================================================
+.SS "Drawing commands"
+.\" ====================================================================
+.
+An additional drawing command is recognized as an extension to those
+documented in
+.MR groff @MAN7EXT@ .
+.
+.
+.TP
+.BI \[rs]D\[aq]R\~ "dh dv" \[aq]
+Draw a rule
+(solid black rectangle)
+with one corner at the drawing position,
+and the diagonally opposite corner at the drawing position
+.RI +( dh , dv ),
+at which the drawing position will be afterward.
+.
+This generates a PCL fill rectangle command,
+and so will work on printers that do not support HP-GL/2,
+unlike the other
+.B \[rs]D
 commands.
 .
 .
@@ -137,42 +215,19 @@ all exit afterward.
 .
 .
 .TP
-.BI \-c " num-copies"
-Print
+.BI \-c\~ num-copies
+Format
 .I num-copies
 copies of each page.
 .
 .
 .TP
-.B \-l
-Print the document with a landscape orientation.
-.
-.
-.TP
 .BR \-d \~[\c
 .IR n ]
 Use duplex mode
 .IR n :
-1\ is long-side binding; 2\ is short-side binding;
-default is\ 1.
-.
-.
-.TP
-.BI \-p " paper-size"
-Set the paper size to
-.IR paper-size ,
-which must be one of
-letter, legal, executive, a4, com10, monarch, c5, b5, dl.
-.
-.
-.TP
-.BI \-w " line-width"
-Set the default line thickness to
-.I line-width
-thousandths of an em.
-.
-If this option isn't specified, the line thickness defaults to
-0.04\~em.
+1\~is long-side binding (default),
+and 2\~is short-side binding.
 .
 .
 .TP
@@ -181,48 +236,42 @@ Prepend directory
 .IR font-directory /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 lj4 .
 .
 .
-.LP
-The following four commands are available additionally in the
-font description files:
-.
-.
-.TP
-.BI pclweight \ N
-The integer value
-.I N
-must be in the range \-7 to +7; default is\~0.
-.
-.
 .TP
-.BI pclstyle \ N
-The integer value
-.I N
-must be in the range 0 to 32767; default is\~0.
+.B \-l
+Format the document in landscape orientation.
 .
 .
 .TP
-.BI pclproportional \ N
-A boolean flag which can be either 0 or\~1; default is\~0.
+.BI \-p " paper-size"
+Set the paper size to
+.IR paper-size ,
+which must be a valid paper format as described above.
 .
 .
 .TP
-.BI pcltypeface \ N
-The integer value
-.I N
-must be in the range 0 to 65535; default is\~0.
+.BI \-w " line-width"
+Set the default line thickness to
+.I line-width
+thousandths of an em;
+the default is
+.B 40
+(0.04\~em).
 .
 .
+.br
+.ne 4v \" Keep section heading and paragraph together.
 .\" ====================================================================
 .SH Environment
 .\" ====================================================================
 .
 .TP
 .I GROFF_FONT_PATH
-A list of directories in which to seek the selected output device's
+lists directories in which to seek the selected output device's
 directory of device and font description files.
 .
 See
@@ -231,8 +280,6 @@ and
 .MR groff_font @MAN5EXT@ .
 .
 .
-.br
-.ne 3v \" Keep section heading and paragraph tag together.
 .\" ====================================================================
 .SH Files
 .\" ====================================================================
@@ -277,6 +324,14 @@ Small dots.
 .SH "See also"
 .\" ====================================================================
 .
+.UR http://\:www\:.hp\:.com/\:ctg/\:Manual/\:bpl13210\:.pdf
+.I HP PCL/PJL Reference:
+.I PCL\~5 Printer Language Technical Reference Manual,
+.I Part I
+.UE
+.
+.
+.P
 .MR hpftodit @MAN1EXT@ ,
 .MR lj4_font @MAN5EXT@ ,
 .MR groff @MAN1EXT@ ,