On Mon, Mar 22, 2010 at 12:19:06PM +0100, Hans Petter Langtangen wrote: > Sun, 21 Mar Anders Logg wrote: > > It looks pretty cool and I very much like the idea of a simple > > text-based format that looks natural (very similar to Publish).
Footnote: http://bitbucket.org/logg/publish/ > It's very similar to Publish (simple format, some options not found > elsewhere), and as with Publish, you can at any time convert to a > standard format such as BibTeX and go with that for the future. > Doconce can at any time be transformed to reST, which is the standard > markup language for sphinx and Python documentation in general. > It should be straightforward to have a script that automates the transition > from doconce to reST in the documentation. 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. > > But how would it be used to document code? Is the doconce input > > written as part of the code, or is the code generated as the result of > > some preprocessing stage? > > 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 -- Anders > > > > 1.a FEniCS Tutorial (C++) > > 1.b FEniCS Tutorial (Python) > > 2.a FEniCS User Manual (C++) > > 2.b FEniCS User Manual (Python) > > 3.a Demos (C++) > > 3.b Demos (Python) > > > > 1 and 2 should be available in both HTML and PDF. > > > > 1.a and 1.b can be created based on the existing C++/Python tutorial. > > > > 3.a and 3.b are in pretty good shape already and can remain where they > > are (as part of the DOLFIN source tree), but some demos are missing in > > C++ and others in Python. We might also consider making the demos more > > easily accessible via the web page. They may be difficult to find, > > especially for someone using the Debian/Ubuntu packages (where they > > are located somewhere under /usr/share/doc). > > > > The question is how to design 2, the user manual, whether it should be > > generated from the code, or if it should be written manually. > > > > A related question is if we need a FEniCS Programmer's Reference and > > how that differs from the User Manual, or if the User Manual should > > contain everything and make a Programmer's Reference unnecessary. > > I think this will be the same. Anyway, just start writing the manual and see > what need it covers. > > Hans Petter > >
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
