On 11.05.06, David Goodger wrote:
> [G. Milde]
> >a group of my rst files need "special treatment" when exported to
> >html: I need to set the title and the path to the stylesheet
> >(currently with command line options to rst2html.py).
> >I would like to store these options in the source file for
> >rememberence. Export would of course be even easier if the
> >front-end tool recognized these file-specific settings.
> >My proposal would be to have a configuration level between
> >configuration files and command-line options.
> Nothing is implemented. There are two ideas in the to-do list:
> 1. Add file-specific settings support to config files, like::
> [file index.txt]
> compact-lists: no
-1 Storing file specific information at two places (in the source
file itself and in the config files) has a lot of disadvantages,
* You will not see the settings if you look at the source file
(violation of the principle of least surprise).
* Renaming/moving of the source file you have to remember to update
the config file.
* The setting remains in the config file even after deletion of the
source file -- a cruft builds up over time.
> 2. ["settings" directive]: Set any(?) Docutils runtime setting from
> within a document? Needs much thought and discussion.
> >Here is my idea:
> > * store the options as a comment.
> > As there are front-tool specific options, precede them with the
> > tool, e.g.:
> > .. rst2html.py --title="A non-default title" --no-datestamp
> > * the front end tool would scan the file for
> > ".. <front-end-tool-filename>" and append (or prepend) the rest
> > of the line to the command line options.
> > (as a workaround, the jed editors rst mode would do this)
> So if you wanted different options for rst2latex.py, you'd add another
> comment for that?
> What if you wanted the same options for rst2latex.py?
I would have to double these options (or to define a non-specific
> My first reaction is that I don't like putting tool-specific details
> in the document. What if the document is part of a CMS, and there is
> no front-end tool per se?
This is no problem, non of the tool-specific settings would "trigger"
but as they are comments, they would not stand in the way either.
I expect a work flow where you are writing a document and testing the
output of a front-end-tool doing some fine-tuning to get it right.
i.e. you know the front-end to work with and want to keep record of the
results of your experimenting.
Another scenario is a small project with a custom stylesheet (and maybe
some other peculiarities like specific title conventions) but too small to
employ a special web front-end. Here, storing the stylesheet-path in the
documents saves hassle during updates as a simple rst2html.py <filename>
will suffice for the export.
> I don't think I would mind putting runtime settings in the document
> though, something like this (from idea 2 above):
> .. settings::
> :title: A non-default title
This looks nice to me.
What would be the syntax for boolean variables?
> If necessary, the "settings" directive could support component
> descriptors (like "html4css1 writer") as arguments, like the sections
> in config files.
+1 as e.g. the stylesheet path will not make sense (or differ) in a
Also, I could expect different "title" settings for html and latex
(e.g. no title is a bad thing in html but fine for smaller documents