Bug#1110374: gs.1: Some remarks and a patch with editorial changes for this man page
Package: ghostscript
Version: 10.05.1~dfsg-1
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
grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>
to find (most) 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?
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:222: warning: trailing space in the line
troff:<stdin>:353: warning: trailing space in the line
troff:<stdin>:355: warning: trailing space in the line
troff:<stdin>:378: warning: trailing space in the line
troff:<stdin>:418: warning: trailing space in the line
troff:<stdin>:422: warning: trailing space in the line
troff:<stdin>:429: 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: 13.0
APT prefers testing-security
APT policy: (500, 'testing-security'), (500, 'testing-proposed-updates'), (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.38+deb13-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-11
ii libgs10 10.05.1~dfsg-1
ghostscript recommends no packages.
Versions of packages ghostscript suggests:
ii texlive-binaries 2024.20240313.70630+ds-6
-- no debconf information
Input file is gs.1
Output from "mandoc -T lint gs.1": (shortened list)
2 PP after SH
1 Restricts file opera...
1 gs.1:194:4: STYLE
1 gs.1:201:4: STYLE
1 gs.1:206:4: STYLE
1 gs.1:222:67: STYLE
1 gs.1:236:4: STYLE
1 gs.1:353:24: STYLE
1 gs.1:355:25: STYLE
1 gs.1:378:68: STYLE
1 gs.1:418:74: STYLE
1 gs.1:422:59: STYLE
1 gs.1:429:61: STYLE
Find trailing space with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Output from
test-nroff -mandoc -t -ww -z gs.1: (shortened list)
7 line(s) with a trailing space
Find trailing space with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
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
-.-.
Reduce space between words.
gs.1:375:.B TEMP
-.-.
Move a full stop (period) and a comma outside of a quoted text, if it is
at the end of the quote and does not end a quoted sentence.
116:to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile="
221:unless, of course, the first explicitly supplied directory is "." in \fB-I\fR.
-.-.
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
151: -sPAPERSIZE=<paper_size>
157: -sPAPERSIZE=a4
161: -sPAPERSIZE=legal
221:unless, of course, the first explicitly supplied directory is "." in \fB-I\fR.
317: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"
[List of affected lines removed.]
-.-.
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 223, length 85
\fBUse.htm\fR for detailed discussion on search paths and how Ghostcript finds files.
Line 281, length 81
Restricts file operations the job can perform. Now the default mode of operation.
Longest line is number 223 with 85 characters
-.-.
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 is 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:164:Most ISO and US paper sizes are recognized. See the usage documentation for
gs.1:277:X Windows). This may be needed if the platform fonts look undesirably
gs.1:281:Restricts file operations the job can perform. Now the default mode of operation.
gs.1:303:SAFER mode is now the default mode of operation. Thus when running programs that
gs.1:319:get more details. On a Debian system they are in \fB/usr\fR.
gs.1:427:Artifex Software, Inc. are the primary maintainers
gs.1:429:Russell J. Lang, gsview at ghostgum.com.au, is the author of
-.-.
Put a subordinate sentence (after a comma) on a new line.
gs.1:116:to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile="
-.-.
Put a (long) web address on a new output line to reduce the posibility of
splitting the address between two output lines.
Or inhibit hyphenation with "\%" in front of the name.
300:by the command line parameters (see https://ghostscript.com/doc/current/Use.htm
-.-.
Add "\&" after an ellipsis, when it does not end a sentence.
116:to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile="
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:222: warning: trailing space in the line
troff:<stdin>:353: warning: trailing space in the line
troff:<stdin>:355: warning: trailing space in the line
troff:<stdin>:378: warning: trailing space in the line
troff:<stdin>:418: warning: trailing space in the line
troff:<stdin>:422: warning: trailing space in the line
troff:<stdin>:429: warning: trailing space in the line
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- gs.1 2025-08-04 00:55:46.158613967 +0000
+++ gs.1.new 2025-08-04 01:29:39.729538122 +0000
@@ -30,7 +30,7 @@ that executable, and the search path for
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".
+which devices your executable includes, run "\fBgs \-h\fR".
.PP
Unless you
specify a particular device, Ghostscript normally opens the first one of
@@ -55,7 +55,7 @@ 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
+you determine with "\fBgs \-h\fR". To specify "AbcXyz" as the
initial output device, include the switch
.PP
.nf
@@ -113,7 +113,7 @@ use the switch
.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="
+to a series of files "foo1.xyz, foo2.xyz, ...\&" using the "\-sOutputFile="
switch with "%d" in a filename template:
.PP
.nf
@@ -148,17 +148,17 @@ 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
@@ -218,8 +218,8 @@ 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
+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.
.TP
.B \-q
@@ -292,7 +292,6 @@ Selects an alternate initial output devi
Selects an alternate output file (or pipe) for the initial output
device, as described above.
.SH "SAFER MODE"
-.PP
The
.B \-dSAFER
option restricts file system accesses to those files and directories
@@ -311,10 +310,9 @@ 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
+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
@@ -350,9 +348,9 @@ 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
+\fBGS_LIB_DEFAULT\fR is
"/usr/share/ghostscript/[0-9]*.[0-9]*/lib"
-on a Debian system where
+on a Debian system where
"[0-9]*.[0-9]*" represents the Ghostscript version number
.PP
Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter)
@@ -375,7 +373,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
@@ -415,16 +413,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
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>
To find trailing space use
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
The same goes for man pages that are used as an input.
-.-
For a style guide use
mandoc -T lint
-.-
For general input conventions consult the man page "nroff(7)" (item
"Input conventions") or the Texinfo manual about the same item.
-.-
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: