fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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

Attachment: signature.asc
Description: Digital signature