Package: par
Version: 1.53.0-2
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 ' $' <file>" to find 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>:74: warning: trailing space in the line
troff:<stdin>:76: warning: trailing space in the line
troff:<stdin>:78: warning: trailing space in the line
troff:<stdin>:80: warning: trailing space in the line
troff:<stdin>:135: warning: trailing space in the line
troff:<stdin>:136: warning: trailing space in the line
troff:<stdin>:137: warning: trailing space in the line
troff:<stdin>:138: warning: trailing space in the line
troff:<stdin>:139: warning: trailing space in the line
troff:<stdin>:140: warning: trailing space in the line
troff:<stdin>:141: warning: trailing space in the line
troff:<stdin>:142: warning: trailing space in the line
troff:<stdin>:143: warning: trailing space in the line
troff:<stdin>:144: warning: trailing space in the line
troff:<stdin>:145: warning: trailing space in the line
troff:<stdin>:984: warning: trailing space in the line
troff:<stdin>:987: warning: trailing space in the line
troff:<stdin>:991: warning: trailing space in the line
troff:<stdin>:993: warning: trailing space in the line
troff:<stdin>:1028: warning: trailing space in the line
troff:<stdin>:1090: warning: trailing space in the line
troff:<stdin>:1098: warning: trailing space in the line
troff:<stdin>:1106: warning: trailing space in the line
troff:<stdin>:1128: warning: trailing space in the line
troff:<stdin>:1136: warning: trailing space in the line
troff:<stdin>:1144: warning: trailing space in the line
an.tmac:<stdin>:1184: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument."
an.tmac:<stdin>:1189: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument."
troff:<stdin>:1220: warning: font name 'CW' is deprecated
* 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.6-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 par depends on:
ii libc6 2.40-4
par recommends no packages.
par suggests no packages.
-- no debconf information
Input file is par.1
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
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
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 -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 of 'diff -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)
-.-.
Output from "mandoc -T lint par.1": (shortened list)
14 skipping paragraph macro
26 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z par.1": (shortened list)
2 .BI is for at least 2 arguments, got 1
2 Use macro '.B' for one argument or split argument."
1 font name 'CW' is deprecated
26 trailing space in the line
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
1184:.BI E
1189:.BI E
-.-.
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 abbreviation point as such by suffixing them with "\&".
1272:features of an editor, such as the ! commands of
1296:\*Q\fB**\fP\*U (star star). If you need to supply
-.-
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
17:.TP .5i
1006:.RS .5i
1038:.RS .5i
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
837:.B \s-1PARINIT\s0,
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
Not considered in a patch, too many lines.
par.1:59:all white characters (except newlines) to spaces, and
par.1:77:words (separated by spaces).
par.1:733:the segment, (scanned from the top down) which have
par.1:739:two lines (both are truncated if both qualify).
par.1:1115:.RI min( afp , prefix )
par.1:1153:.RI min( fs , suffix )
par.1:1852:handles (or doesn't handle) them. It
par.1:1882:are that it is extremely useful (I find it indispensable),
par.1:1889:how-it-works (which is painfully complex) and how-to-use-it
-.-.
Use thousand markers to make large numbers easy to read
501:may be set to any unsigned decimal integer less than 10000.
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:74: warning: trailing space in the line
troff:<stdin>:76: warning: trailing space in the line
troff:<stdin>:78: warning: trailing space in the line
troff:<stdin>:80: warning: trailing space in the line
troff:<stdin>:135: warning: trailing space in the line
troff:<stdin>:136: warning: trailing space in the line
troff:<stdin>:137: warning: trailing space in the line
troff:<stdin>:138: warning: trailing space in the line
troff:<stdin>:139: warning: trailing space in the line
troff:<stdin>:140: warning: trailing space in the line
troff:<stdin>:141: warning: trailing space in the line
troff:<stdin>:142: warning: trailing space in the line
troff:<stdin>:143: warning: trailing space in the line
troff:<stdin>:144: warning: trailing space in the line
troff:<stdin>:145: warning: trailing space in the line
troff:<stdin>:984: warning: trailing space in the line
troff:<stdin>:987: warning: trailing space in the line
troff:<stdin>:991: warning: trailing space in the line
troff:<stdin>:993: warning: trailing space in the line
troff:<stdin>:1028: warning: trailing space in the line
troff:<stdin>:1090: warning: trailing space in the line
troff:<stdin>:1098: warning: trailing space in the line
troff:<stdin>:1106: warning: trailing space in the line
troff:<stdin>:1128: warning: trailing space in the line
troff:<stdin>:1136: warning: trailing space in the line
troff:<stdin>:1144: warning: trailing space in the line
an.tmac:<stdin>:1184: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument."
an.tmac:<stdin>:1189: misuse, warning: .BI is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument."
troff:<stdin>:1220: warning: font name 'CW' is deprecated
-.-.
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
There is no need to add a '\&' before a full stop (.) if it has a character
before it!
--- par.1 2024-12-29 22:18:28.966211964 +0000
+++ par.1.new 2024-12-29 23:54:29.445712681 +0000
@@ -14,7 +14,7 @@ par \- filter for reformatting paragraph
.de OP
.BI \*O\ \\$1 \\$2\ \*C
..
-.TP .5i
+.TP 0.5i
.B par
.na
.OP help
@@ -51,17 +51,25 @@ par \- filter for reformatting paragraph
.el .ds U ""
.de IT
.LP
-\h'-\w'\\$1\ 'u'\\$1\ \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
+.ie \\n(.g \{\
+\h'-\w'\\$1\ 'u'\c
+. nop \\$*
+.\}
+.el \h'-\w'\\$1\ 'u'\\$1\ \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
-.LP
.B par
is a filter which copies its input to its output, changing
-all white characters (except newlines) to spaces, and
-reformatting each paragraph. Paragraphs are separated
-by protected, blank, and bodiless lines (see the
+all white characters
+(except newlines)
+to spaces, and
+reformatting each paragraph.
+Paragraphs are separated by protected,
+blank, and bodiless lines
+(see the
.SM TERMINOLOGY
-section for definitions), and optionally
-delimited by indentation (see the
+section for definitions),
+and optionally delimited by indentation
+(see the
.B d
option in the
.SM OPTIONS
@@ -73,20 +81,21 @@ corresponding input paragraph as follows
.LP
.IT 1) An optional prefix and/or suffix
is removed from each input line.
-.IT 2) The remainder is divided into
-words (separated by spaces).
+.IT 2) The remainder is divided into words
+(separated by spaces).
.IT 3) The words are joined into lines
to make an eye-pleasing paragraph.
.IT 4) The prefixes and suffixes are reattached.
.RE
.LP
-If there are suffixes, spaces are inserted before
-them so that they all end in the same column.
+If there are suffixes,
+spaces are inserted before them
+so that they all end in the same column.
.SH QUICK START
-.LP
.B par
-is necessarily complex. For those who wish to use
-it immediately and understand it later, assign the
+is necessarily complex.
+For those who wish to use it immediately and understand it later,
+assign the
.B \s-1PARINIT\s0
environment variable the following value:
.IP
@@ -122,7 +131,6 @@ and
.SM EXAMPLES
sections.
.SH TERMINOLOGY
-.LP
Miscellaneous terms:
.RS
.IP "charset syntax"
@@ -407,7 +415,6 @@ character in the word before
.IR c .
.RE
.SH OPTIONS
-.LP
Any command line argument may begin with one minus
sign (\-) which is ignored. Generally, more
than one option may appear in a single command
@@ -434,7 +441,7 @@ is printed on the output.
.BI B opset
.I op
is a single character, either an equal sign
-(=), a plus sign (+), or a minus sign (-), and
+(=), a plus sign (+), or a minus sign (\-), and
.I set
is a string using charset syntax. If
.I op
@@ -498,7 +505,7 @@ The first six parameters,
.IR Tab ,
and
.IR width ,
-may be set to any unsigned decimal integer less than 10000.
+may be set to any unsigned decimal integer less than 10,000.
.TP 1i
.BI h\fR[ hang\fR]
Mainly affects the default values of
@@ -730,13 +737,17 @@ is scanned for bodiless lines,
.B par
supplies vacant lines between different quotation nesting
levels as follows: For each pair of adjacent lines in
-the segment, (scanned from the top down) which have
-different quoteprefixes, one of two actions is taken. If
+the segment,
+(scanned from the top down)
+which have different quoteprefixes,
+one of two actions is taken.
+If
.I invis
is 0, and either line consists entirely of quote
characters and spaces (or is empty), that line
is truncated to the longest common prefix of the
-two lines (both are truncated if both qualify).
+two lines
+(both are truncated if both qualify).
Otherwise, a line consisting of the longest common
prefix of the two lines is inserted between them.
.I quote
@@ -834,7 +845,7 @@ will read command line options from
.B \s-1PARINIT\s0
before it reads them from the command line.
Within the value of
-.B \s-1PARINIT\s0,
+.BR \s-1PARINIT\s0 ,
arguments are separated by the initial set of white characters.
.TP
.B \s-1PARPROTECT\s0
@@ -867,7 +878,6 @@ and
options, renders the other environment variables
unnecessary. They are included for backward compatibility.
.SH DETAILS
-.LP
Lines are terminated by newline characters, but the
newlines are not considered to be included in the lines.
If the last character of the input is a non-newline,
@@ -1003,7 +1013,7 @@ is 1. The sum of the squares of the dif
and the lengths of the lines is as small as
possible, subject to properties 1, 2, and 3.
.RE
-.RS .5i
+.RS 0.5i
.LP
If
.I last
@@ -1035,7 +1045,7 @@ consists only of the extra spaces, not t
of the inter-word gaps is as small as
possible, subject to properties 1 and 2.
.RE
-.RS .5i
+.RS 0.5i
.LP
If
.I last
@@ -1158,7 +1168,6 @@ last input line, and the rest are all sp
.LP
Finally, the lines are printed to the output as the OP.
.SH DIAGNOSTICS
-.LP
If there are no errors,
.B par
returns
@@ -1181,21 +1190,27 @@ or environment variable syntax are accom
the same usage message that the help option produces.
.LP
Unless the option
-.BI E
+.B E
is set, trying to print an error message would be
futile if an error resulted from an output function, so
.B par
doesn't bother doing any error checking on output functions if
-.BI E
+.B E
is 0.
.SH EXAMPLES
.de VS
-.RS -.5i
+.RS -0.5i
.LP
.nf
.ps -1p
.vs -2p
-.ft CW
+.ie \\n(.g \{\
+. ie t .ft CR
+. el .ft R
+.\}
+.el \{\
+. ft CW
+.\}
..
.de VE
.ft P
@@ -1207,7 +1222,6 @@ is 0.
.de CM
\&\*Q\fB\\$1\fP\\*U:
..
-.LP
The superiority of
.BR par 's
dynamic programming algorithm over a
@@ -1269,7 +1283,7 @@ are clearly more eye-pleasing.
.LP
.B par
is most useful in conjunction with the text-filtering
-features of an editor, such as the ! commands of
+features of an editor, such as the !\& commands of
.BR vi .
You may wish to add the following lines to your
.B .exrc
@@ -1806,10 +1820,8 @@ After
amc> should not mistake "." for a suffix.
.VE
.SH SEE ALSO
-.LP
.B par.doc
.SH LIMITATIONS
-.LP
The
.I guess
feature guesses wrong in cases like the following:
@@ -1849,8 +1861,11 @@ them if they aren't already in the input
.LP
If you use tabs, you may not like the way
.B par
-handles (or doesn't handle) them. It
-expands them into spaces. I didn't let
+handles
+(or doesn't handle)
+them.
+It expands them into spaces.
+I didn't let
.B par
output tabs because tabs don't make sense. Not everyone's
terminal has the same tab settings, so text files containing
@@ -1870,7 +1885,6 @@ input prefix. Ditto for the suffix. I
adding this capability in a future release, but
right now I'm not sure how I'd want it to work.
.SH APOLOGIES
-.LP
Par began in July 1993 as a small program designed to do one
narrow task: reformat a single paragraph that might have a
border on either side. It was pretty clean back then. Over
@@ -1879,14 +1893,17 @@ multiple paragraphs, offer more options,
guesses, at the cost of becoming extremely complex, and very
unclean. It is nowhere near the optimal design for the larger
task it now tries to address. Its only redeeming features
-are that it is extremely useful (I find it indispensable),
+are that it is extremely useful
+(I find it indispensable),
extremely portable, and very stable since version 1.41 released
on 1993-Oct-31.
.LP
Back in 1993 I had very little experience at writing
documentation for users, so the documentation for Par
became rather nightmarish. There is no separation between
-how-it-works (which is painfully complex) and how-to-use-it
+how-it-works
+(which is painfully complex)
+and how-to-use-it
(which is fairly simple, if you can ever figure it out).
.LP
Someday I ought to reexamine the problem, and redesign
@@ -1894,7 +1911,6 @@ a new, clean solution from scratch. I d
when I might get enough free time to start on such
a project. Text files may be obsolete by then.
.SH BUGS
-.LP
If I knew of any bugs, I wouldn't release the package. Of
course, there may be bugs that I haven't yet discovered.
.LP
