I'm trying to set up docbook-tools...

I'm trying to set up docbook-tools...

[Eric S. Raymond]

I'm trying to set up docbook-tools, and finding it a hideously
frustrating experience.  Why does all the SGML software and
documentation in the world read as though it was carefully designed 
to prevent any actual document production from getting done?

The < http://sourceware.cygnus.com/docbook-tools/ > page directs me to
< ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That server is
perpetually swamped.  Going to one of the mirrors, I find a
docbook-3.1-5.noarch.rpm, but it does not contain any of the db2*
scripts referenced on the DocBook page.  Where are those scripts?
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

"The best we can hope for concerning the people at large is that they be
properly armed."
        -- Alexander Hamilton, The Federalist Papers at 184-188

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page
    Eric> directs me to
    Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That
    Eric> server is perpetually swamped.  Going to one of the mirrors,
    Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain
    Eric> any of the db2* scripts referenced on the DocBook page.
    Eric> Where are those scripts?

There should be several RPMs on that ftp site.  The scripts you seek
are in the stylesheets RPM.  Also make sure you don't only get the
noarch RPMs.

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Mark Galassi <rosalia@galassi.org>:
> 
>     Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page
>     Eric> directs me to
>     Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That
>     Eric> server is perpetually swamped.  Going to one of the mirrors,
>     Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain
>     Eric> any of the db2* scripts referenced on the DocBook page.
>     Eric> Where are those scripts?
> 
> There should be several RPMs on that ftp site.  The scripts you seek
> are in the stylesheets RPM.  Also make sure you don't only get the
> noarch RPMs.

OK, what is the actual stylesheet RPM?  You didn't specify, and all I
can find is SRPMs and tarballs.

Would it be too much to ask that these things actually be described
on the DocBook tools page?

Every time I go near SGML I get headaches...
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

Government is actually the worst failure of civilized man. There has
never been a really good one, and even those that are most tolerable
are arbitrary, cruel, grasping and unintelligent.
	-- H. L. Mencken 

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Eric> OK, what is the actual stylesheet RPM?  You didn't specify,
    Eric> and all I can find is SRPMs and tarballs.

I'm surprised you don't find it.  I went to the first mirror and found
the non-source noarch RPM for stylesheets at:
ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/RPMS/noarch/

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Mark Galassi <rosalia@galassi.org>:
> I'm surprised you don't find it.  I went to the first mirror and found
> the non-source noarch RPM for stylesheets at:
> ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/RPMS/noarch/

Thanks.  The mirror I checked was missing the docware/RPMS part.

The docbook-tools page ought to mention that  the db2* scripts live in the
stylesheets RPM.  Otherwise it's way too easy to get sidetracked by the
docbook RPM.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

When only cops have guns, it's called a "police state".
        -- Claire Wolfe, "101 Things To Do Until The Revolution" 

Re: I'm trying to set up docbook-tools...

[Chuck Mead]

On Tue, 4 Jul 2000, Eric S. Raymond spewed into the bitstream:

ESR>Mark Galassi <rosalia@galassi.org>:
ESR>> 
ESR>>     Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page
ESR>>     Eric> directs me to
ESR>>     Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That
ESR>>     Eric> server is perpetually swamped.  Going to one of the mirrors,
ESR>>     Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain
ESR>>     Eric> any of the db2* scripts referenced on the DocBook page.
ESR>>     Eric> Where are those scripts?
ESR>> 
ESR>> There should be several RPMs on that ftp site.  The scripts you seek
ESR>> are in the stylesheets RPM.  Also make sure you don't only get the
ESR>> noarch RPMs.
ESR>
ESR>OK, what is the actual stylesheet RPM?  You didn't specify, and all I
ESR>can find is SRPMs and tarballs.
ESR>
ESR>Would it be too much to ask that these things actually be described
ESR>on the DocBook tools page?
ESR>
ESR>Every time I go near SGML I get headaches...

I started fooling with this stuff early last fall and I went through similiar
travails. I captured what I did in a colophon for one of the documents I
created in docbook/sgml. Maybe this will help:

http://www.moongroup.com/docs/mailhelp-HOWTO/z632.html

hth!
--
Chuck Mead, CTO, LinuxMall.com
csm@LinuxMall.com
GnuPG Public Key Available: http://pgp.ai.mit.edu/

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Tue, 04 Jul 2000, Eric S. Raymond wrote:
> I'm trying to set up docbook-tools, and finding it a hideously
> frustrating experience.  Why does all the SGML software and
> documentation in the world read as though it was carefully designed 
> to prevent any actual document production from getting done?

That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it
were a briefly written summary written in a foreign language to be as terse as
possible. You would suspect that the authors of documentation tools would
themselves be enamored of documentation. WIth the exception of Donald Knuth, 
that, alas, does not appear to be the case. 

It's bad enough that the authors of every book and document that exists on SGML
have invented their own inscrutable terminology for the process of marking up
documentation... but none of them, zero, zilch, appears to have considered the
notion of a GLOSSARY, and the very thought of explaining complex terms in a
simple, clear manner appears to break every single SGML author out in hives. 
Yes, it's difficult. I've done it before, I know how difficult it is. But it's
as if the creators of SGML DTD's and tools have a death wish... or else they're
trying to protect their cult's purity by keeping out the riff-raff (same
thing). 

Despite all of the above, I have become reasonably proficient in using the
Docbook-Tools set and in Docbook itself.  But the tool kits still do not work
well enough for me to actually use them to produce real documentation. I am
using Docbook for the design documentation for a major project at the office,
but nobody on this list has been able to explain to me why half the entries in
my index have "-999" as the page number, even when the 'jadetex' script does not
complain about unresolved references.  I've even tried updating everything
from the Docbook-tools site thinking maybe Red Hat had a wonked out
docbook-tools installation.  I even tried using Caldera eDesktop 2.4 rather than
Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No
go. I'm on the verge of abandoning the tool kit in frustration. LyX will now
generate decent HTML output, which was my main reason for using DocBook in the
first place (the difficulty of getting good HTML output out of "latex2html" and
its ilk).  My only issue with LyX is the difficulty of maintaining multi-source
documentation in a CVS depository... CVS won't do merges of multi-author edits
of .lyx files, sigh.  But if it's a choice of LyX or using StarOffal, I know
which I'll choose -- at least LyX is a structured markup tool, whereas
StarOffal.. no, don't get me started. 

> The < http://sourceware.cygnus.com/docbook-tools/ > page directs me to
> < ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That server is
> perpetually swamped.  Going to one of the mirrors, I find a
> docbook-3.1-5.noarch.rpm, but it does not contain any of the db2*
> scripts referenced on the DocBook page.  Where are those scripts?

On Red Hat 6.2 Linux, they're in "stylesheets-1.54.13rh-1.xxx.rpm" (put
architecture of choice in place of 'xxx').  Red Hat ships with what is
basically a slight tweak of the docbook-tools kit. 

'docbook-3.1-5.noarch.rpm' is just the DTD (Data Type Definition), it does not
contain the other software you'll need to convert programs written using that
DTD into a useful form. You'll need 'jade' and 'stylesheets' to do that. 
'jade' is the actual grunt engine, while 'stylesheets' is the Scheme and
scripts that the grunt engine uses to know how to do the conversion. 

export SGML_CATALOG_FILES=/usr/lib/sgml/CATALOG 
export SGML_ROOT=/usr/lib/sgml

are also nice to tell Emacs's psgml mode where to find the overall catalog and
SGML dtd and tools. I use 'xemacs', which puts up a nice SGML menu at the top.

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

I'm surprised nobody came across my tutorial:
	http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html

It has been improved on by several people, but always in a specific
context, like the FreeBSD documentation guidelines.

It is mentioned in the sourceware web page.

Re: I'm trying to set up docbook-tools...

[madhu]

On Tue, 04 Jul 2000, you wrote:
> On Tue, 04 Jul 2000, Eric S. Raymond wrote:
> > I'm trying to set up docbook-tools, and finding it a hideously
> > frustrating experience.  Why does all the SGML software and
> > documentation in the world read as though it was carefully designed 
> > to prevent any actual document production from getting done?
> 
> That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it
> were a briefly written summary written in a foreign language to be as terse as
> possible. You would suspect that the authors of documentation tools would
> themselves be enamored of documentation. WIth the exception of Donald Knuth, 
> that, alas, does not appear to be the case. 
an html.zip file exists on the officail docbook site oasis with enough details
for anybody to start with  . it is also linked from normans website from where
you can download the latest stylesheets for the docbook,
oasis wesite is 
 http://www.oasis-open.org/docbook/
and normans website is 
http://nwalsh.com/~ndw/
  > 
> It's bad enough that the authors of every book and document that exists on SGML
> have invented their own inscrutable terminology for the process of marking up
> documentation... but none of them, zero, zilch, appears to have considered the
> notion of a GLOSSARY, and the very thought of explaining complex terms in a
> simple, clear manner appears to break every single SGML author out in hives. 
> Yes, it's difficult. I've done it before, I know how difficult it is. But it's
> as if the creators of SGML DTD's and tools have a death wish... or else they're
> trying to protect their cult's purity by keeping out the riff-raff (same
> thing). 
> 
> Despite all of the above, I have become reasonably proficient in using the
> Docbook-Tools set and in Docbook itself.  But the tool kits still do not work
> well enough for me to actually use them to produce real documentation. I am
> using Docbook for the design documentation for a major project at the office,
> but nobody on this list has been able to explain to me why half the entries in
> my index have "-999" as the page number, even when the 'jadetex' script does not
> complain about unresolved references.  I've even tried updating everything
> from the Docbook-tools site thinking maybe Red Hat had a wonked out
> docbook-tools installation.  I even tried using Caldera eDesktop 2.4 rather than
> Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No
> go. I'm on the verge of abandoning the tool kit in frustration. LyX will now
> generate decent HTML output, which was my main reason for using DocBook in the
> first place (the difficulty of getting good HTML output out of "latex2html" and
> its ilk).  My only issue with LyX is the difficulty of maintaining multi-source
> documentation in a CVS depository... CVS won't do merges of multi-author edits
> of .lyx files, sigh.  But if it's a choice of LyX or using StarOffal, I know
> which I'll choose -- at least LyX is a structured markup tool, whereas
> StarOffal.. no, don't get me started. 
the problems you are mentioning are mostly to do with SGML tools not with
docbook by itself. if you use the scripts like db2pdf it doesn,t some time run
jadtex thrice for the numbers to be printed right .the db2* scripts are a sort
of primer a starting point so to say but without them you can produce docbook
documents , please refer to the readme's of jade, jadetex etc.and be warned
that situation is not likely to improve what with SGML is dead proclamations
doing the rounds and shift is towards XML . but again tools for XML are not unix
favorable  at all .

additionally i would suggest you subcribe to 

docbook-apps@lists.oasis-open.org, 
and
docbook@lists.oasis-open.org
 lists whree you might get more help than this list since this is of late a very
low traffic list.
and as Mark's excellent tutorial, please don't forget this
 http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html

regards
-- 
maddy
-------------------------------------------------------------------------       
         Fishing baskets are employed to catch fish;
         but when the fish are got, the men forget the baskets;
         Words are employed to convey ideas;
         but when the ideas are grasped, the men forget the words; 
				
					        --"Chuang Tzu"

-------------------------------------------------------------------------	

Re: I'm trying to set up docbook-tools...

[Sam Roberts]

> > Despite all of the above, I have become reasonably proficient in using the
> > Docbook-Tools set and in Docbook itself.  But the tool kits still do not work
> > well enough for me to actually use them to produce real documentation. I am

They work well enough for us, so it is possible! See:

http://www.cogent.ca/Download/Documents.htm

The slang programmin language and cascade db docs are all from docbook. I wrote
my own scripts and makefiles to drive jade and [pdf]jadetex based on taking
a peek into the db2* scripts. It took a while, but it was no harder than
dealing with LaTeX, back when I used it in university.

Sgml isn't really a documentation language, it's a markup language, the markup
is then used to generate documentation, by some people, and with some tools.
For those of us who actually want documentation, the vagueness of all the sgml
docs when it comes to actually generating documentation is frustrating, but
sgml+docbook+jade+jadetex are still the best tools around.

> additionally i would suggest you subcribe to 
> 
> docbook-apps@lists.oasis-open.org, 

I second this.

docbook-apps is very active, and very helpful, if you're trying to use docbook
you should be on this list.

Sam

Re: I'm trying to set up docbook-tools...

[Sam Roberts]

----- Original Message ----- 
From: Eric Lee Green <eric@badtux.org>


> Still, TeX and LaTeX still exist. They are thoroughly documented. They run the
> same way everywhere. They look ghe same everywhere. So while they are not the
> be-all and end-all of structured document design, they'll have to do, since the
> SGML crowd has committed collective suicide. A pity, that. 

This is just a variant of the classic complaints about Unix: I just want to
do X, but the docs don't tell me how. LaTeX is a single tool that does it
all, to use sgml you have to use a set of tools, and you can mix and match
them. You can use jade without docbook or norm's style sheets, you can use
jadetex without using docbook, the db2* scripts are so optional most people
write their own, and you don't have to use emacs to edit sgml, but it helps.

As for the sgml crowd committing suicide, judging from the increased traffic
on the oasis docbook lists, which led to a split into two still very busy
mailing lists this spring, and the increasing number of open source projects
whos docs appear to be docbook generated, I'd say people are perservering and
getting the job done.

Sam

Re: I'm trying to set up docbook-tools...

[David C. Mason]

> > I'm trying to set up docbook-tools, and finding it a hideously
> > frustrating experience.  Why does all the SGML software and
> > documentation in the world read as though it was carefully designed 
> > to prevent any actual document production from getting done?

This is one of those cases where certain documentation projects have
taken up the call more so than the tools side. For example, both the
GNOME and KDE doc groups have manuals to help people get involved with
writing documentation for their projects. Both tell the writer where
to get everything they need for Docbook and how to use it - but both
also describe it in terms that are particular to their style of
writing.

I like this approach as it narrows the focus to projects and those who
wish to write for those projects. Outside of that the best resources I
have seen are Mark's tutorial and Deb Richardson's HOWTO at OSWG. The
main problem with it is that describing SGML is not as trivial as you
might think. Describing DocBook is easier, but it still comes as very
foreign to those who come from either the word processor world, or the
format driven mark-up world. The best way to learn is by trying, not
by reading IMHO. Can the documentation be better? Sure it can, and we
shall try.

Still, I find it somewhat humorous at the trouble many hackers (who
would never dream of documenting their code) have when they can read
the source :-)


Cheers,

Dave

-- 

          David Mason
        Red Hat AD Labs

        dcm@redhat.com
  http://people.redhat.com/dcm

Re: I'm trying to set up docbook-tools...

[Ismael Olea]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 893 bytes --]

Sam Roberts escribió:

> them. You can use jade without docbook or norm's style sheets, you can use
> jadetex without using docbook, the db2* scripts are so optional most people
> write their own, and you don't have to use emacs to edit sgml, but it helps.

	We have a little problem with these tools. There aren't a more-or-less
sgml suite made of components (packages) with well made package
dependeces. Then, if you want to use linuxdoc, your package system'll
ask for sp, linuxdoc-dtd and its filters. If you want XML DocBook, the
packages we all know. Add a new package (TEI?) could need to add it's
dtd, the stylesheets and maybe some interface.

	What do you think?

-- 

        A.Ismael Olea González

        mailto:olea@hispalinux.es  http://www.hispalinux.es/~olea
        2:345/108.9@fidonet.org
                
        El mundo debe empezar a tener miedo a un planeta DEF

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Ismael> 	We have a little problem with these tools. There
    Ismael> aren't a more-or-less sgml suite made of components
    Ismael> (packages) with well made package dependeces. Then, if you
    Ismael> want to use linuxdoc, your package system'll ask for sp,
    Ismael> linuxdoc-dtd and its filters. If you want XML DocBook, the
    Ismael> packages we all know. Add a new package (TEI?) could need
    Ismael> to add it's dtd, the stylesheets and maybe some interface.

These problems exist, but are on their way out.  It will eventually be
possible to just install a nice suite of sgml-based tools.

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ Eric Lee Green <eric@badtux.org> was heard to say:
| That puzzles me too. Even Norm Walsh's so-called "Docbook" book
| reads as if it were a briefly written summary written in a foreign
| language to be as terse as possible.

<sigh/> I'm sorry you found it to be that way. That wasn't the intent.
Although the bulk of the book is intended as a reference and not a
how-to, the introductory chapters were supposed to be readable by the
novice. Can you explain, in any more detail, what you found most
troubling?

| It's bad enough that the authors of every book and document that exists on SGML
| have invented their own inscrutable terminology for the process of marking up
| documentation... but none of them, zero, zilch, appears to have considered the
| notion of a GLOSSARY, and the very thought of explaining complex terms in a
| simple, clear manner appears to break every single SGML author out in hives. 
| Yes, it's difficult. I've done it before, I know how difficult it is. But it's
| as if the creators of SGML DTD's and tools have a death wish... or else they're
| trying to protect their cult's purity by keeping out the riff-raff (same
| thing). 

It is an unfortunate fact that Goldfarb created a set of concise,
technical terms for describing the various components of SGML
markup. On the one hand, using these terms precisely tends to be
awkward for novices. On the other, using other terms causes confusion
among other audiences.

I really tried to be clear in this regard. <sigh/>

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | Everything is temporary.
http://nwalsh.com/            | 

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Eric> I don't think anybody doubts that it was your intention to
    Eric> be clear.  Your execution, however, completely failed in
    Eric> that respect.  The failure seems to me to be an indicator of
    Eric> a wider problem in the technical culture surrounding SGML,
    Eric> one I've bitched about before.

Please do not post rude messages to this list.

On this list we should not tell people that "they have failed" just
because their pedagogical approach did not work for us.

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Mark Galassi <rosalia@galassi.org>:
> On this list we should not tell people that "they have failed" just
> because their pedagogical approach did not work for us.

You're quite right.  We tell people they have failed when their
pedagogical approach has been reported to be ineffective by
independent multiple observers.

That is, that's what we do if we actually care about improving matters.
If all we want to do is wrap the failure in a thick layer of feel-good
batting so it can be ignored, then perhaps we do something else.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

