diff options
author | Karl Berry <karl@freefriends.org> | 2012-02-06 01:22:10 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-02-06 01:22:10 +0000 |
commit | 88ad42f78998b5210fa58a05e2e7750f897b2550 (patch) | |
tree | 6faffeb117d275760dd935be86714b25013bcec3 /Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex | |
parent | 6406190e2336a4aa3036d7d8943c14c02a4ccadf (diff) |
l3kernel 3287
git-svn-id: svn://tug.org/texlive/trunk@25306 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.tex | 174 |
1 files changed, 174 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..c14d7d8eefd --- /dev/null +++ b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex @@ -0,0 +1,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: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} |