diff options
author | Karl Berry <karl@freefriends.org> | 2015-09-06 23:19:17 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2015-09-06 23:19:17 +0000 |
commit | 3cb4e75696df6c7abebf17fbc606ca86dcdfb520 (patch) | |
tree | 729978e0726cdb9d9f34a3d2e249c71a82e07f97 /Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex | |
parent | 32f50b97c2ae44e93225d1024afab9727fc02e00 (diff) |
l3 (6sep15)
git-svn-id: svn://tug.org/texlive/trunk@38305 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 | 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. |