## LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

#### View:

 Message: [ First | Previous | Next | Last ] By Topic: [ First | Previous | Next | Last ] By Author: [ First | Previous | Next | Last ] Font: Proportional Font

Subject:

Re: Documentation of local/global variants

From:

Date:

Sat, 3 Dec 2011 12:25:38 +0100

Content-Type:

text/plain

Parts/Attachments:

 text/plain (44 lines)
 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