diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex-dev/base/usrguide.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex-dev/base/usrguide.tex | 94 |
1 files changed, 52 insertions, 42 deletions
diff --git a/Master/texmf-dist/doc/latex-dev/base/usrguide.tex b/Master/texmf-dist/doc/latex-dev/base/usrguide.tex index c76b27c0f08..4c2ddf24af6 100644 --- a/Master/texmf-dist/doc/latex-dev/base/usrguide.tex +++ b/Master/texmf-dist/doc/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 |