Sender: |
|
Date: |
Sat, 3 Dec 2011 12:25:38 +0100 |
Reply-To: |
|
Message-ID: |
|
Subject: |
|
MIME-Version: |
1.0 |
Content-Transfer-Encoding: |
7bit |
In-Reply-To: |
|
Content-Type: |
text/plain; charset=ISO-8859-1; format=flowed |
From: |
|
Parts/Attachments: |
|
|
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
|
|
|