[asterisk-dev] Command Syntax -- weird?

[Peter Beckman]

On Sat, 22 Apr 2006, Tilghman Lesher wrote:

> On Friday 21 April 2006 22:34, Peter Beckman wrote:
>> Is there any reason why Asterisk has chosen such strange and
>> inconsistent methods of passing variables to functions?
>
> Understanding the history will probably open your eyes.
>
>> VoiceMail([flags]boxnumber[@context][&boxnumber2[@context]][&boxnum
>> ber3])
>
> The initial syntax for Voicemail was Voicemail([flags]boxnumber).
> That's it.  There was no context and no multiple mailboxes.  The
> first thing that was added was a context.  So that's simple enough:
> Voicemail([flags]boxnumber[@context]).  From there, we added multiple
> mailboxes, which is how we have the current syntax.  Please note that
> the flags have already been moved to the end for the 1.4 release,
> although flags at the beginning are still accepted for backwards
> compatibility.

  Excellent!  Will they be delimited?  Ie:

  VoiceMail(123 at foo & 456 at bar, su)

>>      Goto([[context|]extension|]priority)
>
> It's always been this way, and it will likely always be this way.  I
> don't see a commanding reason why it ought to change, when any such
> reason must balance against backwards compatibility.
>
>> RetryDial(announce|sleep|loops|Technology/resource[&Technology2/res
>> ource2...[|timeout[|options[|URL]]]])
>
> RetryDial was based upon Dial.  The developer of that app chose to
> prefix the arguments to the Dial command, rather than to add them as
> suffixes.  I can't say I necessarily agree with this approach, but
> it's over and done now.  In any case, since it's a distinct dialplan
> application, it's not nearly that bad.

  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.

>> Something where every time I specify the first parameter, I always
>> know what it is.  Currently if I add on things to Goto, the first
>> parameter could be a priority, an extension or a context.  Who
>> knows!  Sure, obviously you can tell, but I guess I'm asking why!
>
> As above, it's always been that way, and there hasn't been an
> overriding reason to change it.

  Not even to unify the codebase?

>> BTW, the only reason this really has become clear is because I'm
>> working on PHP-like documentation for Asterisk.  OK, I just stole
>> what PHP did and made it for Asterisk.  I'm not nearly done, but
>> the framework is there for review:
>>
>>      http://mph.gotdns.com:82/manual/en/index.php
>>
>> The lack of consistency in function attributes makes it more
>> difficult to document!
>
> First of all, I would encourage you to work with the current Asterisk
> Documentation Project, rather than to duplicate efforts.  Obviously,
> you've already found http://www.asteriskdocs.org, as your current
> content is a duplicate of that page.

  I did -- the lead folk said they've all been busy and encouraged me to do
  so.  I'm doing this as part of the asteriskdocs.org.

> Second, what you're calling function attributes are actually
> application arguments.  Using consistent language in documentation
> is one of the keys to making sure your audience doesn't get more
> confused, at worst, and understands, at best.

  I completely agree.  The problem is that the documentation for Asterisk is
  extremely fragmented and inconsistent.  My goal with the documentation
  above is twofold -- a unified, single source of documentation for Asterisk
  (not a wiki, which is fine, but again, several voices and several formats
  and inconsistent documentation updating means confusion and unprofessional
  face), and a method of writing documentation that extends itself for
  translation and fast updating.

  Right now, there is the wiki on voip-info, there are several other sites
  that attempt to document AGI calls, there is the asteriskdocs.org book,
  but no definitive function reference.  In fact, I've read posts from users
  who say they can't figure out what the function call should do in which
  version!

  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.

Beckman
---------------------------------------------------------------------------
Peter Beckman                                                  Internet Guy
beckman at purplecow.com                             http://www.purplecow.com/
---------------------------------------------------------------------------