Package: diction
Version: 1.14-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 "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?
an.tmac:<stdin>:11: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:22: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
troff:<stdin>:157: 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.12-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 diction depends on:
ii libc6 2.40-7
diction recommends no packages.
diction suggests no packages.
-- no debconf information
Input file is diction.1
Output from "mandoc -T lint diction.1": (shortened list)
1 input text line longer than 80 bytes: This program is GNU ...
1 input text line longer than 80 bytes: or two tabs into two...
1 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-nroff -mandoc -t -ww -z diction.1": (shortened list)
2 Use macro '.I' for one argument or split argument.
2 .IR is for at least 2 arguments, got 1
1 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
1
-.-.
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.
81:deroff -s file.mm | diction -L de | fmt
-.-.
Wrong distance 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"
39:from a database of frequently misused, bad or wordy diction. It further
40:checks for double words. If no files are given, the document is read from
41:standard input. Each found phrase is enclosed in \fB[ ]\fP (brackets).
43:by a right arrow \fB->\fP. A sentence is a sequence of words, that
45:question mark or exclaimation mark. A single letter followed by a dot
73:On usage errors, 1 is returned. Termination caused by lack of memory is
87:phrase language. The default language is \fBen\fP.
94:The file consists of lines, one per entry. Each line is divided by one
97:letters to match suffixes. If it ends with a tilde, it matches a prefix.
101:match for referring to the explanation of that text. The right part can
116:Gary D. Kline,
120:Jeremy C. Reed.
130:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
134:with this program. If not, write to the Free Software Foundation, Inc.,
139:of the AT&T DWB package. The original version was bound to roff by
143:roff documents. Similarly, you can run it in a pipe with \fBdehtml\fP(1)
151:Murray Hill, N.J. (1981), republished as part of the 4.4BSD User's
154:Strunk, William: \fIThe elements of style\fP, Ithaca, N.Y.: Priv. print.,
1918,
-.-.
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 95, length 82
or two tabs into two parts: Left is the text to match and right is the
suggestion.
Line 111, length 87
This program is GNU software, copyright 1997\(en2017 Michael Haardt
<mich...@moria.de>.
-.-.
Use \(en (en-dash) for a dash at the beginning (end) of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
diction.1:135:59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
147:deroff(1), fmt(1), style(1)
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
diction.1:66:Set the phrase file language (\fPde\fP, \fBen\fP, \fBnl\fP).
-.-.
FSF office address update. See
https://lists.gnu.org/archive/html/bug-gnulib/2024-09/msg00004.html
135:59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-.-.
Use a character "\(->" instead of plain "->" or "\->".
43:by a right arrow \fB->\fP. A sentence is a sequence of words, that
-.-.
Space after an end of sentence.
diction.1:39:from a database of frequently misused, bad or wordy diction. It
further
diction.1:40:checks for double words. If no files are given, the document is
read from
diction.1:41:standard input. Each found phrase is enclosed in \fB[ ]\fP
(brackets).
diction.1:43:by a right arrow \fB->\fP. A sentence is a sequence of words, that
diction.1:45:question mark or exclaimation mark. A single letter followed by a
dot
diction.1:73:On usage errors, 1 is returned. Termination caused by lack of
memory is
diction.1:87:phrase language. The default language is \fBen\fP.
diction.1:94:The file consists of lines, one per entry. Each line is divided
by one
diction.1:97:letters to match suffixes. If it ends with a tilde, it matches a
prefix.
diction.1:101:match for referring to the explanation of that text. The right
part can
diction.1:116:Gary D. Kline,
diction.1:120:Jeremy C. Reed.
diction.1:130:MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
diction.1:134:with this program. If not, write to the Free Software
Foundation, Inc.,
diction.1:139:of the AT&T DWB package. The original version was bound to roff
by
diction.1:143:roff documents. Similarly, you can run it in a pipe with
\fBdehtml\fP(1)
diction.1:151:Murray Hill, N.J. (1981), republished as part of the 4.4BSD User's
diction.1:154:Strunk, William: \fIThe elements of style\fP, Ithaca, N.Y.: Priv.
print., 1918,
-.-.
Put a subordinate sentence (after a comma) on a new line.
diction.1:39:from a database of frequently misused, bad or wordy diction. It
further
diction.1:40:checks for double words. If no files are given, the document is
read from
diction.1:42:Suggestions and advice, if any and if asked for, are printed headed
diction.1:43:by a right arrow \fB->\fP. A sentence is a sequence of words, that
diction.1:44:starts with a capitalised word and ends with a full stop, double
colon,
diction.1:46:is considered an abbreviation, so it does not terminate a sentence.
diction.1:47:Various multi-letter abbreviations are recognized, they do not
terminate
diction.1:48:a sentence as well, neither do fractional numbers.
diction.1:59:Suggest better wording, if any.
diction.1:64:Do not read the default database, so only the user-specified
database is used.
diction.1:66:Set the phrase file language (\fPde\fP, \fBen\fP, \fBnl\fP).
diction.1:73:On usage errors, 1 is returned. Termination caused by lack of
memory is
diction.1:94:The file consists of lines, one per entry. Each line is divided
by one
diction.1:97:letters to match suffixes. If it ends with a tilde, it matches a
prefix.
diction.1:105:If both parts are separated by two tabs, then this entry concerns
diction.1:111:This program is GNU software, copyright 1997\(en2017 Michael
Haardt <mich...@moria.de>.
diction.1:125:the Free Software Foundation; either version 3 of the License, or
diction.1:134:with this program. If not, write to the Free Software
Foundation, Inc.,
diction.1:135:59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
diction.1:138:There has been a diction command on old UNIX systems, which is
now part
diction.1:143:roff documents. Similarly, you can run it in a pipe with
\fBdehtml\fP(1)
diction.1:147:deroff(1), fmt(1), style(1)
diction.1:149:Cherry, L.L.; Vesterman, W.: \fIWriting Tools\(emThe STYLE and
DICTION
diction.1:150:programs\fP, Computer Science Technical Report 91, Bell
Laboratories,
diction.1:151:Murray Hill, N.J. (1981), republished as part of the 4.4BSD User's
diction.1:154:Strunk, William: \fIThe elements of style\fP, Ithaca, N.Y.: Priv.
print., 1918,
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
diction.1:1:.TH DICTION 1 "September 2, 2017" "GNU" "User commands"
diction.1:85:.IP "\fBLC_MESSAGES\fP=\fBde\fP\^|\^\fBen\fP\^|\^\fBnl\fP"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:11: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:22: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
troff:<stdin>:157: warning: trailing space in the line
-.-.
Spelling (codespell):
exclaimation ==> exclamation
-.-
Additionally:
Remove unnecessay change between .ad l / .ad b / .ad l.
Only use adjustment to both margins when in troff-mode.
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- diction.1 2025-03-05 22:35:46.874762912 +0000
+++ diction.1.new 2025-03-05 22:30:30.214108427 +0000
@@ -1,4 +1,4 @@
-.TH DICTION 1 "September 2, 2017" "GNU" "User commands"
+.TH DICTION 1 "September 2, 2017" GNU "User commands"
.SH NAME \"{{{roff}}}\"{{{
diction \- print wordy and commonly misused phrases in sentences
.\"}}}
@@ -8,44 +8,47 @@ diction \- print wordy and commonly misu
.RB [ \-b ]
.RB [ \-d ]
.RB [ \-f
-.IR file
+.I file
.RB [ \-n | \-L
.IR language ]]
.RI [ file ...]
-.ad b
.br
-.ad l
.B diction
.RB [ \-\-beginner ]
.RB [ \-\-ignore-double-words ]
.RB [ \-\-file
-.IR file
+.I file
.RB [ \-\-no-default-file | \-\-language
.IR language ]]
.RI [ file ...]
-.ad b
.br
-.ad l
.B diction
.BR \-h | \-\-help
-.ad b
.br
-.ad l
.B diction \-\-version
-.ad b
+.if t ad b
.\"}}}
.SH DESCRIPTION \"{{{
\fBDiction\fP finds all sentences in a document that contain phrases
-from a database of frequently misused, bad or wordy diction. It further
-checks for double words. If no files are given, the document is read from
-standard input. Each found phrase is enclosed in \fB[ ]\fP (brackets).
-Suggestions and advice, if any and if asked for, are printed headed
-by a right arrow \fB->\fP. A sentence is a sequence of words, that
-starts with a capitalised word and ends with a full stop, double colon,
-question mark or exclaimation mark. A single letter followed by a dot
-is considered an abbreviation, so it does not terminate a sentence.
-Various multi-letter abbreviations are recognized, they do not terminate
-a sentence as well, neither do fractional numbers.
+from a database of frequently misused,
+bad or wordy diction.
+It further checks for double words.
+If no files are given,
+the document is read from standard input.
+Each found phrase is enclosed in \fB[ ]\fP (brackets).
+Suggestions and advice,
+if any and if asked for,
+are printed headed by a right arrow \fB\(->\fP.
+A sentence is a sequence of words,
+that starts with a capitalised word and ends with a full stop,
+double colon,
+question mark
+or exclamation mark.
+A single letter followed by a dot is considered an abbreviation,
+so it does not terminate a sentence.
+Various multi-letter abbreviations are recognized,
+they do not terminate a sentence as well,
+neither do fractional numbers.
.PP
\fBDiction\fP understands \fIcpp\fP(1) \fB#line\fP lines for being able to
give precise locations when printing sentences.
@@ -56,104 +59,128 @@ Complain about mistakes typically made b
.IP "\fB\-d\fP, \fB\-\-ignore-double-words\fP"
Ignore double words and do not complain about them.
.IP "\fB\-s\fP, \fB\-\-suggest\fP"
-Suggest better wording, if any.
+Suggest better wording,
+if any.
.IP "\fB\-f\fP \fIfile\fP, \fB\-\-file\fP \fIfile\fP"
Read the user specified database from the specified \fIfile\fP in addition
to the default database.
.IP "\fB\-n\fP, \fB\-\-no-default-file\fP"
-Do not read the default database, so only the user-specified database is used.
+Do not read the default database,
+so only the user-specified database is used.
.IP "\fB\-L\fP \fIlanguage\fP, \fB\-\-language\fP \fIlanguage\fP"
-Set the phrase file language (\fPde\fP, \fBen\fP, \fBnl\fP).
+Set the phrase file language
+(\fPde\fP, \fBen\fP, \fBnl\fP).
.IP "\fB\-h\fP, \fB\-\-help\fP"
Print a short usage message.
.IP \fB\-\-version\fP
Print the version.
.\"}}}
.SH ERRORS \"{{{
-On usage errors, 1 is returned. Termination caused by lack of memory is
-signalled by exit code 2.
+On usage errors, 1 is returned.
+Termination caused by lack of memory is signalled by exit code 2.
.\"}}}
.SH EXAMPLE \"{{{
The following example first removes all roff constructs and headers
from a document and feeds the result to diction with a German database:
.RS
.sp
-deroff -s file.mm | diction -L de | fmt
+deroff \-s file.mm | diction \-L de | fmt
.RE
.\"}}}
.SH ENVIRONMENT \"{{{
-.IP "\fBLC_MESSAGES\fP=\fBde\fP\^|\^\fBen\fP\^|\^\fBnl\fP"
-specifies the message language and is also used as default for the
-phrase language. The default language is \fBen\fP.
+.IP \fBLC_MESSAGES\fP=\fBde\fP\^|\^\fBen\fP\^|\^\fBnl\fP
+specifies the message language
+and is also used as default for the phrase language.
+The default language is \fBen\fP.
.\"}}}
.SH FILES \"{{{
.nf
${prefix}/share/diction/* databases for various languages
.fi
.PP
-The file consists of lines, one per entry. Each line is divided by one
-or two tabs into two parts: Left is the text to match and right is the
suggestion.
-The text to match either starts with a space to match a full word or with
-letters to match suffixes. If it ends with a tilde, it matches a prefix.
+The file consists of lines, one per entry.
+Each line is divided by one
+or two tabs into two parts:
+Left is the text to match
+and right is the suggestion.
+The text to match either starts with a space to match a full word
+or with letters to match suffixes.
+If it ends with a tilde,
+it matches a prefix.
.PP
The suggestion may be empty to mark fill words,
-contain an explanation or start with an equal sign followed by text to
-match for referring to the explanation of that text. The right part can
-consist of an exclamation mark to mark exceptions that should not be
-matched.
+contain an explanation
+or start with an equal sign
+followed by text to match for referring to the explanation of that text.
+The right part can consist of an exclamation mark to mark exceptions
+that should not be matched.
.PP
-If both parts are separated by two tabs, then this entry concerns
-mistakes typically made by beginners.
+If both parts are separated by two tabs,
+then this entry concerns mistakes typically made by beginners.
.PP
Empty lines or lines starting with a hash are ignored.
.\"}}}
.SH AUTHOR \"{{{
-This program is GNU software, copyright 1997\(en2017 Michael Haardt
<mich...@moria.de>.
+This program is GNU software,
+copyright 1997\(en2017 Michael Haardt <mich...@moria.de>.
.PP
The English phrase file contains contributions by
Wil Baden,
Kimberly Hanks
-Gary D. Kline,
+Gary D.\& Kline,
Greg Lindahl <lind...@pbm.com>,
Beth Morris
and
-Jeremy C. Reed.
+Jeremy C.\& Reed.
The Dutch phrase file was contributed by Hans Lodder.
.PP
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 3 of the License, or
-(at your option) any later version.
+This program is free software;
+you can redistribute it
+and/or modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation;
+either version 3 of the License,
+or
+(at your option)
+any later version.
.PP
This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
+but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along
-with this program. If not, write to the Free Software Foundation, Inc.,
-59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+with this program.
+If not, write to the Free Software Foundation, Inc.,
+59 Temple Place \(en Suite 330,
+Boston, MA 02111-1307, USA.
.\"}}}
.SH HISTORY \"{{{
-There has been a diction command on old UNIX systems, which is now part
-of the AT&T DWB package. The original version was bound to roff by
+There has been a diction command on old UNIX systems,
+which is now part of the AT&T DWB package.
+The original version was bound to roff by
enforcing a call to deroff.
This version is a reimplementation
-and must run in a pipe with \fBderoff\fP(1) if you want to process
-roff documents. Similarly, you can run it in a pipe with \fBdehtml\fP(1)
+and must run in a pipe with \fBderoff\fP(1)
+if you want to process roff documents.
+Similarly,
+you can run it in a pipe with \fBdehtml\fP(1)
or \fBdetex\fP(1) to process HTML or TeX documents.
.\"}}}
.SH "SEE ALSO" \"{{{
-deroff(1), fmt(1), style(1)
-.PP
-Cherry, L.L.; Vesterman, W.: \fIWriting Tools\(emThe STYLE and DICTION
-programs\fP, Computer Science Technical Report 91, Bell Laboratories,
-Murray Hill, N.J. (1981), republished as part of the 4.4BSD User's
-Supplementary Documents by O'Reilly.
+.BR deroff "(1), " fmt "(1), " style (1)
.PP
-Strunk, William: \fIThe elements of style\fP, Ithaca, N.Y.: Priv. print., 1918,
+Cherry, L.L.; Vesterman, W.:
+\fIWriting Tools\(emThe STYLE and DICTION programs\fP,
+Computer Science Technical Report 91,
+Bell Laboratories, Murray Hill, N.J.\& (1981),
+republished as part of the 4.4BSD User's Supplementary Documents by O'Reilly.
+.PP
+Strunk, William:
+\fIThe elements of style\fP,
+Ithaca, N.Y.: Priv.\& print., 1918,
http://coba.shsu.edu/help/strunk/
.PP
-There is a huge and actively maintained Standard American English database
+There is a huge and actively maintained Standard American English database
at: https://mrsatterly.com/diction.html
.\"}}}
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)
-.-
