Thread: [Structuredtext-develop] Some problems with option lists
Status: Pre-Alpha
Brought to you by:
goodger
Menu
▾
▴
structuredtext-develop
|
From: Richard J. <rj...@ek...> - 2002-02-19 22:51:42
|
I'm working through more of the html formatter, and have come across some
option list strangenesses:
1. the leading dashes are removed from the short_option and long_option. Is
this intentional? If so, I'll re-add the dashes, but it seems odd.
2. similarly, the arguments lose the '='. This becomes ambiguous:
--foo=bar blah blah blah
-u flebble tblah blahb asadf
results in:
<option_list>
<option_list_item>
<option>
<long_option>
foo
<option_argument>
bar
<description>
<paragraph>
the description of foo
<option_list_item>
<option>
<short_option>
u
<option_argument>
flebble
<description>
<paragraph>
the description of u
3. short options can't have '=' arguments:
-DC_DEFINE_FLAG=value
results in an error.
4. any chance of a format like:
-i / --info get information
being acceptable too? I've seen that around a bit.
Richard
|
|
From: David G. <go...@us...> - 2002-02-20 01:39:58
|
Richard Jones wrote:
> 1. the leading dashes are removed from the short_option and long_option. Is
> this intentional? If so, I'll re-add the dashes, but it seems odd.
Yes, it's intentional. The various option types are uniformly represented in
the tree. Once the options have been parsed into "long_option" or
"short_option" elements, the dashes are implicit; they're boilerplate text,
redundant and uninteresting. It's text to be inserted by the Writer.
> 2. similarly, the arguments lose the '='.
"=" are lost for the same reason: redundancy. The back-end Writer may choose
to always use "--option=arg" or always use "--option arg", but it should be
consistent.
> This becomes ambiguous:
I don't see the ambiguity. Please explain.
> 3. short options can't have '=' arguments:
>
> -DC_DEFINE_FLAG=value
>
> results in an error.
Correct. Short options never have '=' (not on any system I've seen, anyhow).
Short option names are never more than one letter long, either -- that's why
they're short! Your example is actually equivalent to::
-D C_DEFINE_FLAG=value
While this may be valid as an actual option (i.e., as entered on the command
line), it doesn't make sense as a placeholder.
The option list syntax is based on common practice in command-line tools
such as GNU utilities, and on the command-line parsers that they use, such
as getopt.py and Optik.
> 4. any chance of a format like:
>
> -i / --info get information
I chose ", " as the separator from observation of the "--help" output of
various tools. I don't see the need for two ways to spell it. Also, "/" is
used for VMS/DOS-style options, so it may be confusing here.
--
David Goodger go...@us... Open-source projects:
- Python Docstring Processing System: http://docstring.sourceforge.net
- reStructuredText: http://structuredtext.sourceforge.net
- The Go Tools Project: http://gotools.sourceforge.net
|
|
From: Alan J. <ja...@po...> - 2002-02-20 01:59:03
|
On Tue, 19 Feb 2002, David Goodger wrote: > Yes, it's intentional. The various option types are uniformly represented in > the tree. Once the options have been parsed into "long_option" or > "short_option" elements, the dashes are implicit; they're boilerplate text, > redundant and uninteresting. It's text to be inserted by the Writer. > [...] > The option list syntax is based on common practice in command-line tools > such as GNU utilities, and on the command-line parsers that they use, such > as getopt.py and Optik. Unfortunately this is not at all ubiquitous. ImageMagick, to cite the first example that comes to mind, uses long options with one dash and won't accept two dashes. Many standard X utilities use long options prefixed with either a single dash or a single plus. ps and tar are worlds of their own. Read the documentation for Perl's Getopt::Long to get a sense of how many different styles of option parsing there are in common use - it's rather depressing. (Getopt::Long, in the Perl fashion, supports all of them.) Alan |
|
From: David G. <go...@us...> - 2002-02-20 03:44:29
|
> Read the documentation for Perl's Getopt::Long to get a sense of how many > different styles of option parsing there are in common use - it's rather > depressing. Perhaps I will, one day when I'm too happy and need bringing down. ;-) > (Getopt::Long, in the Perl fashion, supports all of them.) Perl is the "everthing *including* the kitchen sink" language, so I'm not surprised. I think it behooves us to choose a self-consistent subset and stick with it, and getopt.py's choices seem just fine to me. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
|
From: Richard J. <rj...@ek...> - 2002-02-20 02:38:12
|
On Wed, 20 Feb 2002 12:42, David Goodger wrote:
> Richard Jones wrote:
> > 1. the leading dashes are removed from the short_option and long_option.
> > Is this intentional? If so, I'll re-add the dashes, but it seems odd.
>
> Yes, it's intentional. The various option types are uniformly represented
> in the tree. Once the options have been parsed into "long_option" or
> "short_option" elements, the dashes are implicit; they're boilerplate text,
> redundant and uninteresting. It's text to be inserted by the Writer.
OK.
> > 2. similarly, the arguments lose the '='.
>
> "=" are lost for the same reason: redundancy. The back-end Writer may
> choose to always use "--option=arg" or always use "--option arg", but it
> should be consistent.
>
> > This becomes ambiguous:
>
> I don't see the ambiguity. Please explain.
I believe it's up to the original source - which knows how the program
accepts arguments - to determine whether an '=' is required, not the output
writer. Assuming that all programs that accept long arguments must use '=' is
dangerous.
> > 3. short options can't have '=' arguments:
> >
> > -DC_DEFINE_FLAG=value
> >
> > results in an error.
>
> Correct. Short options never have '=' (not on any system I've seen,
> anyhow). Short option names are never more than one letter long, either --
> that's why they're short! Your example is actually equivalent to::
The above is a fairly standard define argument for a C compiler. For example:
-DHAVE_CONFIG_H
-DPREFIX='"$(prefix)"'
Is used all over the place in autoconf-generate Makefiles. In the above, the
-D is the option, the rest of the text is the option argument.
> > 4. any chance of a format like:
> >
> > -i / --info get information
>
> I chose ", " as the separator from observation of the "--help" output of
> various tools. I don't see the need for two ways to spell it. Also, "/" is
> used for VMS/DOS-style options, so it may be confusing here.
OK, and it's documented, so I'm happy. Sorry I didn't notice that in the spec.
Richard
ps. 90% of the html formatter is done - biblio and some reference stuff still
to be done. I'm also going to assume from the terminology above that the
formatter should be renamed "HTMLWriter"?
|
|
From: David G. <go...@us...> - 2002-02-20 03:58:36
|
Richard Jones wrote:
> I believe it's up to the original source - which knows how the program
> accepts arguments - to determine whether an '=' is required, not the output
> writer. Assuming that all programs that accept long arguments must use '=' is
> dangerous.
For the purposes of the reStructuredText parser, I think the tighter the
rules are, the better. I'm tempted to tighten the rules even further, to
avoid ambiguity.
I'll spell it out in the spec, that the syntax rules for short and long
POSIX options are based on what's acceptable to getopt.py. As Alan pointed
out, there's a lot of variation in option syntax out there. So much
variation that it's virtually if not absolutely impossible to support it
all. I've no desire to support all the wonky variations out there.
>>> 3. short options can't have '=' arguments:
>>>
>>> -DC_DEFINE_FLAG=value
>>>
>>> results in an error.
I'll add a test case for this, and make sure the result is sane. It should
just produce a paragraph, since it doesn't fit reStructuredText's definition
of an option. The only error I'd expect would be from having a paragraph
immediately following an option list with no blank line between.
> The above is a fairly standard define argument for a C compiler. For example:
>
> -DHAVE_CONFIG_H
> -DPREFIX='"$(prefix)"'
>
> Is used all over the place in autoconf-generate Makefiles. In the above, the
> -D is the option, the rest of the text is the option argument.
In other words, it's a short option (-D) with a complex argument? That's not
a problem. The documented option list would look something like::
-D DEF Process as if '#define DEF' exists at the head of
the source code.
Don't forget, an option list is documentation, not actual usage.
The '-LONG' style (single hyphen with a long option name) is not supported
by getopt.py, so we won't support it either. GNU libc getopt_long_only()
does support such options but only by using an algorithm that can break down
and produce erroneous results. We won't.
--
David Goodger go...@us... Open-source projects:
- Python Docstring Processing System: http://docstring.sourceforge.net
- reStructuredText: http://structuredtext.sourceforge.net
- The Go Tools Project: http://gotools.sourceforge.net
|
|
From: David G. <go...@us...> - 2002-02-21 01:29:19
|
Sorry, I meant to send this yesterday. For some reason, it didn't go through. Richard Jones wrote: > ps. 90% of the html formatter is done - biblio and some reference stuff still > to be done. I'm also going to assume from the terminology above that the > formatter should be renamed "HTMLWriter"? Actually, it should conform to the (not yet finalized) dps.writers.Writer interface. I'm working on a dps.writers.html.Writer, which I'll check in so you can see what I'm thinking. It walks the doctree using dps.nodes.NodeVisitor. I'll check in your code into sandbox/richardj and give you access (maybe tonight, maybe tomorrow, I'll let you know). It doesn't take into account all the transforms that need to be performed on the raw doctree. Take a look at dps.core.Publisher (used by restructuredtext/tools/publish.py and html.py) to see what I mean. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
|
From: Richard J. <rj...@ek...> - 2002-02-21 02:02:12
|
On Thu, 21 Feb 2002 12:31, David Goodger wrote: > Richard Jones wrote: > > ps. 90% of the html formatter is done - biblio and some reference stuff > > still to be done. I'm also going to assume from the terminology above > > that the formatter should be renamed "HTMLWriter"? > > Actually, it should conform to the (not yet finalized) dps.writers.Writer > interface. I'm working on a dps.writers.html.Writer, which I'll check in so > you can see what I'm thinking. It walks the doctree using > dps.nodes.NodeVisitor. OK, I'll start re-working the code to fit the dps frameworks. Which part of the interface are you still working on? Looks like my quick hack needs to be beaten into shape - at least we've got something in the short-term that can be used to generate the documentation for roundup :) Richard |
|
From: David G. <go...@us...> - 2002-02-21 04:12:23
|
Richard Jones wrote: > Which part of the interface are you still working on? I don't know yet. When I find some aspect of the API insufficient for the growing needs of the project, I fix it. If you notice any insufficiencies, please feel free to suggest changes. > at least we've got something in the short-term that can be used to generate > the documentation for roundup :) Cool. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
|
From: David G. <go...@us...> - 2002-02-23 16:36:03
|
I've been mulling it over; here's what I've come up with:
Richard Jones wrote:
> I believe it's up to the original source - which knows how the
> program accepts arguments - to determine whether an '=' is required,
> not the output writer. Assuming that all programs that accept long
> arguments must use '=' is dangerous.
I've implemented a new attribute ``optarg_delimiter`` to element
``option_list``, in the DTD, parser, and test suite.
``optarg_delimiter`` contains the delimiter (either " " or "=")
consistently used by ``long_option`` and/or ``vms_option`` elements.
(Note that ``short_option`` elements may only use spaces as opt/arg
delimiters; they don't affect the attribute.) If no such options
exist, no ``optarg_delimiter`` attribute will be present. If delimiter
usage is mixed (both " " and "=" used), ``optarg_delimiter`` will
contain the value "mixed".
Here are the possibilities:
``<option_list>``
No delimiters were detected.
``<option_list optarg_delimiter=" ">``
Spaces should be used for long POSIX and VMS option/argument
delimiters.
``<option_list optarg_delimiter="=">``
Equals signs should be used for long POSIX and VMS option/argument
delimiters.
``<option_list optarg_delimiter="mixed">``
Mixed usage: representation is up to the client.
I initially thought of adding an attribute to the ``option`` element,
populated with each option's delimiter usage. But in a single option
there may be multiple long POSIX or VMS options, each with a different
delimiter, so that wouldn't be enough. I could have added an attribute
to the ``option_argument`` element instead. But on reflection, if a
single option list is using mixed delimiters, that program's option
parser must be able to handle mixed delimiters as well. Otherwise
there's a bug in the documentation at least. So just one attribute per
option list.
Besides, this is consistent with how bullet lists and enumerated lists
are put together. We store the bullet character or enumeration details
once, at the beginning of the list.
--
David Goodger go...@us... Open-source projects:
- Python Docstring Processing System: http://docstring.sourceforge.net
- reStructuredText: http://structuredtext.sourceforge.net
- The Go Tools Project: http://gotools.sourceforge.net
|
|
From: Tony J I. (Tibs) <to...@ls...> - 2002-02-25 09:57:57
|
David Goodger wrote > Besides, this is consistent with how bullet lists and enumerated lists > are put together. We store the bullet character or enumeration details > once, at the beginning of the list. Hmm. I'm not entirely sure that we should be aiming to support every weird and wonderful command line that someone can come up with, but I do *actually* have a case (that I use) that mixes the slash and dash forms. Specifically, I do a lot of work on Windows/NT, and tend thus to have batch files that encapsulate common commands. These are done "properly", with /help switches, and so on. The specific example I am thinking of is a small batch file that runs the javac, javah or javadoc tools for me. Its command line is of the form: jmake /javac -verbose where the /javac is telling it which tool to choose (and there are other options, like /debug and so on), whilst the rest of the command line is being passed down to the particular tool. Being Unix originated, despite being on NT the Java tools expect dash-style switches (and, as you can see, they don't follow the Gnu conventions). Of course, strictly speaking the dash switches *are* just the "rest of line", and I don't really expect to process them myself, so it perhaps isn't strict doc-tools territory - except that it can be useful to describe the more common switches for each tool. Thinking-out-loud-again, Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X