What would be a best soft to write a Mathematica&Mathematics based book?

Question

Dear Community members,

I am playing with the idea of writing a textbook, and I am asking for advice of those who have done such work. The question is about the technical side.

I have seen a couple of posts with the discussion of a book. They were, however, discussing books of a few sorts.

The first class consisted of books on scientific subjects (such as mathematics, some area of physics or alike), where the functionality of Mathematica was not the principal thing. Such authors were mainly concerned with a comfortable cross-referencing, captions, inserting images and mathematical expressions, navigation and alike.

There were also educational textbooks in which the Mathematica functionality has been mainly used to create beautiful interactive demonstrations.

There is also a class of books teaching various aspects of Mathematica: of how to use it.

I would like to make a symbiosis. I imagine it as a textbook on mathematics useful for physicists and engineers, containing the necessary theory including examples from physics and chemistry, where appropriate. As such, it is aimed to teach practice-oriented mathematics. I would like it to also provide explanations of Mathematica functions related to each mathematical subject discussed with examples and exercises. I would love it explaining how to make all the necessary calculations with Mathematica directly on-screen without passing to the paper as well as how to create demonstrations on one's own.

On the one hand, I have seen posts stating that writing a book within Mathematica is not the best idea, while Latex is much better.

On the other hand, the task I described above requires posting code, and its output, and best of all the possibility to evaluate the code, and eventually, to modify it. This seems to be natural to do within Mathematica.

Finally, the book may be published as a notebook. Alternatively, it can be on the paper, but then there should be a way to differently indicate inputs, outputs and alike.

Let us return now to the question: What is your opinion on the best technical approach for such a task?

Answer 1

It's a dilemma you're facing and you should simply point out pro's and con's

Mathematica:

• You can write and evaluate code, but afaik there is no code highlighting in an exported PDF
• You can write your book "along the way" while working on ideas as Steven Wolfram did with NKS

LaTeX:

• Colored code highlighting
• Easy to maintain citations and cross-references
• Far superior typesetting
• Easy and (opposed to Mma) beautiful formulas
• Easy versioning and your book is diffable text instead of a large notebook expression

Markdown

• The easiest way to write content, but I believe no good support of cross-references
• Can be used with e.g. GitBook
• Code highlighting and support for LaTeX formulas
• As LaTeX, it's plain text which is easier to handle

You should, therefore, consider how you want to publish your book. If you aim for an online book and you don't have a real editor and publishing firm to help you, I would suggest you use GitBook (or similar) and Markdown.

If you aim for a beautiful PDF without an editor or publisher, you should probably use LaTeX. You should remember that even in Mathematica it is not simply a write-publish process. I believe you have to use custom code to process images or ensure a consistent style.

If you are going to a publisher, I'm not sure what the best course of action is. Very likely, they will use their own typesetting except when you aim for the new trend of shitty cheap programming books where the author puts a lot of work in and the publisher tries to bring it to the market as cheap as possible.

Answer 2

I've written a book (lecture notes) about Using Mathematica for Quantum Mechanics and have given these typesetting questions a lot of thought over the past few years. I ended up using LaTeX for typesetting, and would like to offer the following points for consideration:

• As the OP says: LaTeX has excellent cross-referencing (with hyperref), beautiful typesetting, beautiful formulas, indexing, table of contents, conditional typesetting, etc. I'm not a fan of Mathematica's cross-referencing tools, and Mathematica's WYSIWYG typesetting tools for formulae and boxes are a bit of a pain compared to the straight-text entry of LaTeX.
• Portability: a LaTeX-generated PDF output can be read anywhere, on any device. Printing works beautifully.
• Source-code copying: Any Mathematica source code must be selectable&copyable in the PDF, to be pasted into Mathematica and executed straight away. In my opinion, this copy-paste capability is almost as good as having modifyable&executable code within the document itself. It took me a while to hack together a satisfactory way of showing Mathematica source code and results with automatic In[]:= and Out[]= generation, line-numbering, etc., that at the same time allows the reader to copy source code out of the PDF. This involves (i) making the "In[]:=" strings and line numbers not copyable (or else the copied text would be a jumbled mixture of code and line numbers etc.), and (ii) making sure that the copied text is valid Mathematica code, with the symbol "∞", for example, automatically becoming "\[Infinity]" in the clipboard; the alternative of using Unicode was a nightmare for me.
• Source-file attachment: On top of having copyable source code snippets in the text, I've added executable Mathematica notebooks that are attached to the PDF file. Double-clicking a link in the PDF (usually located next to section headings) automatically opens the corresponding source-code file in Mathematica, for execution and modification. This is done quite easily with the attachfile2 package. Again, this way of attaching source files is almost as good as having executable code right in the text. Combined with the copying mechanisms above I consider this a satisfactory solution.
• Syntax coloring: I haven't found a good way of auto-coloring Mathematica code that satisfied all my constraints. For now I'm displaying the code in old-school blue monochrome, but I'm open to finding a better way. There are tools out there, if you can make them work the way you want.
• Code iteration: Addressing @CE's comment on code iteration, it's true that there must be a very simple way of keeping the Mathematica code in the book "fresh", especially if the book takes years to write (as did mine). Being able to copy code straight out of the PDF really helps the author as much as it helps the reader (see above). Keeping attached notebook files "fresh" is less difficult, however there is the issue of keeping the main text and the attached notebook files synchronized with each other.

I hope these points help you in making your decision.