Menu
▾
▴
docutils-develop
|
From: Adam C. <ad...@ch...> - 2002-07-03 10:03:27
|
Hi, it's me again with another wishitem. ;-)
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. The syntax looks
something like this:
NAME/K/N Just you normal...
BOOL/S ...docutils option descriptions.
The "/x" appended to the option-name are "switches" describing that option,
and might be left out for some of them.
NAME And option without any switches.
The "/x" aren't actually used by the user on the command line, but are a guide
to how they can be used (in in a way what they do). /K says that you have to
use the keyword on the command line (cannot be implicit), /N that it is a
number, /S that it is a boolean and so on.
This should (?) be quite simply to implement, apart from the last example
which might be ambigous.
---
Adam Chodorowski <ad...@ch...>
Du räknar så dåligt att du måste vara naken för att kunna räkna till 21.
-- Brad S / Datormagazin
|
|
From: David G. <go...@us...> - 2002-07-04 00:28:02
|
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. 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. -- David Goodger <go...@us...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ |
|
From: Adam C. <ad...@ch...> - 2002-07-04 12:56:32
|
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" |
|
From: David G. <go...@us...> - 2002-07-05 00:37:33
|
Adam Chodorowski wrote:
> 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 much longer description, I'm now even less optimistic. In
fact, I'd have to say that the syntax is not suitable for specialized
markup like option lists.
> Hmmm... How about this syntax:
>
> FILE/M/A : Two or more files to be joined.
> AS=TO/K/A : The destination file.
I seem to recall... Yes, here it is. About a year ago on Doc-SIG,
Tony Ibbs and I were discussing option lists and definition lists, and
he proposed a similar syntax. But I didn't go for it then, and I'm
not going for it now, sorry. The reason being, option lists are
modeled after the --help output of Unixish command-line programs.
Also, in the case of this specific syntax, a multi-line option
description would make it look too much like a definition list::
OPTION/A : A multi-line option
description.
term : classifier
definition
> I guess I should use definitionlists then, but it would be nicer
> with "real" option lists. :)
"Real" option lists are simply two-column lists, and are only possible
because of the distinctive option prefixes. You don't have that
advantage, so you might want to look into alternatives, like the
existing definition list or table syntax, the proposed simple table
syntax (see http://docutils.sf.net/spec/rst/problems.html#tables,
alternatives 3-6), or the proposed "columns" directive (see
http://docutils.sf.net/spec/notes#body-columns).
--
David Goodger <go...@us...> Open-source projects:
- Python Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)
- The Go Tools Project: http://gotools.sourceforge.net/
|
|
From: Adam C. <ad...@ch...> - 2002-07-05 00:52:00
|
On Thu, 04 Jul 2002 20:38:41 -0400 David Goodger <go...@us...> wrote: [...] > > I guess I should use definitionlists then, but it would be nicer > > with "real" option lists. :) > > "Real" option lists are simply two-column lists, and are only possible > because of the distinctive option prefixes. You don't have that > advantage, so you might want to look into alternatives, like the > existing definition list or table syntax, the proposed simple table > syntax (see http://docutils.sf.net/spec/rst/problems.html#tables, > alternatives 3-6), or the proposed "columns" directive (see > http://docutils.sf.net/spec/notes#body-columns). Yes, although you loose some semantic information then (the fact that it is a list of options). Oh well, I guess I'll have to live with that... :) --- Adam Chodorowski <ad...@ch...> There are two major products that come from Berkeley: LSD and UNIX. We don't believe this to be a coincidence. -- Jeremy S. Anderson |
Thanks for helping keep SourceForge clean.
X