User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:8.0) Gecko/20111105
            Thunderbird/8.0
MIME-Version: 1.0
References: <4ED9ED20.40004@morningstar2.co.uk>
            <4EDA0732.5060003@latex-project.org>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Message-ID:  <4EDB8079.6000707@morningstar2.co.uk>
Date:         Sun, 4 Dec 2011 14:15:21 +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: Re: Documentation of local/global variants
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <4EDA0732.5060003@latex-project.org>
Precedence: list
Status: R

On 03/12/2011 11:25, Frank Mittelbach wrote:
> 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.

Hello Frank,

Yes, there are a few cases where such a convention would not be
sufficient, for example \prop_(g)get:NnN. As I said, this mirrors the
situation with TF functions, where there are a few in which the
documentation does have to cover more complex situations on a
case-by-case basis.
--
Joseph Wright