User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:8.0) Gecko/20111105
            Thunderbird/8.0
MIME-Version: 1.0
References: <4ED9ED20.40004@morningstar2.co.uk>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Message-ID:  <4EDA0732.5060003@latex-project.org>
Date:         Sat, 3 Dec 2011 12:25:38 +0100
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: Frank Mittelbach <frank.mittelbach@LATEX-PROJECT.ORG>
Subject: Re: Documentation of local/global variants
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <4ED9ED20.40004@morningstar2.co.uk>
Precedence: list
Status: R

Am 03.12.2011 10:34, schrieb Joseph Wright:

> 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?

I would be quite happy with this approach of documenting local and 
global variants in a single place together as the convention is in 
nearly all cases very clear and the use of "g" or its absence 
understandable without further explanation (other than at the very 
beginning outlining the approach). And in the few cases where the "g" 
may need additional explanation because it could refer to one or the 
other argument that could still either be done on the spot or if 
necessary in that case split into separate documentation blocks.

So yes I would agree to that approach. I do see however a dependency on 
the other suggestion made (in a separate email) on dropping the 
documentation of arg manipulating variants so before anything got 
changed I think both need to be looked at together.

frank