Americans have the will to resist because you have weapons. 
If you don't have a gun, freedom of speech has no power.
         -- Yoshimi Ishikawa, Japanese author, in the LA Times 15 Oct 1992

Re: I'm trying to set up docbook-tools...

[Kendall Clark]

>>>>> "Eric" == Eric S Raymond <esr@thyrsus.com> writes:

    Mark Galassi <rosalia@galassi.org>:
    >> On this list we should not tell people that "they have failed"
    >> just because their pedagogical approach did not work for us.

    Eric> You're quite right.  We tell people they have failed when
    Eric> their pedagogical approach has been reported to be
    Eric> ineffective by independent multiple observers.

    Eric> That is, that's what we do if we actually care about
    Eric> improving matters.  If all we want to do is wrap the failure
    Eric> in a thick layer of feel-good batting so it can be ignored,
    Eric> then perhaps we do something else.

Well if it's about adjudicating pedagogy, then I should chime in with
"Norm's book helped me tremendously, as has Norm personally on the
several occasions when I emailed him with questions." I figured out
SGML and DocBook well before Norm's book came out, well before I
learned to program in fact. There are other SGML books, some of which
are rather practical. Those helped too.

As for actually setting up and installing the various permutations of
the free tool chain, I just don't see why it's *so* hard for someone
with a bit of technical ability or experience. Could it be *easier*?
Of course. But so could nearly every bit of free software I've ever
used. 

I started working with SGML on Linux in '96, well before anyone was
making nice RPM packages for it; maybe that's an advantage in a
perverse way? I'm not sure.

Best,
Kendall Clark

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Kendall> As for actually setting up and installing the various
    Kendall> permutations of the free tool chain, I just don't see why
    Kendall> it's *so* hard for someone with a bit of technical
    Kendall> ability or experience.

It isn't.  The person who started this thread said there was no
tutorial which includes setting up the tools, but there actually was.
Although things are out of date, this whole thread is mostly
unnecessary.

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

David C. Mason <dcm@redhat.com>:
> Your problem installing the tools seemed (as I read back through the
> thread) to be one of finding a mirror that was bad. Once you found a
> mirror which contained the RPMs needed are we to assume the
> installation went according to plan? 

Oh, no.  That wasn't my only problem by a long shot.  I actually went
through three different attempts to get three different sets of tools
running -- Jade, OpenJade, and the DocBook tools.  Not one of them had
adequate documentation for beginners, even technically sophisticated
beginners like me with considerable prior knowledge of SGML (I did a
lot of of extension work on SGML-Tools for the LDP).  All three have
web pages that are remarkable for the amount of detail they convey
without actually saying anything useful.

> Can all of this be improved for the newbie - it sure can. In fact new
> scripts or even applications can be written. You are a hacker, would
> you like to write them? Can I assume the answer is no?

Do you mean like the user's guide I once wrote for SGML-Tools to
address exactly this problem? :-)

Sorry, David.  You don't get to accuse *me* of carping without
contributing.  I happen to be the person who made SGML-Tools 1.1
usable for fast-turnaround book publishing, proved it by producing
"Linux Undercover" for Red Hat, and then documented what I did.  But
don't take my word for any of that -- go ask Ed Bailey about it.  You'd
probably find the story both entertaining and instructive.

> Slamming someone's book certainly cannot help you learn can it?

Slamming someone's book for lack of clarity certainly *can* be helpful
if it wakes the author (and the dysfunctional culture surrounding the
author) up to a problem.  

I did not mean to imply that Norman Walsh's book is without value.  If
I already knew most of what was in it, I'm sure it would make a dandy
reference.  But that's the problem -- the book is only useful for
people who already have a working SGML toolset and considerable
pre-acquired expertise.  

The fact that it was not useful to a person who had already done
substantial SGML publishing and extension work on SGML tools *should*
be an important message.

> I say 'kudos' to Norm for the following: 

I'll cheerfully say Norm is a wonderful guy too, if that will make you
or him feel any better.  He's done a lot of good things.   Unfortunately,
none of those things includes actually making SGML accessible to the
un-initiated. 

*And that is the issue here*.  The DocBook community has a huge blind spot.
The consequences of that blind spot drive away people like Eric Lee Green
or myself who would otherwise love to contrivbute more.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

"Today, we need a nation of Minutemen, citizens who are not only prepared to
take arms, but citizens who regard the preservation of freedom as the basic
purpose of their daily life and who are willing to consciously work and
sacrifice for that freedom."
	-- John F. Kennedy

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Thu, 06 Jul 2000, Mark Galassi wrote:
> Kendall> As for actually setting up and installing the various
>     Kendall> permutations of the free tool chain, I just don't see why
>     Kendall> it's *so* hard for someone with a bit of technical
>     Kendall> ability or experience.
 
> It isn't.  The person who started this thread said there was no
> tutorial which includes setting up the tools, but there actually was.
> Although things are out of date, this whole thread is mostly
> unnecessary.

Futile, perhaps. Unnecessary, no.  I am constantly fighting The Cult Of
Obscurity both on the job and off it, because so many good technical people
just don't see what's wrong with their documentation and programming.  "It
makes sense to me, other people must just be stupid" is the attitude of the
typical adherent of the Cult of Obscurity.  I sometimes have to fuss at my own
co-workers about "Look, I don't care about details x, y, and z, I, the
hypothetical the end user, just want to get job 'n' done",  and I'm certainly
not going to be reticient about doing the same elsewhere,  even if I'm not being
paid to do it elsewhere :-).  

People do not care about elegance. They do not care about how terse and formal
the language is surrounding a topic. They just want to get a job done with as
few keystrokes or mouse clicks as possible, and learning as few details as
possible to do it. This is one place where Lamport's LaTeX book shines (despite
how aweful it is otherwise), the first thing he does is say, "Here is how you
write a letter in LaTeX." What genius! 

Regarding Norm Walsh's book: the biggest problem was a lack of examples of how
to use DocBook to create entire documents.  There's reasonably good examples of
the use of many of the individual elements, but nothing like where Lamport
says, "Here is how you create a document. Here is how you create a letter.
Here is how to create a document that has a table in it." Lamport's LaTeX book
sucks... but it sucks in a way that lets most people write simple documents
after reading it. 

Note that I'm not calling the SGML crowd stupid.  I'm not saying that their
documentation "sucks" for people who are already initiated into the Cult Of
SGML. What I'm saying is that a) there's a paucity of documentation about how
to Get The Job Done, the only one I know about is the FreeBSD one, and b) there
has been a lack of attention to Getting The Job Done on the part of the
SGML community as a whole, they have been absorbed in the technical excellence
of SGML, the theoretical possibilities of parsing SGML, the stylistic elegance
of DSSL and stylesheet languages, whilst ignoring the whole point of the
exercise. I realize this is not an attitude that is restricted to the SGML
crowd. This sort of attitude is rampant in the computer biz, those of us who
have a good understanding of end user wants and needs are always the minority,
and those of us with both technical skills and writing skills are even rarer.
But, as the other Eric mentioned, this sort of attitude is also what kept SGML
from sweeping the world over the last five years, and is what basically has
killed SGML (with the exception of the HTML DTD and XML subset, the former of
which isn't really SGML anymore).  

'Nuff said. I'm sure I'll find many more flames in my mailbox from adherents of
the Highly Theoretical Cult of SGML Gurus.  But (shrug), when it comes to
document production, I'm an end user. I design tape backup and related software
for a living, not documentation tools.  All I want to do is to get a job done.
I don't CARE about how elegant DSSL is, or how flexible the Docbook DTD is...
it's a tool, for cryin' out loud, not a religion.  And if it doesn't Do The
Job, I'll dump it and use some other tool. Which, apparently, has been the
conclusion of most others who would use SGML, too, with the exception of a few
of the Open Source projects which use it because that's what the LinuxDoc
project uses. 

 -- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[David C. Mason]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Oh, no.  That wasn't my only problem by a long shot.  I actually went
> through three different attempts to get three different sets of tools
> running -- Jade, OpenJade, and the DocBook tools.  Not one of them had
> adequate documentation for beginners, even technically sophisticated
> beginners like me with considerable prior knowledge of SGML (I did a
> lot of of extension work on SGML-Tools for the LDP).  All three have
> web pages that are remarkable for the amount of detail they convey
> without actually saying anything useful.


Then I still don't understand the problems you are having... or at
least, I still haven't seen a detail of what you would like to see. I
think the ' Practical Guide...' is a very good intro to the scripts
and creating a DB document - its short, to the point, and includes,
what I think, you need to get started. But again, I can't figure out
except the mirror stuff, what is wrong...I'd like to help



> Do you mean like the user's guide I once wrote for SGML-Tools to
> address exactly this problem? :-)
> 
> Sorry, David.  You don't get to accuse *me* of carping without
> contributing.  I happen to be the person who made SGML-Tools 1.1
> usable for fast-turnaround book publishing, proved it by producing
> "Linux Undercover" for Red Hat, and then documented what I did.  But
> don't take my word for any of that -- go ask Ed Bailey about it.  You'd
> probably find the story both entertaining and instructive.

I had no idea you did the first SGML-Tools and I apologize, you are a
single entity in that case. Otherwise, I find that most hackers ignore
these tools altogether. My apologies.

Still, my problem is this thread has been about the lack of
documentation for DocBook - but I still don't understand what the
problem you are having is. I feel there is quite a bit of
documentation out there, and if I knew the problem I could point you
to it... if not, I could write it (especially since I am going to do a
DocBook talk at OLS, this info would help me). Otherwise complaining
about one or two particular documents doesn't do any good. You have
stated why you didn't like Norm's book, you stated you didn't like the
installation section in the 'Practical Guide...' HOWTO... so what do
you want? Need? Is it *really* helpful to point out flaws in those
particular documents when there might be one that answers your
question?


Dave

-- 


David Mason
Red Hat Advanced Development Labs
dcm@redhat.com (919)547-0012 x248

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Thu, 06 Jul 2000, David C. Mason wrote:
> "Eric S. Raymond" <esr@thyrsus.com> writes:
> > Anyone not already eyebrow-deep in the dysfunctional culture surrounding
> > this software would realize that this lacuna makes the rest of the 
> > chapter a bad joke.
>
> It is very easy to blame the SGML community for the problems inherent
> to understanding the technology, it is not as easy to lend a hand. Why
> is that? Do hackers think that documentation tools are beneath them
> until they actually have to use them?

Well, unfortunate but true, most hackers are no good at documentation. This
applies to SGML software creators as well :-(. 

Equally unfortunate but true, most hackers have no idea how end users think,
and thus have no idea how to create software that is easy to understand and
easy to use that solves problems that end users actually have.  They tend to
get caught up in making the software super-flexible and super-swiss-knife,
which is nice but not at the expense of ease of solving particular problems.  I
had to fight for the concept of "click this single button, and it does what 90%
of users want out of our software" when it came to prototyping a potential
future product, because the hacker who designed the thing had a screen
cluttered with stuff that would confuse the typical end user and which was not
intuitive at all. But it made sense to him. He didn't understand that most
people are not hackers and don't think like hackers. 

Finally:  those of us who are actually being paid to write documentation rarely
are getting paid to write documentation tools at the same time, and in most
cases even writing documentation is not our full-time job (I write
documentation as part of designing software -- you know, requirements docs,
functional specifications, design docs, class heirarchy docs, etc.). In
addition, we're often fighting pointy-haired bosses who want us to use
Microsoft Word or StarOffice or whatever "standard" office suite the
corporation has adopted, and who (having never written anything larger than
a letter) don't understand that structured document layout systems are much more
appropriate for technical documentation.  To put the blame on the end user for
the poor state of Docbook/SGML documentation and tools is a case of blaming the
victim... we're just out here trying to do a job, not fight religious wars, and
we have enough trouble getting permission to use any kind of SDL system without
having to fight a buggy one as well.  As it is, I have to continually justify
to my bosses my use of DocBook... they don't understand why I would want to use
a SDL instead of the "corporate standard" office suite. Now you're going to
blame me for the fact that I'm getting "-999" for half the page numbers in my
index?!  Sad but true, here in the real world the pointy haired boss's response
to problems that we have generating documentation with the Docbook tools is
"quit that Docbook BS and use Microsoft Word [StarOffice, WordPerfect, etc.]
like the rest of us."  

WHich is why my next set of documentation is going to be using LyX/LaTeX. The
tools work, they work reliably, they've worked reliably for years and years and
years, they're not ideal but they get the job done and dammit, that's all I
care about. And that's why SGML has remained a cult rather than a real solution
for most people's documentation problems. 

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Thu, 06 Jul 2000, David C. Mason wrote:
> Still, my problem is this thread has been about the lack of
> documentation for DocBook - but I still don't understand what the
> problem you are having is. I

The problem is not the lack of documentation. The problem is the lack of
attention to documenting DocBook as an actual document production system, rather
than as a theoretical exercise.  There is plenty of good theoretical
documentation, but a paucity of Get The Job Done tools and documentation.  This,
alas, has always been a problem of the SGML crowd. I've been following SGML off
and on since 1995 or so, when the original LinuxDoc project adopted that
LaTeX-like DTD, and aside from that project and one other that died aborning
(don't remember what it was, it was written using 'bigloo' Scheme and a DTD
that was similar to but simpler than DocBook), there has been absolutely no
attention at all amongst the SGML literati to the problems of producing
practical systems for ordinary users' purposes. And I'm talking as someone who
used to read Robin Cover's web page on a monthly basis looking for links that
would solve some actual problem that I had... it just never happened. 

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

David C. Mason <dcm@redhat.com>:
> Then I still don't understand the problems you are having... or at
> least, I still haven't seen a detail of what you would like to see.

I'd like to see documentation that spends less time genuflecting
before the wonderfulness of semantic markup and stylesheets, and more
time telling me how I can install and configure working tools and make
HTML and Postscript from actual documents.

Let's start with replacing that cop-out in the so-called "Practical
Introduction".  It's inexcusable, absurd, perverse, that a so-called
"Practical Guide" doesn't tell you (a) where to find installable
versions of the tools it's describing, and (b) how to set them up
so you can do the examples in the guide.

Let's continue with the fact that in the entire 635 pages of "DocBook:
The Definitive Guide", I found *not one* example of a command line that
could be used to produce actual, viewable HTML or Postscript from an
actual document.

Is it just me?  Am I crazy to think there's something wrong with a 600-page
tome on document production tools that *never once tells you how to 
format a document?*

The unbelievable part is that it's *all* like that.  It's not just the
individual authors of these particular documents that are high priests
of the Cult of Obscurity -- every piece of documentation I've ever
seen from the DocBook/SGML community is pretty much off in theoretical
cloud-cuckoo land.  I can learn more than I ever wanted to know about
DSSL and FOSI and fifty other acronyms, but I can't find any clue about
what to do when jadetex generates bad Postscript that makes gs choke.

What I want to see is a practical guide that is truly a practical guide --
something like what I wrote for SGML-tools, but covering DocBook.

> I had no idea you did the first SGML-Tools and I apologize, you are a
> single entity in that case. Otherwise, I find that most hackers ignore
> these tools altogether. My apologies.

Don't get an exaggerrated idea of my creds, either.  I didn't write
SGML-tools, nor was I ever its official maintainer.  I did one really
serious burst of work on it around 0.99-1.0 -- basically so I could pull
Red Hat's nuts out of the fire after Bob Young asked me nicely to
fix the godawful mess their old TeX-centric production process had
degenerated into.  And I did write the User's Guide.  But I had
very little to do with the design of the tool.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

Idealism is the noble toga that political gentlemen drape over their
will to power.
	-- Aldous Huxley 

Re: I'm trying to set up docbook-tools...

[David C. Mason]

"Eric S. Raymond" <esr@thyrsus.com> writes:


> I'd like to see documentation that spends less time genuflecting
> before the wonderfulness of semantic markup and stylesheets, and more
> time telling me how I can install and configure working tools and make
> HTML and Postscript from actual documents.

Hmmm I just don't see either of the online documents (Mark's or Deb's)
"genuflecting before the wonderfulness of semantic markup.." I do see
them telling you how to use the tools to "produce actual, viewable
HTML or Postscript from an actual document".

You are correct that there is not very good documentation for the
installation and that is partly due to the fact that depending on the
flavor of Linux or UNIX you are using, it is different. However, that
will change with the new DB Tools being created which includes a nice
proposal to the LSB to make sure it is the same across the board. Once
it is done I will be happy to write an installation guide for it.

You are catching DocBook at a time when it is finally being recognized
and used throughout many projects in Linux. The tools are not 100%
satisfactory but they are being worked on as we speak. When tools are
in flux, documentation is either non-existent or also in flux. That is
the nature of the beast. We release early and release often, usually
at the expense of good documentation and translation.

If you want really good docs *now* perhaps try a commercial Windows
product that uses DocBook. Otherwise wait, ask questions here or in
other forums, or pitch in with the effort. The new tools will be used
in a very different way, but with more functionality... I personally
would like to start documenting those even though they are not
available yet.


> Let's start with replacing that cop-out in the so-called "Practical
> Introduction".  

Please stop referring to people's work with words that are meant only
to insult. I'm sure plenty of people could refer to your essays with
venom, they perhaps choose not to as they know your heart is in the
right place for writing them in the first place.

> What I want to see is a practical guide that is truly a practical guide --
> something like what I wrote for SGML-tools, but covering DocBook.

A technical author tends to want other's writing to be exactly as they
write - its one reason why people have a hard time writing a book
together. There isn't much to be done about that except write it
yourself. I personally think that the Practical Guide is a great start
- it is still in progress mind you, but it tells you the *exact*
things you mentioned (besides the installation which I dealt with
above)... I am staring at it... it tells you how to use the scripts,
how to create a document, etc.

Also keep in mind that DocBook Tools is not the only set of tools
available for using DocBook. There are *many* tools available for the
XML side of it... and I guarantee you you would come in with both guns
blazing if you tried those tools... not one word of
documentation. Why? They released early at the expense of good
documentation/translation.


> -- basically so I could pull Red Hat's nuts out of the fire after
> Bob Young asked me nicely to fix the godawful mess their old
> TeX-centric production process had degenerated into.  

What a gentleman like approach to telling me you worked on it.


Dave
-- 


David Mason
Red Hat Advanced Development Labs
dcm@redhat.com (919)547-0012 x248

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

David C. Mason <dcm@redhat.com>:
> Please stop referring to people's work with words that are meant only
> to insult.

David, you ain't *seen* me being insulting yet.  So far, all I've done
is call a spade a spade.  You, and Deb, and Mark, and Norman, can
start being offended the day I don't respect you enough to criticize
your work.  Criticism is the tribute you pay adults who are capable of
better than they have done.  Indifference or dismissal would be the
real insult.

> I'm sure plenty of people could refer to your essays with
> venom, they perhaps choose not to as they know your heart is in the
> right place for writing them in the first place.

And since when is "having your heart in the right place" worth a damn?
If that's the best thing anyone could find to say about my work, *I'd*
be insulted.  I hold myself to higher standards than that.  You should too.

> > -- basically so I could pull Red Hat's nuts out of the fire after
> > Bob Young asked me nicely to fix the godawful mess their old
> > TeX-centric production process had degenerated into.  
> 
> What a gentleman like approach to telling me you worked on it.

The *point* is, I was called in to solve a nasty problem under
emergency conditions, and I did it.  I didn't get a lot of thanks for
it, either.  After "Linux Undercover" Bob decided that the mere fact
of designating me the editor of the book and putting my name on the
cover didn't actually mean that I could have editorial control.  I
declined to produce any more books unless my authority was equal to my
responsibility, and there hasn't been another edition since.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

Let us hope our weapons are never needed --but do not forget what 
the common people knew when they demanded the Bill of Rights: An 
armed citizenry is the first defense, the best defense, and the 
final defense against tyranny.
   If guns are outlawed, only the government will have guns. Only 
the police, the secret police, the military, the hired servants of 
our rulers.  Only the government -- and a few outlaws.  I intend to 
be among the outlaws.
        -- Edward Abbey, "Abbey's Road", 1979

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Thu, 06 Jul 2000, David C. Mason wrote:
> What a gentleman like approach to telling me you worked on it.

Welcome to the Open Source world :-). If we weren't passionate, we wouldn't do
it. 

