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>           
            <4EDA0732.5060003@latex-project.org>           
            <4EDB8079.6000707@morningstar2.co.uk>
            <CANQYN6ymdUs39RamVCK_MpUMx9S8a4D+yZE0G8-nJOAb_NUNFw@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Message-ID:  <4EDBE96A.10806@latex-project.org>
Date:         Sun, 4 Dec 2011 22:43:06 +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:  <CANQYN6ymdUs39RamVCK_MpUMx9S8a4D+yZE0G8-nJOAb_NUNFw@mail.gmail.com>
Precedence: list
Status: R

Am 04.12.2011 21:16, schrieb Bruno Le Floch:

>> 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.
>
> Side note: \prop_gget:NnN doesn't and shouldn't exist. We may want to
> add somewhere a mention that 'pop' and 'gpop' functions always return
> their value locally.

agreed, we decided long ago that all "get" or "pop" would be local in 
their return value and only in case of "pop" the change to the 
underlying data structure could be global.

So yes that should probably better documented up front as well.


> =
> Where functions for variable manipulation can [perform assignments]
> either locally or
> globally, the latter case is indicated by the inclusion of a "g" in the
> [second 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".

sounds good to me

cheers
frank