fenics team mailing list archive

[Hans Petter Langtangen <hpl@xxxxxxxxx>]

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).

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.
 
> 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).

> 
>   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