Différences

Ci-dessous, les différences entre deux révisions de la page.

--- 1_generalites:erreurs_de_debutant [2023/07/18 08:14] – Ajouts, avec exemples. jejust
+++ 1_generalites:erreurs_de_debutant [2023/07/18 21:01] (Version actuelle) – Suite et fin de l'article en anglais. jejust
@@ Ligne 16: / Ligne 16: @@
   * In the author’s years as part of the TeXnical support team for a major math publisher, responsibilities included fielding questions from authors and writing user documentation.
-  * The online TeX forum at StackExchange1 has provided a surfeit of questions both basic and advanced. A community effort has collected a list of “Often referenced questions”, by topic, at [[https://tex.meta.stackexchange.com/q/2419|tex.meta.stackexchange.com/q/2419]].
+  * The online [[https://tex.stackexchange.com/|TeX forum at StackExchange]] has provided a surfeit of questions both basic and advanced. A community effort has collected a list of “Often referenced questions”, by topic, at [[https://tex.meta.stackexchange.com/q/2419|tex.meta.stackexchange.com/q/2419]].
 <note tip>
@@ Ligne 145: / Ligne 145: @@
 </WRAP>
 <WRAP column 25ex>
-<latex>
+<latexdoc>
+\documentclass{article}
+% With T1 enabled, \"\i yields accented i, not bad sqrt.
+% See https://tug.org/TUGboat/tb45-1/tb139beet.pdf
+% %\usepackage[T1]{fontenc}
+  \pagestyle{empty}
+\begin{document}
 \renewcommand{\i}{\ensuremath{\sqrt{-1}}}
 Brezis, Ha\"{\i}m
-</latex>
+\end{document}
+</latexdoc>
 </WRAP>
 <WRAP clear />
@@ Ligne 164: / Ligne 171: @@
 </code>
 The environment name must match at beginning and end;
-if it doesn’t, this error is reported in the log file and on the terminal:
+if it doesn’t, this error is reported in the log file and on the terminal:\\
-<code>
+''! LaTeX Error: \begin{//xxx//} on input line //nn// ended by \end{//yyy//}''\\
-! LaTeX Error: \begin{xxx} on input line nn
-ended by \end{yyy}
-</code>
 Most environments can be nested, but the proper sequence
 must be maintained.
@@ Ligne 301: / Ligne 305: @@
 and it will restore the wider end-of-sentence space.
-All this boils down to a simple rule: Except
+All this boils down to a simple rule: Except at the end of a sentence
-at the end of a sentence (and to a lesser extent
+(and to a lesser extent after other punctuation symbols or within math),
-after other punctuation symbols or within math),
+all spaces within the same line should be the same width.
-all spaces within the same line should be the same
+If they’re not, something is fishy.
-width. If they’re not, something is fishy.
 === Spurious spaces ===
@@ Ligne 336: / Ligne 339: @@
 with extra spaces inserted by our ''\abc'' command.
 The offending spaces can be evicted by inserting ''%''
-where it will “hide” an EOL:
+where it will “hide” an end-of-line:
 <WRAP column 48ex>
 <code latex>
@@ Ligne 358: / Ligne 361: @@
 to produce the desirable <latex>word \emph{abc def} word</latex>.
 The ''%'' character starts a comment, //i.e.//, ignores the rest
-of the input line, including the EOL.
+of the input line, including the end-of-line.
 Another source of extra spaces in the output can be caused by the presence
@@ Ligne 524: / Ligne 527: @@
 === Paragraph endings and vertical mode ===
-The end of a paragraph is a transition from horizontal
+The end of a paragraph is a transition from horizontal to vertical mode.
-to vertical mode. A blank line or \par will accom-
+A blank line or ''\par'' will accomplish this transition. It’s important
-plish this transition. It’s important to be aware of
+to be aware of what mode you’re in, since some operations are best performed
-what mode you’re in, since some operations are best
+in vertical mode; the most important is the insertion of floats
-performed in vertical mode; the most important is
+(figures, tables, algorithms).
-the insertion of floats (figures, tables, algorithms)
-Another important consideration is that some
+Another important consideration is that some features of text are
-features of text are not “frozen” until a paragraph is
+not “frozen” until a paragraph is ended. One important feature is
-ended. One important feature is the vertical spacing
+the vertical spacing of baselines, which depends on the font size.
-of baselines, which depends on the font size. Too
+Too many newbies try to end a paragraph with a double backslash,
-many newbies try to end a paragraph with a double
+resulting in horrors like the following.
-backslash, resulting in horrors like the following.
 <WRAP column 48ex>
@@ Ligne 559: / Ligne 560: @@
 <WRAP clear />
-Some environments (but not //all//) are defined with a
+Some environments (but not //all//) are defined with a paragraph break
-paragraph break at the end. A problem such as the
+at the end. A problem such as the one shown here won’t result
-one shown here won’t result in an error or warning
+in an error or warning message, so adding a proper paragraph break
-message, so adding a proper paragraph break is the
+is the proper correction.
-proper correction.
-The vertical space between paragraphs is determined
+The vertical space between paragraphs is determined by the value
-by the value of ''\parskip''; this is set in the document class,
+of ''\parskip''; this is set in the document class, but can be reset
-but can be reset as needed. But often,
+as needed. But often, it’s convenient to add occasional extra space
-it’s convenient to add occasional extra space between
+between paragraphs explicitly; this is done with ''\vspace'' or
-paragraphs explicitly; this is done with ''\vspace'' or
+''\vskip'' while in vertical mode (that is, after the blank line
-''\vskip'' while in vertical mode (that is, after the
+or ''\par'' that ends a paragraph).
-blank line or ''\par'' that ends a paragraph).
@@ Ligne 617: / Ligne 616: @@
 ==== Font changes ====
+Font changes are a time-honored method of communicating shades
+of meaning or pointing out distinct or particularly important concepts.
+Many such instances are built into document classes and packages;
+for example, theorems are set in an italic font, section headings in bold, and some journals set figure captions in sans serif to distinguish them
+from the main text.
+LaTeX provides two distinct methods for making font changes.
+Commands of one class take an argument and limit the persistence
+of the change to the content of that argument; these have the form
+of ''\textbf{...}'' for bold, ''\textit{...}'' for italic,
+etc. The other class sets the font style so that it will not change
+until another explicit change is made, or it is limited by the scope
+of an environment; some examples are ''{\itshape...}'', ''{\bfseries...}'',
+and ''{\sffamily...}''. These commands are best looked up
+in a good user guide.
+Several font-changing commands do different things depending
+on the context. ''\emph{...}'' will switch to italic
+if the current text is upright, or to upright if the current text
+is italic. Within math, ''\text{...}'' will set a text string
+in the same style as the surrounding text; thus, within a theorem,
+''\text{...}'' will be set in italic. If this string should always
+be upright, like function words, ''\textup{...}'' should be used instead.
+Basic TeX defined two-letter names for most font styles.
+All of these are of the persistent type. They should be avoided
+with LaTeX, as some of the LaTeX forms provide improvements,
+such as a smoother transition between italic and upright type.
 ==== Math ====
+Math is always a scoped environment. If started, it must be ended
+explicitly and unambiguously. Within text, math begins and ends with ''$''. LaTeX also provides ''\(...\)'' for in-text math, but most users stick
+with the ''$''. Many different display environments are defined
+by the packages [[ctanpkg>amsmath]] and [[ctanpkg>mathtools]],
+and it is worthwhile to learn them by reading the user guides.
+Within math, all input spaces are meaningless to (La)TeX;
+they can be entered in the source file as useful to make it readable
+to a human. Blank lines, however, are considered errors.
+In both in-text math and displays, the error message will be\\
+''! Missing $ inserted.''\\
+This will also result if in-text math is not ended before the paragraph ends,
+or if a math-only symbol or command is found outside of math mode.
+If a blank line occurs in a multi-line display environment from [[ctanpkg>amsmath]], the first error message will be\\
+''! Paragraph ended before //⟨env-name⟩//''\\
+''was complete.''\\
+''<to be read again>''\\
+This will be followed by many more error messages, all caused by the first.
+These will be confusing and misleading. Always fix the problem identified
+by the first error and ignore the rest; they will disappear once
+the first error is fixed; here, by removing the blank line.
+If the appearance of a blank line is wanted for readability,
+instead use a line with just a ''%''.
+As with all environments, the ''\end'' name must exactly match
+the name specified at ''\begin''. A “shorthand” for a single-line,
+unnumbered display is ''\[...\]''. The environments designed
+for multi-line displays should not be used for a single-line display.
+Although LaTeX provided ''eqnarray'' as a display environment,
+don’t use it. If the display is numbered and the equation is long,
+the equation can be overprinted by the equation number
 ==== Tables, figures, and other floats ====
+The allowed number of floats, their positions on a page,
+and the spacing around and between them is defined
+by the document class. So if something doesn’t work
+as you expect (hope for?), any potential helper will insist
+on learning what document class is being used.
+Input for a float must appear in the source file while there is
+still enough space on the output page to fit it in.
+In particular, on two-column pages, a ''figure*'' or ''table*''
+must occur in the source before anything else is set on the page.
+LaTeX’s core float handling does not allow full-width floats to be placed
+anywhere but at the top of a page; some packages extend this capability,
+but those won’t be discussed here.
+Here are the defaults for the basic article class:
+  * Total number of floats allowed on a page with text: 3.
+  * Number of floats allowed at top of page: 2. Percentage of page allowed for top-of-page floats: 70%.
+  * Number of floats allowed at bottom of page: 1. Percentage of page allowed for bottom-of-page floats: 30%.
+  * Minimum height of page required for text: 20%.
+  * Minimum height of float requiring a page by itself: 50%.
+The reference height is \textheight. That is, the height of page headers and footers is excluded.
+If an insertion is small, must be placed precisely and fits in that location,
+don’t use a float. ''\includegraphics'' or one of several available table
+structures should be used directly, often wrapped in ''\begin{center} ... \end{center}'' (within a float, use ''\centering'' instead.)
+The [[ctanpkg>wrapfig]] package supports cut-in inserts at
+the sides of a page or column. Refer to the documentation for details.
+By tradition, captions are applied at the top of tables and the bottom
+of figures. If an insertion is not a float, the usual ''\caption''
+can’t be used. Instead, ''\usepackage{caption}'' and the command ''\captionof''.
 ==== The document class and preamble ====
+When embarking on a new document, start by choosing the document class.
+If the goal is publication in a
+particular journal, check the publisher’s instructions
+to see what is required. Many popular journal classes
+are available from [[https://ctan.org/search|CTAN]].
+If the project is a thesis or dissertation, find
+out the special requirements, and if your institution
+provides a tailored class, obtain a copy. Try to
+determine whether it is actively maintained, and
+if there is local support. Read the documentation.
+It is the responsibility of the document class to
+define the essential structure of the intended document.
+If the document you are preparing differs in essential ways from what is supported by the document class, the time to get help is now.
+There will be features not natively supported by
+the document class; for example, the choice of how
+to prepare a bibliography may be left to the author.
+This is why packages have been created.
 === Organizing your document ===
@@ Ligne 656: / Ligne 769: @@
 ==== Processing the job ====
+Once the file is created, it’s time to produce output.
+There are several engines to choose from: pdfLaTeX, XeLaTeX, and LuaLaTeX.
+These can be run interactively from the command line, or initiated from
+an editor. Assuming there are no errors, how many
+times a document must be processed to produce the
+final output depends on what features it contains.
+In particular, if any cross-references or ''\cites''
+are present, this information is written out to an
+''.aux'' file; information for a table of contents is written
+to a ''.toc'' file, and other tables are also possible.
+The bibliography must be processed by a separate
+program (and its log checked for errors) with the
+reformatted bib data written out to yet another file.
+Then LaTeX must be run (at least) twice more --- once
+to read in the ''.aux'' and other secondary files and include
+the bibliography and resolved cross-references,
+and the second time to resolve the correct page num-
+bers (which will change when the TOC and similar
+bits are added at the beginning).
+All this assumes that there are no errors. Errors
+will be recorded in the log file. Learn where the log
+file is located, and make a habit of referring to it.
+Warnings, such as those for missing characters, will
+also be recorded there, but may not be shown online:\\
+''Missing character: There is no //⟨char⟩//''\\
+''in font //⟨font⟩//!''
+In the log, some errors may appear with closely
+grouped line numbers. If so, and the first is one
+that interrupts the orderly processing of a scoped
+environment, following errors may be spurious. So
+fix the first error and try processing before trying to
+understand the others; often, they may just go away.
+Good luck. With practice comes understanding.
+Oh... **Remember to read the documentation.**
 -----