diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex | 39 |
1 files changed, 38 insertions, 1 deletions
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex index c37c9e24dff..690168a4778 100644 --- a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex +++ b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex @@ -1,6 +1,6 @@ \iffalse meta-comment -File l3styleguide.tex Copyright (C) 2011,2012 The LaTeX3 Project +File l3styleguide.tex Copyright (C) 2011,2012,2015 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 @@ -203,6 +203,43 @@ then written in the form ... \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. |