discuss: Docbook, Xml, Jade etc.
Subject:
Re: Docbook, Xml, Jade etc.
From:
Simon Anderson ####@####.####
Date:
29 Jul 2003 14:11:31 -0000
Message-Id: <Pine.LNX.4.44.0307290856001.23151-100000@raven.satexas.com>
On Tue, 29 Jul 2003, Mark Komarinski wrote:
> And you're insinutating that LDP documents are crap without giving
> either reasons why it's crap or suggesting improvements.
OK. Here's an overview of my experience;
-Started by reading through the Author Guide from the beginning to get an
idea of what is required and understand that there are various tools which
need to be in place in order for me to start using Docbook.
-Then prepared to work through the rest of the Howto by installing the
necessary tools.
-Began working through chapter 3 "the tools" section by section, obtaining
each of the pieces required in order; NW DSSL, LDP DSSL, dockbk41.zip,
xml4.1.2, jade-1.2.1 from sections 3.1.1 through to 3.3.1
-Noted that each of these sections gives an extremely brief overview of
what each piece is, but very little detail on how they are used and absolutely
nothing on how they are installed and configured.
-Noted that Section 3.3.1.1 "using jade" does give some hints on
installation of the various pieces, but that this is sparse.
Work through it, installing the pieces into the recommended directory
structure blind as the packages themselves don't include documentation or
if they do, it is extremely small and undescriptive.
-Then created the catalog file and try the example test command provided,
which not only doesn't work, it outputs screeds of error messages.
-Worked back through section 3 in it's entirety, trying to work out what
I've missed, referencing the documentation that I can find inside the
packages and "guess and testing" to try and get it to work.
-Went back to the start of the Author Guide and looked for another source
of documentation, find a reference to some in section 3.7. Look through
the plethora of available documents, none of which appear to have an
answer to the error messages I am getting. Start working through some of
them which introduce a number of completely new tools, rapidly become
confused, struggle through guessing and testing until finally realising
that I'm out of my depth and giving up.
Summary: Section 3 does not adequately document the tools installation and
configuration process or clarify how linked associated documents apply to
an initial installation of the tools as described in the Author Guide.
How it should be: A step by step guide to installing each piece in
section, explaining what it does, how it fits into the overall system and
how it can be configured.
Fix: Martin Brown's excellent post, available here;
http://lists.tldp.org/index.cgi?1:mss:4797:200307:eiekdlajdgeofpemfdln
> The number of documents and variety of authors seems to disprove your
> point.
Have a read through the rest of this thread. A number of other posters
have struggled with the Author Guide and the majority agree that it needs
improvement. For myself, I am now in a position to use the various tools
in spite of my experiences with the Author Guide.
Regards,
Simon.
