Index: doc/CODING-GUIDELINES
===================================================================
--- doc/CODING-GUIDELINES	(revision 107000)
+++ doc/CODING-GUIDELINES	(working copy)
@@ -1,6 +1,5 @@
-	    --------------------------------------
-	    == Asterisk Coding Guidelines ==
-	    --------------------------------------
+Asterisk Coding Guidelines
+--------------------------
 
 This document gives some basic indication on how the asterisk code
 is structured. The first part covers the structure and style of
@@ -27,19 +26,18 @@
 Patches should be in the form of a unified (-u) diff, made from a checkout
 from subversion.
 
-/usr/src/asterisk$ svn diff > mypatch
+  /usr/src/asterisk$ svn diff > mypatch
 
 If you would like to only include changes to certain files in the patch, you
 can list them in the "svn diff" command:
 
-/usr/src/asterisk$ svn diff somefile.c someotherfile.c > mypatch
+  /usr/src/asterisk$ svn diff somefile.c someotherfile.c > mypatch
 
-		-----------------------------------
-		==  PART ONE: CODING GUIDELINES  ==
-		-----------------------------------
 
-* General rules
----------------
+PART ONE: CODING GUIDELINES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+General rules
+^^^^^^^^^^^^^
 
 - All code, filenames, function names and comments must be in ENGLISH.
 
@@ -59,15 +57,15 @@
 - Use spaces instead of tabs when aligning in-line comments or #defines (this makes 
   your comments aligned even if the code is viewed with another tabsize)
 
-* File structure and header inclusion
--------------------------------------
 
+File structure and header inclusion
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Every C source file should start with a proper copyright
 and a brief description of the content of the file.
 Following that, you should immediately put the following lines:
 
