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