[asterisk-dev] Command Syntax -- weird?

[Tilghman Lesher]

On Sunday 23 April 2006 18:46, Peter Beckman wrote:
> On Sat, 22 Apr 2006, Tilghman Lesher wrote:
> >> It must add a lot of code to parse out all of that stuff, and
> >> having an inconsistent method of calling functions make both
> >> documentation confusing and the user/admin confused.  It makes
> >> Asterisk seem cobbled together, and though it may be, the
> >> disconnect between a unified code front seems like more of a
> >> hack, rather than the production-ready and profesional front I
> >> think Asterisk really has.
> >
> > I don't see how this has anything to do with an inconsistent
> > method of calling applications (again, these are applications,
> > not functions; functions are something different).  The method of
> > calling applications is entirely consistent.  The order of the
> > arguments to the application is what you appear to have trouble
> > understanding.
>
>   Sorry, I'm new to Asterisk, so my name-calling :-) seems to be
> inaccurate.
>
>   I didn't mean internally to Asterisk, I meant as an end-user of
> Asterisk. The fact that required parameters passed to an
> application sometimes come at the beginning

> sometimes in the middle,

What application does this?

> and sometimes at the end seems to be inconsistent.  The 

Labels are pretty much the only construct which are parsed right
to left, and they are always done in a way that is clear and
unambiguous.

> fact that flags to voicemail (though you point out that his is
> changing - sweet!) are part of the mailbox# string is confusing
> when the Dial flags are a comma delimited part of the parameters. 
> That's what I meant, though I hope I've explained it better here.
> :-)

The Dial flags are NOT a comma-delimited list.  In fact, none of the
applications currently use a comma to delimit arguments.  They instead
use a vertical-bar-delimited list (except for things like conditionals
which use ternary delimiters ('?' and ':')).

> >>   Not even to unify the codebase?
> >
> > Labels are already consistent across the codebase.  What you're
> > having trouble with is understanding that labels are parsed
> > right-to-left. This isn't an inconsistency -- it's simply
> > different from how other types of arguments are parsed.
>
>   I can understand right-to-left, but then wouldn't all required
>   parameter(s) be the last parameter(s) passed to the application,
> and the optional parameters be listed first?  That's not the case
> with Dial(), right?

Dial is entirely consistent with other applications, in that arguments
are parsed left to right.  Labels are parsed right-to-left, but they
are always present in a location which disambiguates the possibility
of other arguments.  For example, GotoIf is the prime example of where
a label is used:

GotoIf(1?34:s,1)

GotoIf is first parsed using the ternary operators ('?' and ':').
Once this is done, the only things left in the second and third
pieces are labels.  There are no other arguments possible in these
arguments, so parsing this construct right-to-left is not confusing.

> >> I think Asterisk is a great tool, and very powerful, but without
> >> good, solid, accurate and up-to-date online web-based
> >> documentation, it is a tool for the tinkerer, not the masses.
> >
> > I think you've just made an argument for why the coders behind
> > the project should boot the documenters.  :-)  I'm not saying we
> > should do that, but Asterisk has always been for the tinkerer; it
> > will never be for the masses.  This is the concept that a lot of
> > people seem to have trouble understanding -- the community of
> > developers that support an open source project do so for their
> > mutual benefit, not to create a super-polished application that
> > the typical computer user can use.
>
>   That's disappointing.  The voip-info wiki seems to be a cry for
> good documentation.  The docs there are inconsistent, usually out
> of date, and are difficult at times to understand.  But that's the
> best documentation Asterisk has -- documentation written by a bunch
> of people, developers and users, who benefit enough from Asterisk
> to be willing to document this software for free, anonymously.

Which docs, specifically, are out of date?  I'll admit that the Wiki
tends to be disorganized, but I rarely find documentation which is
out of date.

>   It seems a lot of hard work goes into Asterisk by its developers.
>  Many businesses, including mine, rely on Asterisk every day.  The
> VoIP world is growing at a phenomenal rate, and Asterisk seems like
> the perfect glue to bring it all together, for businesses,
> tinkerers, and for the geeky homeowner.

Exactly.  And this time, you left out the masses, which was my point.
Asterisk will always be for a self-selected few who wish for one
reason or another to run a PBX.  This has never included the general
populace, and I doubt it ever will.

>   I think Asterisk deserves to have great, polished documentation,
> and I think the effort to make Asterisk "a super-polished
> application" is very little.  It seems to be pretty well polished
> already -- it sure hasn't crashed on me yet.

There's a difference between polished and stable.  An application
can easily be polished and yet be unstable -- see pretty much any
commercial software that has ever crashed on you for an example.  In
Asterisk, we have an application which is stable but not polished.  I
think that's exactly where we need to be.

>   Is there some sort of general desire to keep Asterisk from being
>   "super-polished?"

-- 
Tilghman