-#include "asterisk.h"
-ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
+  #include "asterisk.h"
+  ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 
 "asterisk.h" resolves OS and compiler dependencies for the basic
 set of unix functions (data types, system calls, basic I/O
@@ -115,8 +113,8 @@
 explain why you need it.
 
 
-* Declaration of functions and variables
-----------------------------------------
+Declaration of functions and variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - Do not declare variables mid-block (e.g. like recent GNU compilers support)
   since it is harder to read and not portable to GCC 2.95 and others.
@@ -131,9 +129,9 @@
 - Strings that are coming from input should not be used as a first argument to
   a formatted *printf function.
 
-* Use the internal API
-----------------------
 
+Use the internal API
+^^^^^^^^^^^^^^^^^^^^
 - Make sure you are aware of the string and data handling functions that exist
   within Asterisk to enhance portability and in some cases to produce more
   secure and thread-safe code. Check utils.c/utils.h for these.
@@ -143,9 +141,9 @@
   stack size.  This reduces the replication of the code to handle the pthread_attr_t
   structure.
 
-* Code formatting
------------------
 
+Code formatting
+^^^^^^^^^^^^^^^
 Roughly, Asterisk code formatting guidelines are generally equivalent to the 
 following:
 
@@ -194,36 +192,44 @@
 Following are examples of how code should be formatted.
 
 - Functions:
+---------------------------------
 int foo(int a, char *s)
 {
-	return 0;
+      return 0;
 }
+---------------------------------
 
 - If statements:
+---------------------------------
 if (foo) {
-	bar();
+      bar();
 } else {
-	blah();
+      blah();
 }
+---------------------------------
 
 - Case statements:
+---------------------------------
 switch (foo) {
 case BAR:
-	blah();
-	break;
+      blah();
+      break;
 case OTHER:
-	other();
-	break;
+      other();
+      break;
 }
+---------------------------------
 
 - No nested statements without braces, e.g.:
-
+---------------------------------
 for (x = 0; x < 5; x++)
 	if (foo) 
 		if (bar)
 			baz();
 
+---------------------------------
 instead do:
+---------------------------------
 for (x = 0; x < 5; x++) {
 	if (foo) {
 		if (bar) {
@@ -231,42 +237,51 @@
 		}
 	}
 }
+---------------------------------
 
 - Always use braces around the statements following an if/for/while construct,
-even if not strictly necessary, as it reduces future possible problems.
+  even if not strictly necessary, as it reduces future possible problems.
 
 - Don't build code like this:
 
+---------------------------------
 if (foo) {
-	/* .... 50 lines of code ... */
+      /* .... 50 lines of code ... */
 } else {
-	result = 0;
-	return;
+      result = 0;
+      return;
 }
+---------------------------------
 
 Instead, try to minimize the number of lines of code that need to be
 indented, by only indenting the shortest case of the 'if'
 statement, like so:
 
+---------------------------------
 if (!foo) {
-	result = 0;
-	return;
+      result = 0;
+      return;
 }
 
 .... 50 lines of code ....
+---------------------------------
 
 When this technique is used properly, it makes functions much easier to read
 and follow, especially those with more than one or two 'setup' operations
 that must succeed for the rest of the function to be able to execute.
 
+
 - Labels/goto are acceptable
+
 Proper use of this technique may occasionally result in the need for a
 label/goto combination so that error/failure conditions can exit the
 function while still performing proper cleanup. This is not a bad thing!
 Use of goto in this situation is encouraged, since it removes the need
 for excess code indenting without requiring duplication of cleanup code.
-       
+
+
 - Never use an uninitialized variable
+
 Make sure you never use an uninitialized variable.  The compiler will 
 usually warn you if you do so. However, do not go too far the other way,
 and needlessly initialize variables that do not require it. If the first
@@ -284,9 +299,9 @@
 type, and when you are passing a pointer to (for example) a callback function
 that accepts a 'void *' you do not need to cast into that type.
 
-* Function naming
------------------
 
+Function naming
+^^^^^^^^^^^^^^^
 All public functions (those not marked 'static'), must be named "ast_<something>"
 and have a descriptive name.
 
@@ -296,10 +311,11 @@
 prototype in an appropriate header file (usually in include/asterisk). A more
 specific name should be given, such as "ast_find_call_feature".
 
-* Variable naming
------------------
 
+Variable naming
+^^^^^^^^^^^^^^^
 - Global variables
+
 Name global variables (or local variables when you have a lot of them or
 are in a long function) something that will make sense to aliens who
 find your code in 100 years.  All variable names should be in lower 
@@ -313,6 +329,7 @@
  e.g.: static char global_something[80]
 
 - Don't use un-necessary typedef's
+
 Don't use 'typedef' just to shorten the amount of typing; there is no substantial
 benefit in this:
 struct foo { int bar; }; typedef struct foo foo_t;
@@ -325,6 +342,7 @@
 this allows structure members, local variables and function arguments to
 be declared as using the enum's type. For example:
 
+---------------------------------
 enum option {
   OPT_FOO = 1
   OPT_BAR = 2
@@ -337,17 +355,18 @@
 {
   ...
 }
+---------------------------------
 
-Note: The compiler will _not_ force you to pass an entry from the enum
+NOTE: The compiler will _not_ force you to pass an entry from the enum
 as an argument to this function; this recommendation serves only to make
 the code clearer and somewhat self-documenting. In addition, when using
 switch/case blocks that switch on enum values, the compiler will warn
 you if you forget to handle one or more of the enum values, which can be
 handy.
 
-* String handling
------------------
 
+String handling
+^^^^^^^^^^^^^^^
 Don't use strncpy for copying whole strings; it does not guarantee that the
 output buffer will be null-terminated. Use ast_copy_string instead, which
 is also slightly more efficient (and allows passing the actual buffer
@@ -370,9 +389,9 @@
 use a direct strcpy(), as it can be inlined and optimized to simple
 processor operations, unlike ast_copy_string().
 
-* Use of functions
-------------------
 
+Use of functions
+^^^^^^^^^^^^^^^^
 When making applications, always ast_strdupa(data) to a local pointer if
 you intend to parse the incoming data string.
 
@@ -391,6 +410,7 @@
 	AST_STANDARD_APP_ARGS(args, parse);
 
 - Create generic code!
+
 If you do the same or a similar operation more than one time, make it a
 function or macro.
 
@@ -399,23 +419,28 @@
 another static function, consider the value of creating a new API call 
 which can be shared.
 
-* Handling of pointers and allocations
---------------------------------------
 
+Handling of pointers and allocations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 - Dereference or localize pointers
+
 Always dereference or localize pointers to things that are not yours like
 channel members in a channel that is not associated with the current 
 thread and for which you do not have a lock.
 	channame = ast_strdupa(otherchan->name);
 
+
 - Use const on pointer arguments if possible
+
 Use const on pointer arguments which your function will not be modifying, as this 
 allows the compiler to make certain optimizations. In general, use 'const'
 on any argument that you have no direct intention of modifying, as it can
 catch logic/typing errors in your code when you use the argument variable
 in a way that you did not intend.
 
+
 - Do not create your own linked list code - reuse!
+
 As a common example of this point, make an effort to use the lockable
 linked-list macros found in include/asterisk/linkedlists.h. They are
 efficient, easy to use and provide every operation that should be
@@ -426,7 +451,9 @@
 and timeval manipulation functions in asterisk/strings.h and asterisk/time.h;
 use them when possible.
 
+
 - Avoid needless allocations!
+
 Avoid needless malloc(), strdup() calls. If you only need the value in
 the scope of your function try ast_strdupa() or declare structs on the
 stack and pass a pointer to them. However, be careful to _never_ call
@@ -434,14 +461,16 @@
 of a function you are calling; this can cause very strange stack
 arrangements and produce unexpected behavior.
 
+
 -Allocations for structures
+
 When allocating/zeroing memory for a structure, use code like this:
 
-struct foo *tmp;
+  struct foo *tmp;
 
-...
+  ...
 
-tmp = ast_calloc(1, sizeof(*tmp));
+  tmp = ast_calloc(1, sizeof(*tmp));
 
 Avoid the combination of ast_malloc() and memset().  Instead, always use
 ast_calloc(). This will allocate and zero the memory in a single operation. 
@@ -477,21 +506,21 @@
 copy the string into the resulting buffer.  This is the exact same thing as
 using ast_strdup.
 
-* CLI Commands
---------------
 
+CLI Commands
+^^^^^^^^^^^^
 New CLI commands should be named using the module's name, followed by a verb
 and then any parameters that the command needs. For example:
 
-*CLI> iax2 show peer <peername>
+  *CLI> iax2 show peer <peername>
 
 not
 
-*CLI> show iax2 peer <peername>
+  *CLI> show iax2 peer <peername>
 
-* New dialplan applications/functions
--------------------------------------
 
+New dialplan applications/functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 There are two methods of adding functionality to the Asterisk
 dialplan: applications and functions. Applications (found generally in
 the apps/ directory) should be collections of code that interact with
@@ -508,12 +537,13 @@
 Functions are registered using 'struct ast_custom_function'
 structures and the ast_custom_function_register function.
 
-* Doxygen API Documentation Guidelines
---------------------------------------
 
+Doxygen API Documentation Guidelines
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 When writing Asterisk API documentation the following format should be
 followed. Do not use the javadoc style.
 
+----------------------------
 /*!
  * \brief Do interesting stuff.
  * \param thing1 interesting parameter 1.
@@ -527,6 +557,7 @@
 {
 	return 0;
 }
+----------------------------
 
 Notice the use of the \param, \brief, and \return constructs.  These should be
 used to describe the corresponding pieces of the function being documented.
@@ -543,6 +574,7 @@
 
 Structures should be documented as follows.
 
+----------------------------
 /*!
  * \brief A very interesting structure.
  */
@@ -553,6 +585,7 @@
 
 	int member2; /*!< \brief Another data member. */
 }
+----------------------------
 
 Note that /*! */ blocks document the construct immediately following them
 unless they are written, /*!< */, in which case they document the construct
@@ -566,14 +599,16 @@
 That way, all of the comments are properly aligned, regardless of what tab
 size is being used for viewing the code.
 
-* Finishing up before you submit your code
-------------------------------------------
 
+Finishing up before you submit your code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 - Look at the code once more
+
 When you achieve your desired functionality, make another few refactor
 passes over the code to optimize it.
 
 - Read the patch
+
 Before submitting a patch, *read* the actual patch file to be sure that 
 all the changes you expect to be there are, and that there are no 
 surprising changes you did not expect. During your development, that
@@ -581,12 +616,14 @@
 latest CVS.
 
 - Listen to advice
+
 If you are asked to make changes to your patch, there is a good chance
 the changes will introduce bugs, check it even more at this stage.
 Also remember that the bug marshal or co-developer that adds comments 
 is only human, they may be in error :-)
 
 - Optimize, optimize, optimize
+
 If you are going to reuse a computed value, save it in a variable
 instead of recomputing it over and over.  This can prevent you from 
 making a mistake in subsequent computations, making it easier to correct
@@ -595,6 +632,7 @@
 
 Just an example (so don't over analyze it, that'd be a shame):
 
+------------------------------------------
 const char *prefix = "pre";	
 const char *postfix = "post";
 char *newname;
@@ -613,9 +651,11 @@
 
 if (name && (len = strlen(name) + strlen(prefix) + strlen(postfix) + 3) && (newname = alloca(len)))
 	snprintf(newname, len, "%s/%s/%s", prefix, name, postfix);
+------------------------------------------
 
-* Creating new manager events?
-------------------------------
+
+Creating new manager events?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 If you create new AMI events, please read manager.txt. Do not re-use
 existing headers for new purposes, but please re-use existing headers
 for the same type of data.
@@ -628,10 +668,10 @@
 Check manager.txt for more information on manager and existing
 headers. Please update this file if you add new headers.
 
-	    ------------------------------------
-	    ==  PART TWO: BUILD ARCHITECTURE  ==
-	    ------------------------------------
 
+
+PART TWO: BUILD ARCHITECTURE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The asterisk build architecture relies on autoconf to detect the
 system configuration, and on a locally developed tool (menuselect) to
 select build options and modules list, and on gmake to do the build.
@@ -679,7 +719,6 @@
 TO BE COMPLETED
 
     
------------------------------------------------
 Welcome to the Asterisk development community!
 Meet you on the asterisk-dev mailing list. 
 Subscribe at http://lists.digium.com!
Index: doc/asterisk-asciidoc
===================================================================
--- doc/asterisk-asciidoc	(revision 0)
+++ doc/asterisk-asciidoc	(revision 0)
@@ -0,0 +1,19 @@
+The Asterisk Documentation
+==========================
+Tzafrir Cohen <tzafrir.cohen@xorcom.com>
+Sat, 08 Mar 2008 22:20:11 +0200
+
+
+Preface
+=======
+Whatever
+
+
+Asterisk Administrator Guide
+============================
+
+include::configs/zapata.conf.sample[]
+
+Asterisk Developer Guide
+========================
+include::CODING-GUIDELINES[tabstop=4]
Index: Makefile
===================================================================
--- Makefile	(revision 107000)
+++ Makefile	(working copy)
@@ -863,4 +863,17 @@
 asterisk.pdf:
 	$(MAKE) -C doc/tex asterisk.pdf
 
+
+# Asciidoc documentation
+doc/configs/%: configs/%
+	mkdir -p $(@D)
+	sed -e 's/^;;;; \(=\+\) /\n\1 /' -e 's/^\([[;]\)/  \1/' $< >$@
+
+ASCIIDOC_INCLUDED	= CODING-GUIDELINES
+ASCIIDOC_CONFS		= zapata
+doc/asterisk-asciidoc.html: doc/asterisk-asciidoc \
+  $(ASCIIDOC_INCLUDED:%=doc/%) $(ASCIIDOC_CONFS:%=doc/configs/%.conf.sample)
+	asciidoc -d book -n -a toc -a toclevel=3 $<
+
+
 .PHONY: menuselect main sounds clean dist-clean distclean all prereqs cleantest uninstall _uninstall uninstall-all pdf dont-optimize $(SUBDIRS_INSTALL) $(SUBDIRS_DIST_CLEAN) $(SUBDIRS_CLEAN) $(SUBDIRS_UNINSTALL) $(SUBDIRS) $(MOD_SUBDIRS_EMBED_LDSCRIPT) $(MOD_SUBDIRS_EMBED_LDFLAGS) $(MOD_SUBDIRS_EMBED_LIBS) badshell main/version.c include/asterisk/version.h
Index: configs/zapata.conf.sample
===================================================================
--- configs/zapata.conf.sample	(revision 107000)
+++ configs/zapata.conf.sample	(working copy)
@@ -1,6 +1,5 @@
+;;;; == zapata.conf: Zapata telephony interface
 ;
-; Zapata telephony interface
-;
 ; Configuration file
 ;
 ; You need to restart Asterisk to re-configure the Zap channel
@@ -21,11 +20,12 @@
 ; are usually sane. Thus you should typically not touch them unless you 
 ; know what they mean or you know you should change them.
 
-
+;;;; === Trunk Groups
 [trunkgroups]
 ;
 ; Trunk groups are used for NFAS or GR-303 connections.
 ;
+;;;; ==== trunkgroup
 ; Group: Defines a trunk group.  
 ;        trunkgroup => <trunkgroup>,<dchannel>[,<backup1>...]
 ;
@@ -37,6 +37,7 @@
 ;trunkgroup => 1,24,48
 ;trunkgroup => 1,24
 ;
+;;;; ==== spanmap
 ; Spanmap: Associates a span with a trunk group
 ;        spanmap => <zapspan>,<trunkgroup>[,<logicalspan>]
 ;
@@ -50,16 +51,20 @@
 ;spanmap => 3,1,3
 ;spanmap => 4,1,4
 
+;;;; === channels
 [channels]
 ;
-; Default language
+;;;; ==== language
+; Defines the language of the channel
 ;
 ;language=en
 ;
+;;;; ==== context
 ; Context for calls. Defaults to 'default'
 ;
 ;context=incoming
 ;
+;;;; ==== switchtype
 ; Switchtype:  Only used for PRI.
 ;
 ; national:	  National ISDN 2 (default)
@@ -72,6 +77,7 @@
 ;
 ;switchtype=euroisdn
 ;
+;;;; ==== nfs
 ; Some switches (AT&T especially) require network specific facility IE
 ; supported values are currently 'none', 'sdn', 'megacom', 'tollfreemegacom', 'accunet'
 ;
@@ -79,6 +85,7 @@
 ;
 ;nsf=none
 ;
+;;;; ==== pridialplan
 ; PRI Dialplan:  Only RARELY used for PRI.
 ; PRI Local Dialplan:  Only RARELY used for PRI (sets the calling number's 
 ; numbering plan)
