Features Download
From: David Goodger <goodger <at> python.org>
Subject: Re: I was thinking that reST would be just the thing for this application...
Newsgroups: gmane.text.docutils.devel
Date: Monday 22nd September 2008 17:19:02 UTC (over 9 years ago)

I have no idea what you're asking for, beyond some hand-holding with
transforms. There is some documentation available:

(search for
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  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

This SF.Net email is sponsored by the Moblin Your Move Developer's
Build the coolest Linux based applications with Moblin SDK & win great
Grand prize is a trip for two to an Open Source event anywhere in the world
CD: 3ms