From: Martin M. <ma...@tw...> - 2008-09-22 15:26:50
|
How to describe it? I need a not too user-unfriendly format for entering items that are mostly a scrap of descriptive text and a hypertext link. The tricky bit is that this is part of a system that has a catalog of URLs, and I want to allow items to refere to cataloged links by name - so that when a URL changes, there's one place to fix it, or to redirect to a "sorry, this resource is no longer available" (and, in my dreams, maybe suggest alternatives... but that's only a dream for now). I've been trying to avoid reinventing this wheel, but the first few things I looked at didn't do well on the user ratings. reST's hyperlink syntax has always seemed kind of funky to me, but my users seem to like it. The problem then would be that this seems to call for a transform, and it's probably quite simple... except that the documentation of that area is so incomplete as to be useless. I've groveled the code enough to decide that if I have to go that route it truly will be simpler to reinvent the wheel once again (this so is a Pythonic trope, isn't it?). I'd lose the other things that reST provides, but frankly they're not of great importance for items, at least we currently envision using them. So sorry, but code is really crappy documentation, even when the trees aren't lost in an ocean of do-nothing classes (was this designed by someone with extensive Jave experience, perhaps?). From what I've been able to make out, dimly, I believe I need to 1) get the item parsed into nodes - that turns out to be easier than the __doc__ suggested, just publish_doctree(item_string) (okay, with stderr redirected if my extended syntax isn't quite legal reST form). 2) I think I can see how to walk the tree - this might actually be easiest if I do use an invalid syntax, since then I can ignore everything but problematic nodes, and I then get the source text from their single Text child. Here I encounter a problem - how the heck do I construct a proper reference node to replace the problematical? After tracing all the twisted class inheritance, all I see in the constructor is the raw source, a text item, and the who knows what they should/can hold *children and **attributes. ...or is that not a reasonable way to get there? I did think at first that it might be handled during parsing, but that part of the process seemed even less well-lit. Okay, that's enough questions for now - I'm already basing most of this on guesswork in lieu of documentation. All suggestions, pointers to more obscure docs, examples of similar work appreciated. And contrary to my usual preferences, please do CC me on replies as I'm not hooked up to the list. Thanks! -- Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won't usually need your flowcharts; they'll be obvious. -- Brooks |
From: David G. <go...@py...> - 2008-09-22 17:19:09
|
Martin, I have no idea what you're asking for, beyond some hand-holding with transforms. There is some documentation available: http://docutils.sourceforge.net/docs/api/publisher.html (search for publish_doctree) http://docutils.sourceforge.net/docs/peps/pep-0258.html http://docutils.sourceforge.net/docs/dev/hacking.html http://docutils.sourceforge.net/docs/ref/doctree.html http://docutils.sourceforge.net/docs/ref/docutils.dtd and the code itself Yes, it's inadequate. Sorry, but nobody has had the right combination of time/will/need to remedy that. Contributions are welcome. You'd do well to ask concrete questions, minimize the flowery prose, and avoid disparaging remarks directed at the very people you're asking for help. Care to try again? -- David Goodger On Mon, Sep 22, 2008 at 11:09, Martin Maney <ma...@tw...> wrote: > > How to describe it? I need a not too user-unfriendly format for > entering items that are mostly a scrap of descriptive text and a > hypertext link. The tricky bit is that this is part of a system that > has a catalog of URLs, and I want to allow items to refere to cataloged > links by name - so that when a URL changes, there's one place to fix > it, or to redirect to a "sorry, this resource is no longer available" > (and, in my dreams, maybe suggest alternatives... but that's only a > dream for now). > > I've been trying to avoid reinventing this wheel, but the first few > things I looked at didn't do well on the user ratings. reST's > hyperlink syntax has always seemed kind of funky to me, but my users > seem to like it. The problem then would be that this seems to call for > a transform, and it's probably quite simple... except that the > documentation of that area is so incomplete as to be useless. I've > groveled the code enough to decide that if I have to go that route it > truly will be simpler to reinvent the wheel once again (this so is a > Pythonic trope, isn't it?). I'd lose the other things that reST > provides, but frankly they're not of great importance for items, at > least we currently envision using them. > > So sorry, but code is really crappy documentation, even when the trees > aren't lost in an ocean of do-nothing classes (was this designed by > someone with extensive Jave experience, perhaps?). From what I've been > able to make out, dimly, I believe I need to > > 1) get the item parsed into nodes - that turns out to be easier than > the __doc__ suggested, just publish_doctree(item_string) (okay, with > stderr redirected if my extended syntax isn't quite legal reST form). > > 2) I think I can see how to walk the tree - this might actually be > easiest if I do use an invalid syntax, since then I can ignore > everything but problematic nodes, and I then get the source text from > their single Text child. Here I encounter a problem - how the heck do I > construct a proper reference node to replace the problematical? After > tracing all the twisted class inheritance, all I see in the constructor > is the raw source, a text item, and the who knows what they should/can > hold *children and **attributes. > > ...or is that not a reasonable way to get there? I did think at first > that it might be handled during parsing, but that part of the process > seemed even less well-lit. > > Okay, that's enough questions for now - I'm already basing most of this > on guesswork in lieu of documentation. All suggestions, pointers to > more obscure docs, examples of similar work appreciated. And contrary > to my usual preferences, please do CC me on replies as I'm not hooked > up to the list. > > Thanks! > > -- > Show me your flowcharts and conceal your tables, and I shall continue > to be mystified. Show me your tables, and I won't usually need your > flowcharts; they'll be obvious. -- Brooks |