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

[Leif Madsen]

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

Right, but if someone is actually going to READ this book, I feel that
the layout would probably be better suited for someone reading straight
through to explain what contexts, includes, priorities and the like
before you delve into a working extensions.conf.  If all they want to
get is just say "hey.. it works!" then they could just as easily skip
this section and go onto the working example... ?


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

I think console calls seem a bit beyond the scope of this section.. ?

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

Also agreed.  I prefer comma seperated values, such as
Dial(foo,bar,widget)

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

Hard to say.  I can see this chapter getting rediculously large already,
and think that a basic and advanced chapter might not be such a bad
idea.  It will also make it easier for the user to navigate if they have
already done the basics, to get right to the advanced stuff if they come
back at a later time.  Might be easier for them not to have to wade half
way through a chapter just to find what they want, when they already
know what they are looking for.

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

I think printed example configurations could be a very good thing in a
book, just like I have in my Linux IPTable Firewall book.  The website
does have links to the scripts used in the book on a website so that
they can be updated, and also downloaded (who wants to type out a script
in a book that is several pages long???).  But then again, they are in
the book as well so that you can follow along with them and read them. 
Long sample files might be better in an appendix though away from the
main chapter which should be more educational text.

> 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've avoided doing the outline because I'm not sure I would make it
better :)  If no one else does it, I suppose I'll give it a shot, but
I'll leave it to the professionals for now.

-- 
Leif Madsen <leif@hacklocalhost.com>
http://www.hacklocalhost.com