[Asterisk-doc] Is this being done?

[Leif Madsen - Certified Asterisk Consultant]

On Sat, 26 Feb 2005 12:46:17 +0100, Randy Resnick <randulo at ssl-mail.com> wrote:
> Hi all,

Ahoi!

> 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.
> 
> 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. Unfortunately the people who do the programming and write the
"documentation" or instructions, aren't always very clear (just ask
Jared). A better effort of trying to keep stuff like that up to date
is a logistical problem that I'm not sure the answer to. I've had
people saying things lately such as, "Documentation needs to be easier
to find" and "Asterisk needs more centralized documentation". Thats
what we're trying to do with the AstDocs project, unfortunately with
only a handful on contributors, those needing documentation far
outweigh those who can and will write it (although docs wouldn't be a
problem if the scales weren't tilted in such a way :))

> 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.

Jared is currently working on such an effort, so yes, there is a push
towards having something like this.

I spoke with Mark briefly, and he calls the :n:n a substring, so that
is what we're going to call it as well.

> 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.

I agree.  I've found myself trying to figure out how to do something
in the dialplan and making it very complicated until someone told me
about some unknown variable which would have made it simple.

Thanks for starting an intelligent discussion!
Leif Madsen.
http://www.asteriskdocs.org
http://www.leifmadsen.com