Services & ResourcesWolfram ForumsMathGroup Archive

Re: How to write a "proper" math document

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

In article <iuukk8$epi$1 at smc.vnet.net>,
"McHale, Paul" <Paul.McHale at excelitas.com> 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
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