What to decide before writing a math book?

Question

Until now, I have only written short documents in LaTeX. Whenever I encounter a problem or an error, I google'd it, and copy-paste'd the package/newcommand to my code.

I use the same beginning code for all my documents which contains many many many packages, newcommands etc. However, this time I have to be careful because I might have to read the whole code just because of a tiny error.

Of course, I don't have to decide the paper size, margins etc. of the book now (do I?). However, there can be several things to pay attention. For instance:

• Should I use only one .tex file, or write the chapters in distinct .tex files, then merge them when everything is finished?
• Is having many packages a bad idea? Do I have to decide which packages to use now?
• Will shortening everything cause a problem? For example, using \bp and \ep instead of \begin{proof} and \end{proof}. Or using \suminfty for \sum_{n=0}^\infty.
• Should I include tikz graphs etc. when the book is finished? Because I have a feeling that after some point with many tikz pictures, compiling the code will last quite long.

So, basically, I don't want to spend much time on where and why the error occured or go back and change everything. What else should I be careful about?

Answer 1

Here is my advice (I loved your question so much I needed to propose an answer). Some people may work differently though.

I use the same beginning code for all my documents which contains many many many packages, newcommands etc.

Everyone does something like this, but it results in a huge accumulation of packages over time, with 80% of them likely to stay unused. There might be interferences and compilation will be slower. I suggest to comment every \usepackageline to make clear what the package is used for, and see if you really need it in that specific document. For instance:

\usepackage{booktabs} % Makes beautiful book-like tables

Then, if you write a document without a single table, you’ll know you can safely ignore this specific package.

Should I use only one .tex file, or write the chapters in distinct .tex files, then merge them when everything is finished?

This likely depends on the length of your document. Some people manage 40 .texfiles just fine, some prefer to deal with just one. If you plan to write 5000 pages, you might prefer to use distinct files. And there is no need to merge them by hand, you can use \include in a main.tex file.

Is having many packages a bad idea? Do I have to decide which packages to use now?

Again, it is not that bad if they are useful and carefully chosen. You should avoid using different packages that do the same thing, and pay attention to the order of packages. Loading some packages too early or too late may cause interferences with other packages. To begin, just add the usual suspects (amsmath, babel, geometry) and wait and see if you need more later.

Will shortening everything cause a problem?

Clear commands are better ;-) Longer to type, but this will save time when you try to modify your document 6 months later.

Should I include tikz graphs etc. when the book is finished? Because I have a feeling that after some point with many tikz pictures, compiling the code will last quite long.

I do include pictures as soon as I can, I find it "motivating" to have a preview of what my document will look like. It does slow down compilation though, your point is valid.

What else should I be careful about?

Always backup your document! One mistake and you could lose your whole book. Also, pay attention to fonts. Fonts have been my number one TeX problem over the past few years. Sometimes the font won’t include one character you need, sometimes it won’t have the adequate bold type that you need, sometimes it will look bad for no reason. I have learned to stay away from anything which is not a very widely used, tried and tested, strong, common font.

Good luck!

Answer 2

Here's my advice ...

The first decision is:

Who shall the publisher be?

Commercial math publishers have a set of standardised book formats (paper size, basic layout, some additional conventions). When you go with such a publisher, use their LaTeX macro packages if possible. When you don't have one, start with the standard book class.

Split your input in chapters

This will not only speed up processing (using devices like \includeonly for label consistency) but also reduces the time to find the right place to continue writing and editing.

Don't be afraid of many packages

Use all the packages that do some good for you, unless you run into a package conflict.

Don't abbreviate

It is harmful to abbreviate things like \begin{proof} or \end{proof}. Don't do it.

Write some sensible macros

When you have some logical structures that aren't predefined in LaTeX or the packages you already include, write some macros for them. Follow the idea of logical markup, don't think in terms of abbreviation.

Include graphics early

Include your graphics and everything complicated (like commutative diagrams, tree drawings, etc.) as early as possible. This will tell you whether there are difficulties, package conflicts, TeX capacity exceeded errors, and allows you to think about remedies for them.

Compile your document often

This helps you catching errors early. Probably they are just in the segment you worked on recently.

Write a makefile or a shell script to create your whole book

Including the runs of other programs (like BibTeX or makeindex)

Don't forget backups

When I wrote my book, I did daily rotating backups on external media. Use a script for the backup. Check that your backup really works (by unpacking a backup and compiling your book)

Be afraid of TeX updates

Unfortunately, an update of your TeX distribution may break your document in unexpected ways. When you update your TeX distribution, be prepared to roll it back, in case something bad happens.

Answer 3

I'll try to extrapolate some issues that I(we) have witnessed here over the years as tendencies.

• Should I use only one .tex file, or write the chapters in distinct .tex files, then merge them when everything is finished?

  This is covered extensively in When should I use \input vs. \include?. That's pretty much is almost all you have to know.

  The main habit you have to, probably, gain is that you turn on and off the chapters/sections that you are not writing, in a productive way. For short term fast compilations keep not so many pages with little number of graphics.

  Avoid compiling the whole book all the time. What you will have is seeing lots of warnings and bad/over-/under-full boxes getting curious and procrastinating like crazy. Depending on the publishers' demand don't waste time on those things. You will have to replace them at least thrice - once for the hipster effect, once for regret and once for the final state (according to my law of irresistible formatting urges (patent pending) ).

• Is having many packages a bad idea? Do I have to decide which packages to use now?

  No and no. But don't try to find a package for everything. Ask here or in the chat. Most of the people who are trying to write a book suffers from a lot of similar things and package authors also see those problems. Hence modern packages offer lots and lots of flexible options. Hence that sentence is ill-formulated. A bit more proper one is In case two equivalent solutions for a feature, choose the one that exists in the already-loaded package.

