MathGroup Archive 2011

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

Search the Archive

Re: How to write a "proper" math document

  • To: mathgroup at
  • Subject: [mg120092] Re: How to write a "proper" math document
  • From: Richard Fateman <fateman at>
  • Date: Fri, 8 Jul 2011 04:52:17 -0400 (EDT)
  • References: <> <iuukk8$epi$> <15944200.6757.1309943765495.JavaMail.root@m06> <iv45b8$es8$>

On 7/7/2011 4:29 AM, David Park wrote:
> 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.

I think you quite miss the point of static documents, at least the best 
of them. Ruskeepaa may be right. At the risk of repeating ...

Documents provide an opportunity for an author and a reader to traverse 
a territory in a fundamentally linear fashion, together, in order to 
transmit an understanding from the author to the reader.

  A "document" with (optional) links might be written with the 
irritating sloppiness of some on-line presentations.  ( sloppy... I can 
use any new terms I wish because the reader can click on them for 
definitions, so why bother trying to present stuff in a linear fashion, 
and anyway someone might find the 5th page of my "paper" via a search 
engine and not read the introduction so why not just plop everything 
where it occurs to me...)

> 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
> reader.
> 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.

In contrast with Ruskeepaa, I think you are confusing a showcase and a 
workshop.  If you visit a "science museum" you will see demonstrations 
of "science stuff"  often oriented towards children, but occasionally 
neat even for scientifically literate adults. These demos are presumably 
carefully crafted to emphasize some point or other; the interaction 
represents a blend of science and showmanship. I have not explored much 
of the Mathematica Demos project, but I gather it has that flavor.

A workshop or laboratory, on the other hand, is filled with the detritus 
of failed experiments, the nasty, dirty details of finding the one rock 
which is a geode and not just a solid rock, etc.

  In Mathematica, the ugly details of setting up a plot or animation, or 
sequencing the definition of a bunch of rules and adding conditions here 
and there, and "waving the dead chicken" of putting N[...] in the right 
place, and ReleaseHold or Hold or ... so it finally comes out right.. 
this is not science, nor math, nor illuminating.  This is grunge, and it 
is the grunge of (arguably) poor idiosyncratic design.

I find it far preferable to take stuff out of a computer algebra system 
as TeX and paste it into a static document.  This also provides an 
opportunity to fix the broken displays.  E.g. we really don't expect a 
display of f=ma   to  come out   f=am.   Or E=mc^2 to come out e=c^2m
(note also that E=2.718... not energy). Mathematica thinks it knows 
better than Einstein and Newton.

> 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.

I think that there is some obligation to provide backup support for 
published results that came from a computer, especially a computer 
algebra system, though this is rarely the case in journal publications. 
  An appendix or an on-line supplement, or a computational substrate 
somehow linked as an incidental coordinated computation to a section in 
a paper is something that I would welcome, in general.  Not as a 
substitute for literate logical mathematical explanation.  I would 
certainly NOT find a workshop or laboratory table or a "notebook" 
cluttered with the impedimenta of Mathematica to be a good first or 
unique presentation. Especially if notions like "equal" or "accuracy" 
are hijacked by Mathematica and do not correspond to ordinary logic or 

Previously I have made the distinction between a "showcase" and a 
"notebook".  You don't want to see my notebook, unless you are perhaps a 
patent lawyer. I don't want to study yours. Indeed, when I write code 
for a computer algebra system, I often do it in a text editor and then 
"batch process" it.  I fiddle a bit, and then fix the file and "batch 
process" it again, as necessary.
I try to make it as clear as possible so I can continue to work on it 
sometime later.  However, it has lots of stuff of no interest to 
bystanders for whom my "results" are some subset of my fiddling.  to 
show others I need to construct a "showcase".

Does Mathematica provide facilities to build showcases?  Sure.  However, 
the usual scientific concept of "notebook" is a different animal from a 
Mathematica notebook.  A real notebook typically has numbered bound 
pages.  You write down (and date) everything you can. You don't go back 
and erase, or tear out pages. You save your notebooks forever.
> The solution is simple. Every technically literate person should have
> Mathematica.

  I suppose that if you think people should learn to program a computer 
and the only programming language you are aware of is Mathematica, then 
you might conclude that people should learn Mathematica. There are 
strong incentives to favor some alternative languages, e.g. you need not 
buy them, and you might get a job.

  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?

Maybe Mathematica should have ads.  E.g. we interrupt this Integrate[] 
to inform you of the excellent record of success of this Cure for 
Acne.... Perhaps Wolfram Alpha does.  I thought about it as a way of 
supporting TILU.

> 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.

There is one, I thought. e.g. in 1994

I believe its style (free open source) was forced on Wolfram by the 
author of the (version 1, 2,) front-end of Mathematica, back then, as a 
concession. Otherwise he wouldn't write the proprietary one. There is a 
sad history there.

  At least you asked for it in 2003 --

but it seems that it has disappeared in favor of MathPlayer.

> The idea is that once users could publish in Mathematica they would write
> more literate documents.

I can't see why someone who cannot write ordinary natural language in a 
journal article would be enabled to do better in a notebook.  While 
there is a certain precision one has available from using a formal 
language, I doubt that most readers would prefer to read a program to 
natural language. Experience reading student programs suggests that the 
dominant thoughts of a reader are probably "what is going on here?" and 
"why did she do that?" and "is that deliberate?" and "huh, a call to a 
program I don't see defined here.."

  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.

You seem unforgiving of Wolfram, who, after all, is only trying to make 
money.  You seem to impute some alternative higher calling to him, like 
making the world a better place.

> 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.

The "Mathematica Journal" has been around for a while. I don't think it 
has been especially accepted. Or the works by Michael Trott. or the math 
functions web site.
> 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.

Yes, I agree entirely here.  I think that Tufte is hard to match.
> 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.

There was some effort (by me, and others) made to have NIST and its 
digital library of mathematical functions provide (free) software to 
augment its information.  I think that the editors felt they were being 
extremely ambitious in making the authors use TeX, for them a novel 
idea, but of course 20-30 years old. To introduce computer algebra 
programs too -- that would be impossible.  Maybe in another 30 years 
NIST will take another step.


  • Prev by Date: Re: Bug 1+4/10
  • Next by Date: Search and replace variable name with subscript
  • Previous by thread: Re: How to write a "proper" math document
  • Next by thread: Re: How to write a "proper" math document