Bug#1100476: gs.1: Some remarks and a patch with editorial changes for this man page
Package: ghostscript
Version: 10.04.0~dfsg-2+b1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff:<stdin>:273: warning: trailing space in the line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.17-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages ghostscript depends on:
ii libc6 2.41-4
ii libgs10 10.04.0~dfsg-2+b1
ghostscript recommends no packages.
Versions of packages ghostscript suggests:
ii texlive-binaries 2024.20240313.70630+ds-5+b1
-- no debconf information
Input file is gs.1
Output from "mandoc -T lint gs.1": (shortened list)
1 input text line longer than 80 bytes: Restricts file opera...
2 skipping paragraph macro: PP after SH
11 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-nroff -mandoc -t -ww -z gs.1": (shortened list)
7 trailing space in the line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
7
-.-.
Change '-' (\-) to '\(en' (en-dash) for a (numeric) range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
gs.1:314:.B /usr/share/ghostscript/[0-9]*.[0.9]*/*
gs.1:315:Startup files, utilities, and basic font definitions (where [0-9]*.[0.9]* is
gs.1:347:"/usr/share/ghostscript/[0-9]*.[0-9]*/lib"
gs.1:349:"[0-9]*.[0-9]*" represents the Ghostscript version number
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
33:which devices your executable includes, run "\fBgs -h\fR".
58:you determine with "\fBgs -h\fR". To specify "AbcXyz" as the
144: -sPAPERSIZE=<paper_size>
150: -sPAPERSIZE=a4
154: -sPAPERSIZE=legal
214:unless, of course, the first explicitly supplied directory is "." in \fB-I\fR.
310:Run "\fBgs -h\fR" to find the
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
16:programs. After doing this, it reads further input from the standard input
19:see below). The
25:below. Please see the usage documentation for complete information. Switches
109:to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile="
157:Most ISO and US paper sizes are recognized. See the usage documentation for
214:unless, of course, the first explicitly supplied directory is "." in \fB-I\fR.
270:X Windows). This may be needed if the platform fonts look undesirably
274:Restricts file operations the job can perform. Now the default mode of operation.
296:SAFER mode is now the default mode of operation. Thus when running programs that
312:get more details. On a Debian system they are in \fB/usr\fR.
420:Artifex Software, Inc. are the primary maintainers
422:Russell J. Lang, gsview at ghostgum.com.au, is the author of
-.-.
Test nr. 32:
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 216, length 85
\fBUse.htm\fR for detailed discussion on search paths and how Ghostcript finds files.
Line 274, length 81
Restricts file operations the job can perform. Now the default mode of operation.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected lines removed.]
-.-.
Only one space character after a possible end of sentence
(after a punctuation, that can end a sentence).
gs.1:16:programs. After doing this, it reads further input from the standard input
gs.1:19:see below). The
gs.1:25:below. Please see the usage documentation for complete information. Switches
gs.1:157:Most ISO and US paper sizes are recognized. See the usage documentation for
gs.1:270:X Windows). This may be needed if the platform fonts look undesirably
gs.1:274:Restricts file operations the job can perform. Now the default mode of operation.
gs.1:296:SAFER mode is now the default mode of operation. Thus when running programs that
gs.1:312:get more details. On a Debian system they are in \fB/usr\fR.
gs.1:420:Artifex Software, Inc. are the primary maintainers
gs.1:422:Russell J. Lang, gsview at ghostgum.com.au, is the author of
-.-.
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
252:.SH "SPECIAL NAMES"
287:.SH "SAFER MODE"
326:.SH "INITIALIZATION FILES"
-.-.
Put a (long) web address on a new line to reduce the posibility of
splitting the address between two output lines.
Or inhibit hyphenation with "\%" in front of the name.
293:by the command line parameters (see https://ghostscript.com/doc/current/Use.htm
415:See http://bugs.ghostscript.com/ and the Usenet news group
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
troff:<stdin>:215: warning: trailing space in the line
troff:<stdin>:346: warning: trailing space in the line
troff:<stdin>:348: warning: trailing space in the line
troff:<stdin>:371: warning: trailing space in the line
troff:<stdin>:411: warning: trailing space in the line
troff:<stdin>:415: warning: trailing space in the line
troff:<stdin>:422: warning: trailing space in the line
-.-.
Spelling (codespell):
Ghostcript ==> Ghostscript
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- gs.1 2025-03-14 08:28:44.599875126 +0000
+++ gs.1.new 2025-03-14 09:26:34.612263959 +0000
@@ -13,24 +13,34 @@ The \fBgs\fR
command invokes \fBGhostscript\fR, an interpreter of Adobe Systems'
\fBPostScript\fR(tm) and \fBPortable Document Format\fR (PDF) languages.
\fBgs\fR reads "files" in sequence and executes them as Ghostscript
-programs. After doing this, it reads further input from the standard input
-stream (normally the keyboard), interpreting each line separately and
-output to an output device (may be a file or an X11 window preview,
-see below). The
-interpreter exits gracefully when it encounters the "quit" command (either
-in a file or from the keyboard), at end-of-file, or at an interrupt signal
+programs.
+After doing this,
+it reads further input from the standard input stream
+(normally the keyboard),
+interpreting each line separately
+and output to an output device
+(may be a file or an X11 window preview, see below).
+The interpreter exits gracefully
+when it encounters the "quit" command
+(either in a file or from the keyboard),
+at end-of-file,
+or at an interrupt signal
(such as Control-C at the keyboard).
.PP
-The interpreter recognizes many option switches, some of which are described
-below. Please see the usage documentation for complete information. Switches
-may appear anywhere in the command line and apply to all files thereafter.
+The interpreter recognizes many option switches,
+some of which are described below.
+Please see the usage documentation for complete information.
+Switches may appear anywhere in the command line
+and apply to all files thereafter.
Invoking Ghostscript with the \fB\-h\fR or \fB\-?\fR switch produces a
message which shows several useful switches, all the devices known to
that executable, and the search path for fonts; on Unix it also shows the
location of detailed documentation.
.PP
-Ghostscript may be built to use many different output devices. To see
-which devices your executable includes, run "\fBgs -h\fR".
+Ghostscript may be built to use many different output devices.
+To see
+which devices your executable includes,
+run "\fBgs \-h\fR".
.PP
Unless you
specify a particular device, Ghostscript normally opens the first one of
@@ -55,8 +65,9 @@ invoke Ghostscript and type
.fi
.PP
but the first device on the resulting list may not be the default device
-you determine with "\fBgs -h\fR". To specify "AbcXyz" as the
-initial output device, include the switch
+you determine with "\fBgs \-h\fR".
+To specify "AbcXyz" as the initial output device,
+include the switch
.PP
.nf
\-sDEVICE=AbcXyz
@@ -72,12 +83,14 @@ The "\-sDEVICE=" switch must precede the
and only the switch's first use has any effect.
.PP
Finally, you can specify a default device in the environment variable
-\fBGS_DEVICE\fR. The order of precedence for these alternatives from
-highest to lowest (Ghostscript uses the device defined highest in the list)
+\fBGS_DEVICE\fR.
+The order of precedence for these alternatives from highest to lowest
+(Ghostscript uses the device defined highest in the list)
is:
.PP
-Some devices can support different resolutions (densities). To specify
-the resolution on such a printer, use the "\-r" switch:
+Some devices can support different resolutions (densities).
+To specify the resolution on such a printer,
+use the "\-r" switch:
.PP
.nf
gs \-sDEVICE=<device> \-r<xres>x<yres>
@@ -98,28 +111,34 @@ and the highest-density (best output qua
.PP
If you select a printer as the output device, Ghostscript also allows you
to choose where Ghostscript sends the output \-\- on Unix systems, usually
-to a temporary file. To send the output to a file "foo.xyz",
+to a temporary file.
+To send the output to a file "foo.xyz",
use the switch
.PP
.nf
\-sOutputFile=foo.xyz
.fi
.PP
-You might want to print each page separately. To do this, send the output
-to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile="
-switch with "%d" in a filename template:
+You might want to print each page separately.
+To do this,
+send the output to a series of files
+"foo1.xyz, foo2.xyz, ...\&"
+using the "\-sOutputFile=" switch with "%d" in a filename template:
.PP
.nf
\-sOutputFile=foo%d.xyz
.fi
.PP
Each resulting file receives one page of output, and the files are numbered
-in sequence. "%d" is a printf format specification; you can also use a
-variant like "%02d".
-.PP
-You can also send output to a pipe. For example, to
-pipe output to the "\fBlpr\fR" command (which, on many Unix systems,
-directs it to a printer), use the option
+in sequence.
+"%d" is a printf format specification;
+you can also use a variant like "%02d".
+.PP
+You can also send output to a pipe.
+For example,
+to pipe output to the "\fBlpr\fR" command
+(which, on many Unix systems, directs it to a printer),
+use the option
.PP
.nf
\-sOutputFile=%pipe%lpr
@@ -141,26 +160,29 @@ from writing messages to standard output
To select a specific paper size, use the command line switch
.PP
.nf
- -sPAPERSIZE=<paper_size>
+ \-sPAPERSIZE=<paper_size>
.fi
.PP
for instance
.PP
.nf
- -sPAPERSIZE=a4
+ \-sPAPERSIZE=a4
.fi
or
.nf
- -sPAPERSIZE=legal
+ \-sPAPERSIZE=legal
.fi
.PP
-Most ISO and US paper sizes are recognized. See the usage documentation for
-a full list, or the definitions in the initialization file "gs_statd.ps".
+Most ISO and US paper sizes are recognized.
+See the usage documentation for a full list,
+or the definitions in the initialization file "gs_statd.ps".
.PP
Ghostscript can do many things other than print or view PostScript and
-PDF files. For example, if you want to know the bounding box of a
-PostScript (or EPS) file, Ghostscript provides a special "device" that
-just prints out this information.
+PDF files.
+For example,
+if you want to know the bounding box of a PostScript (or EPS) file,
+Ghostscript provides a special "device"
+that just prints out this information.
.PP
For example, using one of the example files distributed with Ghostscript,
.PP
@@ -180,15 +202,17 @@ prints out
Takes the next argument as a file name as usual, but takes all remaining
arguments (even if they have the syntactic form of switches) and defines
the name "ARGUMENTS" in "userdict" (not "systemdict") as an
-array of those strings, \fBbefore\fR running the file. When Ghostscript
-finishes executing the file, it exits back to the shell.
+array of those strings, \fBbefore\fR running the file.
+When Ghostscript finishes executing the file,
+it exits back to the shell.
.TP
.BI \-D name = token
.TQ
.BI \-d name = token
-Define a name in "systemdict" with the given definition. The token must be
-exactly one token (as defined by the "token" operator) and may contain no
-whitespace.
+Define a name in "systemdict" with the given definition.
+The token must be exactly one token
+(as defined by the "token" operator)
+and may contain no whitespace.
.TP
.BI \-D name
.TQ
@@ -198,9 +222,10 @@ Define a name in "systemdict" with value
.BI \-S name = string
.TQ
.BI \-s name = string
-Define a name in "systemdict" with a given string as value. This is
-different from \fB\-d\fR. For example, \fB\-dname=35\fR is equivalent to the
-program fragment
+Define a name in "systemdict" with a given string as value.
+This is different from \fB\-d\fR.
+For example,
+\fB\-dname=35\fR is equivalent to the program fragment
.br
/name 35 def
.br
@@ -211,9 +236,11 @@ whereas \fB\-sname=35\fR is equivalent t
.B \-P
Makes Ghostscript to look first in the current directory for library files.
By default, Ghostscript no longer looks in the current directory,
-unless, of course, the first explicitly supplied directory is "." in \fB-I\fR.
-See also the \fBINITIALIZATION FILES\fR section below, and bundled
-\fBUse.htm\fR for detailed discussion on search paths and how Ghostcript finds files.
+unless, of course,
+the first explicitly supplied directory is ".\&" in \fB\-I\fR.
+See also the \fBINITIALIZATION FILES\fR section below, and bundled
+\fBUse.htm\fR for detailed discussion on search paths
+and how Ghostscript finds files.
.TP
.B \-q
Quiet startup: suppress normal startup messages, and also do the
@@ -221,17 +248,21 @@ equivalent of \fB\-dQUIET\fR.
.TP
.BI \-g number1 x number2
Equivalent to \fB\-dDEVICEWIDTH=\fR\fInumber1\fR and
-\fB\-dDEVICEHEIGHT=\fR\fInumber2\fR. This is for the benefit of devices
-(such as X11 windows) that require (or allow) width and height to be
-specified.
+\fB\-dDEVICEHEIGHT=\fR\fInumber2\fR.
+This is for the benefit of devices
+(such as X11 windows)
+that require (or allow) width
+and height to be specified.
.TP
.BI \-r number
.TQ
.BI \-r number1 x number2
Equivalent to \fB\-dDEVICEXRESOLUTION=\fR\fInumber1\fR and
-\fB\-dDEVICEYRESOLUTION=\fR\fInumber2\fR. This is for the benefit of
-devices such as printers that support multiple X and Y resolutions. If
-only one number is given, it is used for both X and Y resolutions.
+\fB\-dDEVICEYRESOLUTION=\fR\fInumber2\fR.
+This is for the benefit of devices such as printers
+that support multiple X and Y resolutions.
+If only one number is given,
+it is used for both X and Y resolutions.
.TP
.BI \-I directories
Adds the designated list of directories at the head of the
@@ -240,43 +271,52 @@ search path for library files.
.B \-
This is not really a switch, but indicates to Ghostscript that standard
input is coming from a file or a pipe and not interactively from the
-command line. Ghostscript reads from standard input until it reaches
-end-of-file, executing it like any other file, and then continues with
-processing the command line. When the command line has been entirely
-processed, Ghostscript exits rather than going into its interactive mode.
+command line.
+Ghostscript reads from standard input until it reaches end-of-file,
+executing it like any other file,
+and then continues with processing the command line.
+When the command line has been entirely processed,
+Ghostscript exits rather than going into its interactive mode.
.PP
Note that the normal initialization file "gs_init.ps" makes "systemdict"
read-only, so the values of names defined with \fB\-D\fR, \fB\-d\fR,
\fB\-S\fR, or \fB\-s\fR cannot be changed (although, of course, they can be
superseded by definitions in "userdict" or other dictionaries.)
-.SH "SPECIAL NAMES"
+.SH SPECIAL NAMES
.TP
.B \-dNOCACHE
-Disables character caching. Useful only for debugging.
+Disables character caching.
+Useful only for debugging.
.TP
.B \-dNOBIND
-Disables the "bind" operator. Useful only for debugging.
+Disables the "bind" operator.
+Useful only for debugging.
.TP
.B \-dNODISPLAY
Suppresses the normal initialization of the output device.
This may be useful when debugging.
.TP
.B \-dNOPAUSE
-Disables the prompt and pause at the end of each page. This may be
-desirable for applications where another program is driving Ghostscript.
+Disables the prompt and pause at the end of each page.
+This may be desirable for applications
+where another program is driving Ghostscript.
.TP
.B \-dNOPLATFONTS
-Disables the use of fonts supplied by the underlying platform (for instance
-X Windows). This may be needed if the platform fonts look undesirably
-different from the scalable fonts.
+Disables the use of fonts supplied by the underlying platform
+(for instance X Windows).
+This may be needed
+if the platform fonts look undesirably different from the scalable fonts.
.TP
.B \-dSAFER
-Restricts file operations the job can perform. Now the default mode of operation.
+Restricts file operations the job can perform.
+Now the default mode of operation.
.TP
.B \-dWRITESYSTEMDICT
-Leaves "systemdict" writable. This is necessary when running special
-utility programs, but is strongly discouraged as it bypasses normal Postscript
-security measures.
+Leaves "systemdict" writable.
+This is necessary
+when running special utility programs,
+but is strongly discouraged
+as it bypasses normal Postscript security measures.
.TP
.BI \-sDEVICE= device
Selects an alternate initial output device, as described above.
@@ -284,8 +324,7 @@ Selects an alternate initial output devi
.BI \-sOutputFile= filename
Selects an alternate output file (or pipe) for the initial output
device, as described above.
-.SH "SAFER MODE"
-.PP
+.SH SAFER MODE
The
.B \-dSAFER
option restricts file system accesses to those files and directories
@@ -293,8 +332,10 @@ allowed by the relevant environment vari
by the command line parameters (see https://ghostscript.com/doc/current/Use.htm
for details).
.PP
-SAFER mode is now the default mode of operation. Thus when running programs that
-need to open files or set restricted parameters
+SAFER mode is now the default mode of operation.
+Thus when running programs
+that need to open files
+or set restricted parameters
you should pass the
.B \-dNOSAFER
command line option or its synonym
@@ -304,15 +345,15 @@ Running with NOSAFER/DELAYSAFER (as the
and is thus recommended ONLY for debugging or in VERY controlled workflows,
and strongly NOT recommended in any other circumstances.
.SH FILES
-.PP
The locations of many Ghostscript run-time files are compiled into the
executable when it is built.
-Run "\fBgs -h\fR" to find the
-location of Ghostscript documentation on your system, from which you can
-get more details. On a Debian system they are in \fB/usr\fR.
+Run "\fBgs \-h\fR" to find the
+location of Ghostscript documentation on your system,
+from which you can get more details.
+On a Debian system they are in \fB/usr\fR.
.TP
-.B /usr/share/ghostscript/[0-9]*.[0.9]*/*
-Startup files, utilities, and basic font definitions (where [0-9]*.[0.9]* is
+.B /usr/share/ghostscript/[0\(en9]*.[0.9]*/*
+Startup files, utilities, and basic font definitions (where [0\(en9]*.[0.9]* is
the ghostscript version)
.TP
.B /usr/share/fonts/type1/gsfonts/*
@@ -323,14 +364,16 @@ Ghostscript demonstration files (if ghos
.TP
.B /usr/share/doc/ghostscript/*
Diverse document files (may need to install ghostscript-doc package)
-.SH "INITIALIZATION FILES"
+.SH INITIALIZATION FILES
When looking for the initialization files "gs_*.ps", the files related to
fonts, or the file for the "run" operator, Ghostscript first tries to open
the file with the name as given, using the current working directory if no
-directory is specified. If this fails, and the file name doesn't specify
-an explicit directory or drive (for instance, doesn't contain "/" on Unix
-systems), Ghostscript tries directories in this
-order:
+directory is specified.
+If this fails,
+and the file name doesn't specify an explicit directory
+or drive
+(for instance, doesn't contain "/" on Unix systems),
+Ghostscript tries directories in this order:
.TP 4
1.
the directories specified by the \fB\-I\fR switches in the command
@@ -343,10 +386,10 @@ if any;
3.
the directories specified by the \fBGS_LIB_DEFAULT\fR macro in the
Ghostscript makefile when the executable was built.
-\fBGS_LIB_DEFAULT\fR is
-"/usr/share/ghostscript/[0-9]*.[0-9]*/lib"
-on a Debian system where
-"[0-9]*.[0-9]*" represents the Ghostscript version number
+\fBGS_LIB_DEFAULT\fR is
+"/usr/share/ghostscript/[0\(en9]*.[0\(en9]*/lib"
+on a Debian system where
+"[0\(en9]*.[0\(en9]*" represents the Ghostscript version number
.PP
Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter)
may be either a single directory or a list of directories separated by
@@ -368,7 +411,7 @@ Path names for initialization files and
.B TEMP
Where temporary files are made
.SH X RESOURCES
-Ghostscript, or more properly the X11 display device, looks for the
+Ghostscript, or more properly the X11 display device, looks for the
following resources under the program name "Ghostscript":
.TP
.B borderWidth
@@ -392,9 +435,9 @@ The number of y pixels per inch (default
Determines whether backing store is to be used for saving display window
(default = true).
.PP
-See the usage document for a more complete list of resources. To set these
-resources on Unix, put them in a file such as "~/.Xresources" in the
-following form:
+See the usage document for a more complete list of resources.
+To set these resources on Unix,
+put them in a file such as "~/.Xresources" in the following form:
.PP
.nf
Ghostscript*geometry: 612x792\-0+0
@@ -408,16 +451,16 @@ Then merge these resources into the X se
% xrdb \-merge ~/.Xresources
.fi
.SH SEE ALSO
-The various Ghostscript document files (above), especially \fBUse.htm\fR.
+The various Ghostscript document files (above), especially \fBUse.htm\fR.
On Debian you may need to install ghostscript-doc before
reading the documentation.
.SH BUGS
-See http://bugs.ghostscript.com/ and the Usenet news group
+See http://bugs.ghostscript.com/ and the Usenet news group
comp.lang.postscript.
.SH VERSION
This document was last revised for Ghostscript version 10.04.0.
.SH AUTHOR
-Artifex Software, Inc. are the primary maintainers
+Artifex Software, Inc.\& are the primary maintainers
of Ghostscript.
-Russell J. Lang, gsview at ghostgum.com.au, is the author of
+Russell J.\& Lang, gsview at ghostgum.com.au, is the author of
most of the MS Windows code in Ghostscript.
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
Reply to: