User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:8.0) Gecko/20111105
            Thunderbird/8.0
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Message-ID:  <4ED9ED20.40004@morningstar2.co.uk>
Date:         Sat, 3 Dec 2011 09:34:24 +0000
Reply-To: Mailing list for the LaTeX3 project
              <LATEX-L@listserv.uni-heidelberg.de>
Sender: Mailing list for the LaTeX3 project <LATEX-L@listserv.uni-heidelberg.de>
From: Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Documentation of local/global variants
To: LATEX-L@listserv.uni-heidelberg.de
Precedence: list
Status: R

Hello all,

Part of our recent efforts with LaTeX3 has been to improve the
documentation, adding in for example 'change dates' for functions in
l3kernel.

One area that I am not sure we have quite right at present is the
documentation of local/global variants. Where functions exist in both
local and global versions (for example \tl_set:Nn and \tl_gset:Nn),
there are currently separate documentation entries for the two cases.
This means that the scope of assignments can be clearly documented, but
does make for rather repetitive text.

A similar issue arises with the (TF) functions, where we have decided to
have a general statement about the nature of the two branches for the
entire content of interface3, and only to include information for
individual functions where a special case applies.

I wonder if it would make more sense to take the same approach for
functions with local/global versions. Something like:

'Where functions for variable manipulation can apply either locally or
globally, the latter case is indicated by the inclusion of a "g" in the
last part of the function name. Thus \tl_set:Nn is a local function but
\tl_gset:Nn acts globally. Functions of this type are always documented
together, and the scope of action may therefore be inferred from the
presence or absence of a "g".'

The scope would then be excluded from the function documentation:

% \begin{function}
%   {
%     \tl_set:Nn,  \tl_set:cn,
%     \tl_gset:Nn, \tl_gset:cn
%   }
%   \begin{syntax}
%     \cs{tl_set:Nn} \meta{tl~var} \Arg{tokens}
%   \end{syntax}
%   Sets \meta{tl~var} to contain \meta{tokens},
%   removing any previous content from the variable.
% \end{function}

Does this make sense as a sensible balance between formality and
documentation length?
--
Joseph Wright