Rich, you've discovered that DocBook can have a bit of a steep learning curve... Its worth working through, in my opinion, and you'll get there shortly.
There have never been too much Mac OS X specific material available... The earliest item that I had found was a packaged installer from Project: Omega in France. "Mezis has gathered several XML-related tools out there in order to build a comprehensive DocBook processing package, initially for the team at Project:Omega. The result of this work is the DocBook-X package" which you can find at:
They offer a tutorial as well, but I've not looked at it in some time, so I can't comment on how useful it may be for you. As I recall it was a good overview of the document creation cycle, although it may be a bit out of date as well.
A more recent resource is Steve Ball's Tcl front-end for XSLT processing, found at:
Steve's site also offers Mac OS X binaries of libxml and libxslt, eliminating the need for Fink.
At 12:44 PM +0900 10/6/05, Michael Smith wrote:
Caveat: I would guess that page is probably not up to date. But
perhaps you can volunteer to update it after you're done getting
your kit set up. :-)
psgml - couldn't find it!!!
Assuming that I'm successful, and that we can finesse the little
"immmutable page" notice at the bottom of the page, I'd be quite
happy to do so.
Bad place to start.
The best place to start now is with Bob Stayton's "DocBook XSL:
The Complete Guide" -
That is up to date and will tell you pretty much everything you
need to know.
... If you are starting fresh with DocBook, you should use the
XSL-based toolchain, following the steps in Bob's book.
Let me get this straight. I should ignore a document that tells
me that I can process a docbook file into (say) HTML with a single
command. Instead, I should fish my way through 20+ pages of dense
installation and configuration information in Bob's book, trying to
figure out which instructions might be applicable to the programs
that I (supposedly) just installed. I begin to see the problem.
Well, there are some things I can determine:
% which pdftex
% which xsltproc
I look into installing xmlto, but it requires a different getopt
than OSX has. I try installing the suggested getopt, but it does
not build on OSX. The problem becomes a bit clearer.
I then look into "Docbook XSL", trying to find a "Hello World",
such as the one in the "Crash Course". No such luck; instead, I
find a long-winded chapter on "XML catalogs". Moan.
The "Crash Course" may be out of date, but it HAS THE RIGHT IDEA.
A newby needs an easy way to get things set up, determine that the
needed commands are all present, and get some plausible results.
THEN, s/he can be told that there are better (though more complex)
ways to do things.
So, what I'd like is a short example file and some equally short
commands to turn it into HTML and PDF. Can someone supply these,
so that I can put them into the wiki?