[asterisk-dev] Command Syntax -- weird?

[Tilghman Lesher]

On Monday 24 April 2006 12:01, Peter Beckman wrote:
> On Sun, 23 Apr 2006, Tilghman Lesher wrote:
> >> 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 |?

No, the '|' character has always been the canonical way to delimit
parameters.

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

In this case, the Wiki was simply wrong, not out of date.  Fixed.

>   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 current version of the Asterisk Handbook does indeed document
the Dial command, as you have noted below.

>   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

Commas are translated to vertical bars during the load of
extensions.conf.

>   Also, is this the recommended format for passing arguments to
> applications?
> http://www.digium.com/en/docs/asterisk_handbook/answer_hangup_congest
>ion_busy.html
>
>      Exten => s,2,MP3Player,southside.mp3
>
>   or is this
>
>      Exten => s,2,MP3Player(southside.mp3)

Both will work from extensions.conf.  The first way is the canonical
way; the second way is the syntactic equivalent that makes it easier to
read in extensions.conf.  Note that you cannot use commas from the
realtime database, nor do they appear if you execute 'show dialplan'
from the command line.

>   The asteriskdocs.org points to the Asterisk Wiki as a "must read"
> yet it is mostly out of date!

I still don't see how it is out of date.

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

That's fine.  You are not going to change the format of a label,
however, so you can pretty well just document it and be done.

-- 
Tilghman