[Asterisk-doc] "The Extensions.conf Cookbook" chapter

[Jared Smith]

On Mon, 2003-12-29 at 21:55, Steven Critchfield wrote:
> I think I am going to repeat some of what Lief has said.
> 
[snip]
> I think that extensions.conf is more important than the channel
> definitions. You can gloss over the channels in the Dial commands, but I
> think it will be important to have a solid knowledge of contexts. It
> will make more sense when you start explaining about the channels and
> VoIP user definitions when you are trying to put them in the appropriate
> context. It allso eliminates the need to have a basic extensions.conf
> file that you can't really explain other than this is how it makes a
> phone ring.

Hmmmn... I 100% agree that a "solid knowledge of contexts" is the *most*
important thing to understanding extensions.conf.  But at the same time,
I want to give the impatient Asterisk newbie a *very simple*
extensions.conf file that just makes a phone ring, so that they can say
"Hey! Look!  I finally got Asterisk working!"  

I shudder to imagine how many people have never gotten to the "I can
make a phone ring" stage and given up... I know I almost did on more
than one occasion.

> 
> While I admit that one or the other is just academic discussions until
> you can combine a phone with a dialplan. Maybe the best part would be to
> explain how to make a console call first since a new user is more likely
> to have a sound card that functions enough to walk their way around an
> extensions.conf file. 

Console calls (at least from my experience a year and a half ago) are a
pain in the backside.  But maybe they actually work well now...

> 
> >   The Extensions.conf File
> >      Contexts ((why to separate))
> >      Includes ((how to reduce typing))
> >      Macro's ((how to write them - Include with above?))
> >      Variables ((extra data))
> >      Call flow ((putting it together))
> >      Special extensions (I,T,S)
> >      More advanced applications calls ((Asterisk allows for a lot of
> > different formats for calling apps))
> 
> It might be a good idea to pick Marks brain and see if the function
> style is the preferred method for the future and stick to just that
> method. Maybe a note about old methods, but all examples should fit to
> the preferred method. It ties into my comment about consistent spelling
> and capitalization. It should be fairly difficult to tell where
> different authors start and stop other than maybe a few nuances in word
> choice or sentence structure.

Agreed. Do we do Dial(foo|bar|widget) or Dial(foo,bar,widget) or
Dial,foo,bar,widget?  I know which one I prefer... What do the rest of
you think?

> 
> >   Asterisk Add-On Applications
> >      Playback()
> >      Record()
> >      GotoIf()
> >      Cut()
> >      Authenticate()
> >      VoiceMail2
> >      ZapBarge()
> >      ... etc
> > Advanced Concepts: a.k.a. "The Cookbook"
> >      Building IVR
> >      Bringing in the DB
> >      DISA
> >      Music On Hold: The moh.conf File (already in Chap. 7?)
> >      Voicemail: The voicemail.conf File
> >      MeetMe: The meetme.conf File
> >      Any number of other neat tricks to go along
> 
> Maybe this should be a separate chapter as it may tie in other conf
> files that either are not described at this point or concepts to be
> explained later. My opinion is that the cookbook section should be like
> a gentle push into some advance concepts that should be mostly obvious
> by having the basics down perfect.  

Maybe we need two cookbooks... a "Gentle Examples for Beginning Cooks"
chapter and a "Awesome Recipes for Experienced Chefs" chapter?  Or
should we just make one giant cookbook, that starts off simple and then
gets hairy at the end?

> 
> > Configuring Channels
> >   The PBX Side of Asterisk
> >      Zaptel cards and config
> >      Configurating Zapata
> >      Channel Banks
> >      PRI/Channelized Voice T1s
> >      CAPI/ISDN
> >      ... etc
> >   The VoIP side of Asterisk
> >      Configurating SIP
> >      Configurating IAX
> >      Configurating H323/OH323
> >      ... etc
> >   Sample Configurations (Working Sample Configurations)
> 
> While this might be helpful, but in a print form this is a lot of space
> that is not much more than what the cookbook and a few pieces will be.
> Not to mention there is a sample that comes with the asterisk source. 

Unfortunately, the sample that comes with the asterisk source has very
little explanation.  Somewhere in the book we should have a couple of
well-documented sample configurations, so that people can at least get
to the "Look! I made a phone ring!" stage.  I don't really care if this
gets pushed to an Appendix or maybe even just the website... but it
ought to be *somewhere*.  (Or, maybe we just point them to one of the
other third-party Asterisk websites?!?)

Again, the reason I keep re-hashing this outline is that this part of
the book is going to be *absolutely vital*.  Would someone mind writing
another version of this outline incorporating the thoughts expressed
above?


Jared Smith