Re: [Docutils-develop] reST Includes

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

Garth Kidd wrote:

>> So, should it be::
>> 
>>   .. raw:: html fragment.html
>> 
>> or::
>> 
>>   .. include:: fragment.html
>>      :raw: html
> 
> +1 to having both both available (i.e. ``raw::`` mapping directly to
> ``include::`` with ``:raw:`` set, or vice versa).

I didn't mention that the "raw" directive's main function is::

    .. raw:: html

       <p>Arbitrary raw HTML here, will be inserted as-is
       into HTML output.</p>

Normally, the "raw" directive's content will be supplied within the document
body.  So the question becomes, does the "raw" directive grow an "include"
attribute (or optional argument), or does the "include" directive grow a
"raw" attribute?  I'm not sure that "both" is a good answer here.

> Now, anyone want to explain why it's ``html`` and not a full MIME type?
> :) 

The "text/" part is implicit? ;-)  But seriously, MIME types *have* been
adopted for reStructuredText-format PEPs (official announcement any day
now), with "text/plain" as the default and "text/x-rst" as the new
alternative.  As for using MIME types with the "raw" directive here, I guess
I'd have to see how they'd be useful.  In other words, would such a MIME
type ever begin with anything *other* than "text/"?

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