LaTeX formatting workflow

Note Since this page was created, DP's approach to math has changed. For current information, see the Formatting Math page

Semantic versus Visual Formatting

At DP, LaTeX formatters capture the semantic structure or meaning of the text rather than the visual appearance. For example: Mathematical variables, definitions, and book titles represent different types of information (semantics), yet all are italicized (similar visual appearance). Correct LaTeX code clearly distinguishes each; variables must occur in math mode, definitions are most likely emphasized, and book titles are in raw italics or perhaps a custom "title" environment. Another example: Books are divided into chapters, chapters into sections, and so forth. Instead of formatting section titles as large, centered, small-caps (assuming that's how the project looks), use a macro \section{My pet section}. When the project is "post-processed" for uploading to Project Gutenberg, the macro will be (re-)defined to give the correct visual appearance.

Work Flow Strategies for LaTeX Formatters

When you download a page of a LaTeX project for formatting, you are presented with proofed text in an editor window, just as with a non-LaTeX project. Your tasks are to

• Add the necessary formatting, being sure to handle every instance of "$$" left by the proofings rounds,
• Test-compile the page, checking for both syntax errors and visual problems, and
• Submit your formatted text as "done".

At some stage, you must cut the proofread text from the DP formatting interface, and possibly paste formatted text back into the interface; there's no other way at present to test-compile your formatted text. As a LaTeX formatter, you have an unusually large number of choices for work flow. You may choose to edit in the formatting interface, or using a LaTeX-aware text editor on your machine. You may choose to test-compile on your own machine, or use a web-based LaTeX compiler. There are even multiple strategies for keeping track of the page text you're currently working on.

Do strive to develop comfortable, simple formatting habits. An organized work flow will both streamline your efforts and help you avoid errors.

Editing

The most straightforward practice is to edit the page text in your web browser, using the formatting interface. This method avoids some cutting and pasting, but forces you to work in a relatively "no-frills" editor.

Alternatively, you may prefer to use a text editor on your computer. Some text editors provide color-coded syntax highlighting for LaTeX, which is extremely helpful in catching errors. There are two potential drawbacks. First, the proofed text must be cut from the formatting interface and pasted into your editor, then later pasted back into the formatting interface. If you go this route, be sure not to "lose" any text in the transfer, and avoid submitting preamble code with your formatted text.

Never use a word processor to format text! The formatted text you submit must be latin-1 encoded, with DOS-style line endings. Word processor files contain additional, software-specific control characters.

Please check your first few pages to ensure no "garbage" characters have been introduced due to differences in text encoding. This problem seems rare, but has been experienced by more than one formatter.

Test-Compiling

Every page you format in a LaTeX project must be test-compiled, and the output inspected visually to ensure there are no obvious formatting errors, before the page is saved as "done". A "compile and preview" button for the formatting interface is in the works, but until this is implemented you need LaTeX on your own computer in order to check your formatting.

A Wiki page is devoted to downloading and installing LaTeX. There are online compilers, but they're trickier to use correctly than a complete distribution, and should probably not be relied on until you're fairly experienced.

In order to compile a formatted page, you must place the text into the "body" of a complete LaTeX source file, which looks conceptually like this:

 \documentclass[12pt]{book}
 \usepackage{amsmath,amssymb,amsthm,amsfonts}
 \usepackage[latin1]{inputenc}
 %% Project-specific macros
 
 \begin{document}
 %% Text to be test-compiled
 \end{document}

The "wrapper" code consists of the preamble (everything before \begin{document}) and the body. When you submit a page as "done", only the body text may be submitted, excluding the lines \begin{document} and \end{document}.

As a project progresses through the first formatting round, formatters may notice non-standard semantic structures and ask that project-specific macros be "added to the project preamble". When you first start working on a project, please read through the recent posts in the project forum, check the project comments to see if the project manager has created a preamble, and (if so) use that preamble to compile pages from that project, and update your copy of the preamble as necessary.

Keeping Files Organized

Especially if you're new to LaTeX, the suggestions below should help you avoid unexpected behavior from the software. They're not hard-and-fast rules, but please don't deviate from them heedlessly.

First, create a separate "folder" or "directory" for each project, and keep all preamble code associated with a project in the project folder. This folder should be somewhere in "user space", for example on your desktop or in "My Documents"; do not create project-specific folders in the same location as LaTeX's "program files". On GNU/Linux, if you create project specific folders in your home directory, everything should be fine.

Try to keep preamble code (which doesn't change often) separate from project text (which gets replaced with each new page). Doing so minimizes the possibility of accidentally submitting preamble code when you save pages as "done". LaTeX allows one file to "include" other files, so it's easy to set up separate "wrapper" and "page code" files. For example, create a file named "book_title.tex" containing

 \documentclass[12pt]{book}
 \usepackage{amsmath,amssymb,amsthm,amsfonts}
 \usepackage[latin1]{inputenc}
 
 \begin{document}
 \input{snippet.tex}
 \end{document}

Increasingly, it should be possible to cut the contents of the wrapper file verbatim from the project comments. The file name is unimportant, and may be chosen to remind you of the project name, e.g. "calculus.tex". This is the file you'll compile to check your page code, but its contents will change rarely -- if at all -- during the lifetime of the project.

Second, create an empty file named "snippet.tex". The name must match the \input line in the wrapper file. This file's contents will be replaced completely each time you test-compile a new page. Once you have formatted a page of text from a project, delete the old contents of snippet.tex, paste in the entire formatted text from your new page, and run LaTeX on the wrapper file, book_title.tex.

Many formatters like to keep copies of all pages they've formatted on a specific project so they can format recurring structures consistently. You might create a file named "past_pages.tex" when you start working on a project. Each time you complete and submit a page, cut the contents of "snippet.tex" (so the file is empty) and paste your formatted text at the end of past_pages.tex. It's advisable to keep track of the png numbers, so you know which page of the project corresponds to each page of LaTeX code. A comment line such as

 %%----- 123.png

may be used to separate chunks of LaTeX code in past_pages.tex.

For best results, no matter how you choose to organize your files, work with one "clean" copy of the formatted text -- either in the formatting interface or in your text editor -- and make corrections only in the clean copy. This will help you avoid checking in the wrong copy of your formatted text.

Again, these are just suggestions; there are nearly as many distinct work flows as there are LaTeX formatters. Find habits that work for you, and develop a routine that minimizes the chance of errors.

Work Rate

LaTeX formatting is time-consuming, but crucial to DP's production of books containing mathematics. Experienced formatters who are fluent at LaTeX can expect to format about 4 to 6 pages per hour (10 - 15 minutes per page). If you're working substantially faster than this, please ask for feedback; LaTeX formatting entails an unusually large number of responsibilities, and it's very easy to miss important tasks when you're getting up to speed. Conversely, don't be discouraged if the work is slow going at first; your high-quality LaTeX formatting is both valuable and greatly appreciated!