[asterisk-dev] Command Syntax -- weird?

[Peter Beckman]

On Sun, 23 Apr 2006, Tilghman Lesher wrote:

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

  From app_dial.c I see that announce, sleep and retries are all required.
  The wiki, clearly out of date, lead me astray.

  My bad, I recind my earlier comment.  I'll stop using the wiki.

>> 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 ':')).

  I must have been confused the exten=> formatting and the application
  argument formatting.  Again, you have pointed out my wrongness, and I am
  indeed wrong.  Damnit!  :-)

  Were they in 1.0.10?  I wrote a dial plan for 1.0.10 that had commas
  separating the Dial parameters, and it worked... did it change at some
  point in the last months/years to standardize on the |?

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

  Again, I think my confusion is the documentation on the voip-info wiki.
  It is incorrect and clearly out of date.

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

  What other documentation is there?  There is the Asterisk book, the
  voip-info wiki, and the show application documentation.

  RetryDial mentioned on the Dial cmd page is wrong, and on the same page,
  the parameters use commas to delimit the timeout, options and URL, and
  make it seem they are all required, while clearly from the code they are
  not:

     http://www.voip-info.org/wiki/index.php?page=Asterisk+cmd+Dial

  The documentaiton link on Asterisk.org takes me to "The Asterisk Handbook"
  which hasn't been edited since 3/30/03.  It doesn't document the Dial
  command.

  The Digium.com docs use a comma and no parenthesis, and in Firefox and IE
  there are strange characters displayed:

     http://www.digium.com/en/docs/asterisk_handbook/dial.html

  Also, is this the recommended format for passing arguments to applications?
  http://www.digium.com/en/docs/asterisk_handbook/answer_hangup_congestion_busy.html

     Exten => s,2,MP3Player,southside.mp3

  or is this

     Exten => s,2,MP3Player(southside.mp3)

  You said earlier that commas are not used, yet the docs here make it seem
  that they are:
     http://www.digium.com/en/docs/asterisk_handbook/playback_background_record_echo.html

  The asteriskdocs.org points to the Asterisk Wiki as a "must read" yet it
  is mostly out of date!  The book, "Asterisk: The Future of Telephony" is a
  great read, but it is not a reference manual.

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

  Sure, my grandmother may use Office, but more than likely she won't use
  Asterisk.  Is that a reason to not have better documentation?

  Asterisk.org only lists the digium online documentation as the only docs
  for Asterisk, and they aren't comprehensive at all.  They are also kind of
  hard to navigate, IMO.  I think it can be better.

>>   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.
>>
>>   Is there some sort of general desire to keep Asterisk from being
>>   "super-polished?"
>
> 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.

  I love that Asterisk is stable.  To be polished takes no more development
  effort.  I want to make Asterisk polished by having a documentation group
  that keeps up-to-date, in-lock-step-with-development docs online that can
  be easily republished into a PDF, into HTML and included with the distro,
  whatever.

  The best application in the world is lacking without good documentation.

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