discuss: LDP Style discussion (cont.)
Subject:
Re: LDP Style discussion (cont.)
From:
Alexander Bartolich ####@####.####
Date:
10 Apr 2002 22:54:45 -0000
Message-Id: <3CB4C1F6.40205@gmx.at>
I have the feeling that this thread currently concentrates
on a sort of beauty contest. Nice language, nice outline,
nice layout.
To me this is wrong priorities.
And I'll annoy you with a concrete example.
I started development of my document with the tools
shipped with RedHat 7.2 (IMHO a typical setup).
No hassle, immediate results.
But then I got notice of the "LDP Author Guide" and decided
to render my stuff with 'ldp.dsl'.
Item '3.3. Jade' is whirl wind tour for installing Jade on
a naked system. There is nothing wrong with that (apart from
suggesting /usr/local/sgml/ instead of /opt/sgml).
But to someone already having clean HTML output
the perspective of having to install everything from
scratch just sounds wrong.
On to next page, '3.4. Jade wrappers'.
After reading the first sentence
# These tools are optional [...]
I would have almost skipped the page. But further down is
something interesting:
# [...] These tools are provided with Red Hat 6.2.
# Make sure the following packages are installed:
Does this mean I still have to install jade from scratch,
as described in item '3.3'? Does not say. There is a
description of 'db2html', but nothing on how to force
ldp.dsl into it.
Anyway, after skipping half the document I find the next
necessary step, '7.3. Using ldp.dsl'.
# [...]
# Change the first "docbook.dsl" to read
# /usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl
I do have a '/usr/lib/sgml' on my installation, but nothing
further down. What distribution is this page talking about?
Does not say. And there is also no hint to try a
$ locate docbook.dsl
Anyway, now it's time for RedHat to complicate matters.
They actually ship two dsl-files.
Package docbook-style-dsssl seems to contains version 1.64
of Norman Walsh's modular stylesheets for DocBook.
It does not work with ldp.dsl (just dumps plain ascii on stdout).
Package docbook-utils contains version 1.0-4 of
"The GNOME Documentation Project's Custion DocBook Stylesheet Layer".
This one works, though by emitting lots of
# invalid value for "attributes" characteristic"
Anyway, I still had to insert
(declare-flow-object-class element
"UNREGISTERED::James Clark//Flow Object Class::element")
at the appropriate place into ldp.dsl to get it going
(found that one on google).
But they journey is not over.
The authors of ldp.dsl seem to hate '-' and '_' as part of entity
names and section IDs. As a C programmer I'm used to identifiers
like 'magic_of_elf'. ldp.dsl accepts only 'magic.of.elf'.
This should be mentioned in LDPAG.
And perhaps some short example for
$ perl -pi.bak -e 's/magic_of_elf/magic.of.elf/g' *.sgml
And why that trivial regular expression may not work.
Ok. Enough. I got it working. First class results with
free software. And I did not have to buy books or pay a hotline.
But I really think that if LDP has excessive energy
it should invest it into quality control and a usability lab.
