summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-03-17 21:51:00 +0000
committerKarl Berry <karl@freefriends.org>2013-03-17 21:51:00 +0000
commit0fc23846257eb94f086d8bde2dce867e483362ad (patch)
treee17b4c9b53a158fa2a6136a5ff1fa0546e1f08ce /Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
parent17a7d32b1d972c5b5bd849776d17d357e9c35993 (diff)
l3kernel
git-svn-id: svn://tug.org/texlive/trunk@29409 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex')
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex242
1 files changed, 242 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
new file mode 100644
index 00000000000..6a3a9d122e6
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
@@ -0,0 +1,242 @@
+\iffalse meta-comment
+
+File l3styleguide.tex Copyright (C) 2011,2012 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: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}
+
+All code-level functions should be \enquote{long} if they accept any
+arguments, even if it seems \enquote{very unlikely} that a \cs{par} token
+will be passed. Thus \cs{cs_new_nopar:Npn} and so forth should only be used
+to create functions which accept no arguments at all.
+
+The expandability of each function should be well-defined. Functions which
+cannot be fully expanded must be \texttt{protected}. This means that expandable
+functions must themselves only contain expandable material. Functions which
+use any non-expandable material must be defined using \cs{cs_new_protected:Npn}
+or similar.
+
+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.
+
+\section{Private and internal functions}
+
+Private functions (those starting \cs{__}) should not be used between modules.
+The only exception is where a \enquote{family} of modules share some
+\enquote{internal} methods: this happens most obviously in the kernel itself.
+Any internal functions or variables \emph{must} be documented in the same way
+as public ones.
+
+The \pkg{l3docstrip} method should be used for internal functions in a module.
+This requires a line
+\begin{quote}
+ \ttfamily
+ \%<@@=\meta{module}>
+\end{quote}
+at the start of the source (\texttt{.dtx}) file, with internal functions
+then written in the form
+\begin{verbatim}
+ \cs_new_protected:Npn \@@_function:nn #1#2
+ ...
+\end{verbatim}
+
+\section{Auxiliary functions}
+
+In general, the team encourage the use of descriptive names in \LaTeX3 code.
+Thus many helper functions will have names which describe briefly what they do,
+rather than simply indicating that they are auxiliary to some higher-level
+function. However, there are places where one or more \texttt{aux} functions
+are required. Where possible, these should be differentiated by signature
+\begin{verbatim}
+ \cs_new_protected:Npn \@@_function:nn #1#2
+ {
+ ...
+ }
+ \cs_new_protected:Npn \@@_function_aux:nn #1#2
+ {
+ ...
+ }
+ \cs_new_protected:Npn \@@_function_aux:w #1#2 \q_stop
+ {
+ ...
+ }
+\end{verbatim}
+Where more than one auxiliary shares the same signature, the recommended naming
+scheme is \texttt{auxi}, \texttt{auxii} and so on.
+\begin{verbatim}
+ \cs_new_protected:Npn \@@_function_auxi:nn #1#2
+ {
+ ...
+ }
+ \cs_new_protected:Npn \@@_function_auxii:nn #1#2
+ {
+ ...
+ }
+\end{verbatim}
+The use of \texttt{aux_i}, \texttt{aux_ii}, \emph{etc.}\ is discouraged as this
+conflicts with the convention used by \cs{use_i:nn} and related functions.
+
+\end{document}