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

[Steven Critchfield]

On Tue, 2003-12-30 at 11:16, Jared Smith wrote:
> 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.

Not to be cruel or too elitist, but technology is not always all
inclusive. Technology providers require a certain amount of intelligence
and/or effort. This is why there is a difference between those who seek
out information and those who have to pay for it. At some point you have
to realize that there are users who you don't want as peers, but rather
customers. 

I think that if someone was to go to the effort of obtaining then
reading this book/manual they will stick through a few more pages to get
the knowledge right. Before giving up due to not enough knowledge to
make their phone ring. This section shouldn't need to be very long, but
cover the important parts first.  

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

maybe as a end to end solution it is a pain, but as a minimum no real
configuration item, I think it would work well if you had to have a user
interactive section. The trick of this is making the examples be
basically easy to implement with all transports.

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

Function style with commas I believe is the preferred method now, but I
may be wrong. If it is the currently preferred method, it is likely to
survive a few extra revisions.  

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

Well a simple examples section could tie in really well after the
channels are defined. This takes it from all the academic learning to a
working minimal system. Afterwords you could delve into the more
interesting examples or cookbook. I think it is a balancing act of
getting enough base down before turning a person loose to a config file
of their own and having too much data that bores the user before they
get to play with the system.   

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

I don't think you have any arguments against you there. I think we all
agree this section is the make or break section. 
-- 
Steven Critchfield  <critch@basesys.com>