fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Mon, Mar 22, 2010 at 08:04:49PM +0100, Hans Petter Langtangen wrote:
> Mon, 22 Mar Anders Logg wrote:
> > 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.
>
> The reason is about the same as why develop Publish when BibTeX exists
> ;-) I wanted to have plain untagged ASCII as a format and found it too
> demanding to write a new backend for docutils. I also wanted to have
> support for math in the text (there is upcoming suppert for LaTeX in
> reST, but not in any official version), plus support for computer code
> copied directly from source files and typeset in a variety of formats.
> The LaTeX and HTML source files generated from reST are quite ugly
> too. Finally, it's simpler to add certain features to a simple markup
> language than to reST.

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?

You don't need to retype the entire page... :-) but maybe some interesting
paragraph that would look different in doconce.

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

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

--
Anders

Attachment: signature.asc
Description: Digital signature