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