[Asterisk-doc] Is this being done?

[Jared Smith]

On Sat, 2005-02-26 at 12:46 +0100, Randy Resnick wrote:
> Now, to my point. Sometimes, it isn't easy to search for stuff that has 
> no name. Example, suppose you know or have seen ${EXTEN:2:5} but don't 
> know what the second number means. I tried to search for this, first by 
> looking for the old ways like "stripLSD+deprecated". Unfortunately, the 
> stuff that came up showed that much and no more.

I know exactly what you mean, as just a couple of weeks ago I went
searching for that very thing, in an effort to document it better.  Leif
found that that not only was it not documented, but it had a serious bug
in it as well.  I still don't know what to call it, but it is being
documented as part of our project.  It's also been added to Asterisk's
documentation (see below).

> 
> Shouldn't the new solution always be mentioned when something is no 
> longer used instead of saying, "oh that's deprecated, don't use it!" ? 
> Thats' about as useful as "this has been discussed many times" in the 
> mailing list :)

I agree.  I hope to get the docs to the point where we can point people
to "see section 4.3 in the docs" instead of "RT(non-existant)M".

> 
> Part two, is there an effort to have the *definitive* text on variables, 
> which would include *all* the related expressions like :n:n (you see, 
> what *is* that called?) If it were a function it'd be SubStr(). So, is 
> the section on variables going to have every bit of knowledge there is 
> to know about the current use of variables? I don't think it does now, 
> but I haven't looked for a while.

Currently, the best we have is the README.variables file in the doc/
subdirectory of the Asterisk source.  Luckily, Olle was kind enough add
documentation for the ${EXTEN:-5:3} syntax when we fixed the bug that
Leif found.  

> 
> If a subject with such limited scope (variables - no pun intended) isn't 
> completely covered, then people asking the simple dialpaln questions on 
> IRC can say "I already read all those" with impunity and it makes for a 
> lot of unanswered questions.

You've cut to the heart of the reason we started the documentation
project.  And just so you know, we are still working hard behind the
scenes on getting these sorts of things documented.  Thanks for keeping
us focused on making sure the simple things are well-documented.  We
appreciate your input!

-Jared