MathGroup Archive 2011

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

Search the Archive

Re: How to write a "proper" math document

  • To: mathgroup at
  • Subject: [mg120041] Re: How to write a "proper" math document
  • From: "David Park" <djmpark at>
  • Date: Thu, 7 Jul 2011 07:28:02 -0400 (EDT)
  • References: <> <iuukk8$epi$> <15944200.6757.1309943765495.JavaMail.root@m06>


The "two document" approach has both feet planted in the past. The first
"document" is really a "programmable super graphical calculator" planted in
the recent past. The second document is a static "text, equations, diagram"
document planted in 3000 year old technology.

It is as if, after the introduction of paper or papyrus media, the mode of
communication was to write drafts on paper but only publish by chiseling in
stone - ignoring the fact that it is much easier to copy and distribute
paper documents.

Similarly the second of the current "two documents" nearly completely throws
away all of the benefits of an active and dynamic mathematical medium. Such
1) Generated knowledge in the form of active tools for using the ideas in
the document.
2) If everything is calculated, then the document has a high level of
self-proofing and high integrity. (Perhaps not perfect, but far better that
documents produced by word processing.) It will be more convincing to the
3) A reader can quickly verify the calculated results, try variations, or
use the material to extend the results.
4) An active and dynamic medium opens up many new ways to present and
envision concepts and information that are just plain missing in static

AES, I sometimes wonder if you have ever tried to write such a document or
ever read one. You seem to be unaware of the advantages.

The solution is simple. Every technically literate person should have
Mathematica. A price of $295 (for the Home edition) is not unreasonable for
people who might at first be casual users or readers. It would probably be a
good business model if the base was much enlarged. Someone has to pay the
developers and maintainers. But how to get to that point?

One path is to produce a free easily obtainable Mathematica Reader on the
model of the Adobe Acrobat Reader. The reader could read the document,
operate the controls (with maybe some minor restrictions) but not much else.
The idea is that once users could publish in Mathematica they would write
more literate documents. More people would see them and decide they really
wanted to do the same (or use the generated knowledge) and so would buy
regular Mathematica themselves. I despair that WRI will ever make this
approach work. (A free Mathematica PlayerPro would be close but they don't
want to do that.) WRI puts too many restrictions and caveats in their
approaches such that it will never convince people that it will be a general
method of publication. For example, it looks as if all dynamics must be via
the Manipulate statement and one cannot write custom dynamics. I was once
hopeful, but now have doubts that this approach will ever work.

One can, of course, publish technical documents within the Mathematica
community. What is needed here is more good examples of literate documents.
Maybe once these are seen, they will seep by osmosis to the wider community
and win their way.

It is not at all a trivial exercise to use this new medium to best
advantage. There are many ways to go wrong, or to generate "computer junk"
or to include things because we just found out in Mathematica how to do
something and then include it without regard to its appropriateness or
without regard to other techniques. It is difficult at first to even have a
grasp of the techniques that are conducive to clear communication. We need
the same kind of thought given to active and dynamic documents as Edward
Tufte has given to data graphics.

For example, WRI has pushed the Demonstrations Project, even as a means of
publication, and it is quite popular. Nevertheless I can't believe that this
can ever be an acceptable general method of publishing ideas. It is far too
restrictive, being built around a single Manipulate statement and not even
allowing custom dynamics. A single object with a lot of knobs on it may be
very impressive but it is not the same thing as clear communication.
Communicating ideas and concepts will usually require development, multiple
modes of presentation, extended textual discussion. In other words,
something that looks more like a classic technical paper but with active
interaction, dynamics and usable generated knowledge.

David Park
djmpark at  

From: AES [mailto:siegman at] 

In article <iuukk8$epi$1 at>,
 "McHale, Paul" <Paul.McHale at> wrote:

> Looking at Mathematica's admitted origins as an authoring tool for Stephen

> Wolfram to publish his books, it's stronger points become evident.  It
> very well in the individual experiment, document and "publish" mode.
> here meaning the document is indistinguishable from a PDF with static
> no interaction.  A book.  I will likely stay in the standard flow of 
> experiment, document and publish.  As we can see from the exchanges of 
> emails, this path is sufficiently difficult to do well.  Stephen just
> it look easy :)

With regard to this specific situation of going from notebook to "static 
book", let me quote from the 3rd edition of Heikki Ruskeepaa's masterful 
Mathematica Navigator.  Navigator is of course "a book" -- a superb book 
-- written in Mathematica.

But in Section 3.4 of this book, entitled "Writing Mathematica 
Documents" and following a subsection on "Mathematica as a Writing 
Tool", Ruskeepaa has a subsection which reads as follows:

Main and Working Documents

When writing a mathematical document with Mathematica, it may be useful 
to work simultaneously with two documents: a {\it main document} and a 
{\it working document. The main document will grow into the final 
publication, whereas all computations are done in the working document. 
Mathematical results, tables, and graphics are copied from the working 
document into the main document. This division into two documents may be 
needed because the main document may not contain the Mathematica 
commands but only the results. The working document contains all used 
Mathematica commands so that all computations can easily be done again. 

   The working document should include the same sections as are in the 
main document so that you can easily find the computations of a certain 
section. Add into the working document comments about the computations, 
such as any difficulties that may arise; they may be valuable if you 
need to do similar computations at a later time.

   When you have completed the writing project, you will then have the 
main document ready to be printed and the working document that will 
enable you to redo and modify computations as needed.

Repeat:  _two_ documents.  And although I can't track down the exact 
quote, I believe that in an earlier edition Ruskeepaa states even more 
explicitly that this approach is how he wrote his book.

In a recent post I've suggested a variation on this two-document 
approach: a Mathematic notebook which contains all the "text" content 
(not necessarily cleanly formatted for publication) and does all the 
computations, and then a post-processor (written in whatever language 
you like) which intelligently converts that notebook into a TeX or LaTeX 
document, which (after minor touchup) produces the book.

I believe there are two great advantages to this approach:

1)  It uses the best tool for each separate task -- and thereby does 
each of them better, more powerfully, AND more easily.

2)  Instead of every individual who uses Mathematica having to struggle 
to learn how to do both the technical computations _and_ the 
publications formatting simultaneously in one tool (and instead of, as a 
result, enormously complicating and messing up the syntax and interface 
to Mathematica, to its substantial detriment), put the hard work of 
writing the post-processor on a few skilled individuals, who know how to 
do that sort of thing.

(In fact, multiple post-processors are likely to emerge and compete in 
this situation -- the best results of meaningful competition.)

In any event, let's note:  Even a Mathematica wizard like Heikki 
Ruskeepaa ended up using a _two_ document approach -- he did NOT 
docomputation and publication, all in one single notebook.

  • Prev by Date: Re: How can I get better solution for this...?
  • Next by Date: Re: How can I get better solution for this...?
  • Previous by thread: Re: How to write a "proper" math document
  • Next by thread: Re: How to write a "proper" math document