## 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:

Documentation of local/global variants

From:

Mailing list for the LaTeX3 project <[log in to unmask]>

Date:

Sat, 3 Dec 2011 09:34:24 +0000

Content-Type:

text/plain

Parts/Attachments:

 text/plain (46 lines)
 Hello all, Part of our recent efforts with LaTeX3 has been to improve the documentation, adding in for example 'change dates' for functions in l3kernel. One area that I am not sure we have quite right at present is the documentation of local/global variants. Where functions exist in both local and global versions (for example \tl_set:Nn and \tl_gset:Nn), there are currently separate documentation entries for the two cases. This means that the scope of assignments can be clearly documented, but does make for rather repetitive text. A similar issue arises with the (TF) functions, where we have decided to have a general statement about the nature of the two branches for the entire content of interface3, and only to include information for individual functions where a special case applies. 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? -- Joseph Wright