Re: Re: Notebooks, packages, cells, and literate programming
- To: mathgroup at smc.vnet.net
- Subject: [mg64218] Re: [mg64202] Re: [mg64195] Notebooks, packages, cells, and literate programming
- From: "Ingolf Dahl" <ingolf.dahl at telia.com>
- Date: Tue, 7 Feb 2006 03:35:44 -0500 (EST)
- Sender: owner-wri-mathgroup at wolfram.com
Mark, I fully agree in what David Park has said, but just want to add two small points. Point one: One alternative way to enter inline comments, if you anyway want that, is to wrap them up in a ordinary Mathematica function in this way: Comment[" This is my comment. "]; There usually are any number of places in the code where you could add comments in this way. If you have not defined the function Comment, the statement will not be evaluated. Such comments are not removed by Shift-Ctrl-N or Shift-Ctrl-I. Of course I must here also remind that the button "CopyAsInputForm" in my SetFaceAndFont Palette preserves (* *) comments by converting them into the suggested alternative. (See http://web.telia.com/~u31815170/Mathematica/) Point two: It is possible to do almost anything in Mathematica, but everything is not sensible. It is possible to embed Input cells inside a Text cell. One could also make a button that merges all such embedded Input cells from one Text cell and executes the resulting code (ignoring the pure text content outside the embedded cells in the Text cell). Mark, would you be happy with such construction, if it was available? Best regards Ingolf Dahl Sweden > -----Original Message----- > From: David Park [mailto:djmp at earthlink.net] To: mathgroup at smc.vnet.net > Subject: [mg64218] [mg64202] RE: [mg64195] Notebooks, packages, cells, > and literate programming > > 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. > >