• Will shortening everything cause a problem?

  Yes!! Any time that you have trimmed off from those abbreviations will be lost in the first problem you will encounter. You will have to triangulate the problem (because it will refuse to be found) so you replace with the expanded version etc. And it will be pointless. Roll up your sleeves and use auto-completion capable editors.

• Should I include tikz graphs etc. when the book is finished? Because I have a feeling that after some point with many tikz pictures, compiling the code will last quite long.

  This is a corollary of the first one but also make short but graphics intensive documents and learn to use TikZ' externalize library.

• What else should I be careful about?

  For example stop doing the following:

  • Until now, I have only written short documents in LaTeX. Whenever I encounter a problem or an error, I google'd it, and copy-paste'd the package/newcommand to my code.

  This will not only bloat your preamble but also will cause hair loss. Try to at least categorize your preamble and roughly know what is doing what. A trade mark behavior of this type of usage is loading the package multiple times when copy/pasting gets out of control. And defs overwrite the existing things and for short abbreviations to some obscure thing such as your suminfty people break a package while trying to be so-called efficient. I don't know what that word means.

  • Decide beforehand whether you would need a glossary/index and don't start writing until you decide.

  • My personal favor to ask is, please don't use obscure greek letters for notation, if possible stick to latin alphabet. Don't go crazy with \Xi,\varsigma,\wp because your readers will go like this: Let ...that thing... be defined as ....v looking thing.... times .... is that a mathcal P? .... anyways what was it, that thing is equal to and so on.

---

In general, TeX usage is pretty much like being a guest at somebody else's house. There are zillions of stuff that you have absolutely no idea what they are about. So don't fiddle too much. Just enjoy your stay and get out as soon as possible.

Answer 4

In addition to what is said, some small pieces of advice:

Use a version control system

Even if you work alone and all your history of editing is linear, you get this way a well-documented history of your work.

Compile often, commit often, backup often.

If you want to get some other person involved (e.g. a corrector), a version control system is a must.

I personally use git and bitbucket.org.

It is much better, than having a set of copies or zip files.

Include an option to compile it in parts

Like [draft] option, skipping images, you can introduce something similar to your book.

My code is like this:

\newcounter{sc}\setcounter{sc}{-1}
\newcounter{cstart}\setcounter{cstart}{1}
\newcounter{cend}\setcounter{cend}{100}
\newcommand{\skipCandidate}[1]{%
\stepcounter{sc}%
\ifboolexpr{%
(
    test {\ifnumcomp{\value{sc} + 1}{>}{\value{cstart}}}
    and
    test {\ifnumcomp{\value{sc}}{<}{\value{cend} + 1}}
)
}{#1}%

...

\skipCandidate{
\input{chapter}
}    

This will save you a lot of time, when you will need to recompile one (or several consecutive) chapter(s) many times.

Answer 5

I learned many good ideas about writing a mathematics book in LaTeX from the code found in the Stacks Project: http://stacks.math.columbia.edu/contribute. This is a huge and extremely complicated book, currently over 5000 pages, with 230 authors. If you have more than one author, avoid using all but the simplest code, and define few macros, because different authors won't remember them. Use few packages. Split into different files for different chapters. Develop your index as you write the book, including index entries for every new term you define, but also read the book many times and add in index entries as you can see they are needed. Read your book many times, and teach from it as often as possible. Every page of my lecture notes changes every time I lecture. For a large book, the index is much more valuable than the chapter or section headings. Make an index of notation. Keep all images, graphs and figures as small as you can (while making them readable), and keep them in black and white or muted colours to avoid having them stand out too much. When the reader turns a page, a distracting coloured image will draw her eye away from the text; it takes effort to return to the flow of the text. So big and bold graphics are only really suited to appear in books that people don't read (coffee table books). Don't use floats (floating figures and tables) or margin figures. Instead put smaller images and "tabulars" directly into the flow of the text, so that the reader knows when to look at them while reading the text. If there is a picture that you would draw on the board if you were lecturing, it is your moral duty to draw it in your book (even if that requires an afternoon spent coding in tikz or asymptote). Explain every topic numerically, graphically, algebraically and in plain English if possible (following James Stewart's advice). You can see some of my lecture notes at http://euclid.ucc.ie/pages/staff/Mckay/ to see how I try to live up to these suggestions.

Answer 6

A note about this:

Should I include tikz graphs etc. when the book is finished? Because I have a feeling that after some point with many tikz pictures, compiling the code will last quite long.

I strongly suggest you write your tikz graphs and diagrams in separate files and includegraphcs them. In fact, I would go one step further and generate the tikz code in a better language like Python. This gives you all the flexibility of programmatic generation with none of the warts of trying to program in latex. Also it mitigates the code compilation time problem.

Answer 7

Think of whether you will be writing straight TeX only or if you will have to include another step before it. This is an edge case, but when it happens, it is important.

For me, I realized that I should start to use knitr in the middle of my thesis. For knitr, you mix up LaTeX and R and then run it through a specific R compiler which outputs pure LaTeX, only after that can you compile the LaTeX. Changing the workflow was complex, and I had to redo some very time intensive work to be compatible.

Consider whether you only need to typeset stuff which you will be writing by hand. If yes, that's great, you can proceed happily. But if you want to include something else - in my case it was R code and its results, for you it can be different - see what way there is to do it automatically. It might turn out that there is an automated workflow, but not a TeX first one, in which case you should employ the available one as early as possible.