MathGroup Archive 2006

[Date Index] [Thread Index] [Author Index]

Search the Archive

RE: Notebooks, packages, cells, and literate programming

  • To: mathgroup at
  • Subject: [mg64202] RE: [mg64195] Notebooks, packages, cells, and literate programming
  • From: "David Park" <djmp at>
  • Date: Sun, 5 Feb 2006 04:44:55 -0500 (EST)
  • Sender: owner-wri-mathgroup at


I think the short answer to your question is no, there is not a way of
splitting a Module, Block or With between cells.

Still, I would like to make some comments that may be useful to you.

First on the use of (* *) comments: I believe these can be very useful in
theory, but in practice, in Mathematica, are a little iffy. I often like to
develop routines in a notebook, usually one in which I am working through
some textbook, and then when I am happy with a routine, move it to a
package. But if I copy and paste a routine with (* *) comments into a
package notebook (package.nb with Initialization cells) I will often get
loading errors with the package. Something happens in the copy and paste
operation. However, if I insert the comments in the package notebook,
without a copy and paste, then it seems to work. Also if you use
Shift-Ctrl-N to change a cell to StandardForm (or just clean up the format),
or Shift-Ctrl-I to change a notebook to InputForm, then all (* *) comments
are deleted. This is certainly frustrating if one has gone to a lot of work
to insert useful comments in the code. WRI never comments or acknowledges
these problems and it is certainly an extreme weak point of Mathematica.

One way to make the code more literate is, of course, to use longer, more
descriptive names for the variables in the routine, and perhaps do things in
multiple steps. I don't know to what extent this may interfere with
efficiency, but in many routines efficiency is not the major concern.

Text cells are fine for giving an overall description of an algorithm, but
they are very awkward for detailed description, which is the reason you
asked your question in the first place.

I would not put many test cases and documentation of the use of a routine
into the package notebook. If you do a lot of this, the package notebook
will end up being quite long and cluttered. Generally, the package notebook
is not seen by the user and, in any case, is not a convenient source of
usage information. I would suggest an alternative approach.

Consider fully documenting your package with Help browser pages, with an
individual Help notebook for each command, and perhaps additional extended
examples. This provides the same level of convenience and documentation that
regular 'core' Mathematica routines have. It is extremely convenient to
users and even to oneself if not constantly using the package. (Standard
Mathematica packages generally only have a single documentation notebook
with them, which is not nearly as convenient.) One advantage of an
individual Help notebook for each command is that you can use the Examples
section to hold your test cases. After all, a test case is not really much
different than a usage examples.

With full documentation you put a Documentation/English folder in your
package folder, then add a Browser.m file, a BrowserIndex.nb notebook, and
your individual Help notebooks. If you want to see a short example of this
you could download the ConicSections package from my web site and look at
the structure. The Browser.m file sets up the items in the Browser window.
It you look at it, it will be pretty much self-explanatory.

If I need to modify or debug a package routine, I often make a new Examples
section in the Help notebook, rename it Routine, and then copy the routine
into it. Then I can experiment with it, run the test cases, add Print
statements to aid in debugging. When I'm happy I move the routine back to
the package file and delete it from the Help notebook. That way, the Help
notebook does double duty as documentation and as a (temporary) development

I think that a detailed and literary explanation of an algorithm is quite
different than an actual algorithm in a package. Exposition and execution
are quite different. This is certainly a huge burden if you did it for EVERY
routine in a package. But there might be some special key algorithms of
special interest. Then why not add this discussion in the Examples section
of the Browser documentation? There you could pull the longer Modules apart,
show the results of intermediate steps with examples without filling up the
actual package notebook with all this material.

In summary, I would suggest going with the regular Mathematica Browser
documentation mechanism, which you can use to achieve your purposes and get
the bonus of good documentation at the same time. It is a little extra work,
but you seem to be interested in extra effort for good documentation.

David Park
djmp at

From: Mark Adler [mailto:madler at]
To: mathgroup at

So I have a notebook that documents a package, the latter being
automatically saved from the initialization cells.  (When that works
anyway.)  All well and good, especially since it permits a literate
programming style, by which I mean detailed comments, example,
illustrations, etc. as desired between and among the actual package
cells.  The comments (cmd-7 text) are visually distinctive and compact.
 The examples can be run by the user to see what the code fragment
does, but is not part of the package.

That all works unless I have a definition of, say, a block with many
lines, then I cannot split those cells and have them work in the
notebook.  I'd like to intersperse comment and other sorts of
illustrative cells in and among the lines of the block.  I'd like to
never use the horrible (* *) comments in the block.

So is there a way to break up an expression among multiple cells in a
notebook and have the cells still work (if executed in the proper


p.s.  The answer is not "use smaller blocks".  I want comments between
individual lines of already small blocks.

  • Prev by Date: Re: Goedel Numbers
  • Next by Date: MathGL3d and Mathematica 5.3
  • Previous by thread: Re: Notebooks, packages, cells, and literate programming
  • Next by thread: Re: Notebooks, packages, cells, and literate programming