Alan G Isaac wrote:
>>[Alan G Isaac]
>>>In the interest of the readability of the reST document,
>>>I would like to be able to put any custom role declarations
>>>at the bottom of the document.
> On Thu, 18 Nov 2004, David Goodger apparently wrote:
>>That would require a lot of work to implement in the
>>current parser. How about putting your custom role
>>declarations in a separate file, and use the "include"
>>directive? That would be one line at the top of the
> Yes, that's pretty good.
> Is there anyway to put them in the config file instead?
This would deeply contradict the (perhaps unwritten) guidelines for
source/style/config separation. I'll try to formulate them here (David,
please correct me as needed):
- The source file should contain enough information to correctly parse and
process it with docutils in absense of any non-default stylesheet (default
one coming with docutils is OK) or configuration. Naturally it will have
the default look but that's OK.
The purpose here is to ensure that reST is a self-contained format. Getting
just the source should be sufficient to read the document.
- Include files are a way of organizing the source. All include files
should be present of course to process a document. The include mechanism
should not rely on external information. Therefore a config file should
not affect what constitutes the source. If you require inclusion of
another source file, it must be indicated in the main source file, so
that someone who got only the source would at least know that another file
- Source should include the minimum of presentation information possible.
Stylistic distinctions in output that can be replaced without breaking the
meaning of the document should not be represented in the source at all.
Distinctions that are essential part of the document have some meaning;
the meaning should be represented in the source and the styling of the
meaning delegated outside.
- Config files, command line options and stylesheet files selected by them
contain all the optional information about presentation of the content
represented by the source file. Config files and stylesheets should be
generic, so that they are applicable in principle to any reST document (of
couse there are combinations that look better or worse).
There are tricks like setting classes and the raw directive that can clearly
violate some or all of this. That's why they are work-around and stop-gap
measures and users are adviced to avoid them if possible.
There are other border-line things, for example the config setting that
enables/disables the doctitle transform - this arguably changes the semantics
of the document. OTOH, the document is parsed sort-of sensibly either way.
It's all a question of judgement and taste.
Beni Cherniavsky <cben@...>, who can only read email on weekends.