Re: [Docutils-develop] reST Includes

[David G. <go...@us...>]

Dethe Elza wrote:
<digression>
> On Fri, 2002-08-16 at 13:04, David Goodger wrote:
>> Thanks for your comments.  How about sharing them with
>> docutils-develop?
> 
> 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.
</digression>

>>> 2. Any comments on the following syntax?
>>> 
>>> .. include:: path/subdocument.rst
>>>    :parse: true | false (default: true)
>> 
>> Looks fine.  What does the "parse" attribute mean?
> 
> parse = true
>   Treat the included text as reST and parse as part of the document
> 
> parse = false
>   Treat the included text as literal text (maybe it's already HTML or
> whatever) and just insert it.

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.

>> Here's my thinking to date, from the to-do list
>> (http://docutils.sf.net/spec/notes.html#misc-include):
>> 
>>     _`misc.include`: ``#include`` one file in another.  But how to
>>     parse wrt sections, reference names, conflicts?  Parse it in the
>>     current document's context (C-preprocessor semantics), or
>>     separately and then merge?
> 
> Treat it all as one document unless notified otherwise?  I think
> that's reasonable default behaviour.

Agreed.

> 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?

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

> So now the directive would look like:
> 
> .. include:: path/subdocument.rst
>    :parse: true | false (default: true)
>    :same-context: true | false (default: true)

Factoring in the above, we get::

    .. include:: path/subdocument.rst
       :raw: (true if set)

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.

>>     Use C-preprocessor semantics for locating include files?  E.g.,
>>     ``.. include:: file.txt`` will read another file into the current
>>     one, relative to the current file's directory, and ``.. include::
>>     <standard>`` will read a standard include file from
>>     ``docutils/include/``.  (Should "quotes" be required around
>>     non-standard include files?)
> 
> 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.

So, care to give it a try?

-- 
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/