MIME-Version: 1.0
References: <4ED9ED20.40004@morningstar2.co.uk>
            <4EDA0732.5060003@latex-project.org>
            <4EDB8079.6000707@morningstar2.co.uk>
Content-Type: text/plain; charset=ISO-8859-1
Message-ID:  <CANQYN6ymdUs39RamVCK_MpUMx9S8a4D+yZE0G8-nJOAb_NUNFw@mail.gmail.com>
Date:         Sun, 4 Dec 2011 15:16:20 -0500
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: Bruno Le Floch <blflatex@GMAIL.COM>
Subject: Re: Documentation of local/global variants
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <4EDB8079.6000707@morningstar2.co.uk>
Precedence: list
Status: R

On 12/4/11, Joseph Wright <joseph.wright@morningstar2.co.uk> wrote:
> 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.
>
> 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.

I agree on having a general statement about local and global
assignments, since there are very few cases where it does not apply.
However, the "g" is not in the last part but in the second part
(\tl_gput_right:Nn, \char_gset_catcode_group_begin:N). Also, I'd
prefer something a little bit more specific than "can apply", replaced
below by "perform assignments", I think that this is the only
situation in which there is such local versus global functions.

=
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".
=

Regards,
Bruno