Package: tcl-expect
Version: 5.45.4-4
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?
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
* 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.21-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 tcl-expect depends on:
ii libc6 2.41-6
ii libtcl8.6 8.6.16+dfsg-1
tcl-expect recommends no packages.
Versions of packages tcl-expect suggests:
ii expect 5.45.4-4
-- no debconf information
Input file is Expect.3tcl
Output from "mandoc -T lint Expect.3tcl": (shortened list)
1 input text line longer than 80 bytes: By default, it repor...
1 input text line longer than 80 bytes: Run fsck, and in res...
1 input text line longer than 80 bytes: Use the extended com...
1 input text line longer than 80 bytes: can be used. If EXP...
1 input text line longer than 80 bytes: itself, first call i...
1 line scope broken: TP breaks I
-.-.
Output from
test-nroff -mandoc -t -ww -z Expect.3tcl: (shortened list)
1 Use macro '.I' for one argument or split argument.
1 .IR is for at least 2 arguments, got 1
-.-.
Reduce space between words.
Expect.3tcl:111: #!/usr/bin/expect \-f
Expect.3tcl:212: #!/usr/bin/expect \-\-
Expect.3tcl:1095:string is not sent to the current process.) The
Expect.3tcl:1155:Any pattern beginning with a "\-" should be protected this
way. (All strings
Expect.3tcl:2465:early, your answer may appear echoed back in the middle of
the question.
Expect.3tcl:2523:newlines to returns, but most don't.) Unfortunately, there is
no way to find
-.-.
Remove space in the first column, if not indented.
Use ".in +<number>n" and ".in" to end it;
Or use ".nf" and ".fi" to end
it, for an extra indention.
Expect.3tcl:111: #!/usr/bin/expect \-f
Expect.3tcl:212: #!/usr/bin/expect \-\-
-.-.
Add a "\&" (or a comma (Oxford comma)) after an abbreviation
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.
1040:but it reads characters from /dev/tty (i.e. keystrokes from the user).
1054:but it reads characters from stdin (i.e. keystrokes from the user).
1912:fails (e.g. when
-.-.
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"
378: . . .
397: . . .
463:executing rather than returning as it normally would. By
466:resets the timeout timer. The
468:flag prevents timer from being restarted. (See
684:lines respectively. However, because expect is not line oriented,
1040:but it reads characters from /dev/tty (i.e. keystrokes from the user).
1054:but it reads characters from stdin (i.e. keystrokes from the user).
1095:string is not sent to the current process.) The
1155:Any pattern beginning with a "\-" should be protected this way. (All
strings
1730:output and for human-style output are mutually exclusive. Only the one
1731:specified last will be used. Furthermore, no
1912:fails (e.g. when
2586:Computing Systems, Vol. 4, No.\& 2, University of California Press
Journals,
2591:Libes, Proceedings of the Summer 1992 USENIX Conference, pp. 135\(en144,
2597:Vol. 23, No.\& 5, May, 1993.
-.-.
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 74, length 91
Run fsck, and in response to its questions, answer "yes", "no" or give control
back to you,
Line 1023, length 143
By default, it reports on the current spawn id. An optional spawn id
specification may be given for information on that spawn id. For example
Line 1262, length 89
itself, first call interpreter (perhaps by using an escape character), and then
press ^Z.
Line 2283, length 83
Use the extended command names if you need this compatibility between
environments.
Line 2450, length 104
can be used. If EXPECT_PROMPT doesn't exist, the code still has a good chance
of functioning correctly.
Longest line is: 143 characters.
Longest line is number 1023 with 143 characters
By default, it reports on the current spawn id. An optional spawn id
specification may be given for information on that spawn id. For example
-.-.
Do not use more than two space characters between sentences or (better)
only a new line character.
1095:string is not sent to the current process.) The
1155:Any pattern beginning with a "\-" should be protected this way. (All
strings
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
46:See libexpect(3).
214:Note that the usual getopt(3) and execve(2) conventions must be observed
266:are Tcl commands (see tcl(3)).
444:takes no other actions beyond what the normal _exit(2) procedure does.
448:typically documented under exit(3).)
1882:initialized so that all settings are "sane" (according to stty(1)).
2191:See signal(3) for more info.
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
1687:must be separated. For example, "set send_slow {10 .001}" would force
1701:transitions. The third parameter is a measure of variability where .1
1714: set send_human {.1 .3 1 .05 2}
1721: set send_human {.4 .4 .2 .5 100}
-.-.
Split a punctuation from a single argument, if a two-font macro is meant.
843:.I any_spawn_id.
-.-.
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).
Expect.3tcl:378: . . .
Expect.3tcl:397: . . .
Expect.3tcl:463:executing rather than returning as it normally would. By
Expect.3tcl:466:resets the timeout timer. The
Expect.3tcl:468:flag prevents timer from being restarted. (See
Expect.3tcl:574:.BI expect " [[\-opts] pat1 body1] ... [\-opts] patn [bodyn]"
Expect.3tcl:684:lines respectively. However, because expect is not line
oriented,
Expect.3tcl:1040:but it reads characters from /dev/tty (i.e. keystrokes from
the user).
Expect.3tcl:1054:but it reads characters from stdin (i.e. keystrokes from the
user).
Expect.3tcl:1088:.BI interact " [string1 body1] ... [stringn [bodyn]]"
Expect.3tcl:1730:output and for human-style output are mutually exclusive. Only
the one
Expect.3tcl:1731:specified last will be used. Furthermore, no
Expect.3tcl:1912:fails (e.g. when
Expect.3tcl:2586:Computing Systems, Vol. 4, No.\& 2, University of California
Press Journals,
Expect.3tcl:2591:Libes, Proceedings of the Summer 1992 USENIX Conference, pp.
135\(en144,
Expect.3tcl:2597:Vol. 23, No.\& 5, May, 1993.
-.-.
Use thousand markers to make large numbers easy to read
2353:timeouts of above 1000000 to be equivalent to 0.
-.-.
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
2437:.SH "EXPECT HINTS"
2559:.SH "SEE ALSO"
-.-.
Add "\&" after an ellipsis, when it does not end a sentence
574:.BI expect " [[\-opts] pat1 body1] ... [\-opts] patn [bodyn]"
1088:.BI interact " [string1 body1] ... [stringn [bodyn]]"
1548:.BI overlay " [\-# spawn_id] [\-# spawn_id] [...] program [args]"
1991:be accessed by appending "< /dev/tty...\&" to the command. (Note that
-.-.
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")
an.tmac:<stdin>:111: style: 4 leading space(s) on input line
an.tmac:<stdin>:212: style: 4 leading space(s) on input line
an.tmac:<stdin>:827: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
Output from "test-nroff -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")
an.tmac:<stdin>:111: style: 4 leading space(s) on input line
an.tmac:<stdin>:212: style: 4 leading space(s) on input line
an.tmac:<stdin>:827: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
-.-.
Spelling (codespell):
overlayed ==> overlaid
reenable ==> re-enable
reenabled ==> re-enabled
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- Expect.3tcl 2025-04-07 01:12:37.878529967 +0000
+++ Expect.3tcl.new 2025-04-07 02:10:03.093326526 +0000
@@ -43,7 +43,8 @@ and
.BR wish .
.B Expect
can also be used directly in C or C++ (that is, without Tcl).
-See libexpect(3).
+See
+.BR libexpect (3).
.PP
The name "Expect" comes from the idea of
.I send/expect
@@ -71,7 +72,10 @@ restart it (again and again) until it do
then hand over control to you.
.TP
\(bu
-Run fsck, and in response to its questions, answer "yes", "no" or give control
back to you,
+Run fsck,
+and in response to its questions,
+answer "yes", "no"
+or give control back to you,
based on predetermined criteria.
.TP
\(bu
@@ -108,7 +112,9 @@ for a list of commands to execute.
may also be invoked implicitly on systems which support the #!\& notation
by marking the script executable, and making the first line in your script:
+.nf
#!/usr/bin/expect \-f
+.fi
Of course, the path must accurately describe where
.B Expect
@@ -209,9 +215,15 @@ interpretation by Expect. For example,
original arguments (including the script name) in the variable
.IR argv .
+.nf
#!/usr/bin/expect \-\-
+.fi
-Note that the usual getopt(3) and execve(2) conventions must be observed
+Note that the usual
+.BR getopt (3)
+and
+.BR execve (2)
+conventions must be observed
when adding arguments to the #!\& line.
.PP
The file $exp_library/expect.rc is sourced automatically if present, unless
@@ -263,7 +275,9 @@ Commands used here but not defined (e.g.
.BR set ,
.BR if ,
.BR exec )
-are Tcl commands (see tcl(3)).
+are Tcl commands
+(see
+.BR tcl (3)).
.B Expect
supports additional commands, described below.
Unless otherwise specified, commands return the empty string.
@@ -291,7 +305,6 @@ program while "expect" with a lower-case
command within the
.B Expect
program.)
-.I
.TP 6
.BI close " [\-slave] [\-onexec 0|1] [\-i spawn_id]"
closes the connection to the current process.
@@ -316,7 +329,7 @@ you will need to explicitly call
The
.B \-onexec
flag determines whether the spawn id will be closed in any new spawned
-processes or if the process is overlayed. To leave a spawn id open,
+processes or if the process is overlaid. To leave a spawn id open,
use the value 0. A non-zero integer value will force the spawn closed
(the default) in any new processes.
@@ -375,7 +388,7 @@ to continue running the script in the ba
if {[fork]!=0} exit
disconnect
- . . .
+ .\& .\& .\&
.fi
The following script reads a password, and then runs a program
@@ -394,7 +407,7 @@ command which demonstrates how to turn o
spawn priv_prog
expect Password:
send "$expect_out(1,string)\er"
- . . .
+ .\& .\& .\&
exit
}
@@ -441,11 +454,14 @@ Upon exiting,
all connections to spawned processes are closed. Closure will be detected
as an EOF by spawned processes.
.B exit
-takes no other actions beyond what the normal _exit(2) procedure does.
+takes no other actions beyond what the normal
+.BR _exit (2)
+procedure does.
Thus, spawned processes that do not check for EOF may continue to run.
(A variety of conditions are important to determining, for example, what
signals a spawned process will be sent, but these are system-dependent,
-typically documented under exit(3).)
+typically documented under
+.BR exit (3).)
Spawned processes that continue to run will be inherited by init.
.I status
@@ -460,12 +476,14 @@ The command
allows
.B expect
itself to continue
-executing rather than returning as it normally would. By
-default
+executing rather than returning as it normally would.
+By default
.B exp_continue
-resets the timeout timer. The
+resets the timeout timer.
+The
.I \-continue_timer
-flag prevents timer from being restarted. (See
+flag prevents timer from being restarted.
+(See
.B expect
for more information.)
.TP
@@ -571,7 +589,7 @@ flag,
.B Expect
prints an error and exits if the version is out of date.
.TP
-.BI expect " [[\-opts] pat1 body1] ... [\-opts] patn [bodyn]"
+.BI expect " [[\-opts] pat1 body1] ...\& [\-opts] patn [bodyn]"
waits until one of the patterns matches the output of a spawned process,
a specified time period has passed, or an end-of-file is seen.
If the final body is empty, it may be omitted.
@@ -681,7 +699,8 @@ can look unnatural. Thus, use of $ is e
describe the characters at the end of a string.
Note that in many editors, the ^ and $ match the beginning and end of
-lines respectively. However, because expect is not line oriented,
+lines respectively.
+However, because expect is not line oriented,
these characters match the beginning and end of the data (as opposed
to lines) currently in the expect matching buffer. (Also, see the
note below on "system indigestion".)
@@ -824,7 +843,7 @@ password" from the spawn_id named by $pr
.fi
The value of the global variable
-.IR any_spawn_id
+.I any_spawn_id
may be used to match patterns to any spawn_ids that are named
with all other
.B \-i
@@ -840,7 +859,7 @@ is made available to any other patterns
in the same
.B expect
command associated with
-.I any_spawn_id.
+.IR any_spawn_id .
The
.B \-i
@@ -1020,7 +1039,11 @@ command was executed (not when its patte
The \-info flag causes
.B expect_before
to return the current specifications of what patterns it will match.
-By default, it reports on the current spawn id. An optional spawn id
specification may be given for information on that spawn id. For example
+By default,
+it reports on the current spawn id.
+An optional spawn id specification may be given
+for information on that spawn id.
+For example
.nf
expect_before \-info \-i $proc
@@ -1037,7 +1060,8 @@ The output of the \-info flag can be reu
.BI expect_tty " [expect_args]"
is like
.B expect
-but it reads characters from /dev/tty (i.e. keystrokes from the user).
+but it reads characters from /dev/tty
+(i.e.\& keystrokes from the user).
By default, reading is performed in cooked mode.
Thus, lines must end with a return in order for
.B expect
@@ -1051,7 +1075,7 @@ command below).
.BI expect_user " [expect_args]"
is like
.B expect
-but it reads characters from stdin (i.e. keystrokes from the user).
+but it reads characters from stdin (i.e.\& keystrokes from the user).
By default, reading is performed in cooked mode.
Thus, lines must end with a return in order for
.B expect
@@ -1085,14 +1109,15 @@ even momentarily. Thus, it is safest to
.B fork
before spawning processes.
.TP
-.BI interact " [string1 body1] ... [stringn [bodyn]]"
+.BI interact " [string1 body1] ...\& [stringn [bodyn]]"
gives control of the current process to the user, so that
keystrokes are sent to the current process,
and the stdout and stderr of the current process are returned.
.IP
String-body pairs may be specified as arguments, in which case the
body is executed when the corresponding string is entered. (By default, the
-string is not sent to the current process.) The
+string is not sent to the current process.)
+The
.B interpreter
command is assumed, if the final body is missing.
.IP
@@ -1152,8 +1177,8 @@ command uses glob-style patterns by defa
flag may be used to protect patterns that might otherwise match
.B interact
flags from doing so.
-Any pattern beginning with a "\-" should be protected this way. (All strings
-starting with "\-" are reserved for future options.)
+Any pattern beginning with a "\-" should be protected this way.
+(All strings starting with "\-" are reserved for future options.)
The
.B \-re
@@ -1259,7 +1284,10 @@ If you really want to send a SIGSTOP to
consider spawning csh first and then running your program.
On the other hand, if you want to send a SIGSTOP to
.B Expect
-itself, first call interpreter (perhaps by using an escape character), and
then press ^Z.
+itself,
+first call interpreter
+(perhaps by using an escape character),
+and then press ^Z.
.IP
String-body pairs can be used as a shorthand for avoiding having
to enter the interpreter and execute commands interactively. The previous
@@ -1523,7 +1551,7 @@ most recent non-info arguments given.
By default, the send/expect dialogue is logged to stdout
(and a logfile if open).
The logging to stdout is disabled by the command "log_user 0"
-and reenabled by "log_user 1". Logging to the logfile is unchanged.
+and re-enabled by "log_user 1". Logging to the logfile is unchanged.
The
.B \-info
@@ -1545,7 +1573,7 @@ With the
flag, the size is set for the named spawn id, otherwise it is set for
the current process.
.TP
-.BI overlay " [\-# spawn_id] [\-# spawn_id] [...] program [args]"
+.BI overlay " [\-# spawn_id] [\-# spawn_id] [...\&] program [args]"
executes
.I "program args"
in place of the current
@@ -1684,7 +1712,7 @@ controlled by the value of the variable
element list. The first element is an integer that describes the
number of bytes to send atomically. The second element is a real
number that describes the number of seconds by which the atomic sends
-must be separated. For example, "set send_slow {10 .001}" would force
+must be separated. For example, "set send_slow {10 0.001}" would force
"send \-s" to send strings with 1 millisecond in between each 10
characters sent.
@@ -1698,7 +1726,7 @@ the variable "send_human" which takes a
two elements are average interarrival time of characters in seconds.
The first is used by default. The second is used at word endings, to
simulate the subtle pauses that occasionally occur at such
-transitions. The third parameter is a measure of variability where .1
+transitions. The third parameter is a measure of variability where 0.1
is quite variable, 1 is reasonably variable, and 10 is quite
invariable. The extremes are 0 to infinity. The last two parameters
are, respectively, a minimum and maximum interarrival time.
@@ -1711,14 +1739,14 @@ example, the following command emulates
consistent typist:
.nf
- set send_human {.1 .3 1 .05 2}
+ set send_human {0.1 0.3 1 0.05 2}
send \-h "I'm hungry. Let's do lunch."
.fi
while the following might be more suitable after a hangover:
.nf
- set send_human {.4 .4 .2 .5 100}
+ set send_human {0.4 0.4 0.2 0.5 100}
send \-h "Goodd party lash night!"
.fi
@@ -1727,8 +1755,10 @@ correction situations yourself by embedd
in a send argument.
The flags for sending null characters, for sending breaks, for forcing slow
-output and for human-style output are mutually exclusive. Only the one
-specified last will be used. Furthermore, no
+output and for human-style output are mutually exclusive.
+Only the one
+specified last will be used.
+Furthermore, no
.I string
argument can be specified with the flags for sending null characters or breaks.
@@ -1879,7 +1909,9 @@ This is not supported on all systems.
Internally,
.B spawn
uses a pty, initialized the same way as the user's tty. This is further
-initialized so that all settings are "sane" (according to stty(1)).
+initialized so that all settings are "sane"
+(according to
+.BR stty (1)).
If the variable
.I stty_init
is defined, it is interpreted in the style of stty arguments
@@ -1909,7 +1941,7 @@ If
.I program
cannot be spawned successfully because
.BR exec (2)
-fails (e.g. when
+fails (e.g.\& when
.I program
doesn't exist), an error message will be returned by the next
.B interact
@@ -2185,10 +2217,12 @@ Alternatively, you can trap to the debug
will not let you override the action for SIGALRM as this is used internally
to
.BR Expect .
-The disconnect command sets SIGALRM to SIG_IGN (ignore). You can reenable
+The disconnect command sets SIGALRM to SIG_IGN (ignore). You can re-enable
this as long as you disable it during subsequent spawn commands.
-See signal(3) for more info.
+See
+.BR signal (3)
+for more info.
.TP
.BI wait " [args]"
delays until a spawned process (or
@@ -2280,7 +2314,8 @@ For this reason, most of the
commands are also available as "exp_XXXX".
Commands and variables beginning with "exp", "inter", "spawn",
and "timeout" do not have aliases.
-Use the extended command names if you need this compatibility between
environments.
+Use the extended command names
+if you need this compatibility between environments.
.B Expect
takes a rather liberal view of scoping.
@@ -2350,7 +2385,7 @@ doesn't know about. Please find out wha
back to me.
Ultrix 4.1 (at least the latest versions around here) considers
-timeouts of above 1000000 to be equivalent to 0.
+timeouts of above 1,000,000 to be equivalent to 0.
Digital UNIX 4.0A (and probably other versions) refuses to allocate
ptys if you define a SIGCHLD handler. See grantpt page for more info.
@@ -2434,7 +2469,7 @@ the command (i.e., sleep).
The expect_background command ignores \-timeout arguments and has no
concept of timeouts in general.
-.SH "EXPECT HINTS"
+.SH EXPECT HINTS
There are a couple of things about
.B Expect
that may be non-intuitive.
@@ -2447,7 +2482,9 @@ shells, portably automating rlogin can b
the prompt. A reasonable convention is to have users store a regular
expression describing their prompt (in particular, the end of it) in
the environment variable EXPECT_PROMPT. Code like the following
-can be used. If EXPECT_PROMPT doesn't exist, the code still has a good chance
of functioning correctly.
+can be used.
+If EXPECT_PROMPT doesn't exist,
+the code still has a good chance of functioning correctly.
.nf
set prompt "(%|#|\e\e$) $" ;# default prompt
@@ -2462,7 +2499,7 @@ patterns that include the end of whateve
you expect to see. This avoids the possibility of answering a question
before seeing the entire thing. In addition, while you may well be
able to answer questions before seeing them entirely, if you answer
-early, your answer may appear echoed back in the middle of the question.
+early, your answer may appear echoed back in the middle of the question.
In other words, the resulting dialogue will be correct but look scrambled.
Most prompts include a space character at the end.
@@ -2556,7 +2593,7 @@ The result is a script which may be exec
When invoked, it runs the
.B Expect
script.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR Tcl (3),
.BR libexpect (3)
.br
@@ -2583,25 +2620,26 @@ Washington, D.C., January 22\(en26, 1990
.br
.I
"expect: Scripts for Controlling Interactive Programs" \fRby Don Libes,
-Computing Systems, Vol. 4, No.\& 2, University of California Press Journals,
+Computing Systems, Vol.\& 4, No.\& 2, University of California Press Journals,
November 1991.
.br
.I
"Regression Testing and Conformance Testing Interactive Programs", \fRby Don
-Libes, Proceedings of the Summer 1992 USENIX Conference, pp. 135\(en144,
+Libes, Proceedings of the Summer 1992 USENIX Conference, pp.\& 135\(en144,
San Antonio, TX, June 12\(en15, 1992.
.br
.I
"Kibitz \- Connecting Multiple Interactive Programs Together", \fRby Don Libes,
Software \- Practice & Experience, John Wiley & Sons, West Sussex, England,
-Vol. 23, No.\& 5, May, 1993.
+Vol.\& 23, No.\& 5, May, 1993.
.br
.I
"A Debugger for Tcl Applications", \fRby Don Libes,
Proceedings of the 1993 Tcl/Tk Workshop, Berkeley, CA, June 10\(en11, 1993.
.SH AUTHOR
Don Libes, National Institute of Standards and Technology
-.SH ACKNOWLEDGMENTS
+.SH
+ACKNOWLEDGMENTS
Thanks to John Ousterhout for Tcl, and Scott Paisley for inspiration.
Thanks to Rob Savoye for Expect's autoconfiguration code.
.PP
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
-.-
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)
-.-
