2004-02-25 Gernot Hillier <gernot@hillier.de>

* docs/.cvsignore: add manpages/*
        * docs/Makefile.am: add support for manpage creation, move validation
          etc. to separate target
        * docs/manual.README: update, add information about manpages
        * docs/manual.docbook: restructure to also create five man pages:
          (capisuite.8, capisuite.conf.5, fax.conf.5, answering_machine.conf.5,
          capisuitefax.1)


git-svn-id: https://svn.ibp.de/svn/capisuite/trunk/capisuite@237 4ebea2bb-67d4-0310-8558-a5799e421b66

ChangeLog

@@ -1,3 +1,12 @@
+2004-02-25  Gernot Hillier  <gernot@hillier.de>
+	* docs/.cvsignore: add manpages/*
+	* docs/Makefile.am: add support for manpage creation, move validation
+	  etc. to separate target
+	* docs/manual.README: update, add information about manpages
+	* docs/manual.docbook: restructure to also create five man pages:
+	  (capisuite.8, capisuite.conf.5, fax.conf.5, answering_machine.conf.5,
+	  capisuitefax.1)
+
 2004-02-20  Gernot Hillier  <gernot@hillier.de>
 	* src/application/capisuite.cpp: changed include order to get rid of
 	  the "_POSIX_C_SOURCE redefined" warning (thx to Hartmut Goebel)

NEWS

@@ -1,6 +1,10 @@
 0.5 (CVS nn):
 =============
 
+	* documentation: 5 man pages are now also created: capisuite(8),
+	  capisuite.conf(5), fax.conf(5), answering_machine.conf(5),
+	  capisuitefax(1) (fixes bug #13, thx to Achim Bohnet for reporting)
+
 	* scripts: remote inquiry now uses correct female form ("eine Nachricht"
 	  instead of "eins Nachricht", thx to Eckhard Rüggeberg and Jörg Fester)
 

docs/.cvsignore

@@ -1,5 +1,7 @@
 reference
 reference/*
+manpages
+manpages/*
 manual.pdf
 de-manual
 de-manual/*

docs/Makefile.am

@@ -4,29 +4,38 @@ EXTRA_DIST = Doxyfile.in mainpage.doxy manual.docbook manual.README
 # dist-hook may be not portable partly, so non-SuSE-users please
 # forgive me and don't call "make dist" or send me a patch ;-)
 
-dist-hook: manual-html manual-pdf reference-html
+dist-hook: manual-html manual-pdf manual-manpages reference-html
 	mkdir $(distdir)/manual
 	cp -r $(srcdir)/manual/* $(distdir)/manual/
 	mkdir $(distdir)/reference
 	cp $(srcdir)/reference/* $(distdir)/reference/
 	cp manual.pdf $(distdir)/
 
-manual-html:
+manual-prepare:
 	sed -e 's,<title>CapiSuite [0-9a-z\.]*</title>,<title>CapiSuite $(VERSION)</title>,g' \
 	  manual.docbook > manual.new # (not another *.in file...)
 	mv manual.new manual.docbook
 	xmllint --noout --valid manual.docbook
-	xsltproc -o manual/ /usr/share/sgml/docbook/docbook-xsl-stylesheets/xhtml/chunk.xsl manual.docbook # create HTML
+
+manual-html: manual-prepare
+	xsltproc --stringparam profile.condition html -o manual-profiled.docbook /usr/share/sgml/docbook/docbook-xsl-stylesheets/profiling/profile.xsl manual.docbook
+	xsltproc -o manual/ /usr/share/sgml/docbook/docbook-xsl-stylesheets/xhtml/chunk.xsl manual-profiled.docbook
+	rm manual-profiled.docbook
 	cp -r /usr/share/sgml/docbook/docbook-xsl-stylesheets/images/ manual/ # missing images...
 	if test ! -d manual/images/callouts; then \
 		echo "manual pages weren't created succesful." ;\
 		exit 1; \
 	fi
 
-manual-pdf: manual-html
-	ln -fs manual.docbook manual.xml # unfortunately db2pdf wants this...
+manual-manpages: manual-prepare
+	xsltproc --stringparam profile.condition man -o manual-profiled.docbook /usr/share/sgml/docbook/docbook-xsl-stylesheets/profiling/profile.xsl manual.docbook
+	xsltproc -o manpages/ /usr/share/sgml/docbook/docbook-xsl-stylesheets/manpages/docbook.xsl manual-profiled.docbook
+	rm manual-profiled.docbook
+
+manual-pdf: manual-prepare
+	xsltproc --stringparam profile.condition pdf -o manual.xml /usr/share/sgml/docbook/docbook-xsl-stylesheets/profiling/profile.xsl manual.docbook
 	db2pdf manual.xml 
-	-rm CATALOG.local manual.aux manual.log manual.out manual.tex suse-*.dsl
+	-rm CATALOG.local manual.aux manual.log manual.out manual.tex suse-*.dsl manual.xml
 
 reference-html: Doxyfile.in
 	sed -e 's,@VERSION\@,$(VERSION),g' \

docs/manual.README

@@ -9,18 +9,55 @@ after the installation and please READ it. :-)
 
 ------ Only experts read on here, please ------
 
+create HTML pages:
+==================
+
 You can create HTML pages by using tools like xsltproc and
-the DocBook stylesheets of Norman Walsh. 
+the DocBook stylesheets of Norman Walsh. This is done in two
+steps: 
 
-An example of how to call xsltproc:
+1. First, you have to profile the document: there are some parts
+in it which shouldn't end up in the HTML documentation. Profiling
+is done by throwing aways all parts which have a "condition" attribute
+not equal to "html" set. To do the profiling, you can also use Norman's
+stylesheets and xsltproc:
 
-xsltproc -o manual/ /usr/share/sgml/docbook/docbook-xsl-stylesheets/xhtml/chunk.xsl manual.docbook
+xsltproc --stringparam profile.condition html -o manual-profiled.docbook \
+  /usr/share/sgml/docbook/docbook-xsl-stylesheets/profiling/profile.xsl  \
+  manual.docbook
 
-You must also copy the images from /usr/share/sgml/docbook/docbook-xsl-stylesheets/xhtml to the created
+2. Then you can call xsltproc to create the real documentation:
+
+xsltproc -o manual/ \
+  /usr/share/sgml/docbook/docbook-xsl-stylesheets/xhtml/chunk.xsl \
+  manual-profiled.docbook
+
+You must also copy the images from 
+/usr/share/sgml/docbook/docbook-xsl-stylesheets/xhtml to the created "manual"
 "manual" directory:
 
 cp -r /usr/share/sgml/docbook/docbook-xsl-stylesheets/images/ manual/ 
 
+create man pages:
+=================
+
+You can again do this by using xsltproc and the DocBook stylesheets:
+
+1. Profiling: 
+
+xsltproc --stringparam profile.condition man -o manual-profiled.docbook \
+  /usr/share/sgml/docbook/docbook-xsl-stylesheets/profiling/profile.xsl \
+  manual.docbook
+
+2. Create man pages:
+
+xsltproc -o manpages/ \
+  /usr/share/sgml/docbook/docbook-xsl-stylesheets/manpages/docbook.xsl \
+   manual-profiled.docbook
+
+validate:
+=========
+
 To validate the document, use e.g. xmllint:
 
 xmllint --noout --valid manual.docbook