From e4c3dc5c0d1dc9cdd47fdb4ffb1ac49b9b768e5b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 19 Jan 2004 13:26:55 +0000 Subject: prelimernary documentation git-svn-id: file:///home/lennart/svn/public/ivam2/trunk@42 dbf6933d-3bce-0310-9bcc-ed052ba35b35 --- Makefile.am | 4 +- conf/msntab | 10 ++- configure.ac | 2 +- doc/Makefile.am | 21 +++++- doc/README | 13 ---- doc/README.html.in | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/style.css | 32 ++++++++ man/Makefile.am | 48 ++++++++++++ man/ivamd.8.xml.in | 184 +++++++++++++++++++++++++++++++++++++++++++++ man/msntab.5.xml.in | 199 ++++++++++++++++++++++++++++++++++++++++++++++++ man/xmltoman.css | 30 ++++++++ man/xmltoman.dtd | 39 ++++++++++ man/xmltoman.xsl | 120 +++++++++++++++++++++++++++++ 13 files changed, 892 insertions(+), 22 deletions(-) delete mode 100644 doc/README create mode 100644 doc/README.html.in create mode 100644 doc/style.css create mode 100644 man/Makefile.am create mode 100644 man/ivamd.8.xml.in create mode 100644 man/msntab.5.xml.in create mode 100644 man/xmltoman.css create mode 100644 man/xmltoman.dtd create mode 100644 man/xmltoman.xsl diff --git a/Makefile.am b/Makefile.am index 1990d86..5022d99 100644 --- a/Makefile.am +++ b/Makefile.am @@ -17,14 +17,14 @@ # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. EXTRA_DIST = bootstrap.sh README LICENSE -SUBDIRS=src clients ulaw conf doc +SUBDIRS=src clients ulaw conf doc man MAINTAINERCLEANFILES = README noinst_DATA = README README: rm -f README -# $(MAKE) -C doc README + $(MAKE) -C doc README cd $(srcdir) && ln -s doc/README README homepage: dist diff --git a/conf/msntab b/conf/msntab index 4b063d3..0cfda89 100644 --- a/conf/msntab +++ b/conf/msntab @@ -17,7 +17,11 @@ # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. -# The MSNs are matched with standard POSIX shell globbing. +# The MSNs are matched with an extended POSIX shell glob matcher based +# on fnmatch(3). The extension is: you may specifiy more than one glob +# expression separated by commas ore semicolons. If you specify a +# tilde as first character regular expression matching (see regexec(3) +# for more information) is used instead. # The options defined are: # rings=n -> specify after how many rings a call should be accepted @@ -33,8 +37,8 @@ # If no line matches, the call is ignored. -# local MSN remote MSN options action -* * rings=8,pipehack ivam-autobox +# local MSN remote MSN options action +* * rings=8,pipehack ivam-autobox # Some more examples diff --git a/configure.ac b/configure.ac index 382db92..a310c3c 100644 --- a/configure.ac +++ b/configure.ac @@ -178,5 +178,5 @@ fi AM_CONDITIONAL([USE_GENGETOPT], [test "x$gengetopt" = xyes]) -AC_CONFIG_FILES([Makefile src/Makefile clients/Makefile ulaw/Makefile doc/Makefile conf/Makefile]) +AC_CONFIG_FILES([Makefile src/Makefile clients/Makefile ulaw/Makefile doc/Makefile conf/Makefile doc/README.html man/Makefile]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am index 34fa300..8a8f63f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,5 +1,5 @@ # $Id$ -# + # This file is part of ivam2. # # ivam2 is free software; you can redistribute it and/or modify it @@ -16,6 +16,21 @@ # along with ivam2; if not, write to the Free Software Foundation, # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. -pkgdata_DATA = README.VoiceBox +noinst_DATA = README.html README +EXTRA_DIST = $(noinst_DATA) style.css README.html.in README.VoiceBox REQUIREMENTS TODO + +MAINTAINERCLEANFILES = README README.html +CLEANFILES = + +if USE_LYNX +README: README.html + lynx --dump $^ | sed 's,file://localhost/.*/doc/README.html,README,' > $@ + +CLEANFILES += README +endif + +tidy: README.html + tidy -e < README.html + +.PHONY: tidy -EXTRA_DIST = README README.VoiceBox TODO REQUIREMENTS diff --git a/doc/README b/doc/README deleted file mode 100644 index 65f09a2..0000000 --- a/doc/README +++ /dev/null @@ -1,13 +0,0 @@ -Not much yet - -Quick installation HOWTO: - - - Install the requirements - - ./configure && make && make install in the ivam directory - - create a user and a group "ivam" - - create a directory /var/spool/ivam2 and make "ivam:ivam" the owner of that directory - - edit /etc/ivam2/msntab - - create some links in /etc/rc?.d for the ivam2 init script - - reboot or run "/etc/init.d/ivam2 start" - -$Id$ diff --git a/doc/README.html.in b/doc/README.html.in new file mode 100644 index 0000000..1128784 --- /dev/null +++ b/doc/README.html.in @@ -0,0 +1,212 @@ + + + + + +ivam2 @PACKAGE_VERSION@ + + + + +

