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
signature.asc
Description: Digital signature
_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
