[OT] Re: [docbook] Using multiple modules

[Tobias Reif <tobiasreif@pinkjuice.com>]

On Sun 2004-02-08 Nikolai Weibull wrote:
> > > This remark was mostly made after having spent many hours trying
> > > to get various versions of DocBook (SGML and XML) to install and
> > > work properly.  Both with the whole catalog business that wasn't
> > > really solved in a standard and clean way until recently it
> > > seems
> >
> > Standardizing the file locations for a certain OS may help in some
> > scenarios, but is not absolutely necessary in general. The OASIS
> > XML Catalog language is standardized; create one and make it
> > visible to your tools (eg via $XML_CATALOG_FILES), should work
> > great.
> 
> yes, but I feel that this has only recently been applied
> successfully recently, at least in distributions I have come across.
> I do not appreciate the use of environment variables, I do prefer
> standardized file locations.

Standardization can serve as a basis but can't solve all the problems
of all types of scenarios. BTW $XML_CATALOG_FILES takes a list so
it's easy to combine standardized and custom (eg system-wide and user
account) catalogs.

> I see the point for environment variables when standards can't be
> made or enforced (Windows), but having something that works for most
> (at least me, now) is good.

Yes, as a basis a standardized setup makes sense, but stuff works for
me, now, without relying on standard file locations for catalogs.

> > In case it helps, here's how I do it:
> > http://www.pinkjuice.com/howto/vimxml/setup.xml#catalogs
> 
> All this is now done automatically when I install DTD's and such for
> my distribution (gentoo).

On my system I combine automatically installed setups with my custom
ones; I'm sure Gentoo can't install the DTD for my address book, or
the RNG for my language list.

> > > and due to bugs in many of the wrapper utilities.
> >
> > I recommend using the tools directly, eg from batch or shell
> > scripts.  Then you are less dependent on wrapper utilities.
> 
> Well, I don't feel this way.

We can always agree to disagree; people prefer different strategies.

> I like being able to write
> 	xmlto xhtml file.xml
> I don't like writing
> 	xmllint --xinclude --postvalid file.xml | xsltproc ...
> and so on, and the above doesn't even do error checking.

I suggested to write shell scripts; mine do have extensive error
checking.

But if the wrapper tools now meet your requirements and preferences
that's great.

> The tools have become much better now, and the XML tools are so much
> better than the SGML ones, so this I no longer have any issues with.

Then there's no reason for all those general complaints?

> > > sgmltools-lite has this one bug that makes all catalog lookups
> > > fail and since it doesn't seem to be under development anymore
> > > it probably won't get fixed (I've fixed it myself after
> > > rediscovering it several times after reinstalls of my system).
> >
> > DocBook is a language, but here you're talking about tools. (BTW I
> > recommend to use DocBook XML and not SGML)
> 
> You are missing my point.  I was referring to past experiences, and
> thus SGML related software I have used in the past.

Yes I do miss the point to post complaints about current ("[...] has
this one bug") problems with SGML tools on the DocBook list ...

> SGML is dead (at least to me) and using XML makes the tools easier
> to implement and documents to write in my opinion, and I don't know
> anyone who disagrees. 

... especially if you don't use SGML anymore.

> And I don't understand what you mean with the first sentence, I
> thought more or less the whole discussion was about the tools that
> drive DocBook.

Then your complaint (you called it a rant) was posted to the wrong
list:

http://www.docbook.org/mailinglist/
"<docbook@lists.oasis-open.org> for general DocBook questions. These
include questions about the DTD or schemas, questions about the syntax
or semantics of elements, and general DocBook markup questions. Please
don't post questions about the stylesheets, formatting or processing
issues, or other application-specific questions to this list.
[...]
<docbook-apps@lists.oasis-open.org> for stylesheet and
application-related DocBook questions. This is the place to ask
questions about formatting or processing issues, stylesheets, and
other applications."

> I don't remember saying that DocBook as a markup standard was at
> fault,

You complained about DocBook being too verbose:
(which is OK and on-topic for this list)

http://sources.redhat.com/ml/docbook/2004-02/msg00026.html
"I think DocBook is a great idea, and I love having both XHTML and PDF
output, but it seems that too much is in flux at the moment
(impossible to install, impossible to get output that looks good (PDF
anyway), and simply too verbose"

> just the tools built around it,

For DocBook tools there's docbook-apps@lists.oasis-open.org .

> > > Also, a lot of problems with passivetex, xmltex, and xmlto on my
> > > current distribution has really limited my use of DocBook.
> >
> > I suggest to send such feedback to the developers of the tools
> > with which you experienced problems.
> 
> As I stated in the next sentence of the original paragraph that you
> have quoted upon (and is in fact included below), these problems
> have mostly been resolved now, and I was in fact responsible for
> getting it done to a large extent, as I was in desperate need of
> these tools these previous two weeks.

I was not able to find out why you complain about tool problems on
docbook@lists.oasis-open.org which is not about tools, especially if
these problems are resolved, all after starting a complaint with "I
think DocBook is a great idea, and I love having both XHTML and PDF
output, but [...]".

> > > Anyway, that has finally been fixed and now that the FHS has
> > > made SGML and XML catalog and DTD locations standard everything
> > > should probably work a lot smoother.
> >
> > Until then (and after that too) you can always set up your own
> > system in any way you like.
> 
> I don't understand this comment, "now" means now, i.e. the present.

I would think it takes a while until all implementers (distro vendors
etc) implement a standard after it has been finalized.

> It seems that a lot of stuff has finally been nailed down (this may
> have been nailed down before, but not for my distribution in any
> case)

That's why I wrote "until then".

> and I have a working system.

So in two days you solved the problem that "DocBook is [...]
impossible to install" [1], congrats :)

You wrote you "switched to using CONTEXT for TeX", which seemed to
imply you hadn't managed to setup your DocBook env.

> The problem with hacking away, setting up files and changing stuff
> in the way you suggest has the inherent problem that next time I
> need to reinstall (or try to produce my documents on another machine
> for that matter) things won't work anymore and the procedure must be
> run yet again.

It's the wrong list if you want to suggest improvements regarding
tools or distros. (If you have feedback on catalogs I suggest to be
constructive and more specific than "the whole catalog business";
people can't really act on that).

As I said before, it's fine if you want to deploy a different
strategy, but I don't have the problems you describe. Reinstallation
and reproducing my documents sure includes setting up the env for
that, I don't and can't expect the distro or some package to do it all
(no distro includes my XSLTs for example). For a typical preference
profile things should be set up in a way that allows people to start
without much fuss, I agree, but for people who use many custom
transformations, custom XML languages, and less popular tools there's
no alternative to "hacking away", which, done in a sensible way, works
smoothly and doesn't result in the problems you describe if done
sensibly (sure I must copy my schemas, catalogs and scripts, no
surprise and no problem).

Tobi

[1]
http://sources.redhat.com/ml/docbook/2004-02/msg00026.html

-- 
Vim users, don't forget to
   http://iccf-holland.org/donate.html