Fix [Bug 1822268]

2 files changed, 42 insertions, 22 deletions

diff --git a/ChangeLog b/ChangeLog
index 7766db0..155ed03 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2007-10-30  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
+
+	* doc/interp.n: Shorten the basic descriptive text for some interp
+	subcommands so Solaris nroff doesn't truncate them. [Bug 1822268]
+
 2007-10-30  Donal K. Fellows  <dkf@users.sf.net>
 
 	* tools/tcltk-man2html.tcl (output-widget-options): Enhance the HTML
diff --git a/doc/interp.n b/doc/interp.n
index 93ef1c8..ea8dd80 100644
--- a/doc/interp.n
+++ b/doc/interp.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: interp.n,v 1.33 2007/10/29 11:28:50 dkf Exp $
+'\" RCS: @(#) $Id: interp.n,v 1.34 2007/10/30 14:06:40 dkf Exp $
 '\" 
 .so man.macros
 .TH interp n 7.6 Tcl "Tcl Built-In Commands"
@@ -14,7 +14,7 @@
 .SH NAME
 interp \- Create and manipulate Tcl interpreters
 .SH SYNOPSIS
-\fBinterp \fIoption \fR?\fIarg arg ...\fR?
+\fBinterp \fIsubcommand \fR?\fIarg arg ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
@@ -82,7 +82,7 @@ Both restrictions are motivated by safety concerns.
 The \fBinterp\fR command is used to create, delete, and manipulate
 slave interpreters, and to share or transfer
 channels between interpreters.  It can have any of several forms, depending
-on the \fIoption\fR argument:
+on the \fIsubcommand\fR argument:
 .TP
 \fBinterp\fR \fBalias\fR \fIsrcPath\fR \fIsrcToken\fR
 Returns a Tcl list whose elements are the \fItargetCmd\fR and
@@ -189,7 +189,7 @@ the slave that find out information about the slave's current state
 and stack frame.
 .TP
 \fBinterp exists \fIpath\fR
-Returns  \fB1\fR if a slave interpreter by the specified \fIpath\fR
+Returns \fB1\fR if a slave interpreter by the specified \fIpath\fR
 exists in this master, \fB0\fR otherwise. If \fIpath\fR is omitted, the
 invoking interpreter is used.
 .TP
@@ -222,29 +222,34 @@ Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 Returns a list of the names of all hidden commands in the interpreter
 identified by \fIpath\fR.
 .TP
-\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fB\-namespace\fR \fInamespace\fR? ?\fB\-global\fR? ?\fB\-\|\-\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR?
+\fBinterp\fR \fBinvokehidden\fR \fIpath\fR ?\fI\-option ...\fR? \fIhiddenCmdName\fR ?\fIarg ...\fR?
 Invokes the hidden command \fIhiddenCmdName\fR with the arguments supplied
 in the interpreter denoted by \fIpath\fR. No substitutions or evaluation
-are applied to the arguments.
+are applied to the arguments. Three \fI\-option\fRs are supported, all
+of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single
+argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR.
 If the \fB\-namespace\fR flag is present, the hidden command is invoked in
-the specified namespace in the target interpreter.
+the namespace called \fInsName\fR in the target interpreter.
 If the \fB\-global\fR flag is present, the hidden command is invoked at the
 global level in the target interpreter; otherwise it is invoked at the
 current call frame and can access local variables in that and outer call
 frames.
+The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a
+.QW \-
+character, and is otherwise unnecessary.
 If both the \fB\-namespace\fR and \fB\-global\fR flags are present, the
 \fB\-namespace\fR flag is ignored.
 Note that the hidden command will be executed (by default) in the
 current context stack frame of the \fIpath\fR interpreter.
 Hidden commands are explained in more detail in \fBHIDDEN COMMANDS\fR, below.
 .TP
-\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fIoption\fR? ?\fIvalue\fR \fI...\fR?
+\fBinterp\fR \fBlimit\fR \fIpath\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
 .VS 8.5
 Sets up, manipulates and queries the configuration of the resource
 limit \fIlimitType\fR for the interpreter denoted by \fIpath\fR.  If
-no \fIoption\fR is specified, return the current configuration of the
-limit.  If \fIoption\fR is the sole argument, return the value of that
-option.  Otherwise, a list of \fIoption\fR/\fIvalue\fR argument pairs
+no \fI\-option\fR is specified, return the current configuration of the
+limit.  If \fI\-option\fR is the sole argument, return the value of that
+option.  Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs
 must supplied. See \fBRESOURCE LIMITS\fR below for a more detailed
 explanation of what limits and options are supported.
 .VE 8.5
@@ -398,15 +403,20 @@ For more details on hidden commands, see \fBHIDDEN COMMANDS\fR, below.
 \fIslave \fBhidden\fR
 Returns a list of the names of all hidden commands in \fIslave\fR.
 .TP
