problems in zshcompctl.1, zshcontrib.1, zshmodules.1

problems in zshcompctl.1, zshcontrib.1, zshmodules.1

[esr]

This is automatically generated email about problems in a man page for which
you appear to be responsible.  If you are not the right person or list, tell
me and I will attempt to correct my database.

See http://catb.org/~esr/doclifter/problems.html for details on how and
why these patches were generated.  Feel free to email me with any questions.
Note: These patches do not change the mod date of any manual page.  You
may wish to do that by hand.

Problems with zshcompctl.1:

1. List syntax error. This means .IP, .TP or .RS/.RE markup is garbled.
This confuses doclifter, and may also mess up stricter troff
interpreters like Xman, Rosetta, and TkMan.

--- zshcompctl.1-orig	2004-11-20 17:09:24.124991416 -0500
+++ zshcompctl.1	2004-11-20 17:10:38.177733688 -0500
@@ -589,17 +589,13 @@
 .PP
 .SH "EXTENDED COMPLETION"
 .PD 0
-.TP
 .nf
 \fBcompctl\fP [ \fB\-CDT\fP ] \fIoptions\fP \fB\-x\fP \fIpattern\fP \fIoptions\fP \fB\-\fP \&.\&.\&. \fB\-\-\fP
   [ \fIcommand\fP \&.\&.\&. ]
-.fi
-.TP
-.nf
+
 \fBcompctl\fP [ \fB\-CDT\fP ] \fIoptions\fP [ \fB\-x\fP \fIpattern\fP \fIoptions\fP \fB\-\fP \&.\&.\&. \fB\-\-\fP ]
   [ \fB+\fP \fIoptions\fP [ \fB\-x\fP \&.\&.\&. \fB\-\-\fP ] \&.\&.\&. [\fB+\fP] ] [ \fIcommand\fP \&.\&.\&. ]
 .fi
-.PD
 .PP
 The form with `\fB\-x\fP' specifies extended completion for the
 commands given; as shown, it may be combined with alternative
-----------------------------
Problems with zshcontrib.1:

1. List syntax error. This means .IP, .TP or .RS/.RE markup is garbled.
This confuses doclifter, and may also mess up stricter troff
interpreters like Xman, Rosetta, and TkMan.

--- zshcontrib.1-orig	2006-12-26 12:04:28.000000000 -0500
+++ zshcontrib.1	2006-12-26 12:05:55.000000000 -0500
@@ -1293,10 +1293,7 @@
 should be checked if attempting to execute a file by extension
 \fB\&.\fP\fIext\fP does not have the expected effect\&.
 .PP
-.PD 0
 .TP
-.PD
-
 The command `\fBalias \-s\fP \fIext\fP' should show
 `\fBps=zsh\-mime\-handler\fP'\&.  If it shows something else, another suffix
 alias was already installed and was not overwritten\&.  If it shows
@@ -1305,7 +1302,6 @@
 \fB\&.ext\fP files\&.  In that case, appropriate handling should be added to
 \fB~/\&.mime\&.types\fP and \fBmailcap\fP\&.
 .TP
-
 If the extension is handled by \fBzsh\-mime\-handler\fP but the file is
 not opened correctly, either the handler defined for the type is
 incorrect, or the flags associated with it are in appropriate\&.  Running
-----------------------------
Problems with zshmodules.1:

1. Unbalanced .RS or .RE macro

2. Unclosed .RS, appears to be a broken attempt to express list structure.

--- zshmodules.1-orig	2004-11-19 14:26:57.372897376 -0500
+++ zshmodules.1	2004-11-19 14:27:19.109592896 -0500
@@ -1179,7 +1179,6 @@
 \fBzsocket\fP [ \fB\-altv\fP ] [ \fB\-d\fP \fIfd\fP ] [ \fIargs\fP ]
 \fBzsocket\fP is implemented as a builtin to allow full use of shell
 command line editing, file I/O, and job control mechanisms\&.
-.RS
 .PP
 .SS "Outbound Connections"
 .PP
-----------------------------

--
                             Eric S. Raymond

Re: problems in zshcompctl.1, zshcontrib.1, zshmodules.1

[Peter Stephenson]

esr@thyrsus.com wrote:
> Problems with zshcompctl.1:
> 
> 1. List syntax error. This means .IP, .TP or .RS/.RE markup is garbled.
> This confuses doclifter, and may also mess up stricter troff
> interpreters like Xman, Rosetta, and TkMan.

I would guess it's complaining about the nofill() instructions, but it's
not clear... I've rewritten it to be closer to other command descriptions.

> Problems with zshcontrib.1:
> 
> 1. List syntax error. This means .IP, .TP or .RS/.RE markup is garbled.
> This confuses doclifter, and may also mess up stricter troff
> interpreters like Xman, Rosetta, and TkMan.

This was an item()(...) formatted so as to get indented paragraphs with
no other mark up; I couldn't find another way of doing that in Yodl.
I've simply removed the extra formatting.

> Problems with zshmodules.1:
> 
> 1. Unbalanced .RS or .RE macro
> 
> 2. Unclosed .RS, appears to be a broken attempt to express list structure.

This doesn't seem to be happening with yodl 1.31.18.  I gave up on more
recent versions in frustration.

Index: Doc/Zsh/compctl.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compctl.yo,v
retrieving revision 1.7
diff -u -r1.7 compctl.yo
--- Doc/Zsh/compctl.yo	24 Apr 2005 18:38:03 -0000	1.7
+++ Doc/Zsh/compctl.yo	5 Jan 2007 20:42:19 -0000
@@ -559,15 +559,19 @@
 list of flags is used even if the current list produced matches.
 
 texinode(Extended Completion)(Example)(Alternative Completion)(Completion Using compctl)
+
+Additional options are available that restrict completion to some part
+of the command line; this is referred to as `extended completion'.
+
 sect(Extended Completion)
 startlist()
