#295 Alternatives, repetition, and list structure

[Lars Hellström]

Doctools has a command [opt] to mark something (often a command argument) as being optional. Two siblings of that piece of markup which I often find useful, but have been unable to apply consistently in .man pages, is alternatives and repetition.

Suitable syntax for alternatives would be

[alt {first alt.} {second alt.} {third alt.} ...]

e.g.

[alt [arg boolean] [const auto]]

to say that something is a boolean value or the constant "auto". A naive implementation of such an alt command could be

proc alt {args} {return "([join $args { | }])"}

since I've seen this formatting with parentheses and vertical bars in e.g. the documentation of the ftp package.

In line with that, repetition could have the syntax

[rep {word} ...]

and be naively implemented as

proc rep {args} {return "([join $args])*"}

i.e., a regexp-style rendering (as is also that of [alt] above), with * denoting zero or more repetitions of the arguments of [rep]. A more traditional rendering might however be

proc rep {args} {return "?[join $args] ...?"}

I want [rep] (name is not important, though) because I often find myself wanting to write

[call [cmd myCmd] [arg mandatory] [rep [arg option] [arg value]]]

for the option-value part of a command that could be

myCmd $mandatory
or
myCmd $mandatory -option $value
or
myCmd $mandatory -option $value -otherOption $otherValue
etc.

Also, the way I write packages and documentation, I often find I need to document the structure of various lists, just like one conventionally documents command syntaxes, and I don't see any good way to do that in doctools markup. For the special case of a list constructed as a command callback, it just occurred to me that I could write a dummy list with only a [call] heading, like so:

A command prefix used to format the values while taking the
key names into account. It is called as
[list_begin definitions]
[call \{*\}[arg choicecmd] [arg key] [arg value]]
[list_end]
Specifying a [option -choicecmd] overrides the
[option -entrycmd], if any.

but this is only a partial solution (and in the HTML rendering it seems to leave an awful lot of vertical space between the "It is called as" and "{*}choicecmd key value" lines).

In LaTeX, I'd write the above as

A command prefix used to format the values while taking the
key names into account. It is called as
\begin{quote}
\meta{choicecmd} \word{key} \word{value}
\end{quote}
Specifying a |-choicecmd| overrides the |-entrycmd|,
if any.

which to some extent (\meta, \word, and \verb shorthand `|') relies on particular packages, but what I'm after right now is something that can be used like the `quote' environment in this example.

As a concrete example, here is a passage of documentation in LaTeX, which documents the structures of two lists. The environment is my own `displaysyntax' rather than `quote', but the idea is the same:

The \word{msg-id} is used to provide a measure of reliability by
providing acknowledgements of message delivery. If an |envelope|
with nonempty \word{msg-id} arrives at its destination then a reply
message with \word{payload}
\begin{displaysyntax}
delivery ack \word{msg-id} \word{time}
\end{displaysyntax}
is sent to the \word{from} address. If an |envelope| with nonempty
\word{msg-id} could not be sent to the next connection in \word{to}
then a reply message with \word{payload}
\begin{displaysyntax}
delivery nack \word{msg-id} \word{remaining to} \word{reason}
\end{displaysyntax}
is sent to the \word{from} address. These |ack| and |nack| messages
have empty \word{msg-id}s.