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

[Simon Budig]

(as promised in a separate mail, focus on technical stuff)

David Goodger (goodger@users.sourceforge.net) wrote:
> Simon Budig (simon.budig@unix-ag.org) wrote:
> > Just to show you what is possible with SSIs and why I think using
> > reST for webpages is not crazy:
> > 
> > Have a look at http://www.home.unix-ag.org/simon/bsdaemon/
> 
> Apart from the extras pulled in through server-side includes, the page
> is very simple, nothing that reStructuredText couldn't handle.
> 
> > The raw source of it is::
> > 
> >    <!--#include virtual="$SCRIPT_NAME/../../include/head_start.shtml" -->
> 
> A server-side include directive could be added to reStructuredText, no
> problem.  Although I'm very careful about new *syntax*, new directives
> are much easier to let in, because they're explicit and typically
> don't require new syntax (and if they do, it's localized and
> *explicit*).

I am not sure if this would be necessary. 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").

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.

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.

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

> >    <img src="bsdaemon.png" alt="Preview of the BSD Daemon" align="right"
> >    width="326" height="352"><p>
> 
> I've thought of adding support for more image attributes, like
> "align".  Care to try?

Maybe on the weekend, when I manage to get the CVS to sourceforge to
work...

Bye,
        Simon
-- 
      Simon.Budig@unix-ag.org       http://www.home.unix-ag.org/simon/