-\fIslave \fBinvokehidden\fR ?\fB\-namespace\fR \fInamespace\fR? ?\fB\-global\fR ?\fB\-\|\-\fR? \fIhiddenName \fR?\fIarg ..\fR?
+\fIslave \fBinvokehidden\fR ?\fI\-option ...\fR? \fIhiddenName \fR?\fIarg ..\fR?
 This command invokes the hidden command \fIhiddenName\fR with the
 supplied arguments, in \fIslave\fR. No substitutions or evaluations are
-applied to the arguments.
+applied to the arguments. Three \fI\-option\fRs are supported, all
+of which start with \fB\-\fR: \fB\-namespace\fR (which takes a single
+argument afterwards, \fInsName\fR), \fB\-global\fR, and \fB\-\|\-\fR.
 If the \fB\-namespace\fR flag is given, the hidden command is invoked in
 the specified namespace in the slave.
 If the \fB\-global\fR flag is given, the command is invoked at the global
 level in the slave; otherwise it is invoked at the current call frame and
 can access local variables in that or outer call frames.
+The \fB\-\|\-\fR flag allows the \fIhiddenCmdName\fR argument to start with a
+.QW \-
+character, and is otherwise unnecessary.
 If both the \fB\-namespace\fR and \fB\-global\fR flags are given, the
 \fB\-namespace\fR flag is ignored.
 Note that the hidden command will be executed (by default) in the
@@ -417,13 +427,13 @@ see \fBHIDDEN COMMANDS\fR, below.
 \fIslave \fBissafe\fR
 Returns  \fB1\fR if the slave interpreter is safe, \fB0\fR otherwise.
 .TP
-\fIslave \fBlimit\fR \fIlimitType\fR ?\fIoption\fR? ?\fIvalue\fR \fI...\fR?
+\fIslave \fBlimit\fR \fIlimitType\fR ?\fI\-option\fR? ?\fIvalue\fR \fI...\fR?
 .VS 8.5
 Sets up, manipulates and queries the configuration of the resource
-limit \fIlimitType\fR for the slave interpreter.  If no \fIoption\fR
+limit \fIlimitType\fR for the slave interpreter.  If no \fI\-option\fR
 is specified, return the current configuration of the limit.  If
-\fIoption\fR is the sole argument, return the value of that option.
-Otherwise, a list of \fIoption\fR/\fIvalue\fR argument pairs must
+\fI\-option\fR is the sole argument, return the value of that option.
+Otherwise, a list of \fI\-option\fR/\fIvalue\fR argument pairs must
 supplied. See \fBRESOURCE LIMITS\fR below for a more detailed explanation of
 what limits and options are supported.
 .VE 8.5
@@ -685,9 +695,10 @@ catch and handle.
 Every limit has a number of options associated with it, some of which are
 common across all kinds of limits, and others of which are particular to the
 kind of limit.
+.VE 8.5
 .TP
 \fB\-command\fR
-.
+.VS 8.5
 This option (common for all limit types) specifies (if non-empty) a Tcl script
 to be executed in the global namespace of the interpreter reading and writing
 the option when the particular limit in the limited interpreter is exceeded.
@@ -697,33 +708,37 @@ reported through the background error mechanism (see \fBBACKGROUND ERROR
 HANDLING\fR). Note that the callbacks defined by one interpreter are
 completely isolated from the callbacks defined by another, and that the order
 in which those callbacks are called is undefined.
+.VE 8.5
 .TP
 \fB\-granularity\fR
-.
+.VS 8.5
 This option (common for all limit types) specifies how frequently (out of the
 points when the Tcl interpreter is in a consistent state where limit checking
 is possible) that the limit is actually checked. This allows the tuning of how
 frequently a limit is checked, and hence how often the limit-checking overhead
 (which may be substantial in the case of time limits) is incurred.
+.VE 8.5
 .TP
 \fB\-milliseconds\fR
-.
+.VS 8.5
 This option specifies the number of milliseconds after the moment defined in
 the \fB\-seconds\fR option that the time limit will fire. It should only ever
 be specified in conjunction with the \fB\-seconds\fR option (whether it was
 set previously or is being set this invocation.)
+.VE 8.5
 .TP
 \fB\-seconds\fR
-.
+.VS 8.5
 This option specifies the number of seconds after the epoch (see \fBclock
 seconds\fR) that the time limit for the interpreter will be triggered. The
 limit will be triggered at the start of the second unless specified at a
 sub-second level using the \fB\-milliseconds\fR option. This option may be the
 empty string, which indicates that a time limit is not set for the
 interpreter.
+.VE 8.5
 .TP
 \fB\-value\fR
-.
+.VS 8.5
 This option specifies the number of commands that the interpreter may execute
 before triggering the command limit. This option may be the empty string,
 which indicates that a command limit is not set for the interpreter.