From 6ac3dbed4b71022bd6bb0cc25e8fc3df81198498 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Wed, 1 May 2024 03:00:54 +0000
Subject: CTAN sync 202405010300

---
 macros/latex/contrib/l3kernel/l3styleguide.tex | 303 -------------------------
 1 file changed, 303 deletions(-)
 delete mode 100644 macros/latex/contrib/l3kernel/l3styleguide.tex

(limited to 'macros/latex/contrib/l3kernel/l3styleguide.tex')

diff --git a/macros/latex/contrib/l3kernel/l3styleguide.tex b/macros/latex/contrib/l3kernel/l3styleguide.tex
deleted file mode 100644
index a2ffe8d770..0000000000
--- a/macros/latex/contrib/l3kernel/l3styleguide.tex
+++ /dev/null
@@ -1,303 +0,0 @@
-\iffalse meta-comment
-
-File: l3styleguide.tex
-
-Copyright (C) 2011,2012,2014-2024 The LaTeX 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
-
-   https://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}
-
-
-\title{%
-  The \LaTeX3 kernel: style guide for code authors%
-}
-\author{%
-  The \LaTeX{} Project\thanks
-    {%
-      E-mail:
-      \href{mailto:latex-team@latex-project.org}%
-        {latex-team@latex-project.org}%
-    }%
-}
-\date{Released 2024-03-14}
-
-\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 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 fewer than $80$ characters per line applies to the code
-itself as well as the surrounding documentation. A number of the general
-style principles 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 be 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 in general
-looks 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 interfaces at the document level (where trapping \cs{par} tokens
-may be appropriate) or where comparison to other code known not to be
-\enquote{long} is required (\emph{e.g.}~when working with mixed
-\LaTeXe{}/\pkg{expl3} situations).
-
-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 may be 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{DocStrip} 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}
-
-\subsection{Access from other modules}
-
-There may be cases where it is useful to use an internal function from
-a third-party module (this includes cases where you are the author of both
-but they are not part of the same \enquote{family}). In these cases, you should
-\emph{copy} the definition of the internal function to your code: this avoids
-relying on non-documented interfaces. At the same time, it is strongly
-encouraged that you discuss your requirements with the author of the
-code you need to access. The best long-term solution to these cases is for
-new documented interfaces to be added to the parent module.
-
-\subsection{Access to primitives}
-
-As \pkg{expl3} is still a developing system, there are places where direct
-access to engine primitives is required. These are all marked as
-\enquote{do not use} in the code and so require special handling. Where a
-programmer is sure that they need to use a primitive (for example where the
-team have not yet covered access to an area) then a local copy of the
-primitive should be made, for example
-\begin{verbatim}
-  \cs_new_eq:NN \__module_message:w \tex_message:D
-  % ...
-  \cs_new_protected:Npn \__module_fancy_msg:n #1
-    { \__module_message:w { *** #1 *** } }
-\end{verbatim}
-This approach makes it possible for the team and others to find such
-usage (by searching for the \texttt{:D} argument type) but avoids
-multiple uses in general code.
-
-At the same time, the team ask that these use cases are raised on the
-\texttt{LaTeX-L} mailing list. The team are keen to collect use cases for
-areas that have not yet been addressed and to provide new code where the
-required interfaces become clear.
-
-Programmers using primitives should be ready to make updates to their
-code as the team develop additional interfaces.
-
-\section{Auxiliary functions}
-
-In general, the team encourages the use of descriptive names in \LaTeX3 code.
-Thus many helper functions would 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.
-
-\section{Functions with `weird' arguments}
-
-When defining commands that do not follow the usual convention of accepting
-arguments as single-tokens or braced-text, the \verb|w| argument specifier
-is used to denote that the function signature cannot fully describe the syntax.
-Two examples from the \LaTeX3 kernel are:
-\begin{quote}
-\verb|\use_none_delimit_by_q_stop:w| $\langle$\,\emph{text}\,$\rangle$ \verb|\q_stop|\\
-\verb|\use_i_delimit_by_q_stop:nw| \char`\{ $\langle$\,\emph{arg}\,$\rangle$\char`}\,$\langle$\,\emph{text}\,$\rangle$ \verb|\q_stop|
-\end{quote}
-More complex definitions are possible if commands are to parse tokens,
-such as the internal kernel command
-\begin{verbatim}
-    \cs_new_protected:Npn \__clist_get:wN #1 , #2 \q_stop #3
-      { \tl_set:Nn #3 {#1} }
-\end{verbatim}
-When the \verb|w| specifier is being used, it is encouraged not to try
-and complicate the rest of the signature too much---for example, it
-would be considered poor style to have a function with a signature like
-\verb|\foo_bar:wnw| unless there were very clear reasons of code clarity.
-A signature such as \verb|:ww| would certainly be discouraged.
-
-Examining the examples above, it can be seen that there are scenarios in
-which it may make logical sense for having a signature such as \verb|:wN| or
-\verb|:nw|, but when in doubt the recommended approach is to simply use
-\verb|:w| as a catch-all.
-
-\end{document}
-- 
cgit v1.2.3

