1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
\iffalse meta-comment
File l3styleguide.tex Copyright (C) 2011 The LaTeX3 Project
It may be distributed and/or modified under the conditions of the
LaTeX Project Public License (LPPL), either version 1.3c of this
license or (at your option) any later version. The latest version
of this license is in the file
http://www.latex-project.org/lppl.txt
This file is part of the "l3kernel bundle" (The Work in LPPL)
and all files in that bundle must be distributed together.
The released version of this bundle is available from CTAN.
\fi
\documentclass{l3doc}
\usepackage{svn-multi}
\svnid{$Id: l3styleguide.tex 2772 2011-09-07 15:07:41Z joseph $}
\def\filedate{\svnfileyear/\svnfilemonth/\svnfileday}
\title{%
The \LaTeX3 kernel: style guide for code authors%
\thanks
{%
This file describes v\svnfilerev,
last revised \filedate.
}%
}
\author{%
The \LaTeX3 Project\thanks
{%
E-mail:
\href{mailto:latex-team@latex-project.org}%
{latex-team@latex-project.org}%
}%
}
\date{Released \filedate}
\begin{document}
\maketitle
\tableofcontents
\section{Introduction}
This document is intended as a style guide for authors of code and
documentation for the \LaTeX3 kernel. It covers both aspects of coding
style and the formatting of the sources. The aim of providing these
guidelines is help ensure consistency of the code and sources from
different authors. Experience suggests that in the long-term this helps
with maintenance. There will of course be places where there are
exceptions to these guidelines: common sense should always be
applied!
\section{Documentation style}
\LaTeX3 source and documentation should be written using the document
class \cls{l3doc} in \file{dtx} format. This class provides a number
of logical mark up elements, which should be used where possible.
In the main, this is standard \LaTeX{} practice, but there are a
few points to highlight:
\begin{itemize}
\item
Where possible, use \cs{cs} to mark up control sequences
rather than using a verbatim environment.
\item
Arguments which are given in braces should be marked using
\cs{Arg} when code-level functions are discussed, but using
\cs{marg} for document functions.
\item
The names \TeX{}, \LaTeX{}, \emph{etc}.\ use the normal logical mark
up followed by an empty group (|{}|), with the exception of |\LaTeX3|,
where the number should follow directly.
\item
Where in line verbatim text is used, it should be marked up
using the \verb=|...|= construct (\emph{i.e.}~vertical bars delimit
the verbatim text).
\item In line quotes should be marked up using the \cs{enquote}
function.
\item
Where numbers in the source have a mathematical meaning,
they should be included in math mode. Such in-line math mode
material should be marked up using |$...$| and \emph{not}
|\(...\)|.
\end{itemize}
Line length in the source files should to be under $80$
characters where possible, as this helps keep everything on the screen
when editing files. In the \file{dtx} format, documentation lines start
with a \texttt{\%}, which is usually followed by a space to leave a
\enquote{comment margin} at the start of each line.
As with code indenting (see later), nested environments and arguments
should be indented by (at least) two spaces to make the nature of the nesting
clear. Thus for example a typical arrangement for the \env{function}
environment might be
\begin{verbatim*}
\begin{function}{\seq_gclear:N, \seq_gclear:c}
\begin{syntax}
\cs{seq_gclear:N} \meta{sequence}
\end{syntax}
Clears all entries from the \meta{sequence} globally.
\end{function}
\end{verbatim*}
The \enquote{outer} \verb*|% \begin{function}| should have the customary
space after the |%| character at the start of the line.
In general, a single \env{function} or \env{macro} environment should be
used for a group of closely-related functions, for example argument
specification variants. In such cases, a comma-separated list should be
used, as shown in the preceding example.
\section{Format of the code itself}
The requirement for less than $80$ characters per line applies to the code
itself as well as the surrounding documentation. A number of the general
style principals for \LaTeX3 code apply: these are described in the following
paragraph and an example is then given.
With the exception of simple runs of parameter (|{#1}|, |#1#2|,
\emph{etc.}), everything should divided up using spaces to make the code
more readable. In general, these will be single spaces, but in some
places it makes more sense to align parts of the code to emphasise
similarity. (Tabs should not be used for introducing white space.)
Each conceptually-separate step in a function should be on a separate
line, to make the meaning clearer. Hence the \texttt{false} branch
in the example uses two lines for the two auxiliary function uses.
Within the definition, a two-space indent should be used to show each
\enquote{level} of code. Thus in the example \cs{tl_if_empty:nTF} is
indented by two spaces, but the two branches are indented by four
spaces. Within the \texttt{false} branch, the need for multiple lines
means that an additional two-space indent should be used to show that
these lines are all part of the brace group.
The result of these lay-out conventions is code which will in general
look like the example:
\begin{verbatim*}
\cs_new_nopar:Npn \module_foo:nn #1#2
{
\tl_if_empty:nTF {#1}
{ \module_foo_aux:n { X #2 } }
{
\module_foo_aux:nn {#1} {#2}
\module_foo_aux:n {#1#2}
}
}
\end{verbatim*}
\section{Code conventions}
When using \cs{cs_generate_variant:Nn}, group related variants together
to make the pattern clearer. A common example is variants of a function
which has an \texttt{N}-type first argument:
\begin{verbatim*}
\cs_generate_variant:Nn \foo:Nn { NV , No }
\cs_generate_variant:Nn \foo:Nn { c , cV , co }
\end{verbatim*}
There are cases where omitting braces from \texttt{o}-type arguments
is desirable for performance reasons. This should only be done if the
argument is a single token, thus for example
\begin{verbatim}
\tl_set:No \l_some_tl \l_some_other_tl
\end{verbatim}
remains clear and can be used where appropriate.
\end{document}
|
