From: Greg W. <gw...@me...> - 2002-10-02 16:16:04
|
I'm trying to document a collection of methods like this: """ Common widget methods --------------------- The Widget base class also provides a couple of useful methods: ``set_name(name : string)`` use this to change the widget name supplied to the constructor. Unless you know what you're doing, you should do this before rendering or parsing the widget. ``set_value(value : any)`` use this to set the widget value; this is the same as supplying a value to the constructor (and the same type rules apply, ie. the type of 'value' depends on the widget class). ``clear()`` clear the widget's current value. Equivalent to ``widget.set_value(None)``. """ but Docutils doesn't seem to like my notation for argument types: Reporter: WARNING (2) Inline literal start-string without end-string at line 10. Reporter: WARNING (2) Inline literal start-string without end-string at line 15. If I remove the whitespace around the colons, it doesn't complain. Oh... bugger... I seem to have run afoul of the "classifier" feature of definition lists. (Have I mentioned how nice it is that reST has a semi-formal spec?) This would be only slightly annoying if it weren't for the fact that that feature appears to have been at least vaguely inspired by the type syntax that I invented for Grouch. That raises it from "slightly annoying" to "richly ironic", I think. So is there a way to work around that feature? I tried backslashing the colons, and they just came out backslashed in the HTML output. Greg -- Greg Ward - software developer gw...@me... MEMS Exchange http://www.mems-exchange.org |
From: David G. <go...@us...> - 2002-10-03 00:11:32
|
Greg Ward wrote: > I'm trying to document a collection of methods like this: ... > ``set_name(name : string)`` > use this to change the widget name supplied to the constructor. ... > but Docutils doesn't seem to like my notation for argument types: > > Reporter: WARNING (2) Inline literal start-string without end-string at line > 10. > Reporter: WARNING (2) Inline literal start-string without end-string at line > 15. It looks like your Docutils installation is out of date. Reporter output doesn't look like that any more. Get the latest snapshot here: http://docutils.sf.net/docutils-snapshot.tgz > If I remove the whitespace around the colons, it doesn't complain. > > Oh... bugger... I seem to have run afoul of the "classifier" feature of > definition lists. Yes, it seems so. The " : " structural markup (delimiting the term line into "term" and "classifier" elements) is picked up before the "``" inline markup. That's a tricky case, one I hadn't anticipated. I think this is the only case of structural markup in the middle of text; in every other case, the markup is either at the beginning or at the end of a text block. > (Have I mentioned how nice it is that reST has a semi-formal spec?) Glad you like it. It certainly helps to be able to occasionally say "RTFM!" and have a "fine manual" to refer to. > This would be only slightly annoying if it weren't > for the fact that that feature appears to have been at least vaguely > inspired by the type syntax that I invented for Grouch. That raises it > from "slightly annoying" to "richly ironic", I think. More than vaguely. Grouch is mentioned in the spec. Ironic indeed! :-) > So is there a way to work around that feature? I tried backslashing the > colons, and they just came out backslashed in the HTML output. Backslash-escaping the colons does indeed prevent the term/classifier split, but then the inline literals take over and the backslashes stay in. Dilemma. Perhaps the entire term line should be checked for inline markup first, and only then split on a top-level " : "? The terms in the cases given won't be split because the " : " would already be inside an inline literal element, and thus not at the top level. This will have to be thought through to see if there are any hidden gotchas. In the interim, how about this? set_name(name \: string) use this to change the widget... You don't get the inline literal effect, but it's better than nothing. -- 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: Greg W. <gw...@me...> - 2002-10-03 14:07:39
|
On 02 October 2002, David Goodger said: > It looks like your Docutils installation is out of date. Reporter output > doesn't look like that any more. Get the latest snapshot here: > http://docutils.sf.net/docutils-snapshot.tgz Yeah, that was the 0.2 release. I like to start playing with stable code. ;-) I'm using the latest CVS now. > Perhaps the entire term line should be checked for inline markup first, and > only then split on a top-level " : "? The terms in the cases given won't be > split because the " : " would already be inside an inline literal element, > and thus not at the top level. This will have to be thought through to see > if there are any hidden gotchas. That sounds sensible to me. The error message I get -- namely, "Inline literal start-string without end-string" -- and the place where it comes from (at the end of the definition paragraph) make it sound like something is out of order. I suspect looking for " : " should come later in the game, but that's all I can say without looking at the code or making a fool of myself. > In the interim, how about this? > > set_name(name \: string) > use this to change the widget... I settled for this: ``set_name(name:string)`` use this to change the ... instead. Please lemme know when I can put my lovely precious whitespace back! ;-) Greg -- Greg Ward - software developer gw...@me... MEMS Exchange http://www.mems-exchange.org |
From: David G. <go...@us...> - 2002-10-03 22:29:44
|
Greg Ward wrote: > I like to start playing with stable code. ;-) Isn't "stable" just a euphemism for "fixed/unchanging"? :-) The current CVS is at 0.2.4 and continually improving. I try to keep bugs from creeping in. Have you tried running the test suite? http://docutils.sf.net/README.html#running-the-test-suite > Please lemme know when I can put my lovely precious whitespace back! Try it now. -- 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/ |