Mathematica Notebook Organiztion

*To*: mathgroup at smc.vnet.net*Subject*: [mg56816] Mathematica Notebook Organiztion*From*: "David Park" <djmp at earthlink.net>*Date*: Fri, 6 May 2005 03:01:35 -0400 (EDT)*Sender*: owner-wri-mathgroup at wolfram.com

I've made this a new topic because we have rather drifted off from the subject of writing packages to the subject of using notebooks in the best manner. It is my view that Mathematica notebooks (and similar such entities) are an entirely new publishing form. They FAR SURPASS printed books and articles because of the ability to interactively meld text, calculations, graphics and animations in one document. Theodore Gray deserves a lot of credit for his work on this concept. We are still learning how to use this media. But things are not perfect yet and Professor Siegman has touched on some issues. There is no reason that the Initialization and Routines Sections couldn't be at the end of the notebook. The Input cells in these Sections should be made into Initialization cells (and choose NOT to save as an AutoSave package). That way one doesn't have to necessarily evaluate a notebook from the top. The initializations are automatically performed when the first statement, anywhere, is evaluated. I like to make my notebooks such that a reader can start at any Section and begin evaluating. If this is not possible because of a rigid progression in the sections then the reader should be so instructed. Often I will select the Initialization and Routine section headings and change the FontColor to Gray. I also often add "Automatically Initialized". This subdues the sections and tells the reader he can generally ignore them. Sections are not automatically opened when Initialization cells are evaluated. My experience is that the sections remain closed. Also you can select a Section and completely evaluate it without ever opening it, or seeing the results. (I've had super geniuses complain that they evaluated my notebook but got no results, simply because they didn't know how to open Sections!) Graphics code can be put in closed cells in the running sections. It doesn't necessarily have to be put in the Routines section. That way you can intermix text, calculations and graphics in a smooth manner. The only problem is getting the reader to evaluate the closed cells, even if it has been carefully explained in an Introduction. They are so thin and small new readers often overlook them. It might be nice if one had the option of having a closed cell display a cell tag. It would also be nice if closed cells could be opened and closed in the same way as Sections. It is also possible to generate proofs, derivations or step by step calculations by interspersing Print statements with %% referenced statements. These can also be put in closed cells so that the main code is hidden. For printing (It will take some time for people to give up the security blanket of printed documents - inferior as they are!) there is no reason why some Sections can't be open and others closed. Professor Siegman's case: Section Text (a few paragraphs introducing the section) Subsection Subsection is a good point. I don't see any direct way around it other than making the Text an Introductory Subsection, which may be objectionable because it is so short, or manually closing these Text cells, but this is too difficult for the reader to work with. Perhaps there might be a FrontEnd command that gives the "outline view". Another approach would be to make a Table of Contents Section. The various items in the Table of Contents could actually be links to the corresponding sections of the notebook. This is like pdf documents where there is often a table of contents with links in the side bar. It requires extra work to write the sections, but then it also requires extra work in a pdf document. It would also be nice to have the following construction: Section Text and Input cells BoxSection Text and Input cells End of BoxSection marker Text and Input cells where the BoxSection could be closed or terminated, and subsequent Text and Input cells would NOT be part of the BoxSection, but part of the containing section. The BoxSections would be like boxes in textbooks which contain a side discussion without interrupting the main flow of material. (Possibly there could be a way to have manual grouping only in some subsection of a notebook, but I would much prefer a more versatile automatic grouping because manual grouping is too subject to abuse.) I have only looked a little at the Author's Tools application. It does give information about constructing Help documentation, which I omitted to mention in an earlier posting. But otherwise I haven't figured out just what Author's Tools does for one in the way of constructing better notebooks for readers. I wish WRI had provided a short elegant example with the application. It might also be nice to have the ability to construct stand alone browsers. Then the categories in the browser would be like the table of contents. In essence, authors would write Mathematica browsers, in which Mathematica notebooks formed the various chapters and sections. I wish that there were better standard notebook styles supplied with Mathematica. I find many of the standard ones useless. WRI needs to hire Edward Tufte, or someone equivalent, to design some notebook styles. It certainly is preferable to use a standard style because then one can count on readers having it. I would like to see one more Section level in notebooks. I would like to see the default to have GroupOpenCloseIcons on all the Section levels - but NOT on anything else. (Especially not on Input/Output groups.) The triangular open/close icons are intuitive to new readers - the cell brackets are not. I would like to see a better balance, actually a smaller range, of font sizes. In the Default style, for instance, I think the Title font size is much too large, and the Text font size is too small. The Text, Input and Output font sizes should be reasonably close in size. After all, text cells and Input/Output cells are of equal importance (IMHO) and should better blend. Look at any technical article or book and you will see that the equations and text have roughly comparable font sizes. David Park djmp at earthlink.net http://home.earthlink.net/~djmp/ From: AES [mailto:siegman at stanford.edu] To: mathgroup at smc.vnet.net Agreed, this is the sensible way to [include routines in notebooks], and how I generally do it. But two gripes about the result: 1) In PhD dissertations, journal papers, books, reports, the (sometimes lengthy) "Routines" are most commonly are sent to the end, e.g. are stuck in Appendices, and the Initialization (or Introduction) section is immediately followed by the important (to the reader) sections such as Calculations and Results. Among other things that lets you easily select and print the Introduction, the Calculations and the Results to toss in a file folder or (three-hole-type) notebook, leaving off the lengthy Routines stuff. Mathematica doesn't make it easy to organize its notebooks that way. 2) In my (limited) experience if I use Automatic Grouping and try to close groups to see only the section headings (to get an overview of the notebook structure and faster scrolling to , this doesn't work right (i.e., the way I want it!) unless the cell structure is strictly hierarchical. E.g., if I have repeated cell sequences in the form Section Text (a few paragraphs introducing the section) Subsection Subsection closing these groups so I'll see just the Section headings does not close the Text cells, although it does close the Subsections (maybe I'm not doing things right?). Also, closing the Routines section, then running the notebook from the top (to get a fresh start) opens the Routines section, doesn't it?

**Follow-Ups**:**Re: Mathematica Notebook Organiztion***From:*Chris Chiasson <chris.chiasson@gmail.com>

**Re: Mathematica Notebook Organiztion***From:*DrBob <drbob@bigfoot.com>

**Re: Re: Re: debugging**

**Re: Re: Re: debugging**

**Re: ZTarnsform[Sin[4 n],n,z] OK, but ZTransform[Sin[5 n],n,z,] hangs?**

**Re: Mathematica Notebook Organiztion**