Lines: 54
References: <bs7n95ikt65p$.dlg@nililand.de> <4E5B6BF7.80208@morningstar2.co.uk>
            <CANQYN6w2ZrLzPY4UqJSwFU_A+Vfw=ApeYgPWjg1UVYTv-k-rew@mail.gmail.com> <eab99gnhctiy$.dlg@nililand.de>
            <4E5BA7FC.8060705@latex-project.org>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
User-Agent: 40tude_Dialog/2.0.15.41de
Message-ID:  <w20e629w9r1q$.dlg@nililand.de>
Date:         Mon, 29 Aug 2011 18:43:05 +0200
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: Ulrike Fischer <news3@NILILAND.DE>
Subject: Re: missing or unclear concept documentation
To: LATEX-L@listserv.uni-heidelberg.de
Precedence: list
Status: R

Am Mon, 29 Aug 2011 16:53:48 +0200 schrieb Frank Mittelbach:


>> (I'm starting to like expl3 quite a lot.
> 
> that's great, a lot of blood sweat and tears went into it (and some 
> people can tell you :-) )

>> But I'm still unsure about
>> the concrete meaning of some concepts, this make it a bit difficult
>> to decide in which part of the documentation to look for something.

> any identification of such parts you feel unsure about would be helpful 
> I guess. Might be difficult to articulate, but please try.

Well here some remarks. Please take into account that I didn't read
the documentation from begin to end but simply searched with the
help of the toc. In most cases imho a simple example would help a
lot (I solved quite a lot problems by looking in existings sty like
siunitx and fontspec). 

1. The first three paragraphs of l3tl: "token list variable" versus
"arbitrary token list". "list of items" versus "list of tokens"

2. Packages l3prop, l3keys, l3keyval: What is their relation?

3. l3seq. What is an sequence compared to a token list?

4. The introduction makes a difference between "functions" and
"variables" but doesn't say which package(s) deal with the one and
which with the other type. It would also help if there were a rule
of thump when a command without argument should be better defined as
a function and when as variable. 

5. In the clist package I was quite bewildered because they didn't
seem to be a command to actually *fill* a list. At the end I found
that I can add more than one item with 
\clist_put_left:Nn.


> Joseph is making quite some effort to improve on the overall 
> documentation but we are well aware that documentation of certain 
> general concepts is effectively missing or bad and I'm sure some 
> concepts we take for granted (having worked with it for quite a while) 
> may not at all be obvious to new users

Well every documentation can be improved. There are errors in
source3.pdf and there are things missing. But nevertheless at my
opinion the documentation if fantastic. Everytime that I had to look
in the conTeXt code I wish they would offer at least 10% of the code
documentation that is done by the latex team.

-- 
Ulrike Fischer