Re: [Docutils-develop] Implementing the "subdocuments" directive

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

> David Goodger wrote:
> > Do you mean "XXX HACK -- field bodies should be left unparsed
> > instead"?  Why would you want to leave them unparsed?

On 6/26/07, Lea Wiemann <lew...@gm...> wrote:
> Since file names may contain special characters that are interpreted
> by the reST parser, the most notorious one being the backslash:
>
> * :file: path\to\file.txt    (ends up as pathtofile.txt)

The question becomes, do we treat the directive content as ordinary
reST, or do we treat it as directive option arguments?

1. We could apply ordinary reST syntax rules here.  So if somebody
   wants to use backslashes, they should use inline literals::

       * :file: ``path\to\file.txt``

   We could check the .rawsource attribute to confirm it matches
   field_body.astext(), and warn if it doesn't.

2. We could treat the directive content the same as directive option
   arguments.  Option arguments don't have their backslashes
   interpreted as escapes.  I don't know where that happens though (is
   escape2null undone, or just never done?; no time to track it down
   now).  The simplest solution may be to undo escape2null with a call
   to unescape, before parsing the directive content.

The problem with (2) is, what if we want to use reST syntax in other
options?  For example, in a title?  (1) seems simpler; I suggest we
go that route for now.

Whatever we choose to do, it should be well documented.

(Bug alert: the current Subdocuments.parse_field_list code should
check the length of field_body before accessing field_body[0].)

-- 
David Goodger <http://python.net/~goodger>