MathGroup Archive 2005

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

Search the Archive

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?





  • Prev by Date: Re: Re: Re: debugging
  • Next by Date: Re: Re: Re: debugging
  • Previous by thread: Re: ZTarnsform[Sin[4 n],n,z] OK, but ZTransform[Sin[5 n],n,z,] hangs?
  • Next by thread: Re: Mathematica Notebook Organiztion