[latex3-commits] [git/LaTeX3-latex3-latex2e] clsguide-cleanup: Add section 'style' (4f17cd0e)

[Joseph Wright]

Repository : https://github.com/latex3/latex2e
On branch  : clsguide-cleanup
Link       : https://github.com/latex3/latex2e/commit/4f17cd0ec342b3c7d4aae6f3c772c56029de0bd3

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

commit 4f17cd0ec342b3c7d4aae6f3c772c56029de0bd3
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Jan 11 09:38:19 2023 +0000

    Add section 'style'
    
    Again copy-paste but with hooks text altered.


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

4f17cd0ec342b3c7d4aae6f3c772c56029de0bd3
 base/doc/clsguide.tex | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index bd6cc9c3..dd589f3c 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -210,4 +210,110 @@ Also of interest is the command |\normalcolor|. This is normally just |\relax|
 regions of the page such as captions or section headings to the `main document
 color'.
 
+\subsection{General style}
+\label{Sec:general}
+
+\subsubsection{Loading other files}
+\label{Sec:loading}
+
+\LaTeX{} provides these commands:
+\begin{verbatim}
+   \LoadClass        \LoadClassWithOptions
+   \RequirePackage   \RequirePackageWithOptions
+\end{verbatim}
+for using classes or packages inside other classes or packages. We recommend
+strongly that you use them, rather than the primitive |\input| command, for a
+number of reasons.
+
+Files loaded with |\input <filename>| will not be listed in the |\listfiles|
+list.
+
+If a package is always loaded with |\RequirePackage...| or |\usepackage| then,
+even if its loading is requested several times, it will be loaded only once. By
+contrast, if it is loaded with |\input| then it can be loaded more than once;
+such an extra loading may waste time and memory and it may produce strange
+results.
+
+If a package provides option-processing then, again, strange results are
+possible if the package is |\input| rather than loaded by means of
+|\usepackage| or |\RequirePackage...|.
+
+If the package |foo.sty| loads the package |baz.sty| by use of |\input baz.sty|
+then the user will get a warning:
+\begin{verbatim}
+   LaTeX Warning: You have requested package `foo',
+                  but the package provides `baz'.
+\end{verbatim}
+Thus, for several reasons, using |\input| to load packages is not a good idea.
+Unfortunately, if you are upgrading the file |myclass.sty| to a class file then
+you have to make sure that any old files which contain |\input myclass.sty|
+still work.
+
+For example, |article.sty| contains just the following lines:
+\begin{verbatim}
+   \NeedsTeXFormat{LaTeX2e}
+   \@obsoletefile{article.cls}{article.sty}
+   \LoadClass{article}
+\end{verbatim}
+You may wish to do the same or, if you think that it is safe to do so, you may
+decide to just remove |myclass.sty|.
+
+\subsubsection{Make it robust}
+
+We consider it good practice, when writing packages and classes, to use
+\LaTeX{} commands as much as possible.
+
+Thus, instead of using |\def...| we recommend using one of |\newcommand|,
+|\renewcommand| or |\providecommand| for programming and for defining document
+interfaces |\NewDocumentCommand|, etc. (see \texttt{usrguide} for details of
+these commands).
+
+When you define an environment, use |\NewDocumentEnviornment| or
+|\ReewDocumentEnviornment| instead |\def\foo{...}| and |\def\endfoo{...}|.
+
+If you need to set or change the value of a \m{dimen} or \m{skip} register, use
+|\setlength|.
+
+To manipulate boxes, use \LaTeX{} commands such as |\sbox|, |\mbox| and
+|\parbox| rather than |\setbox|, |\hbox| and |\vbox|.
+
+Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the equivalent
+class commands) rather than |\@latexerr|, |\@warning| or |\wlog|.
+
+The advantage of this kind of practice is that your code is more readable and
+accessible to other experienced \LaTeX{} programmers.
+
+\subsubsection{Make it portable}
+
+It is also sensible to make your files are as portable as possible. To ensure
+this, files must not have the same name as a file in the standard \LaTeX{}
+distribution, however similar its contents may be to one of these files. It is
+also still lower risk to stick to file names which use only the ASCII range:
+whilst \LaTeX{} works natively with UTF-8, the same cannot be said with
+certainty for all tools. For the same reason, avoid spaces in file names.
+
+It is also useful if local classes or packages have a common prefix, for
+example the University of Nowhere classes might begin with |unw|. This helps to
+avoid every University having its own thesis class, all called |thesis.cls|.
+
+If you rely on some features of the \LaTeX{} kernel, or on a package,
+please specify the release-date you need.  For example, the package
+error commands were introduced in the June 2022 release so, if you use
+them then you should put:
+\begin{verbatim}
+   \NeedsTeXFormat{LaTeX2e}[2022-06-01]
+\end{verbatim}
+
+\subsubsection{Useful hooks}
+
+It is sometimes necessary for a package to arrange for code to be
+executed at the start or end of the preamble, at the end of the document
+or at the start of every use of an environment. This can be carried
+out by using hooks. As a document author, you will likely be familiar with
+|\AtBeginDocument|, a wrapper around the more powerful command |\AddToHook|.
+The \LaTeX{} kernel provides a large number of dedicated hooks (applying in a 
+a pre-defined location) and generic hooks (applying to arbitrary commands):
+the interface for using these is described in \texttt{lthooks} . There are
+also hooks to apply to files, described in \texttt{ltfilehooks}.
+
 \end{document}