summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/usrguide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/usrguide.tex')
-rw-r--r--macros/latex-dev/base/usrguide.tex94
1 files changed, 52 insertions, 42 deletions
diff --git a/macros/latex-dev/base/usrguide.tex b/macros/latex-dev/base/usrguide.tex
index c76b27c0f0..4c2ddf24af 100644
--- a/macros/latex-dev/base/usrguide.tex
+++ b/macros/latex-dev/base/usrguide.tex
@@ -34,10 +34,10 @@
\title{\LaTeXe~for authors}
-\author{\copyright~Copyright 1995--2019, \LaTeX3 Project Team.\\
+\author{\copyright~Copyright 1995--2020, \LaTeX3 Project Team.\\
All rights reserved.}
-\date{27 January 2019}
+\date{25 May 2020}
\begin{document}
@@ -505,44 +505,6 @@ This section describes the new commands available in \LaTeXe.
They are covered in more detail in \emph{\LaTeXbook} and in
\emph{\LaTeXcomp}.
-\subsection{Initial commands}
-
-Initial commands can appear only before the |\documentclass|
-line.
-
-\begin{decl}
-|\begin{filecontents}| \arg{file-name} \\
- \m{file-contents} \\
-|\end{filecontents}|
-\end{decl}
-
-The |filecontents| environment is intended for bundling within a
-single document file the contents of packages, options, or other
-files. When the document file is run through \LaTeXe{} the body of
-this environment is written verbatim (preceded by a comment line) to a
-file whose name is given as the environment's only argument. However,
-if that file already exists then nothing happens except for an
-information message.
-
-Only normal ASCII text characters (7-bit visible text) should be
-included in a |filecontents| environment. Anything else, such as tab
-characters, form-feeds or 8-bit characters, should not be included in a
-|filecontents| environment.
-
-Tabs and form feeds produce a warning, explaining that they are turned
-into spaces or blank lines, respectively.
-What happens to 8-bit characters depends on the \TeX{} installation and
-is in general unpredictable.
-
-The |filecontents| environment is used for including \LaTeX{} files.
-For other plain text files (such as Encapsulated PostScript files),
-you should use the |filecontents*| environment which does not add a
-comment line.
-
-These environments are allowed only before |\documentclass|. This
-ensures that any packages that have been bundled in the document are
-present when needed.
-
\subsection{Preamble commands}
\label{Sec:pre}
@@ -559,8 +521,10 @@ This command replaces the
\LaTeX~2.09 command |\documentstyle|.
There must be exactly one |\documentclass| command in a document; and
-it must come after the |filecontents| environments, if any, but before
-any other commands.
+it should normally come before any other command. (There are some
+exceptions, e.g., you can have |filecontents| environments before it
+or |\RequirePackage| but these should be only used in special
+scenarios as discussed elsewhere.)
The \m{option-list} is a list of options, each of which may modify the
formatting of elements which are defined in the \m{class-name} file,
@@ -657,6 +621,52 @@ through the standard |\setcounter| command. As most \LaTeX\ users do
not want to see the internal definitions of \LaTeX\ commands each time
they make an error, \LaTeXe{} sets this to $-1$ by default.
+
+\subsection{Environments to write out support files}
+
+\NEWfeature{2019}
+%
+Until the \LaTeX\ release in 2019 the |filecontents| environment was
+restricted to a place before the |\documentclass| command. These days
+it can be used anywhere, though we still think that in most cases it is
+best to only use it a the top of your document or in the preamble.
+
+\begin{decl}
+|\begin{filecontents}| \oarg{option-list} \arg{file-name} \\
+ \m{file-contents} \\
+|\end{filecontents}|
+\end{decl}
+
+The |filecontents| environment is intended for bundling within a
+single document file the contents of packages, options, or other
+files. When the document file is run through \LaTeXe{} the body of
+this environment is written verbatim (preceded by a comment line) to a
+file whose name is given as the environment's only argument. However,
+if that file already exists then nothing happens except for an
+information message.
+
+These days most UTF-8 text characters can be used in a
+|filecontents| envi\-ronment---they will be written unchanged to the
+output file. However, tabs and form feeds produce a warning,
+explaining that they are turned into spaces or blank lines,
+respectively.
+
+By default the environment does not overwrite an existing file and it
+even refuses to write out the data if there exists a file that is
+anywhere in the path that \TeX\ searches when inputting files. With
+the option |nosearch| you can ask it to look only into the current
+directory and with the option |overwrite| (or |force|) you can request
+it to write the file regardless. It will, however, never write to
+|\jobname.tex| to avoid overwriting itself.
+
+The |filecontents| environment is used for including \LaTeX{} files.
+For other plain text files (such as Encapsulated PostScript files),
+you should use the |filecontents*| environment which does not add a
+comment line.
+
+
+
+
\subsection{Document structure}
The |book| document class introduces new commands to indicate