Re: [Docutils-develop] reST Includes

[fantasai <fan...@es...>]

David Goodger wrote:
> 
> 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). 
>
> 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.

My first thought after seeing the two syntaxes was that the first
is a shortcut for the second. But, if
  .. raw:: format path
is the same as
  .. include:: path
     :raw: format
why have the raw attribute at all? You can simply have two separate
directives: 'include', which parses as reST, and 'raw', which doesn't.

> > Now, anyone want to explain why it's ``html`` and not a full MIME type?
> > :)
> 
> The "text/" part is implicit? ;-)

I have a feeling a lot of SGML/XML markup formats don't have their own
MIME type--that they're just sent as text/sgml or text/xml. Perhaps
:raw:'s value shouldn't be half a MIME type, but a token used as a
language identifier. One might want to skip printing raw content that
doesn't match the output format, and if there are several different
XML languages, a MIME type won't label the difference.

~fantasai