Re: [Docutils-develop] reST Includes

[Dethe E. <de...@ma...>]

> <digression>
> > Oops!  I meant to do that, but forgot that this list doesn't reply
> > to list by default.
> 
> That's Mailman's default and *strongly recommended* behavior (their
> emphasis).  Seems like "reply to list by default" is aberrant.  See
> http://www.unicom.com/pw/reply-to-harmful.html.  Short form: always
> use your mailer's "Reply-All" feature for mailing lists, and
> "Reply-Originator-Only" when you want private email.  Anyhow, back to
> the point.
Yes, and when I get my main system back up and running it will be
easier.  I'm using a temporary box right now and not only are things
unfamiliar, but there doesn't appear to be a hotkey for "reply all." 
<grumble/>
> </digression>


> I think a ":raw:" flag (attribute with no value) would be better.
> When I saw "parse" I thought of the parsing context: parse separately
> or together.  A bit confusing perhaps.

:raw: is OK with me.

> > There could be another flag on the include directive, as there is in
> > the recursive parse within reST I believe, telling it whether to
> > process the included text within the same context or not, but I
> > think the default should be to assume the same context.
> 
> What "recursive parse within reST" are you talking about?

Ummm.  There was something somewhere in the code.  I can't remember
exactly where and I don't have a chance to dig it out right now.  I
could be wrong.  Your mileage may vary.  Void where prohibited.

> In any case, that route opens up a big can of worms.  So it can remain
> on the to-do list until truly needed.

Yes, or the or-not-to-do list...

> Factoring in the above, we get::
> 
>     .. include:: path/subdocument.rst
>        :raw: (true if set)

Looks good.

> That's feasible.  I wonder how to actually do the parse, though.  I
> don't think it's a good idea to alter the already-read data, so a
> separate, nested parse would probably be in order.  Also, the error
> reporting mechanism would have to be revamped to include the file
> which is the source of system messages.

Um.  I'm not sure if I'm up to revamping the error reporting mechanism. 
I'm trying to find something that's *easier* than 

  cat file1.rst file2.rst file3.rst | html.py > finished.html

I think I can handle creating a directive and even writing up how to
create a directive, but I'm not up for a revamp of the core system.

> > Umm.  I don't see a lot of value in using "standard" include
> > locations. URI are better: Include off the net, include from a file,
> > include from a relative path...
> 
> Yes, it's probably YAGNI (you ain't gonna need it).  Although I
> wouldn't want to deal with generic URI yet (probably also YAGNI, at
> least for now), just simple filesystem paths.

Agreed.  Although Python makes it pretty darn easy to have full URIs if
we want them...

> So, care to give it a try?

Yup, I'll take a look.  Is image still the best directive to get started
with?

--Dethe