ivam2 @PACKAGE_VERSION@

+ +

Copyright 2003,2004 Lennart Poettering <@PACKAGE_BUGREPORT@>

+ + + +

License

+ +

This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License as +published by the Free Software Foundation; either version 2 of the +License, or (at your option) any later version.

+ +

This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details.

+ +

You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

+ +

News

+ +
Sun Jan 11 2004:
+ +

Version 0.1 released, the initial release

+ +

Overview

+ +

ivam2 is an automatic phone answering machine software for ISDN +and Linux. It is the completely rewritten successor of ivam featuring many additions.

+ +

ivam2 is seperated in two parts: the core daemon written +in C and the automate logic coded in Python. The latter is pluggable and +may be replaced by different implementations on a per phone number +basis (both caller and callee). This makes ivam2 a very +powerful application server for telephony services. The software is +very scalable, multiple ISDN channels may be controlled from a single +daemon. To write telephony applications for ivam2 is not +complicated. In fact, they are simple executables which read audio +data of the caller from STDIN and write audio data for the caller to +STDOUT. DTMF sequences may be read from a FIFO special file. A +framework for writing telephony applications in Python is provided, a +simple answering machine script based on this framework as well. You +are free to write applications in other languages such as Perl or +C.

+ +

Status

+ +

Version @PACKAGE_VERSION@ is more or less stable and feature complete.

+ +

Documentation

+ +

Have a look on the man pages ivamd(8), ivam2.conf(5), msntab(5), ivam-autobox(1), ivam-voicebox(1), ivam-echo(1), ivam-play(1), ivam-createvb(1), ivam-spool(5). (An XSLT capable browser is required)

+ +

The core daemon ivamd is configured through both the +command line arguments and the file msntab. The latter +specifies which telephony application to start for which caller/callee +pairs. An example:

+ +
47110816 *        defaults         @ignore
+47110815 12345678 defaults         @hangup
+47110815 87654321 rings=2          ivam-play /path/to/an/ulaw/file.ulaw.gz
+47110815 47110815 rings=0,pipehack ivam-autobox
+47110815 *        rings=8,pipehack ivam-autobox
+
+ +

This configuration can be explained as follows: all calls to the +local phone number 47110816 are ignored. Calls to the local phone +number 47110815 are dispatched as follows: if the caller is 87654321, +he will listen to a static message after two rings. If someone is +calling the local number from the same number he enters the voice box +system immediately. All other callers will be dispatched to the voice +box system after eight rings.

+ +

For more information on this configuration file see the manual page msntab(5).

+ +

The one and only audio format ivam2 uses is 8 bit uLaw at +8000Hz. Audio files stored on harddisk are raw sample data without any +header information. You are free to compress the audio files with +gzip to save some bytes. You can create these files by +recording them with a telephone and ivcall.

+ +

Another way to create these files is by using sox to convert standard .wav files:

+ +
sox foo.wav -t raw -U -b -r 8000 welcome.ulaw
+ +

The distribution of ivam2 comes with four telephony applications:

+ + + +

Have a look on the respective manual pages for more information on +these applications.

+ +

