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 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. 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 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 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.
- References:
- Re: How to write a "proper" math document
- From: dr DanW <dmaxwarren@gmail.com>
- Re: How to write a "proper" math document