summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-01-19 22:49:13 +0000
committerKarl Berry <karl@freefriends.org>2012-01-19 22:49:13 +0000
commit17d590a6bcf898806aeec2d7aa57d641a440ca10 (patch)
treedd82ac37aed8f78a0eca38ab7b5c1250b6585fef /Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
parent2648c52105e48119c27762f885fefa29d172b38b (diff)
l3kernel 3209 (19jan12)
git-svn-id: svn://tug.org/texlive/trunk@25157 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.tex174
1 files changed, 0 insertions, 174 deletions
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
deleted file mode 100644
index c14d7d8eefd..00000000000
--- a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
+++ /dev/null
@@ -1,174 +0,0 @@
-\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}