38

Why is it recommended to split a large document into several parts and include them with \include? Is it only a relic of the past times when computers and LaTeX compilers were slower, or is it still up-to-date? What are the pros and cons of this practice, also in terms of interaction with other external tools (version control, find/replace, et cetera)?

Motivation: I've found a recent discussion that mentions this practice ( Writing and Managing Thesis in LaTeX, Everyday LaTeX and workflow?), as well as a comment that criticizes it in an answer to Everyday LaTeX and workflow?. A couple of months ago, I asked the same question in a comment to Techniques and packages to keep up with good practices, but it's probably better to ask this here again as a "real question".

2
  • 2
    You can find your comments under the 'activity' tab on your user page
    – cmhughes
    Sep 26, 2011 at 19:11
  • @cmhughes: thanks for the tip! I have now found my old comment and edited the question accordingly. Sep 26, 2011 at 22:04

3 Answers 3

20

Splitting a large document into parts is A Good Thing; with today's front-ends or editors it's quite easy to jump from one part to the other.

The choice between \include and \input is very subjective. \include was born when computers were slow and typesetting a complete book could be a good occasion for having a coffee, maybe two. It has its uses now also, because it can solve cross references even when the chapter is not \included. (See also CountZero's answer for another use.)

Personally I don't mind if some references are not solved during trial typesetting sessions, when I'm more interested in the overall shape than in precise line and page breaks. It's easy to comment out some lines in a well-structured main file, but the same can be said about strings passed to \includeonly; however using \input and commenting doesn't require to duplicate the list of files. Not a big deal, of course, but when the chapters are many, it might be a nuisance; on the other hand, writing and reading from .aux files adds a little overhead.

With a modern computer, the times needed to typeset a chapter or an entire book are not very different, unless the book is very large, or it has many graphics using TikZ or PSTricks that slow down the process. In these cases, using \include can save your time.

4
  • Another example for some time-consuming parts of a document are source code listings processed via the listings package. I personally use \include because I tend to work in small, quick typeset cycles. I also like to be certain that every reference works, these ?? reference make me nervous. Unfortunately, the todo package doesn't list all items in a partially typeset document, but that's not that big of a problem for me.
    – 0x6d64
    Sep 26, 2011 at 19:05
  • 8
    You say that it is a good thing, but you do not give reasons why it is so. I am interested in knowing the motivations here; could you argue a bit more? Actually, your last paragraph here seems to support the opposite view --- just keep everything together and avoid the hassle. Sep 26, 2011 at 21:59
  • Splitting the source makes easier to have all the files open at once, for example. It also helps when recovering a corrupted file from a backup.
    – egreg
    Sep 26, 2011 at 22:50
  • 1
    My phd thesis takes about 5 minutes to compile on a modern 4 core PC. The time consumption comes mostly from the figures (about 200 images). So no matter how fast a computer is nowadays, I recommend usage of \include in any case. Sep 27, 2011 at 8:27
11

For one thing you can significantly speed up compilation time by including only certain files, e.g. when you have tons of graphics.

Another advantage is that you can manage more easily documents on which several people work simultaneously.

And finally it gives added reusability of the given parts (e.g. you want to publish the handouts of your collection of laboratory experiments, but you also want to be able to print one at a time and/or give the description of one experimets to your students).

So I guess it really depends on what you have in mind.

4
  • I thought externalizing was the way to go when you have heavy graphics, so I am not totally convinced by #1. Could you be a bit more specific on #2? Are you assuming the group uses revision control or not? Regarding #3, it seems an uncommon use case to me. In most cases, you want to do small modifications to those files (e.g., changing all "in this book..." to "in this handout..."). Sep 26, 2011 at 21:55
  • #1: externalization is certainly an important option. I personally put most of my graphics (I use TikZ) into separate files. Then I can compile a larger document without the graphics much faster. This is the way I do it if the figures are not the part I am currently working on. The method also allows me to reuse the figures.
    – Count Zero
    Sep 26, 2011 at 23:16
  • #2: I have never had the opportunity to use LaTeX in that context.:) But consider journals an example. #3: This is an actual use case of mine: I have a lab class material at the university consisting of handouts for each session. Not all are necessary during a term, but we need to have them in one place, printed as a single book.
    – Count Zero
    Sep 26, 2011 at 23:27
  • 1
    #1 is irrelevant if you have a good editor (emacs has C-c C-r, compile-region). #2 is irrelevant when using a decent VCS. #3 is the only one that might convince me.
    – mbork
    Nov 16, 2012 at 19:46
8

As apostill to the other answers, for me an important reason to still split long documents is not always gain time in compilation previews or reusability (although often these are enough reasons) or sharing with other authors, but the easy of edition. Edit a short text with only a chapter or section or even a minor chuck o LaTeX code have some advantages:

  1. You can focus in the content of this section. Otherwise, before or after you will end will distracted with something else after/before the target.

  2. Tasks as find some sentence is just easier in a short text. If the editor can show some type of outline is a minor problem, but find some piece of text searching a keyword could be annoying because in a large document is also found elsewhere, outside of the target section.

  3. Limit the scope of mistakes. Especially if you are not using a version control systems, this avoid than you can damage accidentally all your work while editing only a small part. A simple wrong search & replace in the whole document can ruin your project for days.

  4. Debugging. Sometimes the compilation error is cryptic but you have no idea of what is causing it and where it could be. Working with subdocuments help to locate the problem.

  5. Reorder contents. Not often useful for chapter of a thesis, for example, but in other contexts you could be unsure of the final right order of the subdocuments, and move an \input{} some lines is much easier and safer that move large blocks of texts. Again, this depend on the editor features. For example, with LyX this is not a problem at all, as you can do that simply re-arranging the sections in the panel of the table of contents.

3
  • 1
    Note that there's another side of the coin with #2 and #3: sometimes you do want to run a search/replace in the whole document, and this is more cumbersome if the document is split into several files. Mar 7, 2019 at 22:35
  • Well, for this case you can use rpl.
    – Fran
    Mar 7, 2019 at 22:42
  • 1
    Sure, there are various tools; I didn't write impossible, just more cumbersome. Mar 7, 2019 at 23:39

You must log in to answer this question.

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