And when the tools suck, we do one of two things -- use different tools, or fix
the tools. In my case, I'm using different tools for my next project, ones that
I know are reliable and work correctly.  I have a sneaking suspicion that ESR's
passion here is going to lead him to fixing the tools,  but on the other hand,
he may have concluded that his contributions aren't welcome in the SGML
community, because they don't meet some purity test (i.e., they're practically
oriented, rather than being pretty, theoretical, and utterly useless). 

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[Edward C. Bailey]

>>>>> "esr" == Eric S Raymond <esr@thyrsus.com> writes:

esr> David C. Mason <dcm@redhat.com>:
>> Then I still don't understand the problems you are having... or at
>> least, I still haven't seen a detail of what you would like to see.

esr> I'd like to see documentation that spends less time genuflecting
esr> before the wonderfulness of semantic markup and stylesheets, and more
esr> time telling me how I can install and configure working tools and make
esr> HTML and Postscript from actual documents.

I wonder if SGML documentation's current focus on the theoretical versus
the practical is an evolutionary backwater from the days when people using
the technology had to explain why they were "doing things the 'hard' way
with SGML" when most people doing documentation were simply using whatever
tools they happened to have available.  Even if this was the case at one
point in time, I think we all agree that most people "get it" when it comes
to markup languages (if for no other reason than all the hype XML has
brought to our part of the world).  So it's time to move on, and leave the
Cult of the Sacred Tag mentality behind us now... :-)

...
esr> Is it just me?  Am I crazy to think there's something wrong with a
esr> 600-page tome on document production tools that *never once tells you
esr> how to format a document?*

To be honest, and at least in the case of _DocBook: The Definitive Guide_,
I think it's just you.  The book is a reference describing a particular
markup language.  That markup language is processed by a wide variety of
software (both open source and non-) on a wide variety of platforms (again,
both open source and non-).  To have this particular reference guide get
into how the markup language is processed by one particular application on
a subset of the possible platforms would be something similar to HP
including a chapter called "Using Your New Printer to Print Romance Novels"
in every LaserJet owner's manual. :-)

That's not to say that there *shouldn't* be a book that does just what you
describe.  I strongly agree with you that this kind of information should
be in a book somewhere.  I just don't think _DocBook: TDG_ is that book.

esr> The unbelievable part is that it's *all* like that.  It's not just the
esr> individual authors of these particular documents that are high priests
esr> of the Cult of Obscurity -- every piece of documentation I've ever
esr> seen from the DocBook/SGML community is pretty much off in theoretical
esr> cloud-cuckoo land.  I can learn more than I ever wanted to know about
esr> DSSL and FOSI and fifty other acronyms, but I can't find any clue
esr> about what to do when jadetex generates bad Postscript that makes gs
esr> choke.

esr> What I want to see is a practical guide that is truly a practical
esr> guide -- something like what I wrote for SGML-tools, but covering
esr> DocBook.

I feel compelled to preface my comments by saying that my goal is neither
to cut anyone down, nor to build myself up.  But I have a bit of background
here that leads me to the following observations:

    o If you were to change a few of the terms in ESR's comments, you'd
      have almost exactly the same kinds of feedback we at Red Hat get from
      users regarding the state of Linux documentation today.  So those of
      us that do documentation for one or more open source software
      projects should keep in mind that we ain't done yet -- not by a long
      shot.  This complaint is true for DocBook documentation, and it's
      true for many (most? all?) open source software projects.

    o Since ESR has worked with me, he knows I'm not the sharpest knife in
      the kitchen (and hopefully feels that I'm at least not the dullest,
      either :-).  Yet he's confounded trying to format DocBook documents,
      while I've been able to convert over 1500 pages of LaTeX-based
      documentation into DocBook, and to create the tools necessary to
      support a production environment to produce DocBook-based content
      here at Red Hat.  What's the difference?  Time.  It was my full-time
      job to make the move to DocBook, while ESR is probably lucky if he
      can devote an hour here and there to the task.  The important point
      here is that we need to get away from the mentality that
      introductory/tutorial texts are for clueless newbies, that hard-core
      reference material is the only truly important documentation.  The
      introductory stuff makes the technology accessible to people that
      would otherwise not have access.  And as I'm sure ESR can vouch,
      being treated like a clueless newbie, on the outside looking in,
      sucks.

esr> Don't get an exaggerrated idea of my creds, either.  I didn't write
esr> SGML-tools, nor was I ever its official maintainer.  I did one really
esr> serious burst of work on it around 0.99-1.0 -- basically so I could
esr> pull Red Hat's nuts out of the fire after Bob Young asked me nicely to
esr> fix the godawful mess their old TeX-centric production process had
esr> degenerated into.

Point of clarification -- ESR helped us replace a contractor (with a
largely manual and TeX-centric production process) that seemed to be unable
to deliver the goods when promised.  That said, the end result still was
the extraction of said gonads from the conflagration -- and in a most
elegant fashion... :-)

                                Ed
-- 
Ed Bailey        Red Hat, Inc.          http://www.redhat.com/

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Edward C. Bailey <ed@redhat.com>:
>                               So it's time to move on, and leave the
> Cult of the Sacred Tag mentality behind us now... :-)

Indeed.  And an important point: I wouldn't be so exercised about the
Cult of the Sacred Tag if, on some level, I didn't grok that the SGML
people have some reason behind the religion.  If it was all just just
bullshit, I could ignore it and go away.  As it is, the fact that the
power of these techniques is surrounded by a near-impenetrable thicket
of theology and jargon is deeply frustrating to me -- and the apparent
inability of SGML people to see that this is an issue is maddening!

> esr> Is it just me?  Am I crazy to think there's something wrong with a
> esr> 600-page tome on document production tools that *never once tells you
> esr> how to format a document?*
> 
> To be honest, and at least in the case of _DocBook: The Definitive Guide_,
> I think it's just you. [...]  To have this particular reference guide get
> into how the markup language is processed by one particular application on
> a subset of the possible platforms would be something similar to HP
> including a chapter called "Using Your New Printer to Print Romance Novels"
> in every LaserJet owner's manual. :-)

No, I'd say it's more like supplying schematics and chip masks for the 
printer's electronics and neglecting to document the front-panel controls.

Really.  What would it have cost to supply *one* explicit example of 
a document-production flow on Unix and Windows?  A few pages could have
made a huge difference -- in helpful symbolism, even if it couldn't
cover all the substance.

As it is, one is left with the impression that Mr. Walsh was so caught
up in the arcana of Scheme and CSS and DTD composition that he couldn't be 
bothered to descend to the level of actually showing the reader how to
actually use any of it.

(All right, everybody.  Calm down -- I'm not claiming that was his actual
state of mind, simply that that is the message the book sends.)

>     o If you were to change a few of the terms in ESR's comments, you'd
>       have almost exactly the same kinds of feedback we at Red Hat get from
>       users regarding the state of Linux documentation today.  So those of
>       us that do documentation for one or more open source software
>       projects should keep in mind that we ain't done yet -- not by a long
>       shot.  This complaint is true for DocBook documentation, and it's
>       true for many (most? all?) open source software projects.

Yup.  That's why I maintain, at last count, eight (8) different technical
FAQ documents.  
 
>                                                The important point
>       here is that we need to get away from the mentality that
>       introductory/tutorial texts are for clueless newbies, that hard-core
>       reference material is the only truly important documentation.  The
>       introductory stuff makes the technology accessible to people that
>       would otherwise not have access.

Amen.  Squared...
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

"Rightful liberty is unobstructed action, according to our will, within limits
drawn around us by the equal rights of others."
	-- Thomas Jefferson

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ Mark Galassi <rosalia@galassi.org> was heard to say:
| I'm surprised nobody came across my tutorial:
| 	http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html

That one's on the DocBook documentation page:

  http://www.oasis-open.org/docbook/documentation/other.html

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | All the labors of the ages, all the
http://nwalsh.com/            | devotion, all the inspiration, all the
                              | noonday brightness of human genius, are
                              | destined to extinction--Bertrand Russell

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "Eric S. Raymond" <esr@thyrsus.com> was heard to say:
| I don't think anybody doubts that it was your intention to be clear.
| Your execution, however, completely failed in that respect.  The

Completely? Thanks.

| failure seems to me to be an indicator of a wider problem in the
| technical culture surrounding SGML, one I've bitched about before.

Yes, you have.

| Two years ago, I complained vociferously on the DocBook list that the
| SGML culture had a pathological case of self-absorption and seemed to

And with such vitriol and ranting that several respectable members of
the list asked you to please be polite or go away.

| unable to explain.  For bringing this unwelcome news, I was flamed and
| shunned.

Is that how you saw it. How, um, symmetrical.

| Can this be fixed?  I don't know.  The problem isn't any lack of
| intelligence or good intentions on the part of the DocBook group.  
| There's something fundamentally disconnected and broken in the
| attitude department, though -- an inability to see what the SGML
| world looks like from the point of view of somebody who just
| wants to get some work done.

That's not really fair, IMHO. Two years ago, when you ranted on the
DocBook list, there *were no tool sets that we could point to*. SGML
was a build-it-yourself world.

Now, as I've said, thanks to the tremdous efforts of lots and lots of
people, we *do have tool sets* that we can point to. They aren't perfect
yet, they don't install easily enough, and they don't satisfy everyone.
But we've come a long way and the efforts continue.

Not only do I think the problem can be fixed, I'm confident it will
be.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | The worst enemy of life, freedom and
http://nwalsh.com/            | the common decencies is total anarchy;
                              | their second worst enemy is total
                              | efficiency.--Aldous Huxley

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "Eric S. Raymond" <esr@thyrsus.com> was heard to say:
| OK, what is the actual stylesheet RPM?  You didn't specify, and all I
| can find is SRPMs and tarballs.
| 
| Would it be too much to ask that these things actually be described
| on the DocBook tools page?

No, that's a good idea. If someone sends me some appropriate text, I'll
be happy to put it on the tools page.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | If you are hankering after certainty,
http://nwalsh.com/            | you are better advised to seek it in
                              | religion: the stock-in-trade of science
                              | is not certainty but doubt.--K.C. Cole

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "Eric S. Raymond" <esr@thyrsus.com> was heard to say:

With respect to this comment,

| As it is, the fact that the
| power of these techniques is surrounded by a near-impenetrable thicket
| of theology and jargon is deeply frustrating to me -- and the apparent
| inability of SGML people to see that this is an issue is maddening!

And bearing in mind something you said earlier,

| You [...] can
| start being offended the day I don't respect you enough to criticize
| your work.

I feel compelled to reply:

First, you're mistaken. As the reader of your comments, I'm free to
become offended whenever I bloody well choose.

Second, I'm tired of your whining about the theology and jargon. I'm
sorry if TDG didn't answer your questions, I'll try to do better next
time (although I still think it's an authors prerogative to decide
what is and what is not in scope), but I don't think it's either
theological or jargon-filled.

It seems to me that the bulk of your ranting boils down to:

"The tools one needs to format a DocBook document and get HTML or
print output are insufficiently documented and too hard to install and
use."

I haven't heard a single person disagree with you. And in the two years
since you first encountered DocBook, tremendous progress has been made.
I'm committed to seeing that, to the extent I can contribute, the
progress continues until it's as nearly dead easy as possible.

Now would you please stop flogging me for not moving fast enough.  I
ain't your whipping boy, son.

| Really.  What would it have cost to supply *one* explicit example of 
| a document-production flow on Unix and Windows?  A few pages could have
| made a huge difference -- in helpful symbolism, even if it couldn't
| cover all the substance.

Now that's an interesting question. You might be right.

| As it is, one is left with the impression that Mr. Walsh was so caught
| up in the arcana of Scheme and CSS and DTD composition that he couldn't be 
| bothered to descend to the level of actually showing the reader how to
| actually use any of it.

For the record, my thought process went something like this. "Today
(when I was writing) things are still pretty immature. I could try to
document one of the many possible tool sets, but then I'd be leaving
out all the others, not to mention the commercial tools from
Arbortext, Frame, and Softquad to name but three. And there's no tool
set that works equally well on Unix and NT, so I'd have to do at least
two. Things will be better soon and the installation instructions for
the individual tool sets can do a better job on installation than I
can. Heck, I don't even have a Linux box at hand these days. The vast
majority of questions that I get aren't about specific tools, people
seem to get those installed, they're about how to customize X, Y, or Z
in the stylesheets. Since the DSSSL stylesheets form the core of
several tool sets, end users would be better served by some
explanation of how to use and customize those."

| (All right, everybody.  Calm down -- I'm not claiming that was his actual
| state of mind, simply that that is the message the book sends.)

And the message you send is...oh, nevermind.

| >                                                The important point
| >       here is that we need to get away from the mentality that
| >       introductory/tutorial texts are for clueless newbies, that hard-core
| >       reference material is the only truly important documentation.  The
| >       introductory stuff makes the technology accessible to people that
| >       would otherwise not have access.
| 
| Amen.  Squared...

Cubed, even.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | Whatever you may be sure of, be sure of
http://nwalsh.com/            | this: that you are dreadfully like
                              | other people.--James Russell Lowell

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "richard offer" <offer@sgi.com> was heard to say:
| be using Jade/your stylesheets to produce the output. I've hacked mine and
| still can get what I'm (visually) looking for. I guess the limitation is in the
| generalities of DocBook, since I could get it if I was using raw LaTeX.

I'm curious about this. Can you provide a couple of examples of things
you can't do in DocBook that you could do in LaTeX? I'm not interested
in the mechanics, per se, but in what markup distinction you feel
you've lost.

|   More details on linking documents, I've got 6 docs that I'm writing in
| parallel and would really like to link between them. I gave up.

These are six separate documents, or six parts of the same document?
SGML doesn't really have a good cross-document linking solution (though
you can cobble one together, see my tutorials about olink on nwalsh.com).
XPointer and XLink should do better, but there are still some problems
given that you don't typically publish the source.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | A moment's insight is sometimes worth a
http://nwalsh.com/            | life's experience.--Oliver Wendell
                              | Holmes

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "Eric S. Raymond" <esr@thyrsus.com> was heard to say:
| Norman Walsh <ndw@nwalsh.com>:
| > Second, I'm tired of your whining about the theology and jargon. I'm
| > sorry if TDG didn't answer your questions, I'll try to do better next
| > time (although I still think it's an authors prerogative to decide
| > what is and what is not in scope), but I don't think it's either
| > theological or jargon-filled.
| 
| In this respect (if not in others), you and the other core DocBook
| people who share this belief are still out to lunch.  And that's sad,
| because it seriously hinders the deployment of your good work.

Moments after sending this message, I regretted making the assertion
that it wasn't jargon-filled. That's nonsense and I knew better.  (I
really don't think it's theological, but if you do, I won't argue the
point any further.)

There's a definite tension when it comes to vocabulary and it bites
very deeply in SGML, possibly because I'm familiar with it, although
my intuition is that it bites deeply in SGML in part because it's
worse in SGML than in many other jargons. 8879 was written by a lawyer
after all :-)

As I expressed earlier, perhaps badly: using the precise 8879
terminology (which I don't claim to have done, in the interest of
trying to fight this exact problem, even if you think I failed) is a
way of describing things in a precise, technically unabiguous way.
Alas, it comes at the expense of the poor reader who could care less
about the distinction between a "tag" and a "generic identifier".  The
trouble is that using loose, informal terms eventually leads to
confusion in those areas where it really makes a difference.

Maybe I got the balance wrong. I could have done better.

| > It seems to me that the bulk of your ranting boils down to:
| > 
| > "The tools one needs to format a DocBook document and get HTML or
| > print output are insufficiently documented and too hard to install and
| > use."
| 
| Nope, see above.

Above only asserts that I'm out to lunch, it doesn't actually describe
any specific problem that I might be able, even anxious, to help you
with.

|  The fact that SGML initiates can't see how
| impenetrable their sacred texts are is a larger problem than the lack
| of documentation for specific tools -- because it means that said
| documentation is unlikely to get written or reviewed by exactly those
| who ought to be best qualified to do it.

