Package: most
Version: 5.2.0-1.1
Severity: minor
Tags: upstream
* 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>:6: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
troff:<stdin>:83: warning: trailing space in the line
troff:<stdin>:102: warning: trailing space in the line
troff:<stdin>:105: warning: trailing space in the line
troff:<stdin>:108: warning: trailing space in the line
troff:<stdin>:111: warning: trailing space in the line
troff:<stdin>:114: warning: trailing space in the line
troff:<stdin>:118: warning: trailing space in the line
troff:<stdin>:123: warning: trailing space in the line
troff:<stdin>:127: warning: trailing space in the line
troff:<stdin>:132: warning: trailing space in the line
troff:<stdin>:137: warning: trailing space in the line
troff:<stdin>:140: warning: trailing space in the line
troff:<stdin>:143: warning: trailing space in the line
troff:<stdin>:147: warning: trailing space in the line
troff:<stdin>:151: warning: trailing space in the line
troff:<stdin>:158: warning: trailing space in the line
troff:<stdin>:162: warning: trailing space in the line
troff:<stdin>:170: warning: trailing space in the line
troff:<stdin>:173: warning: trailing space in the line
troff:<stdin>:177: warning: trailing space in the line
troff:<stdin>:180: warning: trailing space in the line
troff:<stdin>:183: warning: trailing space in the line
troff:<stdin>:187: warning: trailing space in the line
troff:<stdin>:191: warning: trailing space in the line
troff:<stdin>:195: warning: trailing space in the line
troff:<stdin>:198: warning: trailing space in the line
troff:<stdin>:202: warning: trailing space in the line
troff:<stdin>:207: warning: trailing space in the line
troff:<stdin>:211: warning: trailing space in the line
troff:<stdin>:215: warning: trailing space in the line
troff:<stdin>:220: warning: trailing space in the line
troff:<stdin>:225: warning: trailing space in the line
troff:<stdin>:229: warning: trailing space in the line
troff:<stdin>:233: warning: trailing space in the line
troff:<stdin>:237: warning: trailing space in the line
troff:<stdin>:242: warning: trailing space in the line
troff:<stdin>:247: warning: trailing space in the line
troff:<stdin>:250: warning: trailing space in the line
troff:<stdin>:253: warning: trailing space in the line
troff:<stdin>:256: warning: trailing space in the line
troff:<stdin>:260: warning: trailing space in the line
troff:<stdin>:263: warning: trailing space in the line
troff:<stdin>:268: warning: trailing space in the line
troff:<stdin>:273: warning: trailing space in the line
troff:<stdin>:276: warning: trailing space in the line
troff:<stdin>:280: warning: trailing space in the line
troff:<stdin>:291: warning: trailing space in the line
troff:<stdin>:332: warning: trailing space in the line
troff:<stdin>:345: warning: trailing space in the line
troff:<stdin>:349: warning: trailing space in the line
troff:<stdin>:355: 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 most depends on:
ii libc6 2.41-4
ii libslang2 2.3.3-5+b2
most recommends no packages.
most suggests no packages.
-- no debconf information
Input file is most.1
Output from "mandoc -T lint most.1": (shortened list)
9 skipping paragraph macro: PP after SH
1 skipping paragraph macro: PP empty
54 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-nroff -mandoc -t -ww -z most.1": (shortened list)
51 trailing space in the line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Show if docman-to-man created this.
Who is actually creating this man page? Debian or upstream?
Is the generating software out of date?
1:.\" This manpage has been automatically generated by docbook2man
2:.\" from a DocBook document. This tool can be found at:
3:.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
-.-.
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
54
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-"
(begin of an option or end of options)
then use "\-\-".
most.1:161:Secure Mode-- no edit, cd, shell,
most.1:395: status -- the status line
most.1:396: underline -- underlined text
most.1:397: overstrike -- overstruck text
most.1:398: normal -- anything else
-.-.
Reduce space between words.
most.1:201:If \fBi\fR is not specified, then prompt for a line
most.1:210:If the current screen width is 80, make it 132 and
most.1:223:Prompt for a string and
most.1:329:This variable sets commonly used switches.
most.1:341:Either of these environment
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
60:character `\\' will appear at the right edge of the window.
301: fprintf(stdout,"%i: %s\\n",i,argv[i]);
-.-.
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.
12:\fBmost\fR [ \fB-1\fR ] [ \fB-b\fR ] [ \fB-C\fR ] [ \fB-c\fR ] [ \fB-d\fR ]
[ \fB-M\fR ] [ \fB-r\fR ] [ \fB-s\fR ] [ \fB-t\fR ] [ \fB-u\fR ] [ \fB-v\fR ] [
\fB-w\fR ] [ \fB-z\fR ] [ \fB+/\fIstring\fB\fR ] [ \fB+\fIline-number\fB\fR ] [
\fB+d\fR ] [ \fB+s\fR ] [ \fB+u\fR ] [ \fB\fIfile...\fB\fR ]
39:may be disabled with the -k option. See the description of the -b,
40:-k, -v, and -t options for further details.
52:have not been stripped. This may be turned off with the -v option.
58:which extend past the margins of the screen. The -w option may be
78:\fB-1\fR
85:\fB-b\fR
95:When used with the -v option, the same line looks like:
101:\fB-C\fR
104:\fB-c\fR
107:\fB-d\fR
110:\fB-M\fR
113:\fB-r\fR
116:\fB-s\fR
120:\fB-t\fR
123:width, e.g., -t4
125:\fB-u\fR
132:used. The +u and -u switches allow the behavior to be overridden
134:\fB-v\fR
139:\fB-w\fR
142:\fB-z\fR
161:Secure Mode-- no edit, cd, shell,
330:For example, some people prefer to use \fBmost\fR with the -s option so that
337: $ define MOST_SWITCHES "-s"
345:your editor, then set MOST_EDITOR to 'jed %s -g %d'.
395: status -- the status line
396: underline -- underlined text
397: overstrike -- overstruck text
398: normal -- anything else
410:through a file. When in doubt, use the -v and -b options of \fBmost\fR\&.
-.-.
Find a repeated word
! 332 --> done
! 385 --> 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"
27:another may be truncating the lines. Windows may be `locked'
55:not wrapped but are instead truncated. When truncation occurs, this
67:arbitrary 24 bit colors. If your terminal supports 24 bit colors,
88:display the file 16 bytes per line in hexadecimal notation. A
92: 01000000 40001575 9C23A020 4000168D ....@..u.#. @...
98: ^A^@^@^@ @^@^U u 9C #A0 @^@^V8D ....@..u.#. @...
156:it easier to clean unwanted files out of a directory. The file is
342:variables specify an editor for \fBmost\fR to invoke to edit a file. The
359:then a personal configuration file. These files may be used to specify
417:John E. Davis <j...@jedsoft.org>
426:Mats Akerberg, Henk D. Davids, Rex O. Livingston, and Mark Pizzolato
444:Thanks to David W. Sanderson for adapting the early documentation to
-.-.
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 12, length 296
\fBmost\fR [ \fB-1\fR ] [ \fB-b\fR ] [ \fB-C\fR ] [ \fB-c\fR ] [ \fB-d\fR ] [
\fB-M\fR ] [ \fB-r\fR ] [ \fB-s\fR ] [ \fB-t\fR ] [ \fB-u\fR ] [ \fB-v\fR ] [
\fB-w\fR ] [ \fB-z\fR ] [ \fB+/\fIstring\fB\fR ] [ \fB+\fIline-number\fB\fR ] [
\fB+d\fR ] [ \fB+s\fR ] [ \fB+u\fR ] [ \fB\fIfile...\fB\fR ]
Longest line is number 12 with 296 characters
-.-.
Remove unnecessary double font change (e.g., \fR\fI) in a row or (better)
use a two-fonts macro.
12:\fBmost\fR [ \fB-1\fR ] [ \fB-b\fR ] [ \fB-C\fR ] [ \fB-c\fR ] [ \fB-d\fR ]
[ \fB-M\fR ] [ \fB-r\fR ] [ \fB-s\fR ] [ \fB-t\fR ] [ \fB-u\fR ] [ \fB-v\fR ] [
\fB-w\fR ] [ \fB-z\fR ] [ \fB+/\fIstring\fB\fR ] [ \fB+\fIline-number\fB\fR ] [
\fB+d\fR ] [ \fB+s\fR ] [ \fB+u\fR ] [ \fB\fIfile...\fB\fR ]
145:\fB+/\fIstring\fB\fR
149:\fB+\fIlineno\fB\fR
293:\fB\fR
334:\fB\fR
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
most.1:167:argument (1 by default).
-.-.
Use a hyphen between a number and the unit (name) "bit",
see "man-pages(7)", item "Terms to avoid".
65:\fBmost\fR has supported both 256-color and 24 bit truecolor terminals
67:arbitrary 24 bit colors. If your terminal supports 24 bit colors,
74:to force 24 bit truecolors to be used.
87:you want to view files containing 8 bit characters. \fBmost\fR will
-.-.
No need for '\&' to be in front of a period (.),
if there is a character in front of it.
Remove with "sed -e 's/\\&\././g'".
214:Exit from \fBmost\fR\&. On VMS, ^Z also
410:through a file. When in doubt, use the -v and -b options of \fBmost\fR\&.
427:contributed to the early VMS versions of \fBmost\fR\&. In particular, Mark
440:of \fBmost\fR\&.
-.-.
Only one space character after a possible end of sentence
(after a punctuation, that can end a sentence).
most.1:27:another may be truncating the lines. Windows may be `locked'
most.1:55:not wrapped but are instead truncated. When truncation occurs, this
most.1:67:arbitrary 24 bit colors. If your terminal supports 24 bit colors,
most.1:156:it easier to clean unwanted files out of a directory. The file is
most.1:342:variables specify an editor for \fBmost\fR to invoke to edit a file.
The
most.1:359:then a personal configuration file. These files may be used to
specify
most.1:417:John E. Davis <j...@jedsoft.org>
most.1:426:Mats Akerberg, Henk D. Davids, Rex O. Livingston, and Mark Pizzolato
most.1:444:Thanks to David W. Sanderson for adapting the early documentation to
-.-.
Put a subordinate sentence (after a comma) on a new line.
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.
most.1:6:.TH "MOST" "1" "30 July 2022" "" ""
most.1:14:.SH "DESCRIPTION"
most.1:76:.SH "OPTIONS"
most.1:315:.SH "HINTS"
most.1:324:.SH "ENVIRONMENT"
most.1:402:.SH "BUGS"
most.1:415:.SH "AUTHOR"
most.1:418:.SH "ACKNOWLEDGEMENTS"
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
14:.SH "DESCRIPTION"
63:.SH "COLOR SUPPORT"
76:.SH "OPTIONS"
163:.SH "COMMAND USAGE"
315:.SH "HINTS"
324:.SH "ENVIRONMENT"
356:.SH "CONFIGURATION FILE SYNTAX"
402:.SH "BUGS"
415:.SH "AUTHOR"
418:.SH "ACKNOWLEDGEMENTS"
-.-.
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.
3:.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:6: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
troff:<stdin>:83: warning: trailing space in the line
troff:<stdin>:102: warning: trailing space in the line
troff:<stdin>:105: warning: trailing space in the line
troff:<stdin>:108: warning: trailing space in the line
troff:<stdin>:111: warning: trailing space in the line
troff:<stdin>:114: warning: trailing space in the line
troff:<stdin>:118: warning: trailing space in the line
troff:<stdin>:123: warning: trailing space in the line
troff:<stdin>:127: warning: trailing space in the line
troff:<stdin>:132: warning: trailing space in the line
troff:<stdin>:137: warning: trailing space in the line
troff:<stdin>:140: warning: trailing space in the line
troff:<stdin>:143: warning: trailing space in the line
troff:<stdin>:147: warning: trailing space in the line
troff:<stdin>:151: warning: trailing space in the line
troff:<stdin>:158: warning: trailing space in the line
troff:<stdin>:162: warning: trailing space in the line
troff:<stdin>:170: warning: trailing space in the line
troff:<stdin>:173: warning: trailing space in the line
troff:<stdin>:177: warning: trailing space in the line
troff:<stdin>:180: warning: trailing space in the line
troff:<stdin>:183: warning: trailing space in the line
troff:<stdin>:187: warning: trailing space in the line
troff:<stdin>:191: warning: trailing space in the line
troff:<stdin>:195: warning: trailing space in the line
troff:<stdin>:198: warning: trailing space in the line
troff:<stdin>:202: warning: trailing space in the line
troff:<stdin>:207: warning: trailing space in the line
troff:<stdin>:211: warning: trailing space in the line
troff:<stdin>:215: warning: trailing space in the line
troff:<stdin>:220: warning: trailing space in the line
troff:<stdin>:225: warning: trailing space in the line
troff:<stdin>:229: warning: trailing space in the line
troff:<stdin>:233: warning: trailing space in the line
troff:<stdin>:237: warning: trailing space in the line
troff:<stdin>:242: warning: trailing space in the line
troff:<stdin>:247: warning: trailing space in the line
troff:<stdin>:250: warning: trailing space in the line
troff:<stdin>:253: warning: trailing space in the line
troff:<stdin>:256: warning: trailing space in the line
troff:<stdin>:260: warning: trailing space in the line
troff:<stdin>:263: warning: trailing space in the line
troff:<stdin>:268: warning: trailing space in the line
troff:<stdin>:273: warning: trailing space in the line
troff:<stdin>:276: warning: trailing space in the line
troff:<stdin>:280: warning: trailing space in the line
troff:<stdin>:291: warning: trailing space in the line
troff:<stdin>:332: warning: trailing space in the line
troff:<stdin>:345: warning: trailing space in the line
troff:<stdin>:349: warning: trailing space in the line
troff:<stdin>:355: warning: trailing space in the line
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
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)
-.-
