20

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.

7

My opinion is that books about Mathematica should be written in Mathematica, but in such a way that they can be easily exported to some other format in the future. There are several of us (at least I, b3m2a1, Kuba and rm -rf) that have written and published notebook to Markdown/HTML converters that can be built upon and customized (and you certainly are more than good enough to write your own). From Markdown you could go to LaTeX, EPUB or PDF, or whatever, using software like Pandoc.

You should do the actual writing in Mathematica because it will encourage you to go back and improve the things you've already written. Writing a book is an iterative process. The book will be better for it if your setup allows you to easily work on the book iteratively, writing the book in LaTeX or Markdown would discourage you from going over old content because of the pains of transferring graphics and output over to that format.

The biggest pain with typesetting Mathematica, I believe, is the input-output cells. Sure, all programming books have input and output, but Mathematica and its online documentation set a very high aesthetic standard that can make the usual ways of solving this issue look less than impressive. When I created Wolfram Language Reviews, I decided that the best way to render input-output on the web is to simply rasterize the input-output cell. I still believe that this is the way to go when writing for the web.

When not writing for the web, one has to solve it the best one can in the format that one is using. One cannot do better than what is possible, it is simple as that. But having the content in Mathematica is no disadvantage here, rather the opposite; if you decide to publish it both online and in book format, for example, you can adapt its styling for each format. If you wrote it in LaTeX to start with there would be no turning back, no easy way to programmatically style it for the web.

However, writing in Mathematica does not mean you can completely ignore your intended way of publishing your book. I think you have to have some sense of how things are going to look in the final format. For example, if you are writing a book, having an image after each input is probably not feasible. There is going to be a size limit to the images. Maybe they won't be placed next to the input, maybe you will have to reference images. Maybe you won't have color.

The way I would approach this is to try typesetting what you've written early on so that you get a feeling for what will work.

On a final note, I would use Mathematica's typesetting capabilities very sparely. I'd use maybe a few different headings to distinguish chapter, section, and whatever you need, and I would use text cells and that's probably it. I wouldn't use any kind of two-dimensional formatting for sure. If I wanted math then I would simply use $$ delimiters inside a text cell.

  • I'd second the advice to use Mathematica's typesetting sparingly in raw code. However if the point is to provide an equation as it would generally appear in a standard textbook I think a DisplayFormula cell or two isn't an issue. – b3m2a1 Dec 17 '18 at 23:09
  • @b3m2a1 Well, you already have the code for that. For me, it's something that increases the complexity of the converter and it's also more difficult to write than LaTeX. The notebook should not look like a textbook, it is just a temporary format that will then be converted to something else that should look like a textbook. – C. E. Dec 18 '18 at 5:18
  • What does "use $$ delimiters inside a text cell" do? More generally, I'm imagining a book with plenty of equations that should also be nicely typeset as in TeX. – Chris K Dec 18 '18 at 17:46
  • @ChrisK It doesn't do anything anything in the notebook, but it's a block equation in Markdown. It's what you would use if your pipeline were notebook -> Markdown -> other formats via Pandoc. You can also insert LaTeX. – C. E. Dec 18 '18 at 17:56
5

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 at 0:47
  • Thanks @halirutan, I'll look into minted&pygments again. – Roman Feb 25 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 at 13:11

You must log in to answer this question.

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