fenics team mailing list archive

[Hans Petter Langtangen <hpl@xxxxxxxxx>]

Mon, 22 Mar Anders Logg wrote:
> I haven't seen reST before. I took a closer look now and it looks
> pretty nice. Was the motivation for doconce to make it look even
> nicer? reST already looks pretty nice to me.

The reason is about the same as why develop Publish when BibTeX exists
;-) I wanted to have plain untagged ASCII as a format and found it too
demanding to write a new backend for docutils. I also wanted to have
support for math in the text (there is upcoming suppert for LaTeX in
reST, but not in any official version), plus support for computer code
copied directly from source files and typeset in a variety of formats.
The LaTeX and HTML source files generated from reST are quite ugly
too. Finally, it's simpler to add certain features to a simple markup
language than to reST.

> > I usually put the doconce documentation in separate files and
> > preprocess the source code. The text can be put in the source instead,
> > but then you need a little script to extract the text such that you
> > can generate LaTeX and HTML manuals, etc.
> >
> > Personally, I like plain text with minimal tagging in the source code,
> > which means that I filter doconce to plain text before the source code
> > files are preprocessed (and sometimes I filter to Epytext and insert
> > in doc strings to make Epydoc manuals, or to reST for sphinx
> > manuals).
> 
> I still don't get it. So you have foo.do with the documentation, but
> where is the code? Is it in foo.h.pre and then you generate foo.h from
> foo.do and foo.h.pre?
> 
>   foo.do + foo.h.pre --> foo.h
>   foo.do --> foo.html + foo.pdf

Yes! 

Hans Petter