Add ability to generate ASCII documentation from the TeX files.

These changes add the ability to run 'make asterisk.txt' just like the existing
'make asterisk.pdf' commands to generate a text document from the TeX files we
have in the doc/tex/ directory. I've also updated a few of the .tex files because
they weren't properly escaping certain characters so they would show up as Unicode
characters (like [U+021C]). Made changes to the configure scripts so it would
detect the catdvi program which is required to convert the .dvi file generated
by latex.

I've also added a few lines to the build_tools/prep_tarball script so that the
text documentation gets generated and added to future tarballs of Asterisk
releases.

(closes issue #17220)
Reported by: lmadsen
Patches: 
      asterisk.txt.patch uploaded by lmadsen (license 10)
      asterisk.txt.patch-v4 uploaded by pabelanger (license 224)
Tested by: lmadsen, pabelanger

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@258351 65c4cc65-6c06-0410-ace0-fbb531ad65f3

Makefile

@@ -987,6 +987,10 @@ pdf: asterisk.pdf
 asterisk.pdf:
 	$(MAKE) -C doc/tex asterisk.pdf
 
+txt: asterisk.txt
+asterisk.txt:
+	$(MAKE) -C doc/tex asterisk.txt
+
 .PHONY: menuselect
 .PHONY: main
 .PHONY: sounds

build_tools/prep_tarball

@@ -15,6 +15,8 @@ make_tex_docs() {
     mv asterisk_local.tex asterisk.tex
     rubber --pdf asterisk.tex
     latex2html asterisk.tex
+    latex asterisk.tex
+    catdvi -e 1 -U asterisk.dvi | sed -re "s/\[U\+2022\]/*/g" | sed -re "s/\[U\+02C6\]/^/g" | sed -re "s/([^^[:space:]])\s+/\1 /g" > asterisk.txt
     # restore backup of asterisk.tex
     mv asterisk.tex.orig asterisk.tex
 }

configure.ac

@@ -197,6 +197,7 @@ AC_PATH_PROG([DOT], [dot], :)
 AC_PATH_PROG([WGET], [wget], :)
 AC_PATH_PROG([CURL], [curl], :)
 AC_PATH_PROG([RUBBER], [rubber], :)
+AC_PATH_PROG([CATDVI], [catdvi], :)
 AC_PATH_PROG([KPATHSEA], [kpsewhich], :)
 AC_PATH_PROG([XMLSTARLET], [xmlstarlet], :)
 if test "${WGET}" != ":" ; then

doc/tex/Makefile

@@ -20,7 +20,7 @@ ifeq ($(findstring fncychap.sty,$(shell find `$(KPATHSEA) --expand-braces='$${TE
 	@echo "WARNING:  The fncychap.sty document was not found"
 	@echo "On Ubuntu, install the texlive-latex-extra package."
 	@echo
-	@exit
+	@exit 1
 endif
 endif
 	@cp asterisk.tex asterisk.tex.orig
@@ -44,3 +44,33 @@ html:
 	@latex2html asterisk.tex
 	@mv asterisk.tex.orig asterisk.tex
 
+txt: asterisk.txt
+
+asterisk.txt: $(wildcard *.tex)
+ifeq ($(findstring catdvi,$(CATDVI)),)
+	@echo "**********************************************"
+	@echo "** You must install the \"catdvi\" tool      ***"
+	@echo "** to generate the Asterisk reference TXT. ***"
+	@echo "**********************************************"
+else
+	@echo "**********************************************"
+	@echo "** The Asterisk reference TXT will now be  ***"
+	@echo "** generated.  When complete, it will be   ***"
+	@echo "** located at asterisk.txt.                ***"	
+	@echo "**********************************************"
+ifneq ($(findstring kpsewhich,$(KPATHSEA)),)
+ifeq ($(findstring fncychap.sty,$(shell find `$(KPATHSEA) --expand-braces='$${TEXMF}'| tr -d \! | sed 's/:/ /g'` -name fncychap.sty -print)),)
+	@echo
+	@echo "WARNING:  The fncychap.sty document was not found"
+	@echo "On Ubuntu, install the texlive-latex-extra package."
+	@echo
+	@exit 1
+endif
+endif
+	@cp asterisk.tex asterisk.tex.orig
+	@sed -e 's/ASTERISKVERSION/$(ASTERISKVERSION)/' asterisk.tex > asterisk_local.tex
+	@mv asterisk_local.tex asterisk.tex
+	@latex asterisk.tex
+	-@$(CATDVI) -e 1 -U asterisk.dvi | sed -re "s/\[U\+2022\]/*/g" | sed -re "s/\[U\+02C6\]/^/g" | sed -re "s/([^^[:space:]])\s+/\1 /g" > asterisk.txt
+	@mv asterisk.tex.orig asterisk.tex
+endif

doc/tex/ael.tex

@@ -128,7 +128,7 @@ section of extensions.conf.
 To reload extensions.ael, the following command can be issued at the
 CLI:
 
-    *CLI> ael reload
+    *CLI$>$ ael reload
 
 \section{Debugging}
 
@@ -735,7 +735,7 @@ of \$[ ] expressions.
 
 NOTE: These things are wrapped up in a \$[ ] expression: The while() test;
 the if() test; the middle expression in the for( x; y; z) statement
-(the y expression); Assignments - the right hand side, so a = b -> Set(a=\$[b])
+(the y expression); Assignments - the right hand side, so a = b -$>$ Set(a=\$[b])
 
 Writing to a dialplan function is treated the same as writing to a variable.
 

doc/tex/asterisk.tex

@@ -32,7 +32,7 @@
 
 
 \author{Asterisk Development Team \\ Asterisk.org}
-\title{Asterisk Reference Information \\ ASTERISKVERSION}
+\title{Asterisk Reference Information \\ SVN-trunk-r258265M}
 
 \begin{document}
 \maketitle

doc/tex/cel-doc.tex

@@ -141,7 +141,7 @@ events:
 
 "EV\_CHAN\_END","2007-05-09 12:49:26","","151","152","","","","extension","Zap/51-1","Bridged Call","Zap/50-1","DOCUMENTATION","","1178736378.4","",""                     ;;; 151 channel ends
 
-"EV\_CHAN\_END","2007-05-09 12:49:26","fxs.51","151","151","","","h","extension","Zap/51-2<ZOMBIE>","","","DOCUMENTATION","","1178736428.5","",""                          ;;; 152-2 channel ends (zombie)
+"EV\_CHAN\_END","2007-05-09 12:49:26","fxs.51","151","151","","","h","extension","Zap/51-2$<$ZOMBIE$>$","","","DOCUMENTATION","","1178736428.5","",""                          ;;; 152-2 channel ends (zombie)
 
 {\it (just 150 and 152 now)}
 
@@ -820,9 +820,9 @@ And, humorously enough, the above 80 manager events, or 42 CEL events,
 correspond to the following two CDR records (at the moment!):
 
 \begin{astlisting}
-""fxs.52" <152>","152","h","extension","Zap/52-1","Zap/51-1","NoOp","More Hangup message after hopping around"","2007-05-09 17:35:56","2007-05-09 17:36:20","2007-05-09 17:36:36","40","16","ANSWERED","DOCUMENTATION","","1178753756.0",""
+""fxs.52" $<$152$>$","152","h","extension","Zap/52-1","Zap/51-1","NoOp","More Hangup message after hopping around"","2007-05-09 17:35:56","2007-05-09 17:36:20","2007-05-09 17:36:36","40","16","ANSWERED","DOCUMENTATION","","1178753756.0",""
 
-""fxs.50" <150>","150","152","extension","Zap/50-1","Zap/51-1","NoOp","More Hangup message after hopping around"","2007-05-09 17:37:59","2007-05-09 17:38:06","2007-05-09 17:39:11","72","65","ANSWERED","DOCUMENTATION","","1178753871.3",""
+""fxs.50" $<$150$>$","150","152","extension","Zap/50-1","Zap/51-1","NoOp","More Hangup message after hopping around"","2007-05-09 17:37:59","2007-05-09 17:38:06","2007-05-09 17:39:11","72","65","ANSWERED","DOCUMENTATION","","1178753871.3",""
 \end{astlisting}
 
 

doc/tex/enum.tex

@@ -53,7 +53,7 @@ Function: ENUMLOOKUP(number[,Method-type[,options[,record#[,zone-suffix]]]])
      ALL. Default type is "sip".
      Special name of "ALL" will create a list of method types across
      all NAPTR records for the search number, and then put the results
-     in an ordinal list starting with 1. The position <number>
+     in an ordinal list starting with 1. The position $<$number$>$
      specified will then be returned, starting with 1 as the first
      record (lowest value) in the list.  The service types are not
      hardcoded in Asterisk except for the default (sip) if no other
@@ -75,11 +75,11 @@ Function: ENUMLOOKUP(number[,Method-type[,options[,record#[,zone-suffix]]]])
   \item record\#
   \begin{itemize}
     \item which record to present if multiple answers are returned
-    <integer> = The record in priority/order sequence based on the
+    $<$integer$>$ = The record in priority/order sequence based on the
     total count of records passed back by the query. If a service\_type
     is specified, all entries of that type will be sorted into an
     ordinal list starting with 1 (by order first, then priority).
-    The default of <options> is "1"
+    The default of $<$options$>$ is "1"
   \end{itemize}
 
   \item zone\_suffix

doc/tex/localchannel.tex

@@ -383,11 +383,13 @@ as expected.
 
 This following dialplan will not perform as expected.
 
+\begin{verbatim}
 [services]
 exten => 2,1,Dial(SIP/PHONE\_B,,L(60000:45000:15000))
 
 [internal]
-exten => 4,1,Dial(Local/2@services);
+exten => 4,1,Dial(Local/2@services)
+\end{verbatim}
 
 By default, the Local channel will try to optimize itself out of the call path.
 This means that once the Local channel has established the call between the

doc/tex/phoneprov.tex

@@ -79,7 +79,7 @@ subdirectory of AST\_DATA\_DIR/phoneprov specified.
 
 Since phone-specific config files generally have file names based on phone-specifc data, 
 dynamic filenames in res\_phoneprov can be defined with Asterisk dialplan function and 
-variable substitution. In the above example, \$\{TOLOWER(\$\{MAC\})\}.cfg $\Rightarrow$ 
+variable substitution. In the above example, \$\{TOLOWER(\$\{MAC\})\}.cfg =$>$
 000000000000.cfg would define a relative URI to be served that matches the format of 
 MACADDRESS.cfg, all lower case. A request for that file would then point to the template 
 found at AST\_DATA\_DIR/phoneprov/000000000000.cfg. The template can be followed by a 
@@ -96,8 +96,8 @@ Variable substitution on this value is done while building the route list, so
 dynamic filename.
 
 NOTE: Any dialplan function that is used for generation of dynamic file names MUST be 
-loaded before res\_phoneprov. Add "preload $\Rightarrow$ modulename.so" to 
+loaded before res\_phoneprov. Add "preload =$>$ modulename.so" to 
-\path{modules.conf} for required functions. In the example above, "preload $\Rightarrow$ 
+\path{modules.conf} for required functions. In the example above, "preload =$>$
 func\_strings.so" would be required.
 
 \section{Configuration of users.conf}

doc/tex/security-events.tex

@@ -147,7 +147,7 @@ logger levels within Asterisk.
     [Feb 11 07:57:03] SECURITY[23736] res_security_log.c: <...>
 \end{verbatim}
 
-    The part of the log entry identified by <...> is where the security event
+    The part of the log entry identified by $<$...$>$ is where the security event
 content resides.  The security event content is a comma separated list
 of key value pairs.  The key is the information element type, and the value is a
 quoted string that contains the associated meta data for that information

include/asterisk/autoconfig.h.in

@@ -1292,6 +1292,9 @@
 /* Define to the version of this package. */
 #undef PACKAGE_VERSION
 
+/* Define to 1 if the C compiler supports function prototypes. */
+#undef PROTOTYPES
+
 /* Define to necessary symbol if this constant uses a non-standard name on
    your system. */
 #undef PTHREAD_CREATE_JOINABLE
@@ -1311,6 +1314,11 @@
 /* Define to the type of arg 5 for `select'. */
 #undef SELECT_TYPE_ARG5
 
+/* Define to 1 if the `setvbuf' function takes the buffering type as its
+   second argument and the buffer pointer as the third, as on System V before
+   release 3. */
+#undef SETVBUF_REVERSED
+
 /* The size of `char *', as computed by sizeof. */
 #undef SIZEOF_CHAR_P
 
@@ -1340,30 +1348,20 @@
 /* Define to 1 if your <sys/time.h> declares `struct tm'. */
 #undef TM_IN_SYS_TIME
 
-/* Enable extensions on AIX 3, Interix.  */
+/* Define to 1 if on AIX 3.
+   System headers sometimes define this.
+   We just want to avoid a redefinition error message.  */
 #ifndef _ALL_SOURCE
 # undef _ALL_SOURCE
 #endif
+
+/* Number of bits in a file offset, on hosts where this is settable. */
+#undef _FILE_OFFSET_BITS
+
 /* Enable GNU extensions on systems that have them.  */
 #ifndef _GNU_SOURCE
 # undef _GNU_SOURCE
 #endif
-/* Enable threading extensions on Solaris.  */
-#ifndef _POSIX_PTHREAD_SEMANTICS
-# undef _POSIX_PTHREAD_SEMANTICS
-#endif
-/* Enable extensions on HP NonStop.  */
-#ifndef _TANDEM_SOURCE
-# undef _TANDEM_SOURCE
-#endif
-/* Enable general extensions on Solaris.  */
-#ifndef __EXTENSIONS__
-# undef __EXTENSIONS__
-#endif
-
-
-/* Number of bits in a file offset, on hosts where this is settable. */
-#undef _FILE_OFFSET_BITS
 
 /* Define to 1 to make fseeko visible on some hosts (e.g. glibc 2.2). */
 #undef _LARGEFILE_SOURCE
@@ -1381,6 +1379,20 @@
 /* Define to 1 if you need to in order for `stat' and other things to work. */
 #undef _POSIX_SOURCE
 
+/* Enable extensions on Solaris.  */
+#ifndef __EXTENSIONS__
+# undef __EXTENSIONS__
+#endif
+#ifndef _POSIX_PTHREAD_SEMANTICS
+# undef _POSIX_PTHREAD_SEMANTICS
+#endif
+#ifndef _TANDEM_SOURCE
+# undef _TANDEM_SOURCE
+#endif
+
+/* Define like PROTOTYPES; this can be used by system headers. */
+#undef __PROTOTYPES
+
 /* Define to empty if `const' does not conform to ANSI C. */
 #undef const
 

makeopts.in

@@ -25,6 +25,7 @@ WGET=@WGET@
 FETCH=@FETCH@
 DOWNLOAD=@DOWNLOAD@
 RUBBER=@RUBBER@
+CATDVI=@CATDVI@
 KPATHSEA=@KPATHSEA@
 XMLSTARLET=@XMLSTARLET@
 MD5=@MD5@