User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:14.0)
            Gecko/20120713 Thunderbird/14.0
MIME-Version: 1.0
References: <CAFUtaNEaKH3f88CF2TALs+ud9Y1MaaLLp4wjre7KAj+fUeu1-A@mail.gmail.com>           
            <5032A298.9000004@morningstar2.co.uk>
            <CAFUtaNGKU_QOF-A60CK9xHdyY5_ugkvWJyvEWXBY0SmdPgSv8A@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Message-ID:  <50334CFD.1040808@morningstar2.co.uk>
Date:         Tue, 21 Aug 2012 09:55:25 +0100
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: Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: l3doc: \tn vs. \cs
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <CAFUtaNGKU_QOF-A60CK9xHdyY5_ugkvWJyvEWXBY0SmdPgSv8A@mail.gmail.com>
Precedence: list
Status: R

On 20/08/2012 23:08, Joel C. Salomon wrote:
> I'm afraid I'm still seeing an ambiguity.
> 
> For xpeek, I've put almost all command-words not defined in the
> package itself into \DoNotIndex. And actually, the only LaTeX2e
> commands I talk about are \textit, \nocorrlist, \xspace, and
> \xspaceaddexceptions; if (for example) some formatting difference were
> to be applied to LaTeX2e commands, these would be good candidates for
> such.
>
> On the other hand, I'm using qstest's \Expect (LaTeX2e), as well as a
> wrapper (\ExpectIdenticalWidths) I'm defining with xparse's
> \NewDocumentCommand.  Does it make sense for me to index and/or
> display these at all differently?
> 
> On the gripping hand, I imagine that on the wish list for \cs is some
> intelligence to index variables and namespaced functions separately.
> (E.g., \l_tmpa_bool nowhere near \lua_now:n, but \__int_eval:w
> somewhere close to \int_eval:n.)  By this token, user commands might
> well go elsewhere entirely.  If \cs="command sequence" and \tn="TeX
> name", perhaps \uc="user command"?
We've not used \DoNotIndex at all in the team's LaTeX3 code, so our
indexes show every command. We've not actually discussed this as a
policy, but one can see an argument for indexing everything, as
definition and use will be separate in any case. At least part of an
argument here is that for 'users' you should not need to typeset the
code part, so the index will not show stuff from outside a module anyway.

We've used \tn almost entirely within the implementation part of a .dtx,
with mainly \cs in the documentation part. (We've also use verbatim for
cases where the cs should not be indexed at all.) There, \tn is used for
primitives and things which are clearly 'LaTeX2e-based', such as
\@ifnextchar, rather than 'LaTeX interface' based, such as \textit. (I'd
expect the latter to remain in a stand-alone LaTeX3 format.)
--
Joseph Wright