[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:
| So I guess my question is why not just produce an <admonition> element
| that specifies a particular set of roles that are to be used (for
| example: graphics.attrib provides for align=left,right, or center)
| like admonition.attrib where role=note, caution, warning, important,
| tip, hint, etc.? This would help minimize the actual structure of the
| DTD or schema but require a writer to set the role as required. Maybe
| there is a programmitcal reason that this cannot be done.

Only one: you cannot (in DTDs anyway) limit the occurrence of elements
based on attribute values.

In the particular case of admonitions, consider that some
organizations have very carefully prescribed meanings for these
elements. A <warning> for example might be used to indicate a
situation where the possibility of bodily injury or death exists. In
such an application, you might want to enforce constraints on warnings
that you wouldn't want to enforce on notes or tips. If you distinguish
them based on attributes, you can't.

In general, the choice of an element or attribute is partly
subjective.

| As I stated, this seems moot because there are many documents that
| already rely on each individual element and a change like this would
| require a lot of work to retag to meet the new DTD/schema.
|
| There are reasons that elements were added to the DTD in the first
| place. I don't really see a reason for a <figure> and <simplefigure>
| because as I see it the structure could have allowed for zero or one
| title.

Yes, but if you did that you couldn't constrain where figures with (or
without) titles are allowed to occur (in DTDs anyway).

One of the decisions that we'll have to make if we choose to pursue a
RELAX NG design is how much of the new expressive power of RELAX NG we
want to use.

For example, as a stylesheet designer, the fact that some elements can
have titles inside or outside an *info wrapper is annoying because it
means that they can have *two* titles: one inside and one outside and
they don't have to be the same.

  <article>
    <title>Hello World</title>
    <articleinfo>
       <title>Goodbye World</title>
    </articleinfo>
    ...
  </article>

It's a fairly minor point, perhaps, but it bugs me. With RELAX NG we
can avoid that problem. Consider this grammar:

start = article

info.elements = date|releaseinfo # etc.

info.titlereq = element info { title, info.elements* }
info.titleforbidden = element info { info.elements* }

article = element article { ((title,info.titleforbidden?)|info.titlereq), para+ }

date = element date { text }
releaseinfo = element releaseinfo { text }
para = element para { text }
title = element title { text }

This says that an article begins with a title followed optionally by
an info element that forbids a title or it begins with an info element
that requires a title.

The following are legal:

<article>
  <title>Title directly</title>
  <para>...</para>
</article>

<article>
  <info>
    <title>Title in info</title>
  </info>
  <para>...</para>
</article>

<article>
  <title>Title directly, with additional info</title>
  <info>
    <date>2003-07-14</date>
  </info>
  <para>...</para>
</article>

And the following are not:

<article>
  <title>Multiple titles</title>
  <info>
    <title>Multiple titles</title>
  </info>
  <para>...</para>
</article>

<article>
  <!--no title-->
  <info>
    <date>2003-07-14</date>
  </info>
  <para>...</para>
</article>

The extent to which we allow ourselves to take advantage of these
features will have an impact on our designs.

                                        Be seeing you,
                                          norm

P.S. My plan for DTD compatibility is to do a little bit of stylesheet
transformation on the grammar to produce a relaxed grammar (uh, no pun
intended) that accepts a larger set of instances.

- -- 
Norman Walsh <ndw@nwalsh.com>      | Man is the only animal who causes
http://www.oasis-open.org/docbook/ | pain to others with no other
Chair, DocBook Technical Committee | object than wanting to do
                                   | so.--Schopenhauer
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE/EvO4OyltUcwYWjsRAt71AJ9hGqCaqe4y9dmTNTUahV+PFpC/MACePYLr
88J4PsOKipL27qjfGTIm2EI=
=U/Cf
-----END PGP SIGNATURE-----

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