Re: Mathematica Notebook Organiztion

*To*: mathgroup at smc.vnet.net*Subject*: [mg56820] Re: [mg56816] Mathematica Notebook Organiztion*From*: Chris Chiasson <chris.chiasson at gmail.com>*Date*: Sat, 7 May 2005 04:16:32 -0400 (EDT)*References*: <200505060701.DAA06272@smc.vnet.net>*Reply-to*: Chris Chiasson <chris.chiasson at gmail.com>*Sender*: owner-wri-mathgroup at wolfram.com

I would like to second most of what David Park said. In addition, I hope that one day the internet will run on an _executable_ markup language. XHTML and CSS are great for specifying static documents, but they lack the power of executing code on the end user's machine. That is why, for instance, GMail is written (in part) in Java script. Mathematica is most of the way there, because the same markup language that describes text layout and formatting is the language used to execute (inter)active content. (The first 3 of the following ideas may not presently be important in Mathematica, but what about Publicon?:) 1. Mathematica should be able to flow text (and graphics and formulas) from one arbitrary point to another and to fit text within any defined border or region. This would make it possible to set up columns and pages. Think of a printed three column page layout with a heading along the top. 2. Mathematica needs to be able to handle multiple text flows. This would make it possible to have "side bars" and "navigation menus" embedded into a document. 3. Style sheets should be able to exclude some flows from presentation in certain mediums. For instance, the navigation and sidebar menus would be unneeded in a printed version, but a table of contents and footers might be needed. 4. Mathematica's language should be easily embedable in a defined region of an XHTML document and MathReader should be implemented as a browser extension that will render into that defined region. (Note how people don't mind subtle Flash animations, but that loading pdf files can be really annoying to them.) On 5/6/05, David Park <djmp at earthlink.net> wrote: > 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? > > -- Chris Chiasson http://chrischiasson.com/ 1 (810) 265-3161

**References**:**Mathematica Notebook Organiztion***From:*"David Park" <djmp@earthlink.net>