RE: Notebooks, packages, cells, and literate programming
- To: mathgroup at smc.vnet.net
- Subject: [mg64202] RE: [mg64195] Notebooks, packages, cells, and literate programming
- From: "David Park" <djmp at earthlink.net>
- Date: Sun, 5 Feb 2006 04:44:55 -0500 (EST)
- Sender: owner-wri-mathgroup at wolfram.com
Mark, 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 notebook. 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 earthlink.net http://home.earthlink.net/~djmp/ From: Mark Adler [mailto:madler at alumni.caltech.edu] To: mathgroup at smc.vnet.net 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 order)? mark p.s. The answer is not "use smaller blocks". I want comments between individual lines of already small blocks.