The default audio samples for ivam-voicebox and +ivam-autobox are in german language as this is my native +tongue. You probably want to replace them with messages in your own +language. (I am interested in adding high quality english language +samples to the distribution. If you are a native speaker and think +that you are capable of creating them, feel free to contact me.) +Have a look on the manual page ivam-spool(5) for +more information how to change the audio samples.

+ +

Requirements

+ +

A current Linux kernel with isdn4linux and a compatible and +configured (active or passive) ISDN card is required.

+ +

ivam2 relies on a current version of Python. It was developed on Python +2.3, but there are user reports that it works on Python 2.2 without +changes.

+ +

ivam2 needs libdaemon (>= 0.4) +and liboop (>= 1.0).

+ +

If you plan to use the message notification feature of +ivam2 you need metamail, sox and oggenc +installed on the local system.

+ +

Installation

+ +

As this package is made with the GNU autotools you should +run ./configure inside the distribution directory for +configuring the source tree. After that you should run make +for compilation and make install (as root) for installation +of ivam2. A SysV compatible init script is installed to your +init directory.

+ +

After installation of the executables you need to create an user +ivam and a matching group ivam. The spool directory +(by default /var/spool/ivam2) has to be created and must be +owned by ivam:ivam.

+ +

You should edit the configuration file msntab to enable +the telephony services you want to use.

+ + +

Acknowledgements

+ +

Wolfram Schlich for many suggestions and beta testing.

+ +

Download

+ +

The newest release is always available from @PACKAGE_URL@

+ +

The current release is @PACKAGE_VERSION@

+ +

Get ivam2's development sources from the Subversion repository.

+ +
+
Lennart Poettering <@PACKAGE_BUGREPORT@>, January 2004
+ +
$Id$
+ + + diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 0000000..59f2ec6 --- /dev/null +++ b/doc/style.css @@ -0,0 +1,32 @@ +/* $Id$ */ + +/*** + * This file is part of ivam2. + * + * ivam2 is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * ivam2 is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with ivam2; if not, write to the Free Software Foundation, + * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. + ***/ + +body { color: black; background-color: white; margin: 0.5cm; } +a:link, a:visited { color: #900000; } +p { margin-left: 0.5cm; margin-right: 0.5cm; } +div.news-date { margin-left: 0.5cm; font-size: 80%; color: #4f0000; } +p.news-text { margin-left: 1cm; } +h1 { color: #00009F; } +h2 { color: #00009F; } +h3 { color: #00004F; margin-left: 0.5cm; } +ul { margin-left: .5cm; } +ol { margin-left: .5cm; } +pre { margin-left: .5cm; background-color: #f0f0f0; padding: 0.4cm;} +.grey { color: #afafaf; } diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..3e30491 --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,48 @@ +# $Id$ + +# This file is part of ivam2. +# +# ivam2 is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# ivam2 is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with ivam2; if not, write to the Free Software Foundation, +# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. + +SUFFIXES=.xml .xml.in .8 .5 .8.xml .5.xml + +pkgsysconfdir=$(sysconfdir)/@PACKAGE@ + +man_MANS = ivamd.8 msntab.5 + +noinst_DATA = ivamd.8.xml msntab.5.xml + +EXTRA_DIST = $(man_MANS) ivamd.8.xml.in msntab.5.xml.in xmltoman.css xmltoman.xsl xmltoman.dtd + +CLEANFILES = ivamd.8.xml msntab.5.xml + +.xml.in.xml: Makefile + sed -e 's,@sysconfdir\@,$(sysconfdir),g' \ + -e 's,@pkgsysconfdir\@,$(pkgsysconfdir),g' \ + -e 's,@sbindir\@,$(sbindir),g' \ + -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' \ + -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@ + +if USE_XMLTOMAN + +CLEANFILES += $(man_MANS) + +.8.xml.8: Makefile + xmltoman $< > $@ + +.5.xml.5: Makefile + xmltoman $< > $@ + +endif diff --git a/man/ivamd.8.xml.in b/man/ivamd.8.xml.in new file mode 100644 index 0000000..0b753c5 --- /dev/null +++ b/man/ivamd.8.xml.in @@ -0,0 +1,184 @@ + + + + + + + + + + + + ivamd [options] + + + +

ivamd is an application server daemon for telephony + applications. It dispatches voice calls to subprocesses + according to a routing table msntab.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

/var/run/ivamd.pid: the pid file + for ivamd.

+
+ +
+

SIGINT, SIGTERM, SIGQUIT ivamd will quit. This is issued by passing -k to ivamd.

+

SIGHUP ivamd will reload the msntab file immediately. Running connection are not interrupted.

+

SIGUSR1 ivamd will print the current contents of the msntab to syslog.

+
+ +
+

ivamd was written by Lennart Poettering + <@PACKAGE_BUGREPORT@>. ivamd is available + at +

+
+ +
+

+ , +

+
+ +
+

This man page was written using by Oliver Kurth.

+
+ + diff --git a/man/msntab.5.xml.in b/man/msntab.5.xml.in new file mode 100644 index 0000000..c108a68 --- /dev/null +++ b/man/msntab.5.xml.in @@ -0,0 +1,199 @@ + + + + + + + + + + + + @pkgsysconfdir@/msntab + + + + +

msntab is the phone call routing table for ivam2. For each incoming + call the first matching line in the file is used, all others are + ignored. Each line consists of four fields: an expression for + matching the local phone number, an expression for matching the + remote phone number, an option list and an executable file with + its arguments which is run for a matching call.

+ +

The phone numbers are matched by the following way: if the + first character of the matching expression is not a tilde, the + whole expression is matched using an extended version of POSIX + shell globbing based on : + you may specify more than one glob expression seperated by + commas or semicolons. If the first character of the matching + expression is a tilde the expression from its second character + to the end is taken es regular expression and matched with + .

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

/var/run/ivamd.pid: the pid file + for ivamd.

+
+ +
+

SIGINT, SIGTERM, SIGQUIT ivamd will quit. This is issued by passing -k to ivamd.

+

SIGHUP ivamd will reload the msntab file immediately. Running connection are not interrupted.

+

SIGUSR1 ivamd will print the current contents of the msntab to syslog.

+
+ +
+

ivamd was written by Lennart Poettering + <@PACKAGE_BUGREPORT@>. ivamd is available + at +

+
+ +
+

+ , +

+
+ +
+

This man page was written using by Oliver Kurth.

+
+ + diff --git a/man/xmltoman.css b/man/xmltoman.css new file mode 100644 index 0000000..0811e82 --- /dev/null +++ b/man/xmltoman.css @@ -0,0 +1,30 @@ +/* $Id$ */ + +/*** + This file is part of ivam2. + + ivam2 is free software; you can redistribute it and/or modify it under + the terms of the GNU General Public License as published by the Free + Software Foundation; either version 2 of the License, or (at your + option) any later version. + + ivam2 is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + for more details. + + You should have received a copy of the GNU General Public License + along with ivam2; if not, write to the Free Software Foundation, + Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. +***/ + +body { color: black; background-color: white; margin: 0.5cm; } +a:link, a:visited { color: #900000; } +h1 { text-transform:uppercase; font-size: 18pt; color: #00009F; } +p { margin-left:1cm; margin-right:1cm; } +.cmd { font-family:monospace; } +.file { font-family:monospace; } +.arg { text-transform:uppercase; font-family:monospace; font-style: italic; } +.opt { font-family:monospace; font-weight: bold; } +.manref { font-family:monospace; } +.option .optdesc { margin-left:2cm; } diff --git a/man/xmltoman.dtd b/man/xmltoman.dtd new file mode 100644 index 0000000..c6031fb --- /dev/null +++ b/man/xmltoman.dtd @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/man/xmltoman.xsl b/man/xmltoman.xsl new file mode 100644 index 0000000..2da97be --- /dev/null +++ b/man/xmltoman.xsl @@ -0,0 +1,120 @@ + + + + + + + + <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + + + + + + <xsl:value-of select="@name"/>(<xsl:value-of select="@section"/>) + + + + +

Name

+

+ + - + +

+ + + + + + +

+ +

+ + + +

+ +

+ + + + + + + + + + + + + + + +
+ +
+ + + +

Synopsis

+ + + + +

Synopsis

+ + + + +

Description

+ + + + +

Options

+ + + + +

+ + + + +
+ + + + + + () + + + () + + + + + + + + + -- cgit