37

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?

  • 15
    much of this will be opinion based. but a few suggestions: if you intend to submit the book for publication, check the guidelines from the prospective publisher. many authors prepare manuscripts with margins too narrow, and then have to spend too much time re-breaking display math and sizing figures. prepare each figure independently, making sure it is the proper size; don't add it to the main file until it compiles perfectly by itself. put each chapter in a separate file and combine them with \include and \includeonly. start with only the packages you need. read documentation. – barbara beeton Jun 28 '16 at 2:58
  • 2
    Recommend you start you search for advice by exploring the questions with the tag 'book-design'. [book-design] is the tag with 253 questions. Also [books] with 209 questions. Some are very specific, however are also general design in nature. Additionally a search with '[book-design] files' has 74 questions with some in the first couple asking about to manage chapters. – R. Schumacher Jun 28 '16 at 3:49
  • 1
    You may want to look at the externalize tikz library to reduce the typesetting time with included tikz graphics. – Ronny Jun 28 '16 at 5:48
  • 1
    Highly recommended to do all you work in a Dropbox folder (and use revision control). Has saved me MANY times. Also, I'd recommend each section in its own file -- will make it easier to rearrange things should you later decide to do so. So, the chapter file should be just a bunch of includes. Have a look at the standalone package as well. – Peter Grill Jun 28 '16 at 5:49
  • 1
    I'm writing a book in physiology right now. I've chosen the subfilespackage over the \includeonly option (of course, having the chapters of the book in separate files). Then having a directory for every chapter and the main file in the root. This made it possible to work on single files on command line as well as with TeX Shop. – Mats Jun 28 '16 at 20:40
29

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!

  • 4
    Zozor's advice on backup in a following answer is critical. Regularily, (recommend, daily) you keep ALL the files and folders related to the book in a single master folder. Then just copy that folder to several backup locations to a folder on each device with the date of the backup in the folder name. (I usually just copy the master folder to the backup location and then just append the date to the destination with a rename operation) Suggested backup locations 1) On the same machine as you do your work (fix immediate problems) 2) On several other medium for crash recovery. Cloud,Hds,USBs – R. Schumacher Jun 28 '16 at 3:52
  • 18
    Or alternatively, learn to use source control. – Philip Kendall Jun 28 '16 at 7:22
  • 3
    @PhilipKendall source control isn't a replacement for backups (as I'm sure you know). It deals with accidental deletions, but not drive failures. I recommend a cloud-based and an offline, personal backup. – Chris H Jun 28 '16 at 7:56
  • 3
    @ChrisH the point of Philip is (I assume) to use source control pushing to a remote server, e.g. BitBucket. – Andrea Lazzarotto Jun 28 '16 at 10:26
  • 1
    @AndreaLazzarotto Dropbox is not a reliable backup or source control solution! For example it only stores the last 30 days. So if you accidentally delete a chapter, and only work on other chapters for the next 30 days you will have lost the entire chapter! – Roy T. Jun 29 '16 at 12:01
18

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.

  • 4
    I've written a couple of books and all of these are good advice. But I'd extend "Don't forget backups" to "Use a version control system" (such as git), and keep a repository on a different computer. – Jim Hefferon Jun 28 '16 at 15:22
16

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.

  • 3
    +1 and not only for the law of irresistible formatting urges (that would warrant a vote by itself). – egreg Jun 28 '16 at 23:21
  • Late to the party, but this seriously concentrated most of what I try to teach beginners of LaTeX and friends at my work. Hope you don't mind me borrowing (steal is such a bad word) these clear instructions for my next course. :) – Fredrik Johansson Sep 23 '16 at 15:21
  • 1
    @FredrikJohansson All yours. – percusse Sep 23 '16 at 15:25
8

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.

  • The advice to use version control is useful, but your hand-crafted conditional input is not. Use \include in conjunction with \includeonly instead. – Henri Menke Jun 28 '16 at 19:08
  • @HenriMenke, for me it is simpler to change the values of cstart & cend than editing file names in \includeonly. – pantlmn Jun 29 '16 at 6:30
6

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.

  • 1
    +1 For "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."—multi-author books are very different from single author books in the writing process. – jknappen - Reinstate Monica Jun 29 '16 at 16:33
4

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.

3

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.

  • 1
    Also, check from the beginning if you’ll need to use a specific TeX variant. Switching suddenly to LuaLaTeX after you’ve written 500 pages and loaded 200 packages, because you realize that you’ll absolutely need it... this is painful. – user96829 Jun 29 '16 at 7:14
  • Hi, I am just curious because I write my thesis now and I also have it all in ".tex" but maybe I'll need include some R code. I know about knitr and RnW files... should I do something like - write that section in Rnw and then include into main document that .tex documment which it produces? – Jozef Janočko Jun 29 '16 at 8:29
  • Jozef, you cannot do that. Rnw doesn't support it that way. You will need to convert your main tex file into an Rnw and include other Rnws and texs into it. So you can make this one chapter Rnw and the others tex, but the master needs to be Rnw, and when compiling you will have all the text from the Rnw in the one super long master. – rumtscho Jun 29 '16 at 8:43

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.