21

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?

  • If the book will be published as a notebook, that is a very strong argument for writing it in Mathematica (despite all the problems that will bring). Converting from notebook -> LaTeX is more feasible than the reverse. Either way, expect to have to write custom code to transform/convert notebooks to make sure everything will work well and look good. – Szabolcs Dec 17 '18 at 12:42
  • There are also the publisher's limitations to consider. Will you create a print-ready format yourself? Or will you give the source material to the publisher, who will process it? – Szabolcs Dec 17 '18 at 12:43
  • @ Szabolcs That's open. I will answer it only after the book will be written if it will really be. In advance, however, I thought about going to a regular publisher. – Alexei Boulbitch Dec 17 '18 at 12:46
  • Stephen Wolfram's An Elementary Introduction to the Wolfram Language is pretty nice, as notebooks, as a webpage, and as a physical book. Is such a template available? – Chris K Dec 17 '18 at 16:41
  • 1
    It's great that you plan to write a book - I am looking forward to read it; in what ever format you choose. Now, I'd look around for a format that I'd like and then contact the author and ask how it was done. If that then was done with M- I am sure they are willing to share the process details. I for one like the style Roman Maeder wrote his books in. – user21 Dec 18 '18 at 8:04
12

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.

6

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.

  • Regarding the Mathematica code highligthing, I went a different path. I created for each shown code-snip an .m file which I could format easily in IntelliJ IDEA. With the LaTeX minted package and the pygments highlighter, including code was like including an image file. Adapting the highlighter colors to my global LaTeX color scheme, the result looked like this i.imgur.com/t0NkwF1.png – halirutan♦ Feb 24 '19 at 0:47
  • Thanks @halirutan, I'll look into minted&pygments again. – Roman Feb 25 '19 at 2:26
  • @halirutan the concrete point I'm stuck at for syntax highlighting is how to get programmatically generated source code into the lexer. It seems that lexers like minted only accept verbatim source code, not on-the-fly generated source code. I've formulated my concrete problem here; maybe you know how to proceed: tex.stackexchange.com/questions/476554/… – Roman Feb 25 '19 at 13:11

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .