MathGroup Archive 2011

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

Search the Archive

Re: How to write a "proper" math document

  • To: mathgroup at
  • Subject: [mg120029] Re: How to write a "proper" math document
  • From: AES <siegman at>
  • Date: Wed, 6 Jul 2011 05:40:59 -0400 (EDT)
  • References: <> <iuukk8$epi$>

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 works 
> very well in the individual experiment, document and "publish" mode.  Publish 
> here meaning the document is indistinguishable from a PDF with static data, 
> 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 makes 
> 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: Numerical accuracy/precision - this is a bug or a feature?
  • Next by Date: Re: Bug 1+4/10
  • Previous by thread: Re: How to write a "proper" math document
  • Next by thread: Re: How to write a "proper" math document