-list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \
-tt(-x) var(pattern) var(options) tt(-) ... tt(-)tt(-)
-  [ var(command) ... ]))
-list(nofill(tt(compctl) [ tt(-CDT) ] var(options) \
-[ tt(-x) var(pattern) var(options) tt(-) ... tt(-)tt(-) ]
-  [ tt(PLUS()) var(options) [ tt(-x) ... tt(-)tt(-) ] ... [tt(PLUS())] ] \
-[ var(command) ... ]))
+list(tt(compctl) [ tt(-CDT) ] var(options) \
+tt(-x) var(pattern) var(options) tt(-) ... tt(-)tt(-))
+list(         [ var(command) ... ])
+list(tt(compctl) [ tt(-CDT) ] var(options) \
+[ tt(-x) var(pattern) var(options) tt(-) ... tt(-)tt(-) ])
+list(         [ tt(PLUS()) var(options) [ tt(-x) ... tt(-)tt(-) ] ... \
+[tt(PLUS())] ] [ var(command) ... ])
 endlist()
 
 The form with `tt(-x)' specifies extended completion for the
Index: Doc/Zsh/contrib.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/contrib.yo,v
retrieving revision 1.65
diff -u -r1.65 contrib.yo
--- Doc/Zsh/contrib.yo	15 Dec 2006 11:44:29 -0000	1.65
+++ Doc/Zsh/contrib.yo	5 Jan 2007 20:42:21 -0000
@@ -1624,8 +1624,6 @@
 should be checked if attempting to execute a file by extension
 tt(.)var(ext) does not have the expected effect.
 
-startitem()
-item()(
 The command `tt(alias -s) var(ext)' should show
 `tt(ps=zsh-mime-handler)'.  If it shows something else, another suffix
 alias was already installed and was not overwritten.  If it shows
@@ -1633,8 +1631,7 @@
 handler was found in the tt(.mime.types) and tt(mailcap) combination for
 tt(.ext) files.  In that case, appropriate handling should be added to
 tt(~/.mime.types) and tt(mailcap).
-)
-item()(
+
 If the extension is handled by tt(zsh-mime-handler) but the file is
 not opened correctly, either the handler defined for the type is
 incorrect, or the flags associated with it are in appropriate.  Running
@@ -1648,8 +1645,6 @@
 
 example(text/html; /usr/bin/lynx '%s'; needsterminal)
 )
-enditem()
-)
 findex(pick-web-browser)
 item(tt(pick-web-browser))(
 This function is separate from the two MIME functions described above

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/