Package: expect
Version: 5.45.4-3+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 -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?
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
troff:<stdin>:15: warning: trailing space in the line
troff:<stdin>:70: 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.11.10-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 expect depends on:
ii libc6 2.40-4
ii libtcl8.6 8.6.15+dfsg-2
ii tcl-expect 5.45.4-3+b1
ii tcl8.6 8.6.15+dfsg-2
expect recommends no packages.
Versions of packages expect suggests:
ii tk8.6 8.6.15-1
-- no debconf information
Input file is expect_unbuffer.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 expect_unbuffer.1": (shortened list)
1 input text line longer than 80 bytes
1 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z expect_unbuffer.1": (shortened list)
2 trailing space in the line
-.-.
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
-.-.
Test nr. 21:
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.
18: od -c /tmp/fifo | more
28: unbuffer od -c /tmp/fifo | more
31:Normally, unbuffer does not read from stdin. This simplifies use of
unbuffer in some situations. To use unbuffer in a pipeline, use the -p flag.
35: process1 | unbuffer -p process2 | process3
39:unbuffer -p may appear to work incorrectly if a process feeding input
42: process1 | unbuffer -p process2 | process3
-.-.
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.
Line 31, length 146
Normally, unbuffer does not read from stdin. This simplifies use of unbuffer
in some situations. To use unbuffer in a pipeline, use the -p flag.
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
troff:<stdin>:15: warning: trailing space in the line
troff:<stdin>:70: warning: trailing space in the line
-.-.
--- expect_unbuffer.1 2024-12-18 04:12:42.619220843 +0000
+++ expect_unbuffer.1.new 2024-12-18 04:25:49.872825501 +0000
@@ -11,52 +11,69 @@ unbuffer \- unbuffer output
.B unbuffer
disables the output buffering that occurs when program output
is redirected from non-interactive programs.
-For example, suppose you are watching the output from a fifo by running it
-through od and then more.
+For example,
+suppose you are watching the output from a fifo by running it through od
+and then more.
.nf
- od -c /tmp/fifo | more
+ od \-c /tmp/fifo | more
.fi
-You will not see anything until a full page
-of output has been produced.
+You will not see anything
+until a full page of output has been produced.
You can disable this automatic buffering as follows:
.nf
- unbuffer od -c /tmp/fifo | more
+ unbuffer od \-c /tmp/fifo | more
.fi
-Normally, unbuffer does not read from stdin. This simplifies use of unbuffer
in some situations. To use unbuffer in a pipeline, use the -p flag.
+Normally, unbuffer does not read from stdin.
+This simplifies use of unbuffer in some situations.
+To use unbuffer in a pipeline,
+use the \-p flag.
Example:
.nf
- process1 | unbuffer -p process2 | process3
+ process1 | unbuffer \-p process2 | process3
.fi
.SH CAVEATS
-unbuffer -p may appear to work incorrectly if a process feeding input
-to unbuffer exits. Consider:
+unbuffer \-p may appear to work incorrectly
+if a process feeding input to unbuffer exits.
+Consider:
.nf
- process1 | unbuffer -p process2 | process3
+ process1 | unbuffer \-p process2 | process3
.fi
-If process1 exits, process2 may not yet have finished. It is
-impossible for unbuffer to know long to wait for process2 and process2
-may not ever finish, for example, if it is a filter. For expediency,
-unbuffer simply exits when it encounters an EOF from either its input
+If process1 exits,
+process2 may not yet have finished.
+It is impossible for unbuffer to know how long to wait for process2
+and process2 may not ever finish,
+for example,
+if it is a filter.
+For expediency,
+unbuffer simply exits
+when it encounters an EOF from either its input
or process2.
-In order to have a version of unbuffer that worked in all situations,
-an oracle would be necessary. If you want an application-specific
-solution, workarounds or hand-coded Expect may be more suitable. For
-example, the following example shows how to allow grep to finish
-processing when the cat before it finishes first. Using cat to feed
-grep would never require unbuffer in real life. It is merely a
-placeholder for some imaginary process that may or may not finish.
-Similarly, the final cat at the end of the pipeline is also a
-placeholder for another process.
+In order to have a version of unbuffer
+that worked in all situations,
+an oracle would be necessary.
+If you want an application-specific solution,
+workarounds
+or hand-coded Expect may be more suitable.
+For example,
+the following example shows how to allow grep to finish
+processing
+when the cat before it finishes first.
+Using cat to feed grep would never require unbuffer in real life.
+It is merely a placeholder for some imaginary process
+that may or may not finish.
+Similarly,
+the final cat at the end of the pipeline
+is also a placeholder for another process.
.nf
@@ -67,7 +84,7 @@ $ cat /tmp/abcdef.log | unbuffer grep ab
$ (cat /tmp/abcdef.log ; sleep 1) | unbuffer grep abc | cat
abcdef
xxxabc defxxx
-$
+$
.fi
.SH BUGS
