[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: added documentation on filecontents changes (#298) (8a07ed68)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : develop
Link       : https://github.com/latex3/latex2e/commit/8a07ed68fb7f6ca0e8edab45d91b66d6c88da8a1

>---------------------------------------------------------------

commit 8a07ed68fb7f6ca0e8edab45d91b66d6c88da8a1
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Tue Apr 7 22:25:55 2020 +0200

    added documentation on filecontents changes (#298)


>---------------------------------------------------------------

8a07ed68fb7f6ca0e8edab45d91b66d6c88da8a1
 base/doc/usrguide.tex | 88 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 48 insertions(+), 40 deletions(-)

diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex
index c76b27c0..efdde994 100644
--- a/base/doc/usrguide.tex
+++ b/base/doc/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{7 April 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}
 
@@ -657,6 +619,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