Tcl Library Source Code

View Ticket
Login
Ticket UUID: 1969144
Title: Alternatives, repetition, and list structure
Type: RFE Version: None
Submitter: lars_h Created on: 2008-05-21 21:36:59
Subsystem: doctools Assigned To: andreas_kupries
Priority: 5 Medium Severity:
Status: Open Last Modified: 2008-05-21 21:36:59
Resolution: Closed By:
    Closed on:
Description:
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.