I don't think that follows. I'd love to expand on the publishing
sections of TDG to provide practical answers to practical problems in
more detail.  And now that the tool sets are becoming more mature, I
think there's a good chance I'll be able to do that. I'd still like to
see a tool set that ran on both NT and Linux, but that may not yet be
practical.

And I'll happily review anything written on the subject if I'm asked.

| "Floggings will continue until morale improves." :-) No, in fact, I'm
| not flogging you for moving too slowly.  I'm flogging you for an
| apparent inability to understand "motion" at all.  I'll stop when you
| either clue in or my arm gets tired.

Your polite, reasoned demeanor invariably improves my morale.
Thank you, sir! May I have another, sir!

| So why didn't *you* figure one out this out two years ago?  Why does 
| it take an outsider, jumping up and down and screaming, to point out
| the obvious?

It must be wonderful to always have all the right ideas at the right
time. Alas, I have not your gift in that regard.

Oh, and by the way, while it may take an outsider, it does not take an
outsider jumping up and down and screaming. That has very nearly
driven me to stop reading your posts.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | DNA neither cares nor knows. DNA just
http://nwalsh.com/            | is. And we dance to its music.--Richard
                              | Dawkins

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ Eric Bischoff <ebisch@cybercable.tm.fr> was heard to say:
| or whether the user installed it or not. So far, to rely on
| a CGI helper program seems to be the nearest thing from this
| holy graal, but first I don't see exactly how to implement
| it, and second I'm worried about assuming there is an HTTPD
| server up and running.

I can't help with the second part, but I did the first part.
Look over the olink docs on my website, I think it's described
in there and let me know if you have questions.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | When we are tired, we are attacked by
http://nwalsh.com/            | ideas we conquered long ago.--Nietzsche

Re: Crash-course to DocBook

[Eric Bischoff]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 3059 bytes --]

