Différences

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

--- 1_generalites:erreurs_de_debutant [2023/07/18 00:38] – Ajout d'exemples de mauvais espacements. 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 447: / Ligne 450: @@
 === Really unexpected extra spaces ===
+Other possibilities exist that aren’t so predictable.
+Here’s one that was the subject of an online question.
+A text using package [[ctanpkg>tcolorbox]] (it can also happen with
+[[ctanpkg>colorbox]]) had a colorized letter surrounded by spaces
+in the middle of a word. A small frame was applied around the colored element
+by the package:
+<WRAP column 48ex>
+<code latex>
+\usepackage{tcolorbox}
+\newcommand{\pink}[1]{%
+\colorbox{red!20}{#1}}
+Oo\pink{p}s!
+</code>
+</WRAP>
+<WRAP column 25ex>
+<latexdoc>
+\documentclass[10pt]{article}
+  \usepackage[utf8]{inputenc}
+  \usepackage[T1]{fontenc}
+  \usepackage{tcolorbox}
+  \pagestyle{empty}
+\newcommand{\pink}[1]{%
+\colorbox{red!20}{#1}}
+\begin{document}
+Oo\pink{p}s!
+\end{document}
+</latexdoc>
+</WRAP>
+<WRAP clear />
+Explicitly omitting the buffer inside the frame was
+the solution provided by the package documentation:
+<WRAP column 48ex>
+<code latex>
+\usepackage{tcolorbox}
+\renewcommand{\pink}[1]{{%
+\fboxsep=0pt
+\colorbox{red!20}{#1\strut}}}
+Oo\pink{p}s!
+</code>
+</WRAP>
+<WRAP column 25ex>
+<latexdoc>
+\documentclass[10pt]{article}
+  \usepackage[utf8]{inputenc}
+  \usepackage[T1]{fontenc}
+  \usepackage{tcolorbox}
+  \pagestyle{empty}
+\renewcommand{\pink}[1]{{%
+\fboxsep=0pt
+\colorbox{red!20}{#1\strut}}}
+\begin{document}
+Oo\pink{p}s!
+\end{document}
+</latexdoc>
+</WRAP>
+<WRAP clear />
+I added the ''\strut'' so that the color would be obvious
+above and below the highlighted element, rather than covering only the “<latex>p</latex>”.
+While this isn’t really a newbie problem, it’s wise to be aware that such
+possibilities exist, and be ready in such cases to seek expert assistance!
 === Paragraph endings and vertical mode ===
+The end of a paragraph is a transition from horizontal to vertical mode.
+A blank line or ''\par'' will accomplish this transition. It’s important
+to be aware of what mode you’re in, since some operations are best performed
+in vertical mode; the most important is the insertion of floats
+(figures, tables, algorithms).
+Another important consideration is that some features of text are
+not “frozen” until a paragraph is ended. One important feature is
+the vertical spacing of baselines, which depends on the font size.
+Too many newbies try to end a paragraph with a double backslash,
+resulting in horrors like the following.
+<WRAP column 48ex>
+<code latex>
+\Huge Texts with inconsistent descenders
+can result in surprises when the font
+size changes without a proper paragraph
+ending.\\
+</code>
+</WRAP>
+<WRAP column 25ex>
+<latex>
+\begin{minipage}{8.2cm}
+\Huge Texts with inconsistent descenders
+can result in surprises when the font
+size changes without a proper paragraph
+ending.\\
+\end{minipage}
+</latex>
+</WRAP>
+<WRAP clear />
+Some environments (but not //all//) are defined with a paragraph break
+at the end. A problem such as the one shown here won’t result
+in an error or warning message, so adding a proper paragraph break
+is the proper correction.
+The vertical space between paragraphs is determined by the value
+of ''\parskip''; this is set in the document class, but can be reset
+as needed. But often, it’s convenient to add occasional extra space
+between paragraphs explicitly; this is done with ''\vspace'' or
+''\vskip'' while in vertical mode (that is, after the blank line
+or ''\par'' that ends a paragraph).
 === The double backslash \\ ===
+What a paragraph does not end with is the control symbol ''\\''.
+''\\'' does end a line. It is the designated command to end lines in tables,
+poetry, multi-line math environments, and some other situations.
+But it does not end a paragraph and can trigger a number of error or warning messages.
+If ''\\'' is alone on a line in vertical mode, this error is reported:
+<code>
+! LaTeX Error:
+There’s no line here to end.
+</code>
+Further, if the ''\\'' is preceded by a (typed) space,
+in addition to the warning, there may be an extra,
+unwanted, blank line in the output.
+If a line ending with ''\\'' is very short:
+<code>
+Underfull \hbox (badness 10000)
+in paragraph at lines ...
+</code>
+This may be okay, but check.
+If ''\\'' is followed by bracketed text, as in ''[stuff to be typeset]'',
+the result will be the mysterious message
+<code>
+! Missing number, treated as zero.
+</code>
+For ''\\'', a following (optional) ''[...]'' is defined to indicate
+a vertical distance to be skipped; insert ''\relax'' before the opening bracket.
+If extra vertical space is wanted after a line broken with ''\\'',
+it can be added by inserting an optional rubber length (usually just a dimension),
+wrapped in brackets: ''\\[<value>]''. If such a bracketed expression is really meant
+to be typeset, it must be preceded by ''\relax''.
+''\newline'' is often a reasonable alternative to break a line.
+==== 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.
-==== Font changee ====
+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 495: / 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.**
 -----