Re: Requiring use of DocBook; LinuxDoc

[Gary Preckshot <garrell@inreach.com>]

Mark Komarinski wrote:
> 
> Gary Preckshot wrote:
> >
> > Jeff Waugh wrote:
> >
> > > * Not removing from DocBook, removing from example. Read into it a little
> > >   harder, please, without issuing a flame.
> >
> > I think you have a low ignition temperature.
> 
> Tossing gasoline followed by a lit match doesn't help either.
> 
> >
> > There seem to be a lot of people who'd rather use LinuxDoc.
> > Their posts seem to describe DocBook as anything but
> > "straightforward." Certainly, there's a subset of folks that
> > think DocBook is too big for their computers.
> 
> So far I count one person.  Two if you include yourself. That's not "a lot".

Strangely enough, Norman Walsh thought there were enough
people confused by DocBook that he produced a "simplified
DocBook." My comment implied that he was probably the only
one who could do it. If you think that's a flame, here's a
real flame: you think a lot of yourself don't you? See the
difference?

See http://www.nwalsh.com/docbook/simple/index.html for
Norman Walsh's simplified DocBook. It's probably relevant to
this discussion and to your tutorial.

> 
> > >
> > > * Do you think DB:TDG is bad resource?
> >
> > No, I think it's a reference, hardly a tutorial.
> 
> The LAG/H-H is the tutorial, and references DB:TDG.

Tell me something I don't know.

> 
> > >
> > > * As a documentation writer, you need only care about your DocBook. DSSSL is
> >
> > I need feedback. The ultimate objective is putting out
> > documentation that people can read, is it not? If I don't
> > know what effect the tags will have on the final product,
> > I'm running open-loop.
> 
> You shouldn't care what the output look like, as long as it's legible.  That's
> part of the glory of SGML over .doc or .rtf.  There was a usability
> study a few years ago between TeX authors and MSWord writers. The MSWord
> people took much longer (maybe twice as long) because they spent that extra
> time arranging items on the page, while the TeX folk didn't have to worry
> about it.

That's a lot different than knowing what it will look like.
I still need to know something about the effect. If DocBook
is more efficient at achieving the effect that I want, I'm
all for it. However, I still need to know that what I'm
putting down will be some reasonable relation to what else I
write. With DocBook, the formatting software fulfills the
function of a very efficient secretary. I've always wanted
to see what was going out before approving final release.

SGML has another danger that has dogged authors since time
immemorial. That is, being quoted out of context. With the
markup, interested parties can pull anything they want out
of your work, and you may have no recourse.

> 
> When I send a document to the LDP, I don't know exactly what it will look like
> when it's done, but I have a good idea.  And that's good enough for me.
> 

Fine. I'm still wrestling with getting that understanding.

Gary


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org