[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: Add section 'writing' (d6925118)

Joseph Wright joseph.wright at morningstar2.co.uk
Tue Apr 11 13:09:11 CEST 2023

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


commit d6925118e230dc37d42cdce8b16d35b893ba9265
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!


 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}
+This section covers some general points concerned with writing
+\LaTeX{} classes and packages.
+\subsection{Is it a class or a package?}
+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:
+  If the commands could be used with any document class, then make
+  them a package; and if not, then make them a class.
+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
+\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{} 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.
+   \InputIfFileExists  \RequirePackage  \PassOptionsToClass
+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
+\subsection{Box commands and 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:
+   \setbox0=\hbox{\color{green} <text>}
+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

More information about the latex3-commits mailing list.