I was thinking that reST would be just the thing for this application...

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

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/