fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

Chris Richardson pointed me to the PHP documentation which looks
pretty good:

  http://www.php.net/manual/en/function.explode.php

Note the sections ChangeLog, Examples and Notes. Being able to add
notes seems very useful.

It is generated using DocBook:

  http://doc.php.net/php/dochowto/docbook-whatis.php

The problem with it seems to be it's a nightmare to write the input:

  http://doc.php.net/php/dochowto/chapter-skeletons.php

--
Anders


On Sun, Mar 21, 2010 at 12:15:07AM +0100, Anders Logg wrote:
> On Sat, Mar 20, 2010 at 04:10:53PM +0100, Hans Petter Langtangen wrote:
> > Sat, 20 Mar Anders Logg wrote:
> >
> > > > >We have also discussed using a standard format for the Python Docstrings. So
> > > > >nice programmers references can be generated from these. We haven't decided
> > > > >which one we are going to use (epydoc or others). I couldn't find doconce (too
> > > > >close to many other meanings of doc once :P) at the net so I do not know what
> > > > >this software does or how well adapted it is.
> > >
> > > Perhaps Hans Petter could say something about doconce?
> >
> > I wrote doconce during the FEniCS'06 (?) meeting in Delft :-) as a
> > solution to the problem that I wanted to document software in one
> > place only, and still be able to put that single piece of text into
> > pure source code, latex manuals, html manuals, other formats like
> > docbook, etc. There is and was a relevant tool, docutils and the reST
> > (restructured text) markup, for doing this. The problem with docutils
> > was that I think reST has too much markup compared to the plain text
> > you want to see in the source code and with pydoc in a
> > terminal. Writing a new backend in docutils that filters reST to plain
> > (almost) untagged text is the obvious solution, but that seemed
> > very complicated. I also wanted better support for source code and
> > mathematics in documents. The attached tutorial explains what doconce is.
>
> It looks pretty cool and I very much like the idea of a simple
> text-based format that looks natural (very similar to Publish).
>
> 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?
>
> > > It might have some good features we can use. But one issue would be
> > > the status of doconce. To be useful, it needs to be actively
> > > maintained and widely available (as in having a Debian package).
> >
> > Right now it's living in Simula's svn repository only. It has been
> > frequently used by myself and others (Johannes, Ilmar). We have thought
> > of putting it out on googlecode, but that requires maintenance...
> >
> > For example, my latest book has half a chapter where the source is in
> > doconce.  That source is automatically copied into a doc string in the
> > Python code, so that we have the book material also as documentation
> > of a Python module (via pydoc), the source is filtered to Epytext and
> > included in the Python module to produce an Epydoc manual of the
> > module, the source is also filtered to HTML for an online tutorial,
> > and to latex for fancy typesetting in the book (and in fact also
> > Johannes Ring's master thesis). The idea is to document once and only
> > once: if the tutorial is updated, it's the doconce source, and I have
> > automatic update of the book, the Python source code, and other
> > manuals :-)
> >
> > Personally, I use doconce for almost everything I write (except slides
> > and complete books) since that enables me to postpone the choice of
> > format.
> >
> > Johannes (who have made a wiki filter to doconce and done many other
> > adjustments) and I could maintain a more official version and maybe
> > try to get it into Debian. However, we should carefully consider the
> > work associated with a more official version. Doconce is very limited
> > (no footnotes, no citations and bibliography, for instance) and as
> > soon as it gets users, they will demand extensions.  The point was to
> > make it minimal. Debugging errors can also be somewhat frustrating
> > and challenging.
> >
> > FEniCS should definitely adopt the doconce *strategy*, i.e., write a
> > piece of text only once, but maybe distutils and reST is a better
> > technical choice?  The downside is no support for math, you cannot
> > copy code directly from a source file and into a manual, and the reST
> > tagged text (sometimes a bit ugly) appears in Doxygen text or Python
> > doc strings. The upside is strong support.
> >
> > > I think we need to separate demos from tutorial/example programs. The
> > > demos should be as they are now: short, simple and self-explaining.
> > >
> > > Then we can have a different set of programs which are explained very
> > > carefully. It would be natural for these to be part of the tutorial
> > > (based on the existing tutorial written by Hans Petter).
> >
> > I share this view. You copy demos and modify to solve a new problem.
> > Tutorial examples are made for teaching ideas, syntax, etc. The code
> > therefore often becomes quite different from a self-explaining demo.
> >
> >
> > > > >>2. Both the user manual and tutorial will come in two different
> > > > >>flavors, one C++ and Python. With some clever use of LaTex \input, it
> > > > >>should be possible to handle with not too much extra work.
> >
> > I use a program preprocess (in Python :-) to allow for #ifdef and other
> > C preprocessor type of commands in latex, shell, doconce, and almost
> > whatever. Then it's easy to compile a tutorial in one mode. (At the
> > University of Oslo this is used for compiling course manuals with
> > Python or Matlab.)
> >
> > But I doubt that #ifdef or clever \input is the way to go with Python
> > and C++ in a tutorial. The text will naturally be quite different for
> > the Python and C++ versions. I think it's better to explain most of
> > the things in Python first and then provide add-on material for
> > C++. This can be made quite short with a focus on syntax, and reference
> > back to where the example is introduced in the Python part. However,
> > if you have a substantial amount of users who don't want to use or
> > read about the Python interface, you need a stand-alone C++
> > tutorial. In my view, FEniCS users should normally use Python for
> > rapid development, but turn to the C++ interface for speed in a more
> > comprehensive code. That is, the C++ FEniCS programmers are quite
> > advanced users already and you can take advantage of that when writing
> > tutorial material. (For the Python tutorial, I forsee very novice
> > users who don't know finite elements and Python, but they have a PDE
> > to solve...it seems that FEniCS can, maybe uexpectedly, work well
> > for this group of users.)
>
> I think we have some C++ only users that don't care much for the
> Python interface and some Python users that absolutely don't want to
> see the C++ interface, so I think it would be good to split the two
> manuals. But you are probably right that the two texts will be
> different. Instead of one document with #ifdefs, it should perhaps be
> two different documents that share some common chapters that are
> language independent.
>
> > > > >>6. We need well-documented demos. It's currently unclear what the
> > > > >>relation is between the manual, documented demos, current demos in
> > > > >>DOLFIN and the examples in Hans Petter's tutorial so we need to work
> > > > >>out a model for this.
> >
> > I suggest to view the manual, tutorial and demos as three different
> > types of documentation. The tutorial has its example programs, so may
> > the manual (but I guess there will be more of short code snippets in a
> > manual), and the demo selection is a third source of information. To
> > me it seems difficult to maintain these three types of documentation
> > if they are closely related to each other.
>
> Agree. And the "well documented examples" discussed above should be
> part of the tutorial. I think we are looking at the following pieces:
>
>   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.
>



> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp

Attachment: signature.asc
Description: Digital signature