Re: [Docutils-develop] Option fields...

[Adam C. <ad...@ch...>]

On Wed, 03 Jul 2002 20:29:09 -0400 David Goodger
<go...@us...> wrote:

> Adam Chodorowski wrote:
> > Basically, I would like option lists to support also AmigaOS/AROS
> > syntax in option lists. I don't know how easy that would be to add.
> 
> Can you give a link to an authoritative (& specific) reference, with
> more detail and examples?  I don't understand what an AmigaOS command
> line should contain.

Hmmm... I can't find any usefull online reference really for the syntax.
You can find a reference over all standard AmigaDOS commands at
http://www.nethkin.com/bmori/amiga/dos2.html, which contains some real
examples.

The syntax is described in quite good detail in the documentation for the
ReadArgs() library function, although you have to ignore the implementation
details while reading it. Here's is an excerpt:

"ReadArgs() parses the commandline according to a template that is
passed to it.  This specifies the different command-line options and
their types.  A template consists of a list of options.  Options are
named in "full" names where possible (for example, "Quick" instead of
"Q").  Abbreviations can also be specified by using "abbrev=option"
(for example, "Q=Quick").

Options in the template are separated by commas.  To get the results
of ReadArgs(), you examine the array of longwords you passed to it
(one entry per option in the template).  This array should be cleared
(or initialized to your default values) before passing to ReadArgs().
Exactly what is put in a given entry by ReadArgs() depends on the type
of option.  The default is a string (a sequence of non-whitespace
characters, or delimited by quotes, which will be stripped by
ReadArgs()), in which case the entry will be a pointer.

Options can be followed by modifiers, which specify things such as
the type of the option.  Modifiers are specified by following the
option with a '/' and a single character modifier.  Multiple modifiers
can be specified by using multiple '/'s."

Then comes a list of allowed modifiers. For example, the template  for the
"Join" command (which concatenates files) is "FILE/M/A,AS=TO/K/A". 
Some typical invokations (which are all equivalent) would be:

% JOIN file1 file2 AS joined
% JOIN FILE file1 file2 TO joined

The problem for reST is the fact that you don't *need* to have modifiers on
the options, so it's very hard to distinguish. A typical description of the
options in ASCII text looks like:

FILE/M/A	Two or more files to be joined.
AS=TO/K/A	The destination file.

> Given your brief description, I'm not optimistic that it can be added
> easily.  All other option syntaxes begin with some symbol: -o, +o,
> --option, /OPT.  The parser relies on these symbols to do the parsing.
> Without them, it looks like ordinary text; no distinguishing
> characteristics.

Yes, I suspected that. :-/ I guess I should use definitionlists then, but it
would be nicer with "real" option lists. :) Hmmm... How about this syntax:

FILE/M/A	: Two or more files to be joined.
AS=TO/K/A	: The destination file.

?

---
Adam Chodorowski <ad...@ch...>

Alliance, n.:
   In international politics, the union of two thieves who have
   their hands so deeply inserted in each other's pocket that they cannot
   separately plunder a third.
      -- Ambrose Bierce, "The Devil's Dictionary"