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 : [email protected] > Unsubscribe : https://launchpad.net/~fenics > More help : https://help.launchpad.net/ListHelp
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
