Fixed bug #828: Docs in PDF. There was already a rule for making

pazpar2.pdf using jade + pdfjadetex, but there was some constructs in
the documentation that jade considered invalid. So it did not succeed.
And indeed jade is right in a number of cases, where xsltproc does not
validate. However, jade does NOT currently allow references to refsect1,
refsect2.. sections which makes it impossible to refer to stuff from the
Guide to the Reference material. This is major drawback so dblatex is used
instead. dblatex, like jadetex, makes PDF/tex from Docbook. dblatex allows
these references and dblatex is more actively developed and is available
as a Debian package for sarge. Run 'make pazpar2.pdf' to make the
documentation. There is also a 'jade-check' rule.

diff --git a/doc/Makefile.am b/doc/Makefile.am
index f5fd43c..84030a0 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,4 @@
-## $Id: Makefile.am,v 1.2 2007-01-12 14:54:58 adam Exp $
+## $Id: Makefile.am,v 1.3 2007-01-19 21:50:01 adam Exp $
 docdir=$(datadir)/doc/@PACKAGE@
 
 SUBDIRS = common
@@ -41,12 +41,12 @@ index.tkl: $(XMLFILES)
        $(TKL_COMPILE) $(MAINXML)
 
 pazpar2.pdf: $(XMLFILES)
+       rm -f pazpar2.pdf
+       dblatex $(MAINXML) && mv book.pdf pazpar2.pdf
+
+jade-check: $(XMLFILES)
        jade -E14 -D $(srcdir) -d common/print.dsl -t tex $(srcdir)/common/xml.dcl $(MAINXML)
-       rm -f pazpar2.tex
-       mv book.tex pazpar2.tex
-       pdfjadetex pazpar2.tex >/dev/null
-       pdfjadetex pazpar2.tex >/dev/null
-       pdfjadetex pazpar2.tex >/dev/null
+       touch jade-check
 
 manref.xml: $(XMLMAN) $(srcdir)/common/stripref.xsl
        rm -f manref.xml

diff --git a/doc/book.xml b/doc/book.xml
index 4ec781e..4441b2d 100644 (file)
--- a/doc/book.xml
+++ b/doc/book.xml
@@ -9,40 +9,41 @@
      <!ENTITY % common SYSTEM "common/common.ent">
      %common;
 ]>
-<!-- $Id: book.xml,v 1.5 2007-01-19 18:28:08 quinn Exp $ -->
+<!-- $Id: book.xml,v 1.6 2007-01-19 21:50:02 adam Exp $ -->
 <book id="book">
-  <bookinfo>
-   <title>Pazpar2 - User's Guide and Reference</title>
-   <author>
-    <firstname>Sebastian</firstname><surname>Hammer</surname>
-   </author>
-   <copyright>
-    <year>&copyright-year;</year>
-    <holder>Index Data</holder>
-   </copyright>
-   <abstract>
-    <simpara>
-       Pazpar2 is a high-performance, user interface-independent, data
-       model-independent metasearching
-       middleware featuring merging, relevance ranking, record sorting, 
-       and faceted results.
-    </simpara>
-    <simpara>
-     This document is a guide and reference to Pazpar version &version;.
-    </simpara>
-    <simpara>
-     <inlinemediaobject>
-      <imageobject>
-       <imagedata fileref="common/id.png" format="PNG"/>
-      </imageobject>
-      <imageobject>
-       <imagedata fileref="common/id.eps" format="EPS"/>
-      </imageobject>
-     </inlinemediaobject>
-    </simpara>
-   </abstract>
+ <bookinfo>
+  <title>Pazpar2 - User's Guide and Reference</title>
+  <author>
+   <firstname>Sebastian</firstname><surname>Hammer</surname>
+  </author>
+  <releaseinfo>&version;</releaseinfo>
+  <copyright>
+   <year>&copyright-year;</year>
+   <holder>Index Data</holder>
+  </copyright>
+  <abstract>
+   <simpara>
+    Pazpar2 is a high-performance, user interface-independent, data
+    model-independent metasearching
+    middleware featuring merging, relevance ranking, record sorting, 
+    and faceted results.
+   </simpara>
+   <simpara>
+    This document is a guide and reference to Pazpar version &version;.
+   </simpara>
+   <simpara>
+    <inlinemediaobject>
+     <imageobject>
+      <imagedata fileref="common/id.png" format="PNG"/>
+   </imageobject>
+    <imageobject>
+     <imagedata fileref="common/id.eps" format="EPS"/>
+   </imageobject>
+   </inlinemediaobject>
+   </simpara>
+  </abstract>
   </bookinfo>
-
+ 
   <chapter id="introduction">
    <title>Introduction</title>
    <para>
@@ -362,16 +363,16 @@
     </section>
   </chapter> <!-- Using pazpar2 -->
 
-  <reference id="reference">
-   <title>Reference</title>
-   <partintro>
-    <para>
-     The material in this chapter is drawn directly from the individual
-     manual entries.
-    </para>
-   </partintro>
-   &manref;
-  </reference>
+ <reference id="reference">
+  <title>Reference</title>
+  <partintro>
+   <para>
+    The material in this chapter is drawn directly from the individual
+    manual entries.
+   </para>
+  </partintro>
+  &manref;
+ </reference>
 </book>
 
  <!-- Keep this comment at the end of the file

diff --git a/doc/pazpar2_conf.xml b/doc/pazpar2_conf.xml
index 0ec7e6d..64ab21a 100644 (file)
--- a/doc/pazpar2_conf.xml
+++ b/doc/pazpar2_conf.xml
@@ -8,7 +8,7 @@
      <!ENTITY % common SYSTEM "common/common.ent">
      %common;
 ]>
-<!-- $Id: pazpar2_conf.xml,v 1.5 2007-01-19 19:12:16 quinn Exp $ -->
+<!-- $Id: pazpar2_conf.xml,v 1.6 2007-01-19 21:50:02 adam Exp $ -->
 <refentry id="pazpar2_conf">
  <refentryinfo>
   <productname>Pazpar2</productname>
@@ -105,7 +105,7 @@
              respect to your data model. In pazpar2, incoming records are
              normalized, using XSLT, into an internal representation (see
              the <link
-             id="config-retrievalprofile">retrievalprofile</link> secion.
+             linkend="config-retrievalprofile">retrievalprofile</link> secion.
              The 'service' section controls the further processing and
              extraction of data from the internal representation, primarily
              through the 'metdata' sub-element.
@@ -226,7 +226,7 @@
       </variablelist>           <!-- Data elements in server directive -->
     </refsect2>
 
-    <refsect2 id="config-queryprofile">
+    <refsect2 id="config-queryprofile"><title>queryprofile</title>
       <para>
         At the moment, this directive is ignored; there is one global
        CCL-mapping file which governs the mapping of queries to Z39.50
@@ -235,7 +235,7 @@
       </para>
     </refsect2>
 
-    <refsect2 id="config_retrievalprofile">
+    <refsect2 id="config_retrievalprofile"><title>retrievalprofile</title>
       <para>
        Note: In the present version, there is a single retrieval
        profile. However, in a future release, it will be possible to
@@ -316,7 +316,7 @@
  <refsect1><title>EXAMPLES</title>
   <para></para>
  </refsect1> 
-
+</refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml