[latex3-commits] [git/LaTeX3-latex3-latex2e] clsguide-cleanup: Add section 'writing' (bdd660d1)

[Joseph Wright]

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

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

commit bdd660d1643bcd28bc8bf6071f03ad55e8fec7c7
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Jan 11 09:36:37 2023 +0000

    Add section 'writing'
    
    Mainly copied from older file, but now
    mentions L3PL. Notice also 'color' spelling
    is changed!


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

bdd660d1643bcd28bc8bf6071f03ad55e8fec7c7
 base/doc/clsguide.tex | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)

diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex
index d6798d33..bd6cc9c3 100644
--- a/base/doc/clsguide.tex
+++ b/base/doc/clsguide.tex
@@ -74,4 +74,140 @@ the material here is read in conjunction with \texttt{usrguide}, which provides
 information for general \LaTeX{} users on up-to-date approaches to creating
 commands, etc.
 
+\section{Writing classes and packages}
+\label{Sec:writing}
+
+This section covers some general points concerned with writing
+\LaTeX{} classes and packages.
+
+\subsection{Is it a class or a package?}
+\label{Sec:classorpkg}
+
+The first thing to do when you want to put some new \LaTeX{} commands
+in a file is to decide whether it should be a \emph{document class} or a
+\emph{package}.  The rule of thumb is:
+\begin{quote}
+  If the commands could be used with any document class, then make
+  them a package; and if not, then make them a class.
+\end{quote}
+
+There are two major types of class: those like |article|, |report| or
+|letter|, which are free-standing; and those which are extensions or
+variations of other classes---for example, the |proc| document class,
+which is built on the |article| document class.
+
+Thus, a company might have a local |ownlet| class for printing letters
+with their own headed note-paper.  Such a class would build on top of
+the existing |letter| class but it cannot be used with any other
+document class, so we have |ownlet.cls| rather than |ownlet.sty|.
+
+The |graphics| package, in contrast, provides commands for including
+images into a \LaTeX{} document.  Since these commands can be used
+with any document class, we have |graphics.sty| rather than
+|graphics.cls|.
+
+\subsection{Using `docstrip' and `doc'}
+
+If you are going to write a large class or package for \LaTeX{} then
+you should consider using the |doc| software which comes with
+\LaTeX{}.
+\LaTeX{} classes and packages written using this can be
+processed in two ways: they can be run through \LaTeX{}, to produce
+documentation; and they can be processed with |docstrip|, to produce
+the |.cls| or |.sty| file.
+
+The |doc| software can automatically generate indexes of definitions,
+indexes of command use, and change-log lists.  It is very useful for
+maintaining and documenting large \TeX{} sources.
+
+The documented sources of the \LaTeX{} kernel itself, and of the
+standard classes, etc, are |doc| documents; they are in the |.dtx|
+files in the distribution.  You can, in fact, typeset the source code
+of the kernel as one long document, complete with index, by running
+\LaTeX{} on |source2e.tex|.  Typesetting these documents uses the
+class file |ltxdoc.cls|.
+
+For more information on |doc| and |docstrip|, consult the files
+|docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}.  For examples of its
+use, look at the |.dtx| files.
+
+\subsection{Command names}
+
+\LaTeX{} has three types of command.
+
+There are the author commands, such as |\section|, |\emph| and
+|\times|:  most of these have short names, all in lower case.
+
+There are also the class and package writer commands:
+most of these have long mixed-case names such as the following.
+\begin{verbatim}
+   \InputIfFileExists  \RequirePackage  \PassOptionsToClass
+\end{verbatim}
+
+Finally, there are the internal commands used in the \LaTeX{}
+implementation, such as |\@tempcnta|, |\@ifnextchar| and |\@eha|:
+most of these commands contain |@| in their name, which means they
+cannot be used in documents, only in class and package files.
+
+Unfortunately, for historical reasons the distinction between these
+commands is often blurred.  For example, |\hbox| is an internal
+command which should only be used in the \LaTeX{} kernel, whereas
+|\m at ne| is the constant $-1$ and could have been |\MinusOne|.
+
+However, this rule of thumb is still useful: if a command has |@| in
+its name then it is not part of the supported \LaTeX{} language---and
+its behaviour may change in future releases!  If a command is
+mixed-case, or is described in \emph{\LaTeXbook}, then you can rely on
+future releases of \LaTeX{} supporting the command.
+
+\subsection{Programming support}
+
+As noted in the introduction, the \LaTeX{} kernel today loads dedicated support
+from programming, here referred to as the L3 programming layer but also often
+called \pkg{expl3}. Detailes of the general approach taken by the L3
+programming layer are given in the document \texttt{expl3}, while a reference
+for all current code interfaces is available as \texttt{interface3}. This layer
+contains two types of command: a documented set of commands making up the API
+and a large number of private internal commands. The latter all start with two
+underscores and should not be used outside of the code module which defines
+them. This more structured approach means that using the L3 programming layer
+does not suffer from the somewhat fluid situation mentioned above with
+`\texttt{@} commands'.
+
+We do not cover the detail of using the L3 programming layer here. A good
+introduction to the approach is provided at
+\url{https://www.alanshawn.com/latex3-tutorial/}.
+
+\subsection{Box commands and color}
+\label{Sec:color}
+
+Even if you do not intend to use color in your own documents, by taking note of
+the points in this section you can ensure that your class or package is
+compatible with the |color| package. This may benefit people using your class
+or package who have access to color printers.
+
+The simplest way to ensure `color safety' is to always use \LaTeX{} box
+commands rather than \TeX{} primitives, that is use |\sbox| rather than
+|\setbox|, |\mbox| rather than |\hbox| and |\parbox| or the |minipage|
+environment rather than |\vbox|. The \LaTeX{} box commands have new options
+which mean that they are now as powerful as the \TeX{} primitives.
+
+As an example of what can go wrong, consider that in |{\ttfamily <text>}| the
+font is restored just \emph{before} the |}|, whereas in the similar looking
+construction |{\color{green} <text>}| the color is restored just \emph{after}
+the final |}|. Normally this distinction does not matter at all; but consider a
+primitive \TeX{} box assignment such as:
+\begin{verbatim}
+   \setbox0=\hbox{\color{green} <text>}
+\end{verbatim}
+Now the color-restore occurs after the |}| and so is \emph{not} stored in the
+box. Exactly what bad effects this can have depends on how color is
+implemented: it can range from getting the wrong colors in the rest of the
+document, to causing errors in the dvi-driver used to print the document.
+
+Also of interest is the command |\normalcolor|. This is normally just |\relax|
+(i.e., does nothing) but you can use it rather like |\normalfont| to set
+regions of the page such as captions or section headings to the `main document
+color'.
+
 \end{document}