[Doc-SIG] scope of the parser

[Alan Jaffray]

David Goodger wrote:
> Alan Jaffray wrote:
> > 95% of the time the desired behavior for directives will be to process the
> > block argument as RST, and not do any other RST processing.  In those cases,
> > you can decouple.  If you want something else, you have to muck with the
> > inside of the parser.
> 
> I don't follow. Can you give an example of a directive in the other 5%?

A directive indicating an indexed and captioned code fragment::

   .. example:: index=2.2 caption=`Recognizing inline markup`
      inline.openers = '\'"([{<'
      inline.closers = '\'")]}>'
      inline.start_string_prefix = (r'(?:(?<=^)|(?<=[ \n%s]))'
                                    % re.escape(inline.openers))
      inline.end_string_suffix = (r'(?:(?=$)|(?=[- \n.,:;!?%s]))'
                                  % re.escape(inline.closers))

A directive indicating raw output for a given format::

   .. raw:: format=latex
      \documentclass[twocolumn]{article}

> What do you mean by "decouple"?

Do directive processing outside the parser, and in fact outside the
entire DPS/RST codebase.

If a user comes along and decides they want a new directive, they ought
to be able to do this while treating RST as a black box.  User feeds in
``.. foo:: bar``, gets back ``<directive name="foo" args="bar"/>``, and
can then process the XML into whatever they want, or treat it as a
literal, or output a warning, or whatever.

Alan