[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: DocBook customization layer for the DDP



On Tue, 17 Jun 2003 09:42:51 -0600, Mark Johnson <mrj@debian.org>
claimed:

> Quoting Aaron Isotton <aaron@isotton.com>:
> 
> > Is there any docbook customization layer for the DDP?  [...]
>  
> Not that I'm aware of.
> 
> > Is there anything like that/is anybody working on it?  
> 
> I've been thinking about proposing such a customization as I've been
> composing the new xml-sgml-policy in DocBook XML. 
> 
> It'll probably be a couple of months until I could even propose such a
> customization, as I'm still busy with the policy docs.
> 
> > Do you feel such a thing is necessary at all?
> 
> I think it would be useful to standardize on a debian version
> (customization) of the standard schema (aka DocBook) in general use
> for computing-related documentation. 
> 
> Adoption of a customization of DocBook would also mean a move away
> from debiandoc-sgml, which would free up some of Ardo's time to work
> on the xml infrastructure stuff.

These are the basic ideas of what I would propose (sorry for the line
breaks):


<?xml version='1.0' encoding='utf-8'?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform";>
                                                                        
       
  <!-- import the real stylesheet -->
  <xsl:import
href="file:///usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/docbook
.xsl"/>
                                                                        
       
  <!-- make HTML 4.01 output with utf-8 encoding -->
  <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"/>
                                                                        
       
  <!-- custom tables -->
  <xsl:variable name="html.cellpadding">0</xsl:variable>
  <xsl:variable name="html.cellspacing">0</xsl:variable>
                                                                        
       
  <!-- 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>
                                                                        
       
</xsl:stylesheet>


There are quite some problems though which need being solved:

- What's the best encoding?  iso-8859-1 is probably the most widely
used, but utf-8 is the future.  As long as the files are viewed offline
(i.e. not via http) that's not so much of a problem as long as the
browser supports the chosen encoding, and nowadays most browsers support
utf-8.  To the other side, if the file is transferred via http the <meta
http-equiv="content-type" content="asdfafd"> is ignored and the encoding
specified in the http headers is encoded.  Thus, if a file is utf-8
encoded many people putting it on a webserver will have to adapt the
used http content type.  What's the way to go?  utf-8?  iso-8859-1? 
something else?

- Use an external stylesheet or not? Or no css at all?  Using an
external stylesheet is better for large collections of documents and/or
large stylesheets.  It's more problematic for offline viewing.  Using
CSS at all may be problematic for browsers such as Netscape 4, but how
many people are still using that?  Not using CSS at all and using no
formatting and/or using tags such as <font> may be limiting and/or more
work.

- Should there be more versions of the stylesheet?  Like, one for online
viewing with modern GUI browsers and one for printing/lynx?

However these answers may be, I thing that it is necessary to define a
customization layer for the DDP.  Once everybody uses it (even if it
just imports the original stylesheet and does nothing else) it is much
easier to apply a new stylesheet to the whole DDP.

Something else I sometimes think is missing is a guide defining which
tags are to be used for what.  DocBook defines an overwhelming number of
tags, and it's not always clear whether something should be a <literal>
or a <command> or a <filename> or whatever else.  I remember this was
already discussed once; did anything come out of that discussion?


Aaron Isotton                                 [ http://www.isotton.com ]
-- 
University politics are vicious precisely because the stakes are so
small.
		-- C. P. Snow

Attachment: pgpSFYj5QcDcc.pgp
Description: PGP signature


Reply to: