* Add a "docs" target to generate documentation.

* Demote/promote some headers.
* Fix URL for on-line copy of the README.


git-svn-id: http://svn.asterisk.org/svn/dahdi/tools/trunk@4844 a0bf4364-ded3-4de4-8d8a-66a801d63aff

3 files changed, 29 insertions, 19 deletions

diff --git a/Makefile b/Makefile
index db78b8f..fbc1d61 100644
--- a/Makefile
+++ b/Makefile
@@ -114,6 +114,8 @@ MAN_PAGES:=$(wildcard $(BINS:%=doc/%.8))
 GROFF_PAGES	:= $(wildcard doc/*.8 xpp/*.8)
 GROFF_HTML	:= $(GROFF_PAGES:%=%.html)
 
+GENERATED_DOCS	:= $(GROFF_HTML) README.html # README.Astribank.html
+
 all: menuselect.makeopts 
 	@$(MAKE) _all
 
@@ -184,11 +186,13 @@ tonezones.txt: zonedata.c
 		$< \
 	| perl -p -e 'if (/^  #?(\w+)=/ && ! exists $$cfgs{$$1}){my $$cfg = $$1; $$cfgs{$$cfg} = 1; s/^/\n[[cfg_$$cfg]]\n/}'  >$@
 
+docs: $(GENERATED_DOCS)
+
 README.html: README system.conf.asciidoc init.conf.asciidoc tonezones.txt
 	$(ASCIIDOC) -n -a toc -a toclevels=3 $<
 
-kernel/xpp/README.Astribank.html: kernel/xpp/README.Astribank
-	cd $(@D); $(ASCIIDOC) -o $(@F) -n -a toc -a toclevels=4 $(<F)
+README.Astribank.html: xpp/README.Astribank
+	$(ASCIIDOC) -o $@ -n -a toc -a toclevels=4 $<
 
 # on Debian: this requires the full groof, not just groff-base.
 %.8.html: %.8
@@ -304,8 +308,7 @@ clean:
 	rm -f fxotune
 	rm -f core
 	rm -f dahdi_cfg-shared fxstest
-	rm -rf $(GROFF_HTML)
-	rm -rf README.html xpp/README.Astribank.html *.asciidoc tonezones.txt
+	rm -rf $(GENERATED_DOCS) *.asciidoc tonezones.txt
 
 distclean: dist-clean
 
diff --git a/README b/README
index be0332e..c851415 100644
--- a/README
+++ b/README
@@ -8,7 +8,7 @@ package contains the userspace tools to configure the kernel modules
 included in the package dahdi-linux.
 
 Build Requirements
-~~~~~~~~~~~~~~~~~~
+------------------
 This package needs the headers from dahdi-linux. Thus you should install
 dahdi-linux before building dahdi-tools.
 
@@ -24,7 +24,7 @@ run:
 
 
 Build System
-~~~~~~~~~~~~~~
+~~~~~~~~~~~~
 gcc and friends. Generally you will need to install the package gcc.
 There may be cases where you will need a specific version of gcc to build
 kernel modules.
@@ -72,8 +72,9 @@ parts of DAHDI:
     partial targets)
   - make config: should be run once to configure 
 
-Building to a Subtree
-^^^^^^^^^^^^^^^^^^^^^
+
+Installation to a Subtree
+^^^^^^^^^^^^^^^^^^^^^^^^^
 The following may be useful when testing the package or when preparing a
 package for a binary distribution (such as an rpm package) installing
 onto a subtree rather than on th real system. 
@@ -82,6 +83,7 @@ onto a subtree rather than on th real system.
 
 This can be useful for any partial install target from the list above.
 
+
 ./configure Options
 ^^^^^^^^^^^^^^^^^^^
 The configure script various several tests and based on them generates
@@ -100,8 +102,9 @@ time, use:
 
   ./ocnfig.status --recheck
 
+
 Configuration
-~~~~~~~~~~~~~
+-------------
 Configuration for DAHDI resides under /etc/dahdi . 
 
 /etc/dahdi/system.conf
@@ -182,6 +185,7 @@ dahdi_hardware::
   by a driver. Shows also some more information for Astribanks from
   /proc/xpp .
 
+
 PPP Support
 ~~~~~~~~~~~
 DAHDI digital cards can provide data channels through ppp as
@@ -201,8 +205,9 @@ that is included in the ppp/ subdirectory. To install it:
    distribution kernels and for HDLC (much less common) - CONFIG_PPP and
    CONFIG_HDLC .
 
+
 License
-~~~~~~~
+-------
 This package is distributed under the terms of the GNU General Public License
 Version 2, except for some components which are distributed under the terms of
 the GNU Lesser General Public License Version 2.1. Both licenses are included
@@ -213,15 +218,17 @@ terms are not appropriate (e.g. a proprietary embedded system), licenses under
 more flexible terms can be readily obtained through Digium, Inc. at reasonable
 cost.
 
+
 Reporting Bugs
-~~~~~~~~~~~~~~
+--------------
 Please report bug and patches to the Asterisk bug tracker at
 http://bugs.digium.com in the "DAHDI" category.
 
+
 Links
 -----
 - http://asterisk.org/[] - The Asterisk PBX
 - http://voip-info.org/[]
 - http://voip-info.org/wiki/view/Asterisk+Zaptel+Installation[]
-- http://docs.tzafrir.org.il/dahdi/README.html[Up-to-date HTML version
+- http://docs.tzafrir.org.il/dahdi-tools/README.html[Up-to-date HTML version
   of this file]
diff --git a/system.conf.sample b/system.conf.sample
index 23c7b75..cdfdc20 100644
--- a/system.conf.sample
+++ b/system.conf.sample
@@ -4,7 +4,7 @@
 # This file is parsed by the DAHDI Configurator, dahdi_cfg
 #
 # Span Configuration
-# ~~~~~~~~~~~~~~~~~~
+# ^^^^^^^^^^^^^^^^^^
 # First come the span definitions, in the format
 # 
 #   span=<span num>,<timing source>,<line build out (LBO)>,<framing>,<coding>[,yellow]
@@ -57,7 +57,7 @@
 #span=3,0,0,ccs,hdb3,crc4
 #
 # Dynamic Spans
-# ~~~~~~~~~~~~~
+# ^^^^^^^^^^^^^
 # Next come the dynamic span definitions, in the form:
 # 
 #   dynamic=<driver>,<address>,<numchans>,<timing>
@@ -75,7 +75,7 @@
 # have the non-zero value. 
 #
 # Channel Configuration
-# ~~~~~~~~~~~~~~~~~~~~~
+# ^^^^^^^^^^^^^^^^^^^^^
 # Next come the definitions for using the channels.  The format is:
 # <device>=<channel list>
 #
@@ -178,7 +178,7 @@
 #dacsrbs=1-24:48
 #
 # Tone Zone Data
-# ~~~~~~~~~~~~~~
+# ^^^^^^^^^^^^^^
 # Finally, you can preload some tone zones, to prevent them from getting
 # overwritten by other users (if you allow non-root users to open /dev/dahdi/*
 # interfaces anyway.  Also this means they won't have to be loaded at runtime.
@@ -206,7 +206,7 @@ loadzone = us
 defaultzone=us
 #
 # PCI Radio Interface
-# ~~~~~~~~~~~~~~~~~~~
+# ^^^^^^^^^^^^^^^^^^^
 # (see http://www.zapatatelephony.org/app_rpt.html)
 #
 # The PCI Radio Interface card interfaces up to 4 two-way radios (either
@@ -272,7 +272,7 @@ defaultzone=us
 #channels=1-4
 #
 # Overiding PCM encoding
-# ~~~~~~~~~~~~~~~~~~~~~~
+# ^^^^^^^^^^^^^^^^^^^^^^
 # Usually the channel driver sets the encoding of the PCM for the
 # channel (mulaw / alaw. That is: g711u or g711a). However there are
 # some cases where you would like to override that. 'mulaw' and 'alaw'
@@ -287,7 +287,7 @@ defaultzone=us
 #deflaw=5
 #
 # Echo Cancellers
-# ~~~~~~~~~~~~~~~
+# ^^^^^^^^^^^^^^^
 # DAHDI uses modular echo cancellers that are configured per channel. The echo
 # cancellers are compiled and installed as part of the dahdi-linux package.
 # You can specify in this file the echo canceller to be used for each