not a PATCH: fix/break indenting in _arguments docs

not a PATCH: fix/break indenting in _arguments docs

[Mikael Magnusson]

I probably have no idea what I'm doing, but without doing this the
whole rest of the text from the point of the enditem on goes back on the
same column as the tag names in the man pages. Ie, the end of the
_arguments text looks like this:

       The last two descriptions say what should be  completed  as  arguments.   The
       first  describes  the  first  argument as a `postscript file' and makes files
       ending in `ps' or `eps' be completed.  The last description gives  all  other
       arguments the description `page numbers' but does not offer completions.     

       _cache_invalid cache_identifier
              This function returns status zero if the completions cache correspond-
              ing to the given cache identifier  needs  rebuilding.   It  determines

The first place it seems to go wrong is here:

                     refer  only  to  the  words after the option.  When preceded by
                     three colons, they are modified to refer only to the words cov-
                     ered by this description.

       Any  literal  colon  in  an optname, message, or action must be preceded by a
       backslash, `\:'.                                                             

For some reason the subsequent text gets unindented after an enditem()
instead of staying at the same level. I initially suspected my yodl was
broken, but sshing in to some other hosts it looks like they have the
same problem.

With the patch however, the indenting is totally wrong in the pdf version,
and it was correct before there.

Other places seem to nest startitem()s without any problem. Maybe I
should look at some yodl docs one of these days.

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 8ceeb9d..545e616 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -3472,7 +3472,6 @@ has not been reached, tt(NORMARG) is set to tt(-1).  The caller
 should declare `tt(integer NORMARG)' if the tt(-n) option is passed;
 otherwise the parameter is not used.
 
-startitem()
 xitem(var(n)tt(:)var(message)tt(:)var(action))
 item(var(n)tt(::)var(message)tt(:)var(action))(
 This describes the var(n)'th normal argument.  The var(message) will be 
@@ -3531,7 +3530,6 @@ utility function like tt(_guard) as part of the action.
 The following forms are available for the initial var(optspec), whether
 or not the option has arguments.
 
-startitem()
 item(tt(*)var(optspec))(
 Here var(optspec) is one of the remaining forms below.  This indicates
 the following var(optspec) may be repeated.  Otherwise if the
@@ -3584,7 +3582,6 @@ value of the style is displayed, with any appearance of the sequence
 `tt(%d)' in it replaced by the var(message) of the first var(optarg)
 that follows the var(optspec); see below.
 )
-enditem()
 
 It is possible for options with a literal `PLUS()' or `tt(=)' to
 appear, but that character must be quoted, for example `tt(-\+)'.
@@ -3592,7 +3589,6 @@ appear, but that character must be quoted, for example `tt(-\+)'.
 Each var(optarg) following an var(optspec) must take one of the
 following forms:
 
-startitem()
 xitem(tt(:)var(message)tt(:)var(action))
 item(tt(::)var(message)tt(:)var(action))(
 An argument to the option; var(message) and var(action) are treated as
@@ -3621,9 +3617,7 @@ modified during the execution or evaluation of the var(action) to refer
 only to the words after the option.  When preceded by three colons, they
 are modified to refer only to the words covered by this description.
 )
-enditem()
 )
-enditem()
 
 Any literal colon in an var(optname), var(message), or var(action)
 must be preceded by a backslash, `tt(\:)'.
@@ -3664,7 +3658,6 @@ of tags is needed unless a function call introduces a new one.
 
 The forms for var(action) are as follows.
 
-startitem()
 item(tt( ) (single unquoted space))(
 This is useful where an argument is required but it is not possible or
 desirable to generate matches for it.  The
@@ -3760,7 +3753,6 @@ before executing the var(action) and hence may be referred to inside it,
 typically in an expansion of the form `tt($expl[@])' which preserves empty
 elements of the array.
 )
-enditem()
 
 During the performance of the action the array `tt(line)'
 will be set to the command name and normal arguments from the command

Re: not a PATCH: fix/break indenting in _arguments docs

[Bart Schaefer]

On May 25, 12:01am, Mikael Magnusson wrote:
}
} I probably have no idea what I'm doing, but without doing this the
} whole rest of the text from the point of the enditem on goes back on the
} same column as the tag names in the man pages.
[...]
} Other places seem to nest startitem()s without any problem. Maybe I
} should look at some yodl docs one of these days.

You don't need to look at the yodl docs, really (I never have).  What you
need to look at is zman.yo, where startitem() et al. are defined.

startitem() defines ITEM().

enditem() first calls ENDITEM() and then (re)defines it.

item() calls ITEM(), redefines ITEM(), ENDITEM(), and PARAGRAPH(),
then expands ARG2 [which might call startitem, item, et al. and
thereby redefine things again] and finally calls ENDITEM().

There are also some shenanigans inside xitem() but I don't think they
are material here.

The upshot is that something about the *way* that startitem/enditem
are nested in the _arguments region causes ENDITEM() to be defined
such that .RE is emitted four times when it should only be emitted
(I think) twice.  ENDITEM() is called by [1] the nested item(), [2]
the nested enditem(), [3] the outer item(), [4] the final enditem(),
and spits out .RE each time.

Of note is that the startitem() just before _all_labels is the only
one I can find where there have been three calls to startitem() with
no intervening enditem(); the third call starts at *optspec.  I think
the business with redefining only handles at most one nested set.

However, removing the just the startitem()/enditem() pair is not
sufficient to fix this -- it seems to be the multiple levels of
nested item() that actually create the problem.

I don't see any way to fix this without pulling the description of
_arguments out into its own subsection [which it is certainly long
enough to warrant anyway] or completely reworking startitem() and
enditem() in all document formats so that item() doesn't have to
muck around with redefining ENDITEM().

--