[Doc-SIG] Making reST more useable with HTML templates

Wed, 03 Jul 2002 20:30:11 -0400

Simon Budig wrote:
> (as promised in a separate mail, focus on technical stuff)

Good idea.  I'll merge in some technical answers from previous posts.

> I would not want to have these SSI-directives in my sourcecode,
> since they add unnecessary complexity to the raw page source ("The
> secretary would have to know about SSIs").

That's fair.

> I would prefer if the stuff could be embedded easily in a template
> system. Either make it easy to write a tool for creating the pages
> where the site administrator has full control over the HTML output
> of the htmp4css1-writer. This means customizeable headers with the
> option to discard the headers/footers.

[Simon, from previous post]
> But for a start I'd like to have a bit more configurable html
> converter for reST. This means for example to be able to switch off
> the <html>....<body> and </body>...</html> parts.

The HTMLTranslator class of the docutils/writers/html4css1.py module
keeps the parts separately: head_prefix (<?xml ...><!DOCTYPE html
...><html ...> ... <link rel="stylesheet" ...>), head (<title> &
<meta>), body_prefix (</head><body>), body (page contents), and
body_suffix (</body></html).  These are all lists of strings.  I'll
expose these in the Writer class.  Beyond that it's up to you.

Please don't feel that you have to use html4css1.py.  It's just one
way of producing HTML.  You can write your own, or subclass it and add
in your customizations.

Patches are gratefully accepted.

> I am not sure how the preferred use of the docutils would be for a
> random site administrator. I think I would try to write a small
> propriate application where I would try to derive the correct writer
> class and expand it with my personal preferences. Other people might
> prefer to have a simple template system where you can specify a
> simple template.

Sounds good.

> Also the class names used in some <span>'s should be customizeable,
> maybe a dictionary with a native <--> target mapping of the class
> names.

I don't follow.  Examples?

[David, from previous post]
>> However, such functionality is certainly within the realm of
>> possibility, and I'd encourage anyone to tackle the challenge posed
>> in the To Do list:
>>
>>     Construct a _`templating system`, as in ht2html/yaptu, using
>>     directives and substitutions for dynamic stuff.

[Simon]
> I don't know yaptu.

It's a simple templating tool by Alex Martelli, a recipe in the Python
Cookbook:
http://aspn.activestate.com/ASPN/Python/Cookbook/Recipe/52305.  I
helped to extend it a bit, and used it for the old project pages.  The
extended version is here:
http://structuredtext.sourceforge.net/yaptu.py.

-- 
David Goodger  <goodger@users.sourceforge.net>  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/