Mark Johnson wrote:
> 
> On Wed, 9 Aug 2000, Eric Bischoff wrote:
> 
> > Hi folks,
> >
> > I'm happy to announce the birth of the "Crash-Course to
> > DocBook".
> >
> > You can find it on http://public.lst.de/~eric
> >
> > It is released under FDL. Feel free to make it evolve.
> >
> Great idea! So much to tell, so little time...
> 
> On the PSGML page
> ( http://www.lst.de/~eric/crash-course/HTML/emacs-psgml-mode-tips.html ) you
> say
> 
> "PSGML mode is for SGML DocBook. It does not support XML DocBook."
> 
> which isn't true. PSGML has an XML mode that works fine with DocBook. A
> group of use it daily (w/ Emacs 20.7) with no problems at all.

I did not know that. Please update the guide to remove this
sentence and send it back to me under private mail.

> You only need to put something like this into your .emacs:
> 
> ;; load xml-mode
>  (autoload 'xml-mode "psgml" "Major mode to edit XML files." t)
>        (setq auto-mode-alist
>        (append (list (cons "\\.xml\\'" 'xml-mode))
>        auto-mode-alist)
>  )

psgml, as packaged for the docbook-tools, doesn't even
require you to do this for SGML ;-). It uses emacs
initialization files to do it for all users on a given
machine.

This suggests I should do the same manipulation in %Post and
%Postun sections of the SPEC file so that it becomes fully
transparent to the user. Would you mind testing it for me
when it's done? (reply in private please).

> Along with the path to the declaration.
> 
> I started a page of Emacs/PSGML Tips, based on stuff I read in Bob Snee's
> SGML CD chapter. It's here:
> 
>         http://ed.phy.duke.edu/xml/psgml-tips/index.html
> 
> I'd be happy to contribute to your tutorial, as I already spend too much
> time showing folks how to do this or that.

With much pleasure! (it's not *my* tutorial - it's a mixture
of David Rugge's one, Mark Galassi's one and mine).

Please feel free to modify this appendix in the DocBook
source file. If we get many collaborators, it should move
under CVS - for the time being attachements to private email
should be enough. Splitting the source into several files
might help as well.

> Another idea would be to start a database of docbook-user FAQs, we already
> have a number of Zope installations that would make it very easy to do
> something like this. It would automatically be searchable, and indexed,
> etc.
> 
> Does that sound useful to anyone?

Sure!!!!! We could point to it from the Crash-course.

But isn't already one at DocBook-tools home page? (BTW this
page is slowly becoming outdated).

-- 
 Éric Bischoff   -   mailto:ebisch@cybercable.tm.fr
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                        Konqui     \__=v
 __________________________________________________

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

Norm's thought process for not documenting a specific set of tools is
quite valid: the various tool sets were immature then, and are still
so now.

Let's not forget that the whole thread began because the person who
started it did not read the docbook-tools home page: that home page
points you to my tutorial which has a "get going" approach and an
appendix on downloading and installing the tools.  There are also many
examples of how to run the tools.

The main fault in my get-going document is that it is not up-to-date,
but since the packages have changed little, it is no big deal.

As the list maintainer I have asked the person who posted insulting
messages to not do so.  Sadly they continued to do so.

I recommend that everyone ignore these inflammatory posts and get back
to contributing useful information.

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Mark Galassi <rosalia@galassi.org>:
> I'm surprised you don't find it.  I went to the first mirror and found
> the non-source noarch RPM for stylesheets at:
> ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/RPMS/noarch/

Thanks.  The mirror I checked was missing the docware/RPMS part.

The docbook-tools page ought to mention that  the db2* scripts live in the
stylesheets RPM.  Otherwise it's way too easy to get sidetracked by the
docbook RPM.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

When only cops have guns, it's called a "police state".
        -- Claire Wolfe, "101 Things To Do Until The Revolution" 

Re: docbook-tools-discuss: Re: I'm trying to set up docbook-tools...

[Bill Campbell]

On Fri, Jul 07, 2000 at 09:56:40AM -0400, Norman Walsh wrote:
>/ Bill Campbell <bill@celestial.com> was heard to say:
....
>| Another thing I would really like to see are more tools that convert
>| existing input from ?roff, TeX, and similar markup languages into DocBook
>| SGML, because this would make it much easier for those of us who are fluent
>
>A little more discussion about how to convert from procedural markup
>to structural markup is probably in order, but tools to do this are
>very, very hard to write. This is the problem I call "dragging markup
>up hill".  Look at the troff source for an (old) O'Reilly book (I have :-),
>and you'll find that the same troff markup for "italic" is used for
>all the things that are italic in print. (Quelle surprise). But if you
>want to mark those things up semantically, you have to distinguish
>between at least three or four different kinds of italic things which
>is nearly impossible to do accurately.

I understand the difficulties of conversion programs like this, and the
best one can hope for is to convert what exists (i.e. italic, bold, and
other formatting codes) to their lowest common denominator in DocBook.

On the other hand, I have thousands of pages of documentation that I've
written using the -mm, -ms, and -man macros that I would like to convert
with minimal effort.  If someone else had written mm2db, ms2db, man2db,
then I could learn a lot about DocBook by looking at the output of these
commands.  Furthermore, I find it a lot easier to write documentation
initially using a format suitable for the -mm macros than I do going
straight to DB, primarily because this is what I've been doing for the
better part of twenty years (it's also a lot easier to do simple tables in
tbl format than CAL tables :-).

I'm well on my way to having a working program that handles the ?roff input
that I've been writing for years.  It's based on a program I wrote years
ago that takes ?roff input, parses it for preprocessor directives,
(.TS/.TE, .PS, .PE, etc.), assembles a command line that then invokes the
appropriate preprocessors in the correct order, and passes it off to ?roff.
Currently it handles -mm macros fairly well, and by dbtbl preprocessor at
least gets my fairly simple tables into reasonable shape.  I haven't
tackled the pic, eqn, or grap, preprocessors because I rarely use them
myself.  If there are others out there who would like to work on this
project, I welcome input, help -- even Andrew Tridgell's favorite pizza
(with anchovies).

Bill
--
INTERNET:   bill@Celestial.COM  Bill Campbell; Celestial Systems, Inc.
UUCP:               camco!bill  PO Box 820; 6641 E. Mercer Way
FAX:            (206) 232-9186  Mercer Island, WA 98040-0820; (206) 236-1676
URL: http://www.celestial.com/

``The best we can hope for concerning the people at large is that they be
properly armed.''
        -- Alexander Hamilton, The Federalist Papers at 184-188

Re: Crash-course to DocBook

[Peter Toft]

On Wed, 9 Aug 2000, Eric Bischoff wrote:

> Hi folks,
> 
> I'm happy to announce the birth of the "Crash-Course to
> DocBook".

And I have just finished writting a Danish one -
http://www.sslug.dk/artikler/docbook
OPL license (thanx to Eric for that one)

BR

-- 
Peter Toft, Ph.D. [pto@sslug.dk] http://www.sslug.dk/~pto

"You don't win a battle by asking, `Will we win?' 
You win it by doing your best to win"
- Richard M Stallman

----> Visit http://petition.eurolinux.org <---

Re: I'm trying to set up docbook-tools...

[Sam Roberts]

----- Original Message ----- 
From: Eric Lee Green <eric@badtux.org>


> Still, TeX and LaTeX still exist. They are thoroughly documented. They run the
> same way everywhere. They look ghe same everywhere. So while they are not the
> be-all and end-all of structured document design, they'll have to do, since the
> SGML crowd has committed collective suicide. A pity, that. 

This is just a variant of the classic complaints about Unix: I just want to
do X, but the docs don't tell me how. LaTeX is a single tool that does it
all, to use sgml you have to use a set of tools, and you can mix and match
them. You can use jade without docbook or norm's style sheets, you can use
jadetex without using docbook, the db2* scripts are so optional most people
write their own, and you don't have to use emacs to edit sgml, but it helps.

As for the sgml crowd committing suicide, judging from the increased traffic
on the oasis docbook lists, which led to a split into two still very busy
mailing lists this spring, and the increasing number of open source projects
whos docs appear to be docbook generated, I'd say people are perservering and
getting the job done.

Sam

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Norman Walsh <ndw@nwalsh.com>:
> / Eric Lee Green <eric@badtux.org> was heard to say:
> | That puzzles me too. Even Norm Walsh's so-called "Docbook" book
> | reads as if it were a briefly written summary written in a foreign
> | language to be as terse as possible.
> 
> <sigh/> I'm sorry you found it to be that way. That wasn't the intent.

I don't think anybody doubts that it was your intention to be clear.
Your execution, however, completely failed in that respect.  The
failure seems to me to be an indicator of a wider problem in the
technical culture surrounding SGML, one I've bitched about before.

I looked forward to your book with the hope that it would dispel the
thick fog surrounding DocBook -- only to be disappointed in pretty
much the same way Eric Lee Green was.  What was missing was (a)
motivation, and (b) any mention of the tools ordinary mortals might
use to format actual documents. 

It's symptomatic that the chapter titled "Publishing DocBook Documents"
-- which one might reasonably expect to answer questions like "How do
I generate HTML or Postscript from a DocBook document?" -- consists
mainly of pages and pages of mind-numbing detail about stylesheet
languages, with not a sample command line or complete example of
production code in it anywhere.

Two years ago, I complained vociferously on the DocBook list that the
SGML culture had a pathological case of self-absorption and seemed to
be chronically unable to address the needs or questions of people who
actually want to get some formatting done without first memorizing
fourteen different sacred tomes of document theology. all filled with
an impenetrable jargon that the priests of the cult seem unwilling or
unable to explain.  For bringing this unwelcome news, I was flamed and
shunned.

Sadly, there seems to have been little or no improvement since.  The
SGML- and DocBook-related pages on the Web are marvels of their kind
-- exhaustively detailed and *completely* unhelpful.  (And remember,
this judgment is coming from someone with a very high tolerance for
complexity and lots of expertise in related technical areas!)  As
a result, SGML-related markup now has all the appeal to me of
chewing on barbed wire.  I wouldn't be messing with it at all if
it weren't a political requirement for one of my projects.

Can this be fixed?  I don't know.  The problem isn't any lack of
intelligence or good intentions on the part of the DocBook group.  
There's something fundamentally disconnected and broken in the
attitude department, though -- an inability to see what the SGML
world looks like from the point of view of somebody who just
wants to get some work done.

Again, a symptom, In the document "A Practical Introduction to DocBook",
the Tools section contains the following blatant cop-out:  

"Unfortunately, installing and configuring DocBook Tools is
(currently) outsidethe scope of this document."

Anyone not already eyebrow-deep in the dysfunctional culture surrounding
this software would realize that this lacuna makes the rest of the 
chapter a bad joke.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

Alcohol still kills more people every year than all `illegal' drugs put
together, and Prohibition only made it worse.  Oppose the War On Some Drugs!

Re: docbook-tools-discuss: Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ Bill Campbell <bill@celestial.com> was heard to say:
| I would have liked to see some more discussion of some topics like how to
| build indexes (indices?), cross-referencing, etc. -- i.e. the things one

Yes, there definitely needs to be more about indexing. I also need to
get an XSL solution for indexing, but that's a different problem.

| has to consider when writing books, documentation, and that sort of thing.
| The examples on the CD, and the sgml input for the book have been the most
| useful things for me.

That's why they're there.

| Another thing I would really like to see are more tools that convert
| existing input from ?roff, TeX, and similar markup languages into DocBook
| SGML, because this would make it much easier for those of us who are fluent

A little more discussion about how to convert from procedural markup
to structural markup is probably in order, but tools to do this are
very, very hard to write. This is the problem I call "dragging markup
up hill".  Look at the troff source for an (old) O'Reilly book (I have :-),
and you'll find that the same troff markup for "italic" is used for
all the things that are italic in print. (Quelle surprise). But if you
want to mark those things up semantically, you have to distinguish
between at least three or four different kinds of italic things which
is nearly impossible to do accurately.

| References are invaluable, but they're not usually something that is used
| to initially learn a language.  I've always learned best by seeing concrete

Yep, "Learning DocBook" would be a worthy project.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | The firmest line that can be drawn upon
http://nwalsh.com/            | the smoothest paper is still jagged
                              | edges if seen through a microscope.
                              | This does not matter until important
                              | deductions are made on the supposition
                              | that there are no jagged edges.--Samuel
                              | Butler (II)

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Eric> I don't think anybody doubts that it was your intention to
    Eric> be clear.  Your execution, however, completely failed in
    Eric> that respect.  The failure seems to me to be an indicator of
    Eric> a wider problem in the technical culture surrounding SGML,
    Eric> one I've bitched about before.

Please do not post rude messages to this list.

On this list we should not tell people that "they have failed" just
because their pedagogical approach did not work for us.

Re: I'm trying to set up docbook-tools...

[richard offer]

* $ from ndw@nwalsh.com at "6-Jul:12:21pm" | sed "1,$s/^/* /"
*
*
* / Eric Lee Green <eric@badtux.org> was heard to say:
* | That puzzles me too. Even Norm Walsh's so-called "Docbook" book
* | reads as if it were a briefly written summary written in a foreign
* | language to be as terse as possible.
*
* <sigh/> I'm sorry you found it to be that way. That wasn't the intent.
* Although the bulk of the book is intended as a reference and not a
* how-to, the introductory chapters were supposed to be readable by the
* novice. Can you explain, in any more detail, what you found most
* troubling?

I didn't find anything really wrong with the book... A few additions would have
helped...

  A reference card of the hierarchy of markups---this was what I used the book
for the most initially.

  More stylessheet specfic text, perhaps including some more examples of
different stylesheets for print/HTML and how they can change the outlook of the
whole doc. While you're trying to document docbook, people are most likely to
be using Jade/your stylesheets to produce the output. I've hacked mine and
still can get what I'm (visually) looking for. I guess the limitation is in the
generalities of DocBook, since I could get it if I was using raw LaTeX.

  More details on linking documents, I've got 6 docs that I'm writing in
parallel and would really like to link between them. I gave up.


*
*
*                                         Be seeing you,
*                                           norm


richard.


-----------------------------------------------------------------------
Richard Offer           Widget FAQ --> http://reality.sgi.com/widgetFAQ
MTS-Core Design (Motif)
___________________________________________ http://reality.sgi.com/offer

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

David C. Mason <dcm@redhat.com>:
> Please stop referring to people's work with words that are meant only
> to insult.

David, you ain't *seen* me being insulting yet.  So far, all I've done
is call a spade a spade.  You, and Deb, and Mark, and Norman, can
start being offended the day I don't respect you enough to criticize
your work.  Criticism is the tribute you pay adults who are capable of
better than they have done.  Indifference or dismissal would be the
real insult.

> I'm sure plenty of people could refer to your essays with
> venom, they perhaps choose not to as they know your heart is in the
> right place for writing them in the first place.

And since when is "having your heart in the right place" worth a damn?
If that's the best thing anyone could find to say about my work, *I'd*
be insulted.  I hold myself to higher standards than that.  You should too.

> > -- basically so I could pull Red Hat's nuts out of the fire after
> > Bob Young asked me nicely to fix the godawful mess their old
> > TeX-centric production process had degenerated into.  
> 
> What a gentleman like approach to telling me you worked on it.

The *point* is, I was called in to solve a nasty problem under
emergency conditions, and I did it.  I didn't get a lot of thanks for
it, either.  After "Linux Undercover" Bob decided that the mere fact
of designating me the editor of the book and putting my name on the
cover didn't actually mean that I could have editorial control.  I
declined to produce any more books unless my authority was equal to my
responsibility, and there hasn't been another edition since.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

Let us hope our weapons are never needed --but do not forget what 
the common people knew when they demanded the Bill of Rights: An 
armed citizenry is the first defense, the best defense, and the 
final defense against tyranny.
   If guns are outlawed, only the government will have guns. Only 
the police, the secret police, the military, the hired servants of 
our rulers.  Only the government -- and a few outlaws.  I intend to 
be among the outlaws.
        -- Edward Abbey, "Abbey's Road", 1979

Re: I'm trying to set up docbook-tools...

[Eric Bischoff]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1502 bytes --]

richard offer wrote:
> 
>   More details on linking documents, I've got 6 docs that I'm writing in
> parallel and would really like to link between them. I gave up.

We are also suffering a lot with <olink> at kde. I'm just
trying to figure out a mechanism
to link an HTML file to another one at DocBook level without
knowing where this file will be implemented on the user's
hard disk (this prevents from using "SYSTEM" FPIs), just
because some distributions use /opt/kde and other ones /usr.
To complicate everything, the target file can be in the
middle of the docbook file, and its name results from the ID
of a chapter or section! And the target file might exist or
not, according to whether it is already translated or not,
or whether the user installed it or not. So far, to rely on
a CGI helper program seems to be the nearest thing from this
holy graal, but first I don't see exactly how to implement
it, and second I'm worried about assuming there is an HTTPD
server up and running.


-- 
 Éric Bischoff   -   mailto:ebisch@cybercable.tm.fr
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                        Konqui     \__=v
 __________________________________________________

Re: docbook-tools-discuss: Re: I'm trying to set up docbook-tools...

[Bill Campbell]

On Thu, Jul 06, 2000 at 12:21:20PM -0400, Norman Walsh wrote:
...
><sigh/> I'm sorry you found it to be that way. That wasn't the intent.
>Although the bulk of the book is intended as a reference and not a
>how-to, the introductory chapters were supposed to be readable by the
>novice. Can you explain, in any more detail, what you found most
>troubling?

I would have liked to see some more discussion of some topics like how to
build indexes (indices?), cross-referencing, etc. -- i.e. the things one
has to consider when writing books, documentation, and that sort of thing.
The examples on the CD, and the sgml input for the book have been the most
useful things for me.

Another thing I would really like to see are more tools that convert
existing input from ?roff, TeX, and similar markup languages into DocBook
SGML, because this would make it much easier for those of us who are fluent
in these to see how various constructs translate.  I'm pretty well along
now with a set to convert my ?roff -mm and -man files into docbook format,
but it's not going quickly because of my limited skills and knowledge of
docbook (particularly tbl->table).

References are invaluable, but they're not usually something that is used
to initially learn a language.  I've always learned best by seeing concrete
examples, then generalizing from that.  I didn't really understand Backus
Normal Form until I had already learned a lot of ALGOL, and could work
backwards from complex ALGOL code generated by Burroughs FORTRAN compiler
for the B-5500 (really FORTRAN->ALGOL then compile the ALGOL).

Bill
--
INTERNET:   bill@Celestial.COM  Bill Campbell; Celestial Systems, Inc.
UUCP:               camco!bill  PO Box 820; 6641 E. Mercer Way
FAX:            (206) 232-9186  Mercer Island, WA 98040-0820; (206) 236-1676
URL: http://www.celestial.com/

``Everybody is ignorant, only on different subjects.''
    Will Rogers

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

I'm surprised nobody came across my tutorial:
	http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html

It has been improved on by several people, but always in a specific
context, like the FreeBSD documentation guidelines.

It is mentioned in the sourceware web page.

I'm trying to set up docbook-tools...

[Eric S. Raymond]

I'm trying to set up docbook-tools, and finding it a hideously
frustrating experience.  Why does all the SGML software and
documentation in the world read as though it was carefully designed 
to prevent any actual document production from getting done?

The < http://sourceware.cygnus.com/docbook-tools/ > page directs me to
< ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That server is
perpetually swamped.  Going to one of the mirrors, I find a
docbook-3.1-5.noarch.rpm, but it does not contain any of the db2*
scripts referenced on the DocBook page.  Where are those scripts?
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

"The best we can hope for concerning the people at large is that they be
properly armed."
        -- Alexander Hamilton, The Federalist Papers at 184-188

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

David C. Mason <dcm@redhat.com>:
> Then I still don't understand the problems you are having... or at
> least, I still haven't seen a detail of what you would like to see.

I'd like to see documentation that spends less time genuflecting
before the wonderfulness of semantic markup and stylesheets, and more
time telling me how I can install and configure working tools and make
HTML and Postscript from actual documents.

Let's start with replacing that cop-out in the so-called "Practical
Introduction".  It's inexcusable, absurd, perverse, that a so-called
"Practical Guide" doesn't tell you (a) where to find installable
versions of the tools it's describing, and (b) how to set them up
so you can do the examples in the guide.

Let's continue with the fact that in the entire 635 pages of "DocBook:
The Definitive Guide", I found *not one* example of a command line that
could be used to produce actual, viewable HTML or Postscript from an
actual document.

Is it just me?  Am I crazy to think there's something wrong with a 600-page
tome on document production tools that *never once tells you how to 
format a document?*

The unbelievable part is that it's *all* like that.  It's not just the
individual authors of these particular documents that are high priests
of the Cult of Obscurity -- every piece of documentation I've ever
seen from the DocBook/SGML community is pretty much off in theoretical
cloud-cuckoo land.  I can learn more than I ever wanted to know about
DSSL and FOSI and fifty other acronyms, but I can't find any clue about
what to do when jadetex generates bad Postscript that makes gs choke.

What I want to see is a practical guide that is truly a practical guide --
something like what I wrote for SGML-tools, but covering DocBook.

> I had no idea you did the first SGML-Tools and I apologize, you are a
> single entity in that case. Otherwise, I find that most hackers ignore
> these tools altogether. My apologies.

Don't get an exaggerrated idea of my creds, either.  I didn't write
SGML-tools, nor was I ever its official maintainer.  I did one really
serious burst of work on it around 0.99-1.0 -- basically so I could pull
Red Hat's nuts out of the fire after Bob Young asked me nicely to
fix the godawful mess their old TeX-centric production process had
degenerated into.  And I did write the User's Guide.  But I had
very little to do with the design of the tool.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

Idealism is the noble toga that political gentlemen drape over their
will to power.
	-- Aldous Huxley 

Re: docbook-tools-discuss: Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Norman Walsh <ndw@nwalsh.com>:
> A little more discussion about how to convert from procedural markup
> to structural markup is probably in order, but tools to do this are
> very, very hard to write. This is the problem I call "dragging markup
> up hill".

I shall perhaps astonish Norman by supporting him here.  This is *not* on
my list of criticisms of DTG, for the excellent reason that this topic is
just too hard.  
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

The possession of arms by the people is the ultimate warrant
that government governs only with the consent of the governed.
        -- Jeff Snyder

Crash-course to DocBook

[Eric Bischoff]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1168 bytes --]

Hi folks,

I'm happy to announce the birth of the "Crash-Course to
DocBook".

You can find it on http://public.lst.de/~eric

It is released under FDL. Feel free to make it evolve.

It has been made out of three documents:
- David Rugge's "Crash-Course to DocBook" for KDE
- Mark Galassi's "Introduction to DocBook"
- My own Lunch&Learn presentation "Using DocBook at Caldera"
with a lot of glue and reorganization (and a small waste
basket - everything that was KDE-specific has been removed).

The purpose is to have a "tutorial" for newcomers to
DocBook, to be used in conjunction with Norm's book which I
see more as a reference manual.

I hope this helps.

-- 
 Éric Bischoff   -   mailto:ebisch@cybercable.tm.fr
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                        Konqui     \__=v
 __________________________________________________

Re: I'm trying to set up docbook-tools...

[Chuck Mead]

On Tue, 4 Jul 2000, Eric S. Raymond spewed into the bitstream:

ESR>Mark Galassi <rosalia@galassi.org>:
ESR>> 
ESR>>     Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page
ESR>>     Eric> directs me to
ESR>>     Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That
ESR>>     Eric> server is perpetually swamped.  Going to one of the mirrors,
ESR>>     Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain
ESR>>     Eric> any of the db2* scripts referenced on the DocBook page.
ESR>>     Eric> Where are those scripts?
ESR>> 
ESR>> There should be several RPMs on that ftp site.  The scripts you seek
ESR>> are in the stylesheets RPM.  Also make sure you don't only get the
ESR>> noarch RPMs.
ESR>
ESR>OK, what is the actual stylesheet RPM?  You didn't specify, and all I
ESR>can find is SRPMs and tarballs.
ESR>
ESR>Would it be too much to ask that these things actually be described
ESR>on the DocBook tools page?
ESR>
ESR>Every time I go near SGML I get headaches...

I started fooling with this stuff early last fall and I went through similiar
travails. I captured what I did in a colophon for one of the documents I
created in docbook/sgml. Maybe this will help:

http://www.moongroup.com/docs/mailhelp-HOWTO/z632.html

hth!
--
Chuck Mead, CTO, LinuxMall.com
csm@LinuxMall.com
GnuPG Public Key Available: http://pgp.ai.mit.edu/

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "Eric S. Raymond" <esr@thyrsus.com> was heard to say:
| Norman Walsh <ndw@nwalsh.com>:
| > Second, I'm tired of your whining about the theology and jargon. I'm
| > sorry if TDG didn't answer your questions, I'll try to do better next
| > time (although I still think it's an authors prerogative to decide
| > what is and what is not in scope), but I don't think it's either
| > theological or jargon-filled.
| 
| In this respect (if not in others), you and the other core DocBook
| people who share this belief are still out to lunch.  And that's sad,
| because it seriously hinders the deployment of your good work.

Moments after sending this message, I regretted making the assertion
that it wasn't jargon-filled. That's nonsense and I knew better.  (I
really don't think it's theological, but if you do, I won't argue the
point any further.)

There's a definite tension when it comes to vocabulary and it bites
very deeply in SGML, possibly because I'm familiar with it, although
my intuition is that it bites deeply in SGML in part because it's
worse in SGML than in many other jargons. 8879 was written by a lawyer
after all :-)

As I expressed earlier, perhaps badly: using the precise 8879
terminology (which I don't claim to have done, in the interest of
trying to fight this exact problem, even if you think I failed) is a
way of describing things in a precise, technically unabiguous way.
Alas, it comes at the expense of the poor reader who could care less
about the distinction between a "tag" and a "generic identifier".  The
trouble is that using loose, informal terms eventually leads to
confusion in those areas where it really makes a difference.

Maybe I got the balance wrong. I could have done better.

| > It seems to me that the bulk of your ranting boils down to:
| > 
| > "The tools one needs to format a DocBook document and get HTML or
| > print output are insufficiently documented and too hard to install and
| > use."
| 
| Nope, see above.

Above only asserts that I'm out to lunch, it doesn't actually describe
any specific problem that I might be able, even anxious, to help you
with.

|  The fact that SGML initiates can't see how
| impenetrable their sacred texts are is a larger problem than the lack
| of documentation for specific tools -- because it means that said
| documentation is unlikely to get written or reviewed by exactly those
| who ought to be best qualified to do it.

I don't think that follows. I'd love to expand on the publishing
sections of TDG to provide practical answers to practical problems in
more detail.  And now that the tool sets are becoming more mature, I
think there's a good chance I'll be able to do that. I'd still like to
see a tool set that ran on both NT and Linux, but that may not yet be
practical.

And I'll happily review anything written on the subject if I'm asked.

| "Floggings will continue until morale improves." :-) No, in fact, I'm
| not flogging you for moving too slowly.  I'm flogging you for an
| apparent inability to understand "motion" at all.  I'll stop when you
| either clue in or my arm gets tired.

Your polite, reasoned demeanor invariably improves my morale.
Thank you, sir! May I have another, sir!

| So why didn't *you* figure one out this out two years ago?  Why does 
| it take an outsider, jumping up and down and screaming, to point out
| the obvious?

It must be wonderful to always have all the right ideas at the right
time. Alas, I have not your gift in that regard.

Oh, and by the way, while it may take an outsider, it does not take an
outsider jumping up and down and screaming. That has very nearly
driven me to stop reading your posts.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | DNA neither cares nor knows. DNA just
http://nwalsh.com/            | is. And we dance to its music.--Richard
                              | Dawkins

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page
    Eric> directs me to
    Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That
    Eric> server is perpetually swamped.  Going to one of the mirrors,
    Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain
    Eric> any of the db2* scripts referenced on the DocBook page.
    Eric> Where are those scripts?

There should be several RPMs on that ftp site.  The scripts you seek
are in the stylesheets RPM.  Also make sure you don't only get the
noarch RPMs.

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Thu, 06 Jul 2000, David C. Mason wrote:
> What a gentleman like approach to telling me you worked on it.

Welcome to the Open Source world :-). If we weren't passionate, we wouldn't do
it. 

And when the tools suck, we do one of two things -- use different tools, or fix
the tools. In my case, I'm using different tools for my next project, ones that
I know are reliable and work correctly.  I have a sneaking suspicion that ESR's
passion here is going to lead him to fixing the tools,  but on the other hand,
he may have concluded that his contributions aren't welcome in the SGML
community, because they don't meet some purity test (i.e., they're practically
oriented, rather than being pretty, theoretical, and utterly useless). 

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[Derek Simkowiak]

-> Second, I'm tired of your whining about the theology and jargon.

	There's a great T-Shirt from the geekshirts project:

http://geekshirts.sourceforge.net/shirts/bitchandmoan//bitchfix.png


	It seemed to apply here...

--Derek

Re: I'm trying to set up docbook-tools...

[David C. Mason]

> > I'm trying to set up docbook-tools, and finding it a hideously
> > frustrating experience.  Why does all the SGML software and
> > documentation in the world read as though it was carefully designed 
> > to prevent any actual document production from getting done?

This is one of those cases where certain documentation projects have
taken up the call more so than the tools side. For example, both the
GNOME and KDE doc groups have manuals to help people get involved with
writing documentation for their projects. Both tell the writer where
to get everything they need for Docbook and how to use it - but both
also describe it in terms that are particular to their style of
writing.

I like this approach as it narrows the focus to projects and those who
wish to write for those projects. Outside of that the best resources I
have seen are Mark's tutorial and Deb Richardson's HOWTO at OSWG. The
main problem with it is that describing SGML is not as trivial as you
might think. Describing DocBook is easier, but it still comes as very
foreign to those who come from either the word processor world, or the
format driven mark-up world. The best way to learn is by trying, not
by reading IMHO. Can the documentation be better? Sure it can, and we
shall try.

Still, I find it somewhat humorous at the trouble many hackers (who
would never dream of documenting their code) have when they can read
the source :-)


Cheers,

Dave

-- 

          David Mason
        Red Hat AD Labs

        dcm@redhat.com
  http://people.redhat.com/dcm

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Tue, 04 Jul 2000, madhu wrote:
> On Tue, 04 Jul 2000, you wrote:
> > On Tue, 04 Jul 2000, Eric S. Raymond wrote:
> > > I'm trying to set up docbook-tools, and finding it a hideously
> > > frustrating experience.  Why does all the SGML software and
> > > documentation in the world read as though it was carefully designed 
> > > to prevent any actual document production from getting done?
> > 
> > That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it
> > were a briefly written summary written in a foreign language to be as terse as
> > possible. You would suspect that the authors of documentation tools would
> > themselves be enamored of documentation. WIth the exception of Donald Knuth, 
> > that, alas, does not appear to be the case. 
> an html.zip file exists on the officail docbook site oasis with enough details
> for anybody to start with 

Are you talking about Paul Prescod's tutorial? That was one of the things that
got me going. Right now the manual I'm working on is >200 pages and still
growing, so obviously I figured out how to get things going, but I'm still
puzzled by the lack of understandable documentation. Donald Knuth's stuff about
TeX is not exactly the world's most accessible documentation either, but it is
complete, it is clear and unambiguous (except where he deliberately simplifies
things for the heathen :-),  and it clearly documents all parts of the system.
Unfortunately, the SGML purists appear to believe that their job is done once
they've created the raw DTD... "just read the DTD!" appears to be the notion. 

> the problems you are mentioning are mostly to do with SGML tools not with
> docbook by itself. 

Correct. I've already discussed the notion that SGML purists appear to believe
that their job is done once they've created the raw DTD and (optionally) style
sheet.  This attitude is what has prevented SGML from supplanting TeX/LaTeX for
structured document creation.  As I mentioned earlier, as soon as I'm finished
with the current document, I'm falling back to LyX and TeX/LaTeX. 

> If you use the scripts like db2pdf it doesn,t some time run
> jadtex thrice for the numbers to be printed right .

I have taken to running jadetex by hand until the 'unresolved reference'
messages go away, then running dvi2ps by hand. Some of my page references STILL
turn out to be -999. 

> that situation is not likely to improve what with SGML is dead proclamations
> doing the rounds and shift is towards XML . but again tools for XML are not unix
> favorable  at all .

I have come to that conclusion.  A pity. Especially since Microsoft seems bound
and detirmined to subvert XML into a Microsoft-only standard if in any way
possible. 

Still, TeX and LaTeX still exist. They are thoroughly documented. They run the
same way everywhere. They look ghe same everywhere. So while they are not the
be-all and end-all of structured document design, they'll have to do, since the
SGML crowd has committed collective suicide. A pity, that. 

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "richard offer" <offer@sgi.com> was heard to say:
| be using Jade/your stylesheets to produce the output. I've hacked mine and
| still can get what I'm (visually) looking for. I guess the limitation is in the
| generalities of DocBook, since I could get it if I was using raw LaTeX.

I'm curious about this. Can you provide a couple of examples of things
you can't do in DocBook that you could do in LaTeX? I'm not interested
in the mechanics, per se, but in what markup distinction you feel
you've lost.

|   More details on linking documents, I've got 6 docs that I'm writing in
| parallel and would really like to link between them. I gave up.

These are six separate documents, or six parts of the same document?
SGML doesn't really have a good cross-document linking solution (though
you can cobble one together, see my tutorials about olink on nwalsh.com).
XPointer and XLink should do better, but there are still some problems
given that you don't typically publish the source.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | A moment's insight is sometimes worth a
http://nwalsh.com/            | life's experience.--Oliver Wendell
                              | Holmes

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

David C. Mason <dcm@redhat.com>:
> Your problem installing the tools seemed (as I read back through the
> thread) to be one of finding a mirror that was bad. Once you found a
> mirror which contained the RPMs needed are we to assume the
> installation went according to plan? 

Oh, no.  That wasn't my only problem by a long shot.  I actually went
through three different attempts to get three different sets of tools
running -- Jade, OpenJade, and the DocBook tools.  Not one of them had
adequate documentation for beginners, even technically sophisticated
beginners like me with considerable prior knowledge of SGML (I did a
lot of of extension work on SGML-Tools for the LDP).  All three have
web pages that are remarkable for the amount of detail they convey
without actually saying anything useful.

> Can all of this be improved for the newbie - it sure can. In fact new
> scripts or even applications can be written. You are a hacker, would
> you like to write them? Can I assume the answer is no?

Do you mean like the user's guide I once wrote for SGML-Tools to
address exactly this problem? :-)

Sorry, David.  You don't get to accuse *me* of carping without
contributing.  I happen to be the person who made SGML-Tools 1.1
usable for fast-turnaround book publishing, proved it by producing
"Linux Undercover" for Red Hat, and then documented what I did.  But
don't take my word for any of that -- go ask Ed Bailey about it.  You'd
probably find the story both entertaining and instructive.

> Slamming someone's book certainly cannot help you learn can it?

Slamming someone's book for lack of clarity certainly *can* be helpful
if it wakes the author (and the dysfunctional culture surrounding the
author) up to a problem.  

I did not mean to imply that Norman Walsh's book is without value.  If
I already knew most of what was in it, I'm sure it would make a dandy
reference.  But that's the problem -- the book is only useful for
people who already have a working SGML toolset and considerable
pre-acquired expertise.  

The fact that it was not useful to a person who had already done
substantial SGML publishing and extension work on SGML tools *should*
be an important message.

> I say 'kudos' to Norm for the following: 

I'll cheerfully say Norm is a wonderful guy too, if that will make you
or him feel any better.  He's done a lot of good things.   Unfortunately,
none of those things includes actually making SGML accessible to the
un-initiated. 

*And that is the issue here*.  The DocBook community has a huge blind spot.
The consequences of that blind spot drive away people like Eric Lee Green
or myself who would otherwise love to contrivbute more.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

"Today, we need a nation of Minutemen, citizens who are not only prepared to
take arms, but citizens who regard the preservation of freedom as the basic
purpose of their daily life and who are willing to consciously work and
sacrifice for that freedom."
	-- John F. Kennedy

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Thu, 06 Jul 2000, David C. Mason wrote:
> Still, my problem is this thread has been about the lack of
> documentation for DocBook - but I still don't understand what the
> problem you are having is. I

The problem is not the lack of documentation. The problem is the lack of
attention to documenting DocBook as an actual document production system, rather
than as a theoretical exercise.  There is plenty of good theoretical
documentation, but a paucity of Get The Job Done tools and documentation.  This,
alas, has always been a problem of the SGML crowd. I've been following SGML off
and on since 1995 or so, when the original LinuxDoc project adopted that
LaTeX-like DTD, and aside from that project and one other that died aborning
(don't remember what it was, it was written using 'bigloo' Scheme and a DTD
that was similar to but simpler than DocBook), there has been absolutely no
attention at all amongst the SGML literati to the problems of producing
practical systems for ordinary users' purposes. And I'm talking as someone who
used to read Robin Cover's web page on a monthly basis looking for links that
would solve some actual problem that I had... it just never happened. 

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Mark Galassi <rosalia@galassi.org>:
> On this list we should not tell people that "they have failed" just
> because their pedagogical approach did not work for us.

You're quite right.  We tell people they have failed when their
pedagogical approach has been reported to be ineffective by
independent multiple observers.

That is, that's what we do if we actually care about improving matters.
If all we want to do is wrap the failure in a thick layer of feel-good
batting so it can be ignored, then perhaps we do something else.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

Americans have the will to resist because you have weapons. 
If you don't have a gun, freedom of speech has no power.
         -- Yoshimi Ishikawa, Japanese author, in the LA Times 15 Oct 1992

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Eric> OK, what is the actual stylesheet RPM?  You didn't specify,
    Eric> and all I can find is SRPMs and tarballs.

I'm surprised you don't find it.  I went to the first mirror and found
the non-source noarch RPM for stylesheets at:
ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/RPMS/noarch/

Re: I'm trying to set up docbook-tools...

[Kendall Clark]

>>>>> "Eric" == Eric S Raymond <esr@thyrsus.com> writes:

    Mark Galassi <rosalia@galassi.org>:
    >> On this list we should not tell people that "they have failed"
    >> just because their pedagogical approach did not work for us.

    Eric> You're quite right.  We tell people they have failed when
    Eric> their pedagogical approach has been reported to be
    Eric> ineffective by independent multiple observers.

    Eric> That is, that's what we do if we actually care about
    Eric> improving matters.  If all we want to do is wrap the failure
    Eric> in a thick layer of feel-good batting so it can be ignored,
    Eric> then perhaps we do something else.

Well if it's about adjudicating pedagogy, then I should chime in with
"Norm's book helped me tremendously, as has Norm personally on the
several occasions when I emailed him with questions." I figured out
SGML and DocBook well before Norm's book came out, well before I
learned to program in fact. There are other SGML books, some of which
are rather practical. Those helped too.

As for actually setting up and installing the various permutations of
the free tool chain, I just don't see why it's *so* hard for someone
with a bit of technical ability or experience. Could it be *easier*?
Of course. But so could nearly every bit of free software I've ever
used. 

I started working with SGML on Linux in '96, well before anyone was
making nice RPM packages for it; maybe that's an advantage in a
perverse way? I'm not sure.

Best,
Kendall Clark

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Ismael> 	We have a little problem with these tools. There
    Ismael> aren't a more-or-less sgml suite made of components
    Ismael> (packages) with well made package dependeces. Then, if you
    Ismael> want to use linuxdoc, your package system'll ask for sp,
    Ismael> linuxdoc-dtd and its filters. If you want XML DocBook, the
    Ismael> packages we all know. Add a new package (TEI?) could need
    Ismael> to add it's dtd, the stylesheets and maybe some interface.

These problems exist, but are on their way out.  It will eventually be
possible to just install a nice suite of sgml-based tools.

Re: I'm trying to set up docbook-tools...

[madhu]

On Tue, 04 Jul 2000, you wrote:
> On Tue, 04 Jul 2000, Eric S. Raymond wrote:
> > I'm trying to set up docbook-tools, and finding it a hideously
> > frustrating experience.  Why does all the SGML software and
> > documentation in the world read as though it was carefully designed 
> > to prevent any actual document production from getting done?
> 
> That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it
> were a briefly written summary written in a foreign language to be as terse as
> possible. You would suspect that the authors of documentation tools would
> themselves be enamored of documentation. WIth the exception of Donald Knuth, 
> that, alas, does not appear to be the case. 
an html.zip file exists on the officail docbook site oasis with enough details
for anybody to start with  . it is also linked from normans website from where
you can download the latest stylesheets for the docbook,
oasis wesite is 
 http://www.oasis-open.org/docbook/
and normans website is 
http://nwalsh.com/~ndw/
  > 
> It's bad enough that the authors of every book and document that exists on SGML
> have invented their own inscrutable terminology for the process of marking up
> documentation... but none of them, zero, zilch, appears to have considered the
> notion of a GLOSSARY, and the very thought of explaining complex terms in a
> simple, clear manner appears to break every single SGML author out in hives. 
> Yes, it's difficult. I've done it before, I know how difficult it is. But it's
> as if the creators of SGML DTD's and tools have a death wish... or else they're
> trying to protect their cult's purity by keeping out the riff-raff (same
> thing). 
> 
> Despite all of the above, I have become reasonably proficient in using the
> Docbook-Tools set and in Docbook itself.  But the tool kits still do not work
> well enough for me to actually use them to produce real documentation. I am
> using Docbook for the design documentation for a major project at the office,
> but nobody on this list has been able to explain to me why half the entries in
> my index have "-999" as the page number, even when the 'jadetex' script does not
> complain about unresolved references.  I've even tried updating everything
> from the Docbook-tools site thinking maybe Red Hat had a wonked out
> docbook-tools installation.  I even tried using Caldera eDesktop 2.4 rather than
> Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No
> go. I'm on the verge of abandoning the tool kit in frustration. LyX will now
> generate decent HTML output, which was my main reason for using DocBook in the
> first place (the difficulty of getting good HTML output out of "latex2html" and
> its ilk).  My only issue with LyX is the difficulty of maintaining multi-source
> documentation in a CVS depository... CVS won't do merges of multi-author edits
> of .lyx files, sigh.  But if it's a choice of LyX or using StarOffal, I know
> which I'll choose -- at least LyX is a structured markup tool, whereas
> StarOffal.. no, don't get me started. 
the problems you are mentioning are mostly to do with SGML tools not with
docbook by itself. if you use the scripts like db2pdf it doesn,t some time run
jadtex thrice for the numbers to be printed right .the db2* scripts are a sort
of primer a starting point so to say but without them you can produce docbook
documents , please refer to the readme's of jade, jadetex etc.and be warned
that situation is not likely to improve what with SGML is dead proclamations
doing the rounds and shift is towards XML . but again tools for XML are not unix
favorable  at all .

additionally i would suggest you subcribe to 

docbook-apps@lists.oasis-open.org, 
and
docbook@lists.oasis-open.org
 lists whree you might get more help than this list since this is of late a very
low traffic list.
and as Mark's excellent tutorial, please don't forget this
 http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html

regards
-- 
maddy
-------------------------------------------------------------------------       
         Fishing baskets are employed to catch fish;
         but when the fish are got, the men forget the baskets;
         Words are employed to convey ideas;
         but when the ideas are grasped, the men forget the words; 
				
					        --"Chuang Tzu"

-------------------------------------------------------------------------	

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ Mark Galassi <rosalia@galassi.org> was heard to say:
| I'm surprised nobody came across my tutorial:
| 	http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html

That one's on the DocBook documentation page:

  http://www.oasis-open.org/docbook/documentation/other.html

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | All the labors of the ages, all the
http://nwalsh.com/            | devotion, all the inspiration, all the
                              | noonday brightness of human genius, are
                              | destined to extinction--Bertrand Russell

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ Eric Bischoff <ebisch@cybercable.tm.fr> was heard to say:
| or whether the user installed it or not. So far, to rely on
| a CGI helper program seems to be the nearest thing from this
| holy graal, but first I don't see exactly how to implement
| it, and second I'm worried about assuming there is an HTTPD
| server up and running.

I can't help with the second part, but I did the first part.
Look over the olink docs on my website, I think it's described
in there and let me know if you have questions.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | When we are tired, we are attacked by
http://nwalsh.com/            | ideas we conquered long ago.--Nietzsche

Re: I'm trying to set up docbook-tools...

[David C. Mason]

"Eric S. Raymond" <esr@thyrsus.com> writes:


> Again, a symptom, In the document "A Practical Introduction to DocBook",
> the Tools section contains the following blatant cop-out:  
> 
> "Unfortunately, installing and configuring DocBook Tools is
> (currently) outsidethe scope of this document."
> 
> Anyone not already eyebrow-deep in the dysfunctional culture surrounding
> this software would realize that this lacuna makes the rest of the 
> chapter a bad joke.

Your problem installing the tools seemed (as I read back through the
thread) to be one of finding a mirror that was bad. Once you found a
mirror which contained the RPMs needed are we to assume the
installation went according to plan? 

If so, I would say you found help rather easily (through this list)
and it is indeed outside the scope of the document I pointed you
to.(If you want the packages for Debian please 'apt get' them)

Now you will find that such a document - and Norm's book will give you
a fine introduction on how to create a DocBook document. Is this
correct?

After that you need to find out how to use the scripts - correct? Well
the document I sent you to *has* each script and how to use it. That
*was* within the scope... or did you stop reading after the
installation section?

Can all of this be improved for the newbie - it sure can. In fact new
scripts or even applications can be written. You are a hacker, would
you like to write them? Can I assume the answer is no?

It is very easy to blame the SGML community for the problems inherent
to understanding the technology, it is not as easy to lend a hand. Why
is that? Do hackers think that documentation tools are beneath them
until they actually have to use them?

Slamming someone's book certainly cannot help you learn can it?
Especially when you are talking about someone who has put more into
bringing SGML/XML into the open source community than even he might
realize. Would you rather him not have written *any* book? 

I say 'kudos' to Norm for the following: 

1) Keeping DocBook moving and up to date with the trends of writing
   for computer documentation

2) Keeping two sets of fully functional stylesheets (DSSSL and XSL)
   applicable to DocBook and ready to use 'out of the box'.

3) Convincing a company to publish a *free* book on DocBook

4) Taking his time to write said book

5) Keeping the reference documentation up to date (have you seen the
   quick guide reference section? I use it everyday and I know most of
   the tags in docbook) 

6) Finally, doing all of this in a cross platform, open source model.

Oh, and lets not forget the fact that even though he eclipses me in
the number of mailing lists he is on, he still answers every personal
question I have ever sent (and probably everyone else's). Can you find
an equivalent figure in the open source community?

I would say that this person is following the model presented in the
'Cathedral and the Bazaar' rather closely - are you?

Dave


-- 


David Mason
Red Hat Advanced Development Labs
dcm@redhat.com (919)547-0012 x248

Re: docbook-tools-discuss: Re: I'm trying to set up docbook-tools...

[Edward C. Bailey]

>>>>> "Norm" == Norman Walsh <ndw@nwalsh.com> writes:
...
Norm> A little more discussion about how to convert from procedural markup
Norm> to structural markup is probably in order, but tools to do this are
Norm> very, very hard to write. This is the problem I call "dragging markup
Norm> up hill".  Look at the troff source for an (old) O'Reilly book (I
Norm> have :-), and you'll find that the same troff markup for "italic" is
Norm> used for all the things that are italic in print. (Quelle
Norm> surprise). But if you want to mark those things up semantically, you
Norm> have to distinguish between at least three or four different kinds of
Norm> italic things which is nearly impossible to do accurately.

We had the same problem going from LaTeX to DocBook; for every
\texttt{foo}, our script converted it to <TT?>foo</TT?>.  We then used
Emacs to do multiple query-replaces (ie, one to go from "TT?" to
"filename", one for "TT?" to "command", etc).  Once you got going, it was
possible to crank through a surprising volume of markup in a reasonable
amount of time.  Pretty mind-numbing, though... :-)  And I wouldn't
recommend taking this approach if you're a large company converting tons of
legacy content.

To really automate this kind of thing requires something on the order of a
HAL 9000 -- by looking at the few words surrounding the content in
question, a human being can make a pretty accurate assessment in a second
or so, but having a machine do the same thing is "Sir
Not-Appearing-in-This-Film", at least for the time being... :-)

                            Ed
-- 
Ed Bailey        Red Hat, Inc.          http://www.redhat.com/

Re: I'm trying to set up docbook-tools...

[David C. Mason]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Oh, no.  That wasn't my only problem by a long shot.  I actually went
> through three different attempts to get three different sets of tools
> running -- Jade, OpenJade, and the DocBook tools.  Not one of them had
> adequate documentation for beginners, even technically sophisticated
> beginners like me with considerable prior knowledge of SGML (I did a
> lot of of extension work on SGML-Tools for the LDP).  All three have
> web pages that are remarkable for the amount of detail they convey
> without actually saying anything useful.


Then I still don't understand the problems you are having... or at
least, I still haven't seen a detail of what you would like to see. I
think the ' Practical Guide...' is a very good intro to the scripts
and creating a DB document - its short, to the point, and includes,
what I think, you need to get started. But again, I can't figure out
except the mirror stuff, what is wrong...I'd like to help



> Do you mean like the user's guide I once wrote for SGML-Tools to
> address exactly this problem? :-)
> 
> Sorry, David.  You don't get to accuse *me* of carping without
> contributing.  I happen to be the person who made SGML-Tools 1.1
> usable for fast-turnaround book publishing, proved it by producing
> "Linux Undercover" for Red Hat, and then documented what I did.  But
> don't take my word for any of that -- go ask Ed Bailey about it.  You'd
> probably find the story both entertaining and instructive.

I had no idea you did the first SGML-Tools and I apologize, you are a
single entity in that case. Otherwise, I find that most hackers ignore
these tools altogether. My apologies.

Still, my problem is this thread has been about the lack of
documentation for DocBook - but I still don't understand what the
problem you are having is. I feel there is quite a bit of
documentation out there, and if I knew the problem I could point you
to it... if not, I could write it (especially since I am going to do a
DocBook talk at OLS, this info would help me). Otherwise complaining
about one or two particular documents doesn't do any good. You have
stated why you didn't like Norm's book, you stated you didn't like the
installation section in the 'Practical Guide...' HOWTO... so what do
you want? Need? Is it *really* helpful to point out flaws in those
particular documents when there might be one that answers your
question?


Dave

-- 


David Mason
Red Hat Advanced Development Labs
dcm@redhat.com (919)547-0012 x248

Re: I'm trying to set up docbook-tools...

[Mark Galassi]

    Kendall> As for actually setting up and installing the various
    Kendall> permutations of the free tool chain, I just don't see why
    Kendall> it's *so* hard for someone with a bit of technical
    Kendall> ability or experience.

It isn't.  The person who started this thread said there was no
tutorial which includes setting up the tools, but there actually was.
Although things are out of date, this whole thread is mostly
unnecessary.

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Thu, 06 Jul 2000, Mark Galassi wrote:
> Kendall> As for actually setting up and installing the various
>     Kendall> permutations of the free tool chain, I just don't see why
>     Kendall> it's *so* hard for someone with a bit of technical
>     Kendall> ability or experience.
 
> It isn't.  The person who started this thread said there was no
> tutorial which includes setting up the tools, but there actually was.
> Although things are out of date, this whole thread is mostly
> unnecessary.

Futile, perhaps. Unnecessary, no.  I am constantly fighting The Cult Of
Obscurity both on the job and off it, because so many good technical people
just don't see what's wrong with their documentation and programming.  "It
makes sense to me, other people must just be stupid" is the attitude of the
typical adherent of the Cult of Obscurity.  I sometimes have to fuss at my own
co-workers about "Look, I don't care about details x, y, and z, I, the
hypothetical the end user, just want to get job 'n' done",  and I'm certainly
not going to be reticient about doing the same elsewhere,  even if I'm not being
paid to do it elsewhere :-).  

People do not care about elegance. They do not care about how terse and formal
the language is surrounding a topic. They just want to get a job done with as
few keystrokes or mouse clicks as possible, and learning as few details as
possible to do it. This is one place where Lamport's LaTeX book shines (despite
how aweful it is otherwise), the first thing he does is say, "Here is how you
write a letter in LaTeX." What genius! 

Regarding Norm Walsh's book: the biggest problem was a lack of examples of how
to use DocBook to create entire documents.  There's reasonably good examples of
the use of many of the individual elements, but nothing like where Lamport
says, "Here is how you create a document. Here is how you create a letter.
Here is how to create a document that has a table in it." Lamport's LaTeX book
sucks... but it sucks in a way that lets most people write simple documents
after reading it. 

Note that I'm not calling the SGML crowd stupid.  I'm not saying that their
documentation "sucks" for people who are already initiated into the Cult Of
SGML. What I'm saying is that a) there's a paucity of documentation about how
to Get The Job Done, the only one I know about is the FreeBSD one, and b) there
has been a lack of attention to Getting The Job Done on the part of the
SGML community as a whole, they have been absorbed in the technical excellence
of SGML, the theoretical possibilities of parsing SGML, the stylistic elegance
of DSSL and stylesheet languages, whilst ignoring the whole point of the
exercise. I realize this is not an attitude that is restricted to the SGML
crowd. This sort of attitude is rampant in the computer biz, those of us who
have a good understanding of end user wants and needs are always the minority,
and those of us with both technical skills and writing skills are even rarer.
But, as the other Eric mentioned, this sort of attitude is also what kept SGML
from sweeping the world over the last five years, and is what basically has
killed SGML (with the exception of the HTML DTD and XML subset, the former of
which isn't really SGML anymore).  

'Nuff said. I'm sure I'll find many more flames in my mailbox from adherents of
the Highly Theoretical Cult of SGML Gurus.  But (shrug), when it comes to
document production, I'm an end user. I design tape backup and related software
for a living, not documentation tools.  All I want to do is to get a job done.
I don't CARE about how elegant DSSL is, or how flexible the Docbook DTD is...
it's a tool, for cryin' out loud, not a religion.  And if it doesn't Do The
Job, I'll dump it and use some other tool. Which, apparently, has been the
conclusion of most others who would use SGML, too, with the exception of a few
of the Open Source projects which use it because that's what the LinuxDoc
project uses. 

 -- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "Eric S. Raymond" <esr@thyrsus.com> was heard to say:

With respect to this comment,

| As it is, the fact that the
| power of these techniques is surrounded by a near-impenetrable thicket
| of theology and jargon is deeply frustrating to me -- and the apparent
| inability of SGML people to see that this is an issue is maddening!

And bearing in mind something you said earlier,

| You [...] can
| start being offended the day I don't respect you enough to criticize
| your work.

I feel compelled to reply:

First, you're mistaken. As the reader of your comments, I'm free to
become offended whenever I bloody well choose.

Second, I'm tired of your whining about the theology and jargon. I'm
sorry if TDG didn't answer your questions, I'll try to do better next
time (although I still think it's an authors prerogative to decide
what is and what is not in scope), but I don't think it's either
theological or jargon-filled.

It seems to me that the bulk of your ranting boils down to:

"The tools one needs to format a DocBook document and get HTML or
print output are insufficiently documented and too hard to install and
use."

I haven't heard a single person disagree with you. And in the two years
since you first encountered DocBook, tremendous progress has been made.
I'm committed to seeing that, to the extent I can contribute, the
progress continues until it's as nearly dead easy as possible.

Now would you please stop flogging me for not moving fast enough.  I
ain't your whipping boy, son.

| Really.  What would it have cost to supply *one* explicit example of 
| a document-production flow on Unix and Windows?  A few pages could have
| made a huge difference -- in helpful symbolism, even if it couldn't
| cover all the substance.

Now that's an interesting question. You might be right.

| As it is, one is left with the impression that Mr. Walsh was so caught
| up in the arcana of Scheme and CSS and DTD composition that he couldn't be 
| bothered to descend to the level of actually showing the reader how to
| actually use any of it.

For the record, my thought process went something like this. "Today
(when I was writing) things are still pretty immature. I could try to
document one of the many possible tool sets, but then I'd be leaving
out all the others, not to mention the commercial tools from
Arbortext, Frame, and Softquad to name but three. And there's no tool
set that works equally well on Unix and NT, so I'd have to do at least
two. Things will be better soon and the installation instructions for
the individual tool sets can do a better job on installation than I
can. Heck, I don't even have a Linux box at hand these days. The vast
majority of questions that I get aren't about specific tools, people
seem to get those installed, they're about how to customize X, Y, or Z
in the stylesheets. Since the DSSSL stylesheets form the core of
several tool sets, end users would be better served by some
explanation of how to use and customize those."

| (All right, everybody.  Calm down -- I'm not claiming that was his actual
| state of mind, simply that that is the message the book sends.)

And the message you send is...oh, nevermind.

| >                                                The important point
| >       here is that we need to get away from the mentality that
| >       introductory/tutorial texts are for clueless newbies, that hard-core
| >       reference material is the only truly important documentation.  The
| >       introductory stuff makes the technology accessible to people that
| >       would otherwise not have access.
| 
| Amen.  Squared...

Cubed, even.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | Whatever you may be sure of, be sure of
http://nwalsh.com/            | this: that you are dreadfully like
                              | other people.--James Russell Lowell

Re: I'm trying to set up docbook-tools...

[Edward C. Bailey]

>>>>> "esr" == Eric S Raymond <esr@thyrsus.com> writes:

esr> David C. Mason <dcm@redhat.com>:
>> Then I still don't understand the problems you are having... or at
>> least, I still haven't seen a detail of what you would like to see.

esr> I'd like to see documentation that spends less time genuflecting
esr> before the wonderfulness of semantic markup and stylesheets, and more
esr> time telling me how I can install and configure working tools and make
esr> HTML and Postscript from actual documents.

I wonder if SGML documentation's current focus on the theoretical versus
the practical is an evolutionary backwater from the days when people using
the technology had to explain why they were "doing things the 'hard' way
with SGML" when most people doing documentation were simply using whatever
tools they happened to have available.  Even if this was the case at one
point in time, I think we all agree that most people "get it" when it comes
to markup languages (if for no other reason than all the hype XML has
brought to our part of the world).  So it's time to move on, and leave the
Cult of the Sacred Tag mentality behind us now... :-)

...
esr> Is it just me?  Am I crazy to think there's something wrong with a
esr> 600-page tome on document production tools that *never once tells you
esr> how to format a document?*

To be honest, and at least in the case of _DocBook: The Definitive Guide_,
I think it's just you.  The book is a reference describing a particular
markup language.  That markup language is processed by a wide variety of
software (both open source and non-) on a wide variety of platforms (again,
both open source and non-).  To have this particular reference guide get
into how the markup language is processed by one particular application on
a subset of the possible platforms would be something similar to HP
including a chapter called "Using Your New Printer to Print Romance Novels"
in every LaserJet owner's manual. :-)

That's not to say that there *shouldn't* be a book that does just what you
describe.  I strongly agree with you that this kind of information should
be in a book somewhere.  I just don't think _DocBook: TDG_ is that book.

esr> The unbelievable part is that it's *all* like that.  It's not just the
esr> individual authors of these particular documents that are high priests
esr> of the Cult of Obscurity -- every piece of documentation I've ever
esr> seen from the DocBook/SGML community is pretty much off in theoretical
esr> cloud-cuckoo land.  I can learn more than I ever wanted to know about
esr> DSSL and FOSI and fifty other acronyms, but I can't find any clue
esr> about what to do when jadetex generates bad Postscript that makes gs
esr> choke.

esr> What I want to see is a practical guide that is truly a practical
esr> guide -- something like what I wrote for SGML-tools, but covering
esr> DocBook.

I feel compelled to preface my comments by saying that my goal is neither
to cut anyone down, nor to build myself up.  But I have a bit of background
here that leads me to the following observations:

    o If you were to change a few of the terms in ESR's comments, you'd
      have almost exactly the same kinds of feedback we at Red Hat get from
      users regarding the state of Linux documentation today.  So those of
      us that do documentation for one or more open source software
      projects should keep in mind that we ain't done yet -- not by a long
      shot.  This complaint is true for DocBook documentation, and it's
      true for many (most? all?) open source software projects.

    o Since ESR has worked with me, he knows I'm not the sharpest knife in
      the kitchen (and hopefully feels that I'm at least not the dullest,
      either :-).  Yet he's confounded trying to format DocBook documents,
      while I've been able to convert over 1500 pages of LaTeX-based
      documentation into DocBook, and to create the tools necessary to
      support a production environment to produce DocBook-based content
      here at Red Hat.  What's the difference?  Time.  It was my full-time
      job to make the move to DocBook, while ESR is probably lucky if he
      can devote an hour here and there to the task.  The important point
      here is that we need to get away from the mentality that
      introductory/tutorial texts are for clueless newbies, that hard-core
      reference material is the only truly important documentation.  The
      introductory stuff makes the technology accessible to people that
      would otherwise not have access.  And as I'm sure ESR can vouch,
      being treated like a clueless newbie, on the outside looking in,
      sucks.

esr> Don't get an exaggerrated idea of my creds, either.  I didn't write
esr> SGML-tools, nor was I ever its official maintainer.  I did one really
esr> serious burst of work on it around 0.99-1.0 -- basically so I could
esr> pull Red Hat's nuts out of the fire after Bob Young asked me nicely to
esr> fix the godawful mess their old TeX-centric production process had
esr> degenerated into.

Point of clarification -- ESR helped us replace a contractor (with a
largely manual and TeX-centric production process) that seemed to be unable
to deliver the goods when promised.  That said, the end result still was
the extraction of said gonads from the conflagration -- and in a most
elegant fashion... :-)

                                Ed
-- 
Ed Bailey        Red Hat, Inc.          http://www.redhat.com/

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Norman Walsh <ndw@nwalsh.com>:
> Second, I'm tired of your whining about the theology and jargon. I'm
> sorry if TDG didn't answer your questions, I'll try to do better next
> time (although I still think it's an authors prerogative to decide
> what is and what is not in scope), but I don't think it's either
> theological or jargon-filled.

In this respect (if not in others), you and the other core DocBook
people who share this belief are still out to lunch.  And that's sad,
because it seriously hinders the deployment of your good work.
 
> It seems to me that the bulk of your ranting boils down to:
> 
> "The tools one needs to format a DocBook document and get HTML or
> print output are insufficiently documented and too hard to install and
> use."

Nope, see above.  The fact that SGML initiates can't see how
impenetrable their sacred texts are is a larger problem than the lack
of documentation for specific tools -- because it means that said
documentation is unlikely to get written or reviewed by exactly those
who ought to be best qualified to do it.

Instead, hapless schlubs like me end up jerry-rigging together 
things like the SGML-Tools user's guide...and feeling very ill-served 
by an SGML community that seems unwilling to climb down from their
heights of abstraction.

> Now would you please stop flogging me for not moving fast enough.  I
> ain't your whipping boy, son.

"Floggings will continue until morale improves." :-) No, in fact, I'm
not flogging you for moving too slowly.  I'm flogging you for an
apparent inability to understand "motion" at all.  I'll stop when you
either clue in or my arm gets tired.

If we're both committed to excellence of results, it *is* my job to do
that, and your job to cope with it.  Welcome to the sharp end of peer
review, daddy-o.

> | Really.  What would it have cost to supply *one* explicit example of 
> | a document-production flow on Unix and Windows?  A few pages could have
> | made a huge difference -- in helpful symbolism, even if it couldn't
> | cover all the substance.
> 
> Now that's an interesting question. You might be right.

And this is a perfect example of not understanding motion.  You are,
by all accounts, an intelligent and well-intentioned person with a
considerable capacity for both creativity and hard work.  You are also
a pretty good writer -- there is nothing wrong with DTG's prose at the
microlevel.

So why didn't *you* figure one out this out two years ago?  Why does 
it take an outsider, jumping up and down and screaming, to point out
the obvious?

If and when you achieve enlightenment on this koan, I think the root
problem of the SGML culture will also be clear to you.

(I deeply regret that I wasn't on DTG's pre-pub review list...)
 
> | (All right, everybody.  Calm down -- I'm not claiming that was his actual
> | state of mind, simply that that is the message the book sends.)
> 
> And the message you send is...oh, nevermind.

Uh huh.  "The meaning of a communication is not what is sent, but what
is received."  If you really understood that and had acted on it, DTG 
would have been a better book.

This is not academic criticism, nor is it consigning DTG to the trash heap.
I've written two pretty successful books (one technical, one mass-market)
and substantial portions of three others.  I do a lot of technical review
work.  DTG's strengths and its weaknesses are both characteristic of books
written by experts with both an unsurpassed grasp of their technical domain
and a near-complete inability to view that domain from outside.
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

"They that can give up essential liberty to obtain a little temporary 
safety deserve neither liberty nor safety."
	-- Benjamin Franklin, Historical Review of Pennsylvania, 1759.

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Thu, 06 Jul 2000, David C. Mason wrote:
> "Eric S. Raymond" <esr@thyrsus.com> writes:
> > Anyone not already eyebrow-deep in the dysfunctional culture surrounding
> > this software would realize that this lacuna makes the rest of the 
> > chapter a bad joke.
>
> It is very easy to blame the SGML community for the problems inherent
> to understanding the technology, it is not as easy to lend a hand. Why
> is that? Do hackers think that documentation tools are beneath them
> until they actually have to use them?

Well, unfortunate but true, most hackers are no good at documentation. This
applies to SGML software creators as well :-(. 

Equally unfortunate but true, most hackers have no idea how end users think,
and thus have no idea how to create software that is easy to understand and
easy to use that solves problems that end users actually have.  They tend to
get caught up in making the software super-flexible and super-swiss-knife,
which is nice but not at the expense of ease of solving particular problems.  I
had to fight for the concept of "click this single button, and it does what 90%
of users want out of our software" when it came to prototyping a potential
future product, because the hacker who designed the thing had a screen
cluttered with stuff that would confuse the typical end user and which was not
intuitive at all. But it made sense to him. He didn't understand that most
people are not hackers and don't think like hackers. 

Finally:  those of us who are actually being paid to write documentation rarely
are getting paid to write documentation tools at the same time, and in most
cases even writing documentation is not our full-time job (I write
documentation as part of designing software -- you know, requirements docs,
functional specifications, design docs, class heirarchy docs, etc.). In
addition, we're often fighting pointy-haired bosses who want us to use
Microsoft Word or StarOffice or whatever "standard" office suite the
corporation has adopted, and who (having never written anything larger than
a letter) don't understand that structured document layout systems are much more
appropriate for technical documentation.  To put the blame on the end user for
the poor state of Docbook/SGML documentation and tools is a case of blaming the
victim... we're just out here trying to do a job, not fight religious wars, and
we have enough trouble getting permission to use any kind of SDL system without
having to fight a buggy one as well.  As it is, I have to continually justify
to my bosses my use of DocBook... they don't understand why I would want to use
a SDL instead of the "corporate standard" office suite. Now you're going to
blame me for the fact that I'm getting "-999" for half the page numbers in my
index?!  Sad but true, here in the real world the pointy haired boss's response
to problems that we have generating documentation with the Docbook tools is
"quit that Docbook BS and use Microsoft Word [StarOffice, WordPerfect, etc.]
like the rest of us."  

WHich is why my next set of documentation is going to be using LyX/LaTeX. The
tools work, they work reliably, they've worked reliably for years and years and
years, they're not ideal but they get the job done and dammit, that's all I
care about. And that's why SGML has remained a cult rather than a real solution
for most people's documentation problems. 

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Mark Galassi <rosalia@galassi.org>:
> 
>     Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page
>     Eric> directs me to
>     Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That
>     Eric> server is perpetually swamped.  Going to one of the mirrors,
>     Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain
>     Eric> any of the db2* scripts referenced on the DocBook page.
>     Eric> Where are those scripts?
> 
> There should be several RPMs on that ftp site.  The scripts you seek
> are in the stylesheets RPM.  Also make sure you don't only get the
> noarch RPMs.

OK, what is the actual stylesheet RPM?  You didn't specify, and all I
can find is SRPMs and tarballs.

Would it be too much to ask that these things actually be described
on the DocBook tools page?

Every time I go near SGML I get headaches...
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

Government is actually the worst failure of civilized man. There has
never been a really good one, and even those that are most tolerable
are arbitrary, cruel, grasping and unintelligent.
	-- H. L. Mencken 

Re: I'm trying to set up docbook-tools...

[Eric S. Raymond]

Edward C. Bailey <ed@redhat.com>:
>                               So it's time to move on, and leave the
> Cult of the Sacred Tag mentality behind us now... :-)

Indeed.  And an important point: I wouldn't be so exercised about the
Cult of the Sacred Tag if, on some level, I didn't grok that the SGML
people have some reason behind the religion.  If it was all just just
bullshit, I could ignore it and go away.  As it is, the fact that the
power of these techniques is surrounded by a near-impenetrable thicket
of theology and jargon is deeply frustrating to me -- and the apparent
inability of SGML people to see that this is an issue is maddening!

> esr> Is it just me?  Am I crazy to think there's something wrong with a
> esr> 600-page tome on document production tools that *never once tells you
> esr> how to format a document?*
> 
> To be honest, and at least in the case of _DocBook: The Definitive Guide_,
> I think it's just you. [...]  To have this particular reference guide get
> into how the markup language is processed by one particular application on
> a subset of the possible platforms would be something similar to HP
> including a chapter called "Using Your New Printer to Print Romance Novels"
> in every LaserJet owner's manual. :-)

No, I'd say it's more like supplying schematics and chip masks for the 
printer's electronics and neglecting to document the front-panel controls.

Really.  What would it have cost to supply *one* explicit example of 
a document-production flow on Unix and Windows?  A few pages could have
made a huge difference -- in helpful symbolism, even if it couldn't
cover all the substance.

As it is, one is left with the impression that Mr. Walsh was so caught
up in the arcana of Scheme and CSS and DTD composition that he couldn't be 
bothered to descend to the level of actually showing the reader how to
actually use any of it.

(All right, everybody.  Calm down -- I'm not claiming that was his actual
state of mind, simply that that is the message the book sends.)

>     o If you were to change a few of the terms in ESR's comments, you'd
>       have almost exactly the same kinds of feedback we at Red Hat get from
>       users regarding the state of Linux documentation today.  So those of
>       us that do documentation for one or more open source software
>       projects should keep in mind that we ain't done yet -- not by a long
>       shot.  This complaint is true for DocBook documentation, and it's
>       true for many (most? all?) open source software projects.

Yup.  That's why I maintain, at last count, eight (8) different technical
FAQ documents.  
 
>                                                The important point
>       here is that we need to get away from the mentality that
>       introductory/tutorial texts are for clueless newbies, that hard-core
>       reference material is the only truly important documentation.  The
>       introductory stuff makes the technology accessible to people that
>       would otherwise not have access.

Amen.  Squared...
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

"Rightful liberty is unobstructed action, according to our will, within limits
drawn around us by the equal rights of others."
	-- Thomas Jefferson

Re: I'm trying to set up docbook-tools...

[Ismael Olea]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 893 bytes --]

Sam Roberts escribió:

> them. You can use jade without docbook or norm's style sheets, you can use
> jadetex without using docbook, the db2* scripts are so optional most people
> write their own, and you don't have to use emacs to edit sgml, but it helps.

	We have a little problem with these tools. There aren't a more-or-less
sgml suite made of components (packages) with well made package
dependeces. Then, if you want to use linuxdoc, your package system'll
ask for sp, linuxdoc-dtd and its filters. If you want XML DocBook, the
packages we all know. Add a new package (TEI?) could need to add it's
dtd, the stylesheets and maybe some interface.

	What do you think?

-- 

        A.Ismael Olea González

        mailto:olea@hispalinux.es  http://www.hispalinux.es/~olea
        2:345/108.9@fidonet.org
                
        El mundo debe empezar a tener miedo a un planeta DEF

Re: I'm trying to set up docbook-tools...

[Chuck Dale]

Wrote Norman Walsh on Thu, Jul 06, 2000 at 12:21:20PM -0400:
> / Eric Lee Green <eric@badtux.org> was heard to say:
> | That puzzles me too. Even Norm Walsh's so-called "Docbook" book
> | reads as if it were a briefly written summary written in a foreign
> | language to be as terse as possible.
> 
> <sigh/> I'm sorry you found it to be that way. That wasn't the intent.
> Although the bulk of the book is intended as a reference and not a
> how-to, the introductory chapters were supposed to be readable by the
> novice. Can you explain, in any more detail, what you found most
> troubling?

Get to the point. An introduction should explain the essence of
DocBook, give a few examples of how to do it, and give the user some
ideas where to start using the tools.

Some diagrams would be useful. Such as:

    Structured document editing ( DocBook markup + stylesheet = output )

Don't talk about SGML/XML explicitly in the introduction - explain an
example of DocBook. DocBook is very easy and mostly self explanatory so
you will have little to do. I had to read more than half TDG to get the
bigger picture of DocBook - I was reading about Public/System
Identifiers before I even knew the very basics of writing a DocBook
document. All the entities and identifiers stuff went straight over my
head first time through.

Other than that I liked TDG a lot! =)

Chuck

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ Eric Lee Green <eric@badtux.org> was heard to say:
| Unfortunately, the SGML purists appear to believe that their job is
| done once they've created the raw DTD... "just read the DTD!"
| appears to be the notion.

Reading the DTD isn't going to help at all with the problem of setting
up a toolchain, so I'm confused. Are you saying that SGML/XML are not
well described? Or that a particular DTD (e.g, DocBook) is not well
described? Or that the mechanics of setting up a toolchain (on your
system, for the output you want) are not well described?

| Correct. I've already discussed the notion that SGML purists appear
| to believe that their job is done once they've created the raw DTD
| and (optionally) style sheet. 

An SGML purist *is done* when they've created the doctype (or Schema).
That's the job you hire them to do. (Note that a doctype includes
prose documentation, a .dtd file isn't enough and was never believed
to be enough.) That said, I don't consider myself a purist and I've
spent a lot of time writing stylesheets and documenting them as best I
could under the constraints of time and a day job.

No one (that I know) would be silly enough to argue that you *don't
need* a toolchain, but there is tremendous variablity in setting up
the toolchain. Thanks to the tremdous effort of folks involved in
efforts like docbook-tools, we're beginning to see open source
distributions of tools that can be reasonably documented and will
produce results for lots of folks on lots of platforms. This is a
welcome change for those of us who have been lamenting the fact that
SGML was almost completely a "build your own" environment for so many
years.

| This attitude is what has prevented
| SGML from supplanting TeX/LaTeX for structured document creation.

Prevented where? Oh, nevermind, it's an inflammatory remark.

| I have taken to running jadetex by hand until the 'unresolved
| reference' messages go away, then running dvi2ps by hand. Some of my
| page references STILL turn out to be -999.

I've forgotten where this started. These are TOC page references or
index page references?

| > that situation is not likely to improve what with SGML is dead
| proclamations > doing the rounds and shift is towards XML . but
| again tools for XML are not unix > favorable at all .

For the purposes of this discussion, XML is SGML. There's no
appreciable difference.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | All professional men are handicapped by
http://nwalsh.com/            | not being allowed to ignore things
                              | which are useless.--Goethe

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ Eric Lee Green <eric@badtux.org> was heard to say:
| Regarding Norm Walsh's book: the biggest problem was a lack of
| examples of how to use DocBook to create entire documents.  There's
| reasonably good examples of the use of many of the individual
| elements, but nothing like where Lamport says, "Here is how you
| create a document. Here is how you create a letter.  Here is how to
| create a document that has a table in it." Lamport's LaTeX book

Fair cop. It needs more of that.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | An ill-humoured man is a prisoner at
http://nwalsh.com/            | the mercy of an enemy from whom he can
                              | never escape.--Sa'di

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "Eric S. Raymond" <esr@thyrsus.com> was heard to say:
| OK, what is the actual stylesheet RPM?  You didn't specify, and all I
| can find is SRPMs and tarballs.
| 
| Would it be too much to ask that these things actually be described
| on the DocBook tools page?

No, that's a good idea. If someone sends me some appropriate text, I'll
be happy to put it on the tools page.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | If you are hankering after certainty,
http://nwalsh.com/            | you are better advised to seek it in
                              | religion: the stock-in-trade of science
                              | is not certainty but doubt.--K.C. Cole

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ Eric Lee Green <eric@badtux.org> was heard to say:
| That puzzles me too. Even Norm Walsh's so-called "Docbook" book
| reads as if it were a briefly written summary written in a foreign
| language to be as terse as possible.

<sigh/> I'm sorry you found it to be that way. That wasn't the intent.
Although the bulk of the book is intended as a reference and not a
how-to, the introductory chapters were supposed to be readable by the
novice. Can you explain, in any more detail, what you found most
troubling?

| It's bad enough that the authors of every book and document that exists on SGML
| have invented their own inscrutable terminology for the process of marking up
| documentation... but none of them, zero, zilch, appears to have considered the
| notion of a GLOSSARY, and the very thought of explaining complex terms in a
| simple, clear manner appears to break every single SGML author out in hives. 
| Yes, it's difficult. I've done it before, I know how difficult it is. But it's
| as if the creators of SGML DTD's and tools have a death wish... or else they're
| trying to protect their cult's purity by keeping out the riff-raff (same
| thing). 

It is an unfortunate fact that Goldfarb created a set of concise,
technical terms for describing the various components of SGML
markup. On the one hand, using these terms precisely tends to be
awkward for novices. On the other, using other terms causes confusion
among other audiences.

I really tried to be clear in this regard. <sigh/>

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | Everything is temporary.
http://nwalsh.com/            | 

Re: I'm trying to set up docbook-tools...

[Eric Lee Green]

On Tue, 04 Jul 2000, Eric S. Raymond wrote:
> I'm trying to set up docbook-tools, and finding it a hideously
> frustrating experience.  Why does all the SGML software and
> documentation in the world read as though it was carefully designed 
> to prevent any actual document production from getting done?

That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it
were a briefly written summary written in a foreign language to be as terse as
possible. You would suspect that the authors of documentation tools would
themselves be enamored of documentation. WIth the exception of Donald Knuth, 
that, alas, does not appear to be the case. 

It's bad enough that the authors of every book and document that exists on SGML
have invented their own inscrutable terminology for the process of marking up
documentation... but none of them, zero, zilch, appears to have considered the
notion of a GLOSSARY, and the very thought of explaining complex terms in a
simple, clear manner appears to break every single SGML author out in hives. 
Yes, it's difficult. I've done it before, I know how difficult it is. But it's
as if the creators of SGML DTD's and tools have a death wish... or else they're
trying to protect their cult's purity by keeping out the riff-raff (same
thing). 

Despite all of the above, I have become reasonably proficient in using the
Docbook-Tools set and in Docbook itself.  But the tool kits still do not work
well enough for me to actually use them to produce real documentation. I am
using Docbook for the design documentation for a major project at the office,
but nobody on this list has been able to explain to me why half the entries in
my index have "-999" as the page number, even when the 'jadetex' script does not
complain about unresolved references.  I've even tried updating everything
from the Docbook-tools site thinking maybe Red Hat had a wonked out
docbook-tools installation.  I even tried using Caldera eDesktop 2.4 rather than
Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No
go. I'm on the verge of abandoning the tool kit in frustration. LyX will now
generate decent HTML output, which was my main reason for using DocBook in the
first place (the difficulty of getting good HTML output out of "latex2html" and
its ilk).  My only issue with LyX is the difficulty of maintaining multi-source
documentation in a CVS depository... CVS won't do merges of multi-author edits
of .lyx files, sigh.  But if it's a choice of LyX or using StarOffal, I know
which I'll choose -- at least LyX is a structured markup tool, whereas
StarOffal.. no, don't get me started. 

> The < http://sourceware.cygnus.com/docbook-tools/ > page directs me to
> < ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That server is
> perpetually swamped.  Going to one of the mirrors, I find a
> docbook-3.1-5.noarch.rpm, but it does not contain any of the db2*
> scripts referenced on the DocBook page.  Where are those scripts?

On Red Hat 6.2 Linux, they're in "stylesheets-1.54.13rh-1.xxx.rpm" (put
architecture of choice in place of 'xxx').  Red Hat ships with what is
basically a slight tweak of the docbook-tools kit. 

'docbook-3.1-5.noarch.rpm' is just the DTD (Data Type Definition), it does not
contain the other software you'll need to convert programs written using that
DTD into a useful form. You'll need 'jade' and 'stylesheets' to do that. 
'jade' is the actual grunt engine, while 'stylesheets' is the Scheme and
scripts that the grunt engine uses to know how to do the conversion. 

export SGML_CATALOG_FILES=/usr/lib/sgml/CATALOG 
export SGML_ROOT=/usr/lib/sgml

are also nice to tell Emacs's psgml mode where to find the overall catalog and
SGML dtd and tools. I use 'xemacs', which puts up a nice SGML menu at the top.

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org  

Re: I'm trying to set up docbook-tools...

[David C. Mason]

"Eric S. Raymond" <esr@thyrsus.com> writes:


> I'd like to see documentation that spends less time genuflecting
> before the wonderfulness of semantic markup and stylesheets, and more
> time telling me how I can install and configure working tools and make
> HTML and Postscript from actual documents.

Hmmm I just don't see either of the online documents (Mark's or Deb's)
"genuflecting before the wonderfulness of semantic markup.." I do see
them telling you how to use the tools to "produce actual, viewable
HTML or Postscript from an actual document".

You are correct that there is not very good documentation for the
installation and that is partly due to the fact that depending on the
flavor of Linux or UNIX you are using, it is different. However, that
will change with the new DB Tools being created which includes a nice
proposal to the LSB to make sure it is the same across the board. Once
it is done I will be happy to write an installation guide for it.

You are catching DocBook at a time when it is finally being recognized
and used throughout many projects in Linux. The tools are not 100%
satisfactory but they are being worked on as we speak. When tools are
in flux, documentation is either non-existent or also in flux. That is
the nature of the beast. We release early and release often, usually
at the expense of good documentation and translation.

If you want really good docs *now* perhaps try a commercial Windows
product that uses DocBook. Otherwise wait, ask questions here or in
other forums, or pitch in with the effort. The new tools will be used
in a very different way, but with more functionality... I personally
would like to start documenting those even though they are not
available yet.


> Let's start with replacing that cop-out in the so-called "Practical
> Introduction".  

Please stop referring to people's work with words that are meant only
to insult. I'm sure plenty of people could refer to your essays with
venom, they perhaps choose not to as they know your heart is in the
right place for writing them in the first place.

> What I want to see is a practical guide that is truly a practical guide --
> something like what I wrote for SGML-tools, but covering DocBook.

A technical author tends to want other's writing to be exactly as they
write - its one reason why people have a hard time writing a book
together. There isn't much to be done about that except write it
yourself. I personally think that the Practical Guide is a great start
- it is still in progress mind you, but it tells you the *exact*
things you mentioned (besides the installation which I dealt with
above)... I am staring at it... it tells you how to use the scripts,
how to create a document, etc.

Also keep in mind that DocBook Tools is not the only set of tools
available for using DocBook. There are *many* tools available for the
XML side of it... and I guarantee you you would come in with both guns
blazing if you tried those tools... not one word of
documentation. Why? They released early at the expense of good
documentation/translation.


> -- basically so I could pull Red Hat's nuts out of the fire after
> Bob Young asked me nicely to fix the godawful mess their old
> TeX-centric production process had degenerated into.  

What a gentleman like approach to telling me you worked on it.


Dave
-- 


David Mason
Red Hat Advanced Development Labs
dcm@redhat.com (919)547-0012 x248

Re: I'm trying to set up docbook-tools...

[Norman Walsh]

/ "Eric S. Raymond" <esr@thyrsus.com> was heard to say:
| I don't think anybody doubts that it was your intention to be clear.
| Your execution, however, completely failed in that respect.  The

Completely? Thanks.

| failure seems to me to be an indicator of a wider problem in the
| technical culture surrounding SGML, one I've bitched about before.

Yes, you have.

| Two years ago, I complained vociferously on the DocBook list that the
| SGML culture had a pathological case of self-absorption and seemed to

And with such vitriol and ranting that several respectable members of
the list asked you to please be polite or go away.

| unable to explain.  For bringing this unwelcome news, I was flamed and
| shunned.

Is that how you saw it. How, um, symmetrical.

| Can this be fixed?  I don't know.  The problem isn't any lack of
| intelligence or good intentions on the part of the DocBook group.  
| There's something fundamentally disconnected and broken in the
| attitude department, though -- an inability to see what the SGML
| world looks like from the point of view of somebody who just
| wants to get some work done.

That's not really fair, IMHO. Two years ago, when you ranted on the
DocBook list, there *were no tool sets that we could point to*. SGML
was a build-it-yourself world.

Now, as I've said, thanks to the tremdous efforts of lots and lots of
people, we *do have tool sets* that we can point to. They aren't perfect
yet, they don't install easily enough, and they don't satisfy everyone.
But we've come a long way and the efforts continue.

Not only do I think the problem can be fixed, I'm confident it will
be.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | The worst enemy of life, freedom and
http://nwalsh.com/            | the common decencies is total anarchy;
                              | their second worst enemy is total
                              | efficiency.--Aldous Huxley

Re: I'm trying to set up docbook-tools...

[Sam Roberts]

> > Despite all of the above, I have become reasonably proficient in using the
> > Docbook-Tools set and in Docbook itself.  But the tool kits still do not work
> > well enough for me to actually use them to produce real documentation. I am

They work well enough for us, so it is possible! See:

http://www.cogent.ca/Download/Documents.htm

The slang programmin language and cascade db docs are all from docbook. I wrote
my own scripts and makefiles to drive jade and [pdf]jadetex based on taking
a peek into the db2* scripts. It took a while, but it was no harder than
dealing with LaTeX, back when I used it in university.

Sgml isn't really a documentation language, it's a markup language, the markup
is then used to generate documentation, by some people, and with some tools.
For those of us who actually want documentation, the vagueness of all the sgml
docs when it comes to actually generating documentation is frustrating, but
sgml+docbook+jade+jadetex are still the best tools around.

> additionally i would suggest you subcribe to 
> 
> docbook-apps@lists.oasis-open.org, 

I second this.

docbook-apps is very active, and very helpful, if you're trying to use docbook
you should be on this list.

Sam

Re: Crash-course to DocBook

[Mark Johnson]

On Wed, 9 Aug 2000, Eric Bischoff wrote:

> Hi folks,
> 
> I'm happy to announce the birth of the "Crash-Course to
> DocBook".
> 
> You can find it on http://public.lst.de/~eric
> 
> It is released under FDL. Feel free to make it evolve.
>
Great idea! So much to tell, so little time...

On the PSGML page
( http://www.lst.de/~eric/crash-course/HTML/emacs-psgml-mode-tips.html ) you
say 

"PSGML mode is for SGML DocBook. It does not support XML DocBook."

which isn't true. PSGML has an XML mode that works fine with DocBook. A
group of use it daily (w/ Emacs 20.7) with no problems at all. 

You only need to put something like this into your .emacs:

;; load xml-mode 
 (autoload 'xml-mode "psgml" "Major mode to edit XML files." t)
       (setq auto-mode-alist
       (append (list (cons "\\.xml\\'" 'xml-mode))
       auto-mode-alist)
 )

Along with the path to the declaration.

I started a page of Emacs/PSGML Tips, based on stuff I read in Bob Snee's
SGML CD chapter. It's here:

	http://ed.phy.duke.edu/xml/psgml-tips/index.html 

I'd be happy to contribute to your tutorial, as I already spend too much
time showing folks how to do this or that. 

Another idea would be to start a database of docbook-user FAQs, we already
have a number of Zope installations that would make it very easy to do
something like this. It would automatically be searchable, and indexed,
etc.


Does that sound useful to anyone?

Mark

> It has been made out of three documents:
> - David Rugge's "Crash-Course to DocBook" for KDE
> - Mark Galassi's "Introduction to DocBook"
> - My own Lunch&Learn presentation "Using DocBook at Caldera"
> with a lot of glue and reorganization (and a small waste
> basket - everything that was KDE-specific has been removed).
> 
> The purpose is to have a "tutorial" for newcomers to
> DocBook, to be used in conjunction with Norm's book which I
> see more as a reference manual.
> 
> I hope this helps.
> 
>