Re: Making distribute-deb.xml work properly

[Aaron Isotton <aaron@isotton.com>]

On Sun, 6 Apr 2003 17:20:40 +0200, Wichert Akkerman <wichert@wiggy.net>
claimed:

> Josip mentioned that there were some problems with using DocBook/XML
> for documentation so I took a quick look at it. The only problem I can
> find is the use of an incorrect URL in the doctype. Changing that to
> this one makes everything work for me:
> 
> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
>         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>

Why that?  For me it doesn't make any difference.

> 
> 
> I still get a bunch of warnings about the mdash entity not being
> defined, but that seems to be a docbook problem (I get the same for
> other common entities).
> 
> Instead of using xsltproc I'm using xmlto, which makes things a bit
> more convenient. 

If you convert it using xmlto, all entities (such as &mdash;, &auml;
etc) is *lost* in the output (#183744); if you use xsltproc, the
warnings are the same but the output is correct, *independently of the
used doctype url*.


> I would also suggest using an xslt snippet to make the output a bit
> nicer, especially for publising documentation online. Something like
> this should work:
> 
> ---------------------------------------------------------------------
> ---<?xml version='1.0'?>
> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
>                 xmlns:fo="http://www.w3.org/1999/XSL/Format";
>                 version="1.0">
> 
>   <!-- Use ids for filenames -->
>   <xsl:param name="use.id.as.filename" select="'1'"/>
> 
>   <!-- Turn on admonition graphics. -->
>   <xsl:param name="admon.graphics" select="'1'"/>
> </xsl:stylesheet>
> ---------------------------------------------------------------------
> ---

A Debian Docbook customization layer would be nice.  

The problem with admonition graphics is that they require additional
fiels installed in standard locations, which is often a problem when one
wants to view the same documents online and offline.

Additionally to your stylesheet, I'd suggest something like this:

  <!-- necessary to use as stylesheet -->
  <xsl:import
href="file:///usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/docbook
.xsl"/>                                                                 
    
  <!-- docbook doesn't specify a doctype by default -->
  <xsl:output method="html" encoding="utf-8"
    doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN"
    doctype-system="http://www.w3.org/TR/html4/loose.dtd"; indent="no"/> 
                                                                        
  <!-- no link targets  -->
  <xsl:variable name="ulink.target"/>
                                                                        
  <!-- shade verbatim stuff -->
  <xsl:param name="shade.verbatim">1</xsl:param>
  <xsl:attribute-set name="shade.verbatim.style">
    <xsl:attribute name="border">0</xsl:attribute>
    <xsl:attribute name="bgcolor">#EEEEEE</xsl:attribute>
  </xsl:attribute-set>
                                                                        
  <!-- use admonition graphics -->
  <xsl:param name="admon.graphics" select="1"/>
  <xsl:param name="admon.graphics.path">/admons/</xsl:param>
  <xsl:param name="admon.style"/>


Aaron Isotton                                 [ http://www.isotton.com ]
-- 
It is easier to run down a hill than up one.

Attachment: pgpJZQ9PEzfsz.pgp
Description: PGP signature