Re: Requiring use of DocBook; LinuxDoc

[Gary Preckshot <garrell@inreach.com>]

Jorge Godoy wrote:

> DocBook _IS_ the LDP recommended authoring SGML DTD. LinuxDoc is
> supported.
> 
> With all this discussion, you seem to ignore this fact.

All the discussion is what confuses me. There are a lot of
opinions floating around, and I'm not sure yet which count.
As a practical matter, the opinion of the person or persons
responsible for the LDP servers count 100%, because they
decide what's going on and in what form. So far, I haven't
identified these worthies, but Godoy, LeBlanc, Gjoen,
Ferguson, Aznar, and Drake seem to get the most deference.
Even among them, there seems to be disagreement.

> 
> Maybe you should be here when we've decided to change to DocBook. Now
> migration has already started. We must talk about how to improve
> DocBook authoring tools, documentation and things like that.

Even if I had been, I doubt my perceptions would be any
different. What you're missing is an official organ that
sets forth policy as finally decided. Even Usenet groups
have votes, and the tallies are announced, and the sys
admins go along (mostly) with the vote results. Here,
there's healthy discussion, which is good, but no
resolution, which is poor guidance. It's possible to have a
democracy, but still have a decision process.


> You can do it.

I did it, or did you ignore the markup I sent Mark?

> Install DocBook following the instructions from one of
> many websites available on internet, download the LDP stylesheet and
> convert the documents to whatever format you want to. You'll get
> basically the same looking. (I won't say exactly because you may have
> some other customizations of your own)

The basic problem is that there are 341 tags, and I only
know what about 50 of them do. In order to find out what
they really do, I have to do a test document, try them out,
and file the results. Some of them are "wrappers," used
mainly to identify tags within their embrace as fulfilling a
particular purpose. For instance, "Author" is a general
purpose wrapper that can be used in a variety of contexts
(nestings) and means something different depending on the
tags it's nested in.

> 
> Now, I ask: what's the advantage of worring about the structure if
> you're still worried with the appearance of your document?

They're both intimately connected, and the appearance
directly affects the impact. Or have you forgotten the
experience of generations of advertisers, or more
impolitely, propagandists?

> 
> I agree that you may want to know how it will look while on the
> Internet, but if it doesn't looks good, what are you going to do?
> Telling us to change our stylesheet (the right thing) or changing tags
> to make the document suitable to your aesthetics standards? Too many
> people chooses the wrong approach.

There are quite a number of things that have nothing to do
with stylesheets, just one of which is the use of
illustrations. Sometimes a figure can short-circuit mounds
of tedious explanation, and the presence or absence of a
figure has nothing to do with stylesheets. For want of a
better word, it's called "art," and DocBook doesn't
eradicate the need for the authoring art, otherwise you
would all be best-selling authors simply by virtue of using
DocBook.


> There's no safety on what's on the net. It can be used the way that
> people want. And be manipulated.

If you read the papers on SGML (see
http://www.oasis-open.org/cover/biblio.html for a selection)
the movement now is to separate the content provider (the
author) from the user (the publisher), so the publisher can
pick and choose the parts he/she wants to publish by
efficient computer-mediated selection. Yes, it's true that
by the use of older tools by an expert, if you're singled
out for attention, they can do the same thing to you now.
But experts are expensive, and the objectives of markups are
to make this process cost-effective.

Certainly, Mark makes some good points about publishers.
Right now, they're using MS-Word with publisher-defined
styles so that they can automatically import author content
into type setting programs (Quark is favored). (BTW, the
styles they favor make Word look suspiciously like a DocBook
markup). Markup languages will make this easier. Now,
instead of Word styles, author content can be tagged with
standardized tags from a known DTD, and publishers are no
longer dependent on a de facto standard such as MS-Word. But
this is a two-edged sword. What publishers can do for a
legitimate purpose, others can do for their own purposes.
Cost effectively.

> 
> Lets start doing something, not just talking. We need authors. We need
> a good tool. Our authors are trying to use DocBook and I --- and
> others --- am here to help them. Do you want to start using it? Ok. I
> can show you a starting point to DocBook
> (http://metalab.unc.edu/godoy/using-docbook) and give you all needed
> help that you couldn't get there. I'm changing this document for two
> purposes: including more basic information (maybe another document)
> and converting it to a chapter for the LAG (Mark, we chould change
> this name. It may be either the Linux Authoring Guide or the Linux
> Administrator's Guide. I suggest it be LDAG - Linux Documentation
> Authoring Guide).
> 
> Feedback is appreciated.

I am doing something. I'm writing a HOWTO entitled "Using
DocBook HOWTO". Here's the abstract 

"How to use DocBook"

"Shows the classes of DocBook SGML tags and what they do.
There are 341 tags in DocBook version 3.1, and many of them
are special purpose. This HOWTO approaches DocBook from
three directions: 1) from classes of tag, 2) from the
viewpoint of an author wishing to accomplish normal
authoring tasks, and 3) from the viewpoint of how to make
your document searchable for commonly expected data."

It's taking a while because

a) I wrote an awk parser to extract the complete content
model and tag list from the DocBook defining files.

b) I'm trying out each of the 341 tags with WordPerfect and
Jade to see what they do.

c) I'm writing the howto in DocBook, but stopping along the
way to write macros that make the job easier - such as
indexing. Right now, Norman Walsh has a perl script
("collateindex.pl") that requires you to generate the final
document with jade, run the indexer with the final form, and
regenerate the final form with index.
> 
> Thanks and sorry for my bad English.
> --
Da nada.

Gary


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