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