LATEX-L Archives

Mailing list for the LaTeX3 project

LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

Options: Use Forum View

Use Monospaced Font
Show HTML Part by Default
Condense Mail Headers

Message: [<< First] [< Prev] [Next >] [Last >>]
Topic: [<< First] [< Prev] [Next >] [Last >>]
Author: [<< First] [< Prev] [Next >] [Last >>]

Print Reply
Content-Type:
text/plain; charset=ISO-8859-1
Date:
Sat, 3 Dec 2011 09:34:24 +0000
Reply-To:
Mailing list for the LaTeX3 project <[log in to unmask]>
Subject:
MIME-Version:
1.0
Message-ID:
Content-Transfer-Encoding:
7bit
Sender:
Mailing list for the LaTeX3 project <[log in to unmask]>
From:
Joseph Wright <[log in to unmask]>
Parts/Attachments:
text/plain (47 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

ATOM RSS1 RSS2