Services & ResourcesWolfram ForumsMathGroup Archive

Re: How to write a "proper" math document

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

AES,

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
as:
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
media.

AES, I sometimes wonder if you have ever tried to write such a document or

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 comcast.net http://home.comcast.net/~djmpark/ From: AES [mailto:siegman at stanford.edu] 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: 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