Español
Português
中文 (中国)
العربية
हिन्दी
Русский
Français
Deutsch
Ελληνικά
Italiano
日本語
한국어
LatineSummary
This lesson opens the first unit of the course, devoted to the first steps with LaTeX. It explains what the unit is for: to bring someone who has never used LaTeX to the point of writing, compiling and correcting a short document unaided; it presents its four lessons and the thread that joins them, from the idea of typesetting to the reading of errors; it states the little that is taken for granted, which is the handling of files and folders on a computer; it formulates the problem the unit solves, that of going from an empty file to a typeset document and, when something fails, from the engine's message to its cause; and it shows that this same cycle serves a laboratory report as well as a philosophy essay or an edition of a Latin text.
Learning objectives
- Describe the sequence of contents of the unit and explain what each lesson contributes to the next.
- Recognize the prior knowledge the unit assumes and prepare the computer for it, in particular the visibility of file extensions.
- Explain, with an example, why a LaTeX document may produce no output and why an error is not always reported where it lies.
- Recognize, in other disciplines and in the following units, the cycle of writing, compiling and correcting that the unit builds.
Entry assessment
Before working through the unit, it is worth measuring the starting point. This assessment is a self-assessment: it is not graded, and its only purpose is to guide your study. Its eight questions cover, two by two and in order, the four lessons of the unit; anyone who has never used LaTeX should not expect to get them right, and that does not matter: every answer, right or wrong, explains the point and names the lesson that deals with it. The same skills are measured again at the end, in the synthesis lesson; since this is the first unit of the course, there are no questions on earlier units.
Before starting the unit, measure your starting point. It is a short self-assessment: it is not graded and its result is stored only in your browser.
Question 1A researcher is writing an article in English that quotes passages in polytonic Greek, and the journal requires an OpenType typeface that she has installed on her computer. Which engine should she compile it with, according to the criterion of this course?
Its speed does not make up for what it cannot do: pdfLaTeX does not load the system's OpenType typefaces directly, and a Greek letter written in Unicode stops its compilation unless special encodings and typefaces are set up.They understand the same LaTeX, but they differ in how they read the text and in which typefaces they can use; fontspec, which loads the system's typeface, requires XeLaTeX or LuaLaTeX.Texmaker is the editor, not an engine: it is where the source is written, and it calls the engine supplied by the installed distribution. The question is which of those engines it should call.LuaLaTeX writes Greek directly, with its accents and breathings, and loads the required typeface with\setmainfont. XeLaTeX would also do; the course adopts LuaLaTeX so that all its documents are compiled in the same way.Review: What LaTeX is
Question 2What does the line
The pass rate was 70% of the students.print when written as it stands in the body of a document?The percent sign is one of the characters that LaTeX reserves: written as it stands, it is not printed but does something.A comment is not an error; that is what makes this slip dangerous: the engine discards half a sentence without reporting anything, and the loss is noticed only on reading the output.The comment is not limited to the sign: it covers everything that follows up to the end of the line.The percent sign starts a comment: the engine ignores everything that follows up to the end of the line, the line break included, and gives no warning. To print the sign, write\%.Review: What LaTeX is
Question 3The folder of a thesis contains
thesis.tex,thesis.aux,thesis.log,thesis.toc,thesis.pdfandmap.png, a figure that the thesis includes. A co-author will compile the thesis on their own computer. What is the minimum they must receive?The auxiliary files are regenerated when compiling, and they are of no use to the co-author; someone else's.auxmay even carry outdated references through to the next compilation.The figure is not produced by compilation but used by it: withoutmap.png, the engine stops because it cannot find the file.The table of contents is obtained with a second compilation, and the figure, which is indispensable, has been left out.They need exactly what the engine cannot produce: what the author wrote or supplied. The other files are regenerated by compilation.Review: The working environment
Question 4A student corrects the source and compiles, but the PDF shown in the viewer does not change. The log ends with the line
Fatal error occurred, no output PDF file produced!. Which PDF is the student looking at?That happens when the log ends without errors and the PDF in the folder bears the time of the last compilation; here the log says that no PDF was produced.If it were damaged, the viewer would show nothing; it shows a complete, readable document, only an old one.That would be another possible failure, but the log rules it out: it says that no PDF was produced, so there is no new PDF.A fatal error stopped the compilation before the output was written; the PDF in the folder is the last one produced successfully, and the viewer shows it as if nothing had happened. The error that the log reports must be corrected.Review: The working environment
Question 5In the body of a document, after several paragraphs, the author writes
\usepackage{amsmath}. What happens when compiling?Some declarations behave that way, such as\setmainfont, which work in the body from the point where they are written; packages do not.The engine does not reorder the source: it reads it in order, and what it finds out of place it reports as an error.It is true that it typesets no text, but that only allows it to be placed before the body; it does not entitle it to go inside it.On reaching\begin{document}the configuration is closed, and a package loaded afterwards could change decisions already applied; that is why packages are loaded only in the preamble.Review: Anatomy of a document
Question 6In the body of a document there appears, written as it stands, the sentence
Save the file as final_report.tex.What happens when compiling?The underscore is one of the ten reserved characters: written as it stands, it is not printed.That is what the percent sign does, since it starts a comment; the underscore has another function, that of subscripts.The engine attempts something similar, but only after reporting the error, when it inserts on its own the dollar sign it believes to be missing; the result is not the one intended.The underscore writes subscripts inside formulas; in text, the engine assumes that a formula has not been opened and reports it. To print it, write\_.Review: Anatomy of a document
Question 7The log of a compilation contains the error
! Undefined control sequence.and, below it, the linel.7 \sectoin. What does it indicate?An undefined command may be due to a package that was not loaded; but\sectionneeds none, and the command the log shows betrays a typo in its name.The indicationl.7refers to the source, which is what gets corrected; the log only reports.The number is that of a line of the source, not that of a section of the document.The error names the failure, an undefined command; the indicationl.7gives the line number in the source, and the text after it ends exactly at the unknown command.Review: Compiling and fixing errors
Question 8Compilation produces the PDF, but the log contains the line
Overfull \hbox (3.21451pt too wide) in paragraph at lines 20--24. What does it mean?Errors begin with an exclamation mark; this line is a warning about the typesetting, and the PDF is valid.The numbers are lines of the source, not pages of the PDF, and what sticks out is a line of text, not a page.The length of the paragraph does not matter: the problem is a single line that could not be broken well, and it is solved within that line.The engine found no acceptable way to break some line of that paragraph, for instance because of a long word it cannot hyphenate, and left it wider than the text block. The PDF was produced; it is worth looking at that paragraph in it and deciding whether action is needed.Review: Compiling and fixing errors
The contents of the unit
This unit serves the first of the course objectives, producing and compiling documents while diagnosing and correcting their errors, and it is the precondition of all the others: typesetting texts in several languages and scripts, structuring long documents, writing mathematics and logic, presenting tables and figures, managing the bibliography and choosing the class suited to each academic genre all presuppose that the cycle of writing, compiling and correcting no longer poses any difficulty. Its goal is that someone who has never used LaTeX can, on finishing it, write a short document from an empty file, compile it with LuaLaTeX in Texmaker or on Overleaf and, when it does not compile, find and correct the cause unaided. Its four lessons form a chain in which each rests on the ones before.
- What LaTeX is. It explains typesetting, compares the markup language with the word processor, tells the origin of TeX and LaTeX and their principle of separating content from form, justifies the choice of LuaLaTeX and shows how a source becomes a PDF. It fixes the vocabulary of the whole unit: source, engine, compilation, preamble, body and log.
- The working environment. It installs what the first lesson described: a TeX distribution, with its package manager, and the Texmaker editor, configured to compile with LuaLaTeX and to save in UTF-8; it presents Overleaf as an alternative in the browser, and explains which files compilation leaves behind and which are kept. It ends with two test documents that verify the installation.
- Anatomy of a document. It breaks the source down into its pieces: the preamble and the body, commands with their arguments, the groups that limit the scope of declarations, environments, the ten reserved characters, comments, packages and the class. With it, the minimal document of the first lesson ceases to be a recipe and becomes a structure understood piece by piece.
- Compiling and correcting errors. It teaches how to read the log: to distinguish errors from warnings, to locate each error in the source, to recognize the most frequent messages and to isolate the cause when the message is not enough. It brings together what came before, because almost every error is the breach of a rule of the anatomy of the source, and its diagnosis relies on the working environment.
The unit ends with the lesson of synthesis and challenges, which gathers what has been achieved into a chain of concepts and procedures, repeats in its exit assessment the skills of the entry assessment and proposes challenges that combine several lessons.
What is taken for granted
The unit starts from almost nothing. It does not assume that you have used LaTeX, nor that you can program, nor any knowledge of mathematics; and although the engine's messages are terse and technical, the course explains each of the ones it presents. It assumes only the ordinary handling of a computer: creating a folder, saving a file under a given name and in a given folder, finding it afterwards, copying, moving and deleting files, and installing a program, or else having a browser and an Overleaf account.
From this follows a single preliminary preparation, best done before the lesson on the working environment. A file name consists of a base and an extension, the part after the last dot: in report.tex, the base is report and the extension is tex. Now, File Explorer in Windows and the Finder in macOS hide known extensions by default, so that report.tex and report.pdf both appear as report, and the auxiliary files of compilation, which differ only in their extension, become indistinguishable. Therefore it is advisable to turn on the option that shows extensions: in Windows, in the View menu of File Explorer; in macOS, in the advanced settings of the Finder. On Linux, file managers show them by default.
The problem the unit solves
Someone writing in a word processor sees the result while writing. In LaTeX, between the source and the page there is a program that reads the source to the letter, and the result appears only on compiling. This raises two problems, which are those of the unit. The first is how to go from an empty file to a typeset document: what must be installed, what the source must contain at the very least and what the engine does with it. The second is what to do when the document does not come out, or comes out differently from what was intended: the engine does not show the error on the page but describes it in the log, in a language of its own, and sometimes reports it far from the place where it was made. The following example shows both problems in a fifteen-line document.
The following source is a complete document: it declares the class, loads the packages, stores the title, the author and an empty date, and typesets two sections. Compiled with LuaLaTeX, it produces this result.
\documentclass{article}\usepackage{fontspec}\usepackage[english]{babel}\title{Reading Report}\author{Alex Morgan}\date{}\begin{document}\maketitle\section{The Question}The text examines a \emph{hypothesis} about 40\% of the cases.\section{The Answer}The answer relies on the previous section.\end{document}
If, on the eleventh line, the brace that closes the argument of \emph is left out, the engine produces no PDF, and the log contains, among others, these lines.
Runaway argument?{hypothesis about 40\% of the cases. \par \section {The Answer} The a\ETC.! File ended while scanning use of \emph ....! ==> Fatal error occurred, no output PDF file produced!The error is not reported on the eleventh line but at the end of the file: the engine went on reading the argument of \emph through the paragraph, the following section and \end{document}, until the file ran out. Now, the log gives the missing clue: the line after “Runaway argument?” reproduces the runaway argument from its beginning, and that beginning, the brace before “hypothesis”, is exactly the place of the error. Reading the log in this way is what the lesson on compiling and correcting errors teaches; understanding why an unclosed brace drags along everything that follows is what the lesson on the anatomy of a document teaches.
The unit's answer to these two problems therefore has two parts. For the first, an environment installed and tested, and a source whose structure is understood piece by piece, so that nothing in it is a magic formula. For the second, a method: read the log from the first error, locate the error in the source, recognize the rule that was broken and, if the message is not enough, isolate the cause by disabling parts of the source. Neither part requires memorizing commands; both require reading the source as the engine reads it.
The unit across the disciplines
The cycle the unit teaches is the same in every discipline, and what changes from one to another is only what is written. A chemistry laboratory report, a philosophy essay with a hundred footnotes, a commentary on a passage of Cicero with the Latin text and its translation, an economics paper with tables, a history thesis with archival documents and a mathematics article with theorems all begin in the same way: a folder, a source file with its preamble and its body, a compilation and the reading of its log. Likewise, the errors of this unit, an unclosed brace, a reserved character written as it stands, a package loaded out of place, turn up in any of those documents, whatever the discipline.
For this reason, what the unit teaches is used in the other courses of the site. Assignments and notes for Aristotelian Logic or for Foundations of Mechanics can be written in LaTeX from the first week; in Data Analysis with R, the results of an analysis are incorporated into a typeset document; and in Programming in C++ I the cycle is essentially the same: a source is written, a compiler reads it, and its messages, which refer to line numbers, are read with the method this unit teaches.
Where it leads
On finishing the unit, the minimal document will be a familiar starting point, and the following units will build on it. The second will deal with the text itself: languages and scripts, among them Greek and Latin, typefaces, footnotes and long quotations. The third, with the structure of long documents, with their chapters, their table of contents and their cross-references, spread over several files. The fourth, with writing mathematics and logic in their correct notation; the fifth, with tables and figures; the sixth, with the bibliography and the citation conventions of each discipline; and the seventh, with the document classes suited to each academic genre, from presentations to letters and posters. In all of them, each new command will be written, compiled and, when it fails, corrected with what was learned in this one.
Completed
Sign in to save your progress