Thread: [Docutils-users] Pre-defining substitutions.

Hi everyone. I'm using the publish_parts API to generate some HTML files from 
ReST sources. I want to introduce some 'variables' into the document, and 
"substitution references" seemed the perfect match.

How can I define a substitution reference programmatically so that I can use its 
value though-out the document by using the |ref| syntax?

Thanks.

On Sun, Feb 21, 2010 at 16:18, Yuri D'Elia <wa...@us...> wrote:
> Hi everyone. I'm using the publish_parts API to generate some HTML files from
> ReST sources. I want to introduce some 'variables' into the document, and
> "substitution references" seemed the perfect match.
>
> How can I define a substitution reference programmatically so that I can use its
> value though-out the document by using the |ref| syntax?

The easiest way would be to tack on the text of the substitution
definitions to the input reST sources. Either do it manually with an
"include" directive, or programmatically by concatenating text.

I'm sure it could also be done directly, but there's no simple API for
it that would take care of all the bookkeeping.

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

On Sun, 21 Feb 2010 17:19:39 -0500
David Goodger <go...@py...> wrote:

> > Hi everyone. I'm using the publish_parts API to generate some HTML
> > files from ReST sources. I want to introduce some 'variables' into
> > the document, and "substitution references" seemed the perfect
> > match.
> >
> > How can I define a substitution reference programmatically so that
> > I can use its value though-out the document by using the |ref|
> > syntax?
> 
> The easiest way would be to tack on the text of the substitution
> definitions to the input reST sources. Either do it manually with an
> "include" directive, or programmatically by concatenating text.
> 
> I'm sure it could also be done directly, but there's no simple API for
> it that would take care of all the bookkeeping.

I was thinking that publish_doctree/publish_from_doctree would allow
this somehow, but couldn't figure out how.

Concatenating text is... weird at best.

Could you use a templating system like Cheetah or Django templates?  Turn
your ReST to HTML with the "variables" still there and then put the result
through the templating system. That gives you a lot of flexibility.

-- Peter



David Goodger wrote:
> On Sun, Feb 21, 2010 at 16:18, Yuri D'Elia <wa...@us...> wrote:
>   
>> Hi everyone. I'm using the publish_parts API to generate some HTML files from
>> ReST sources. I want to introduce some 'variables' into the document, and
>> "substitution references" seemed the perfect match.
>>
>> How can I define a substitution reference programmatically so that I can use its
>> value though-out the document by using the |ref| syntax?
>>     
>
> The easiest way would be to tack on the text of the substitution
> definitions to the input reST sources. Either do it manually with an
> "include" directive, or programmatically by concatenating text.
>
> I'm sure it could also be done directly, but there's no simple API for
> it that would take care of all the bookkeeping.
>
>   

On Mon, Feb 22, 2010 at 07:27, Peter Mott <pe...@mo...> wrote:
> Could you use a templating system like Cheetah or Django templates?  Turn
> your ReST to HTML with the "variables" still there and then put the result
> through the templating system. That gives you a lot of flexibility.

Yes, you certainly could. In fact, I'd recommend it. ReST is not and
never will be a templating system, nor will it become a
Turing-complete programming language (or anywhere near). Better to
choose a suitable templating system that does the job well.

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

On Mon, 22 Feb 2010 12:27:06 +0000
Peter Mott <pe...@mo...> wrote:

> Could you use a templating system like Cheetah or Django templates?
> Turn your ReST to HTML with the "variables" still there and then put
> the result through the templating system. That gives you a lot of
> flexibility.

I don't need such kind of flexibility. I just need to replace
substitutions for very simple definitions (like "currentdate", and the
like). I could do a simple regex replace on the file to be
honest, but I would have loved a better way.

If I pull a templating system in, I need to think about escaping for
both ReST and the template engine. That's truly overkill.

On 2010-02-22, Peter Mott wrote:
>> On Sun, Feb 21, 2010 at 16:18, Yuri D'Elia <wa...@us...> wrote:

>>> Hi everyone. I'm using the publish_parts API to generate some HTML
>>> files from ReST sources. I want to introduce some 'variables' into
>>> the document, and "substitution references" seemed the perfect match.

>>> How can I define a substitution reference programmatically so that I
>>> can use its value though-out the document by using the |ref| syntax?

> Could you use a templating system like Cheetah or Django templates?  Turn
> your ReST to HTML with the "variables" still there and then put the result
> through the templating system. That gives you a lot of flexibility.

You might try Sphinx http://sphinx.pocoo.org/ which uses the Jinja
templating engine for its HTML templates.

Günter