fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Tue, Mar 23, 2010 at 08:28:52AM +0100, Hans Petter Langtangen wrote:
> Mon, 22 Mar Anders Logg wrote:
> > I'm probably missing something here, but I don't see much difference
> > between the reST and doconce input. Take for example the following page:
> >
> >   http://sphinx.pocoo.org/rest.html
> >
> > The reST input can be viewed by clicking "Show Source" in the right
> > column. What would the corresponding input look like for doconce?
>
> Very, very similar! There are only some small differences for making
> it easier to parse the text with regular expressions (which I use for
> simplicity, but that's sometimes a real hazzle).
>
> There are a couple of features of doconce that I wanted to have:
> 1) copying of source code from files, with specification of a certain
> style of typesetting the code (in LaTeX), and 2) better support for
> equations and inline math so that the math comes nicely out in LaTeX.
> Doconce has special paragraphs for code and math, so this is the
> biggest (and almost only) syntax difference from reST.  These
> constructions are nice things if you work on some document where the
> final format is unclear, but LaTeX (=book/paper) is very likely. Over
> the years I've written a lot of educational material that have ended
> up in LaTeX books, but started it's life as doconce text and lived for
> a while in HTML, some parts also as Epytext and plain text for Python
> (module/package) doc strings. The ugly LaTeX from reST was not
> suitable for (my) books ;-)

ok! I haven't seen the LaTeX output from Sphinx.

> For FEniCS documentation you don't need that flexibility, and you have
> more emphasis on HTML output than LaTeX or other formats. Then reST
> is definitely the answer! This is my clear conclusion now after having
> thought about it for a few days :-) Sphinx + reST! (If it's okay for C++ too)

ok, let's start with reST! Perhaps we will realize the benefits of
doconce somewhere along the road.

> > I'm not too keen on not editing the source files directly, but from
> > what I understand, you do this to make things work with docstrings in
> > Python? Then this can be avoided by Johan Hake's trick (assigning some
> > appropriate output from doconce to __doc__).
>
> Sure, Python can preprocess itself - I do that a lot. One example is
> to list all options of various kinds in static class variables, use
> these lists (or dicts) for checking input in the code and provide nice
> error messages, while these lists can also be formatted nicely and
> inserted automatically in doc strings so that you always have an
> updated list of what's possible in a class or function when you
> process the doc string (pydoc, help in the interpreter, Epydoc, I
> guess it works with sphinx too). Just the import statement does all
> the processing. Large sections of text that goes into various
> documents, can either be preprocessed (#include) or loaded into doc
> strings at import time (the latter strategy takes more time and is not
> my personal favorite, but that's just a matter of taste - I'm very
> much a preprocessing guy).

I personally prefer import. Hopefully the overhead is not noticeable.

--
Anders

Attachment: signature.asc
Description: Digital signature