On Mon, Jan 31, 2011 at 08:11:54AM +0000, Guenter Milde wrote:
> On 2011-01-28, Berend van Berkum wrote:
> > On Fri, Jan 14, 2011 at 09:23:02AM +0000, Guenter Milde wrote:
> >> On 2011-01-13, Berend van Berkum wrote:
> > OK, I've taken up my efforts on that code again. Non-lossy rst2rst was
> > not really a consideration for me before so I'll have to see what that
> > takes.
> A non-lossless "rst" writer could be used to
> * "normalize" the rst markup
> * replace auto enumeration and auto footnotes with generated numbers
> * do the second step (writing) of an anything-to-rst conversion.
> * ...
- add generated content
- add/update content stored elsewhere ('metadata')
- normalize content (references, citations, ids)
I have been missing a writer as well. With it, docutils is an even more
tempting storage format.
But it takes some more before its there. Testing however is going well and it
looks promising. Only the formatting of the output is really rough.
> After "normalization", the round-trip would be lossless.
Which is nice, to clean up differences in indentation and fix line formatting.
But not always I think, I can understand the a lossness requirement to some
By using some additional internal attributes, I figure that some of the
whitespace and most of the adoration choices of the document author can be
retained during an rst-to-rst publish cycle, while keeping the formatting
May matter to the readability of a document, as does whitespace.
> >> For projects (as opposed to single documents), Sphinx
> >> (http://sphinx.pocoo.org/) is the "state of the art". It is tested on
> >> large projects (including the official Python documentation), [...]
> > Of course.. I had found that project and mentally parked it as it did not
> > immeadeatly seem compatible with what I'm looking for. But I agree with
> > you, the two times I looked at it it seemed somewhat too far removed from
> > regular docutils though.
> I agree that it introduces (too) many new directives and roles.
> > It is a fine application of Du and I think it has some good ideas.
> > The fall-backs sound like a real saver. It would help rST if the
> > 'dialects' will always run on the standalone Du/rST publisher.
> With current versions, the only "true" incompatibility (the "class"
> directive) can be solved by configuration (I did not test it yet).
> way it should be possible to use sources with both Docutils and Sphinx,
> as long as it sticks to the core set of directives and roles.
> I thought about a compatiblility mode that implements Sphix extensions
> for Docutils (as dummy, if not useful for single documents) but did not
> find the time to pursue this further.
Some fallback to catch/filter for missing roles/directives should not be too
hard. I don't think it needs to know *what* is out there.
Have not tested it either, but afaik Sphinx has syntax-wise:
- domains (directive names containing semi-colons), not sure if that is
parseble by std rST.
- reference roles (that accept explicit target id like a regular inline
reference) would not be parsed to a link.
The latter is not really compatible, but the ID will not be recognized and
displayed <...> inline.