| 1 |
\iffalse meta-comment |
| 2 |
|
| 3 |
File: l3styleguide.tex |
| 4 |
|
| 5 |
Copyright (C) 2011,2012,2014-2026 The LaTeX Project |
| 6 |
|
| 7 |
It may be distributed and/or modified under the conditions of the |
| 8 |
LaTeX Project Public License (LPPL), either version 1.3c of this |
| 9 |
license or (at your option) any later version. The latest version |
| 10 |
of this license is in the file |
| 11 |
|
| 12 |
https://www.latex-project.org/lppl.txt |
| 13 |
|
| 14 |
This file is part of the "l3kernel bundle" (The Work in LPPL) |
| 15 |
and all files in that bundle must be distributed together. |
| 16 |
|
| 17 |
The released version of this bundle is available from CTAN. |
| 18 |
|
| 19 |
\fi |
| 20 |
|
| 21 |
\documentclass{l3doc} |
| 22 |
|
| 23 |
|
| 24 |
\title{% |
| 25 |
The \LaTeX3 kernel: style guide for code authors% |
| 26 |
} |
| 27 |
\author{% |
| 28 |
The \LaTeX{} Project\thanks |
| 29 |
{% |
| 30 |
E-mail: |
| 31 |
\href{mailto:[email protected]}% |
| 32 |
{[email protected]}% |
| 33 |
}% |
| 34 |
} |
| 35 |
\date{Released 2026-05-15} |
| 36 |
|
| 37 |
\begin{document} |
| 38 |
|
| 39 |
\maketitle |
| 40 |
|
| 41 |
\tableofcontents |
| 42 |
|
| 43 |
\section{Introduction} |
| 44 |
|
| 45 |
This document is intended as a style guide for authors of code and |
| 46 |
documentation for the \LaTeX3 kernel. It covers both aspects of coding |
| 47 |
style and the formatting of the sources. The aim of providing these |
| 48 |
guidelines is help ensure consistency of the code and sources from |
| 49 |
different authors. Experience suggests that in the long-term this helps |
| 50 |
with maintenance. There will of course be places where there are |
| 51 |
exceptions to these guidelines: common sense should always be |
| 52 |
applied! |
| 53 |
|
| 54 |
\section{Documentation style} |
| 55 |
|
| 56 |
\LaTeX3 source and documentation should be written using the document |
| 57 |
class \cls{l3doc} in \file{dtx} format. This class provides a number |
| 58 |
of logical mark up elements, which should be used where possible. |
| 59 |
In the main, this is standard \LaTeX{} practice, but there are a |
| 60 |
few points to highlight: |
| 61 |
\begin{itemize} |
| 62 |
\item |
| 63 |
Where possible, use \cs{cs} to mark up control sequences |
| 64 |
rather than using a verbatim environment. |
| 65 |
\item |
| 66 |
Arguments which are given in braces should be marked using |
| 67 |
\cs{Arg} when code-level functions are discussed, but using |
| 68 |
\cs{marg} for document functions. |
| 69 |
\item |
| 70 |
The names \TeX{}, \LaTeX{}, \emph{etc}.\ use the normal logical mark |
| 71 |
up followed by an empty group (|{}|), with the exception of |\LaTeX3|, |
| 72 |
where the number should follow directly. |
| 73 |
\item |
| 74 |
Where in line verbatim text is used, it should be marked up |
| 75 |
using the \verb=|...|= construct (i.e., vertical bars delimit |
| 76 |
the verbatim text). |
| 77 |
\item In line quotes should be marked up using the \cs{enquote} |
| 78 |
function. |
| 79 |
\item |
| 80 |
Where numbers in the source have a mathematical meaning, |
| 81 |
they should be included in math mode. Such in-line math mode |
| 82 |
material should be marked up using |$...$| and \emph{not} |
| 83 |
|\(...\)|. |
| 84 |
\end{itemize} |
| 85 |
|
| 86 |
Line length in the source files should be under $80$ |
| 87 |
characters where possible, as this helps keep everything on the screen |
| 88 |
when editing files. In the \file{dtx} format, documentation lines start |
| 89 |
with a \texttt{\%}, which is usually followed by a space to leave a |
| 90 |
\enquote{comment margin} at the start of each line. |
| 91 |
|
| 92 |
As with code indenting (see later), nested environments and arguments |
| 93 |
should be indented by (at least) two spaces to make the nature of the nesting |
| 94 |
clear. Thus for example a typical arrangement for the \env{function} |
| 95 |
environment might be |
| 96 |
\begin{verbatim*} |
| 97 |
\begin{function}{\seq_gclear:N, \seq_gclear:c} |
| 98 |
\begin{syntax} |
| 99 |
\cs{seq_gclear:N} \meta{sequence} |
| 100 |
\end{syntax} |
| 101 |
Clears all entries from the \meta{sequence} globally. |
| 102 |
\end{function} |
| 103 |
\end{verbatim*} |
| 104 |
The \enquote{outer} \verb*|% \begin{function}| should have the customary |
| 105 |
space after the |%| character at the start of the line. |
| 106 |
|
| 107 |
In general, a single \env{function} or \env{macro} environment should be |
| 108 |
used for a group of closely-related functions, for example argument |
| 109 |
specification variants. In such cases, a comma-separated list should be |
| 110 |
used, as shown in the preceding example. |
| 111 |
|
| 112 |
\section{Format of the code itself} |
| 113 |
|
| 114 |
The requirement for fewer than $80$ characters per line applies to the code |
| 115 |
itself as well as the surrounding documentation. A number of the general |
| 116 |
style principles for \LaTeX3 code apply: these are described in the following |
| 117 |
paragraph and an example is then given. |
| 118 |
|
| 119 |
With the exception of simple runs of parameter (|{#1}|, |#1#2|, |
| 120 |
etc.), everything should be divided up using spaces to make the code |
| 121 |
more readable. In general, these will be single spaces, but in some |
| 122 |
places it makes more sense to align parts of the code to emphasize |
| 123 |
similarity. (Tabs should not be used for introducing white space.) |
| 124 |
|
| 125 |
Each conceptually-separate step in a function should be on a separate |
| 126 |
line, to make the meaning clearer. Hence the \texttt{false} branch |
| 127 |
in the example uses two lines for the two auxiliary function uses. |
| 128 |
|
| 129 |
Within the definition, a two-space indent should be used to show each |
| 130 |
\enquote{level} of code. Thus in the example \cs{tl_if_empty:nTF} is |
| 131 |
indented by two spaces, but the two branches are indented by four |
| 132 |
spaces. Within the \texttt{false} branch, the need for multiple lines |
| 133 |
means that an additional two-space indent should be used to show that |
| 134 |
these lines are all part of the brace group. |
| 135 |
|
| 136 |
The result of these lay-out conventions is code which in general |
| 137 |
looks like the example: |
| 138 |
\begin{verbatim*} |
| 139 |
\cs_new:Npn \module_foo:nn #1#2 |
| 140 |
{ |
| 141 |
\tl_if_empty:nTF {#1} |
| 142 |
{ \module_foo_aux:n { X #2 } } |
| 143 |
{ |
| 144 |
\module_foo_aux:nn {#1} {#2} |
| 145 |
\module_foo_aux:n { #1 #2 } |
| 146 |
} |
| 147 |
} |
| 148 |
\end{verbatim*} |
| 149 |
|
| 150 |
\section{Code conventions} |
| 151 |
|
| 152 |
All code-level functions should be \enquote{long} if they accept any |
| 153 |
arguments, even if it seems \enquote{very unlikely} that a \cs{par} token |
| 154 |
will be passed. Thus \cs{cs_new_nopar:Npn} and so forth should only be used |
| 155 |
to create interfaces at the document level (where trapping \cs{par} tokens |
| 156 |
may be appropriate) or where comparison to other code known not to be |
| 157 |
\enquote{long} is required (\emph{e.g.}~when working with mixed |
| 158 |
\LaTeXe{}/\pkg{expl3} situations). |
| 159 |
|
| 160 |
The expandability of each function should be well-defined. Functions which |
| 161 |
cannot be fully expanded must be \texttt{protected}. This means that expandable |
| 162 |
functions must themselves only contain expandable material. Functions which |
| 163 |
use any non-expandable material must be defined using \cs{cs_new_protected:Npn} |
| 164 |
or similar. |
| 165 |
|
| 166 |
When using \cs{cs_generate_variant:Nn}, group related variants together |
| 167 |
to make the pattern clearer. A common example is variants of a function |
| 168 |
which has an \texttt{N}-type first argument: |
| 169 |
\begin{verbatim} |
| 170 |
\cs_generate_variant:Nn \foo:Nn { NV , No } |
| 171 |
\cs_generate_variant:Nn \foo:Nn { c , cV , co } |
| 172 |
\end{verbatim} |
| 173 |
|
| 174 |
There may be cases where omitting braces from \texttt{o}-type arguments |
| 175 |
is desirable for performance reasons. This should only be done if the |
| 176 |
argument is a single token, thus for example |
| 177 |
\begin{verbatim} |
| 178 |
\tl_set:No \l_some_tl \l_some_other_tl |
| 179 |
\end{verbatim} |
| 180 |
remains clear and can be used where appropriate. |
| 181 |
|
| 182 |
\section{Private and internal functions} |
| 183 |
|
| 184 |
Private functions (those starting \cs{__}) should not be used between modules. |
| 185 |
The only exception is where a \enquote{family} of modules share some |
| 186 |
\enquote{internal} methods: this happens most obviously in the kernel itself. |
| 187 |
Any internal functions or variables \emph{must} be documented in the same way |
| 188 |
as public ones. |
| 189 |
|
| 190 |
The \pkg{DocStrip} method should be used for internal functions in a module. |
| 191 |
This requires a line |
| 192 |
\begin{quote} |
| 193 |
\ttfamily |
| 194 |
\%<@@=\meta{module}> |
| 195 |
\end{quote} |
| 196 |
at the start of the source (\texttt{.dtx}) file, with internal functions |
| 197 |
then written in the form |
| 198 |
\begin{verbatim} |
| 199 |
\cs_new_protected:Npn \@@_function:nn #1#2 |
| 200 |
... |
| 201 |
\end{verbatim} |
| 202 |
|
| 203 |
\subsection{Access from other modules} |
| 204 |
|
| 205 |
There may be cases where it is useful to use an internal function from |
| 206 |
a third-party module (this includes cases where you are the author of both |
| 207 |
but they are not part of the same \enquote{family}). In these cases, you should |
| 208 |
\emph{copy} the definition of the internal function to your code: this avoids |
| 209 |
relying on non-documented interfaces. At the same time, it is strongly |
| 210 |
encouraged that you discuss your requirements with the author of the |
| 211 |
code you need to access. The best long-term solution to these cases is for |
| 212 |
new documented interfaces to be added to the parent module. |
| 213 |
|
| 214 |
\subsection{Access to primitives} |
| 215 |
|
| 216 |
As \pkg{expl3} is still a developing system, there are places where direct |
| 217 |
access to engine primitives is required. These are all marked as |
| 218 |
\enquote{do not use} in the code and so require special handling. Where a |
| 219 |
programmer is sure that they need to use a primitive (for example where the |
| 220 |
team have not yet covered access to an area) then a local copy of the |
| 221 |
primitive should be made, for example |
| 222 |
\begin{verbatim} |
| 223 |
\cs_new_eq:NN \__module_message:w \tex_message:D |
| 224 |
% ... |
| 225 |
\cs_new_protected:Npn \__module_fancy_msg:n #1 |
| 226 |
{ \__module_message:w { *** #1 *** } } |
| 227 |
\end{verbatim} |
| 228 |
This approach makes it possible for the team and others to find such |
| 229 |
usage (by searching for the \texttt{:D} argument type) but avoids |
| 230 |
multiple uses in general code. |
| 231 |
|
| 232 |
At the same time, the team ask that these use cases are raised by |
| 233 |
emailing us. The team are keen to collect use cases for |
| 234 |
areas that have not yet been addressed and to provide new code where the |
| 235 |
required interfaces become clear. |
| 236 |
|
| 237 |
Programmers using primitives should be ready to make updates to their |
| 238 |
code as the team develop additional interfaces. |
| 239 |
|
| 240 |
\section{Auxiliary functions} |
| 241 |
|
| 242 |
In general, the team encourages the use of descriptive names in \LaTeX3 code. |
| 243 |
Thus many helper functions would have names which describe briefly what they do, |
| 244 |
rather than simply indicating that they are auxiliary to some higher-level |
| 245 |
function. However, there are places where one or more \texttt{aux} functions |
| 246 |
are required. Where possible, these should be differentiated by signature |
| 247 |
\begin{verbatim} |
| 248 |
\cs_new_protected:Npn \@@_function:nn #1#2 |
| 249 |
{ |
| 250 |
... |
| 251 |
} |
| 252 |
\cs_new_protected:Npn \@@_function_aux:nn #1#2 |
| 253 |
{ |
| 254 |
... |
| 255 |
} |
| 256 |
\cs_new_protected:Npn \@@_function_aux:w #1#2 \q_stop |
| 257 |
{ |
| 258 |
... |
| 259 |
} |
| 260 |
\end{verbatim} |
| 261 |
Where more than one auxiliary shares the same signature, the recommended naming |
| 262 |
scheme is \texttt{auxi}, \texttt{auxii} and so on. |
| 263 |
\begin{verbatim} |
| 264 |
\cs_new_protected:Npn \@@_function_auxi:nn #1#2 |
| 265 |
{ |
| 266 |
... |
| 267 |
} |
| 268 |
\cs_new_protected:Npn \@@_function_auxii:nn #1#2 |
| 269 |
{ |
| 270 |
... |
| 271 |
} |
| 272 |
\end{verbatim} |
| 273 |
The use of \texttt{aux_i}, \texttt{aux_ii}, etc.\ is discouraged as this |
| 274 |
conflicts with the convention used by \cs{use_i:nn} and related functions. |
| 275 |
|
| 276 |
\section{Functions with `weird' arguments} |
| 277 |
|
| 278 |
When defining commands that do not follow the usual convention of accepting |
| 279 |
arguments as single-tokens or braced-text, the \verb|w| argument specifier |
| 280 |
is used to denote that the function signature cannot fully describe the syntax. |
| 281 |
Two examples from the \LaTeX3 kernel are: |
| 282 |
\begin{quote} |
| 283 |
\verb|\use_none_delimit_by_q_stop:w| $\langle$\,\emph{text}\,$\rangle$ \verb|\q_stop|\\ |
| 284 |
\verb|\use_i_delimit_by_q_stop:nw| \char`\{ $\langle$\,\emph{arg}\,$\rangle$\char`}\,$\langle$\,\emph{text}\,$\rangle$ \verb|\q_stop| |
| 285 |
\end{quote} |
| 286 |
More complex definitions are possible if commands are to parse tokens, |
| 287 |
such as the internal kernel command |
| 288 |
\begin{verbatim} |
| 289 |
\cs_new_protected:Npn \__clist_get:wN #1 , #2 \q_stop #3 |
| 290 |
{ \tl_set:Nn #3 {#1} } |
| 291 |
\end{verbatim} |
| 292 |
When the \verb|w| specifier is being used, it is encouraged not to try |
| 293 |
and complicate the rest of the signature too much---for example, it |
| 294 |
would be considered poor style to have a function with a signature like |
| 295 |
\verb|\foo_bar:wnw| unless there were very clear reasons of code clarity. |
| 296 |
A signature such as \verb|:ww| would certainly be discouraged. |
| 297 |
|
| 298 |
Examining the examples above, it can be seen that there are scenarios in |
| 299 |
which it may make logical sense for having a signature such as \verb|:wN| or |
| 300 |
\verb|:nw|, but when in doubt the recommended approach is to simply use |
| 301 |
\verb|:w| as a catch-all. |
| 302 |
|
| 303 |
\end{document} |