[docbook] Re: Ruminations on the future of DocBook

[Norman Walsh <ndw at nwalsh dot com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ Jeff Biss <jeff@marco-inc.com> was heard to say:
| I think that one of the major problems is that many of us have never
| been trained to properly use the DocBook. We figure it out as we go

I don't know if that's a problem or not, but it seems likely to remain
true.

| Another problem is that some people just don't understand proper
| document structure at all. I work as a tech writer and know many

Yes, that's a problem. Again, I'm not sure we can do anything about it
though.

| I agree that the number of tags could be reduced if done properly.
| Maybe this makes more sense if we rely on attributes more for
| providing information about the intended use. For example why have
| <note>, <important>, <caution>, <warning>, <tip>? Maybe a single tag
| could have been used with the differences being made with role:
|
| <attention role=caution> <para>Don't touch that!</para></attention>.
|
| The same could have been done with sections: <section>This is just a
| section</section> or
| <section role=numbered>This section gets a number.</section>
|
| I know that this is water under the bridge (especially considering the
| need to support existing documents), and my not simplify things, but
| with my limited experience with DTDs it seems that it may provide some
| way of simplifying the structure while allowing the complexity to be
| handled through the use of attributes.

I don't think that's really making things simpler. It's just moving
the complexity around. Consider the absurd reduction:

  <docbook name="book">
    <docbook name="title">The Book Title</docbook>
    <docbook name="chpater">
      ...

I don't think anyone would argue that that is really simpler. That
said, there may be cases where it does make sense to merge things.
We've already got a proposal to do away with a half dozen or more
ToC-related elements by replacing them with just two or three.

| Another problem is how we look at the world. For example there is the
| discussion about a <task> element. I usually use the word "process"
| (high level) rather than "task" in contradistinction to "procedure"
| (low level). This may lead to excessive elements or not realizing
| one's needs are already met. This may be a poor example because there
| is no <process> or <task> element at the moment but there may be very
| closely related elements that could have used the same term. This
| happens a lot in programming languages such as "method" versus
| "function". Perhaps a careful generalization could be done to
| accommodate similar functionality but different terms (jargon).

Finding the right balance of specificity and generality is a constant
challenge.

| I may be off-base but those are a few of my thoughts, for whatever
| they're worth.

Thanks!

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | Every vice you destroy has a
http://www.oasis-open.org/docbook/ | corresponding virtue, which
Chair, DocBook Technical Committee | perishes along with it.--Anatole
                                   | France
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE/EszWOyltUcwYWjsRAgVuAJsEAStTAucTKCYlP0euLPFj/0KTmACgmhyN
FcKP4bTbhsdRpd/HzlCg6zA=
=bFeY
-----END PGP SIGNATURE-----

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org