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

[Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx>]

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().

--