Re: DOCBOOK: objection to docbook.dcl

[Norman Walsh <ndw@nwalsh.com>]

/ Adam Di Carlo <adam@onshore.com> was heard to say:
| accept.  The unnecessarily broad divergance of the shipped Docbook
| declaration puts a burden on document engineers using DocBook.

This whole problem is probably the result of documentation errors on
my part. The declaration shipped with DocBook is advisory and was
never intended to be normative: the documentation should state that
clearly.

There's no reason why you should use it if your software behaves
better with a different declaration.

| I am considering here only the DocBook SGML DTD, since I presume the
| Declaration is rather irrelevant for XML files, since all XML files
| have the same XML declaration applied to them.

Yep.

| I consider here 'docbook.dcl' as shipped with DocBook 4.1.
| 
| Major problems:
| 
|  OMITTAG is turned off (why?)

I can explain how this declaration came to have the restricted
features that it has. In the early days of DocBook, way before XML, SP
was not the only SGML application (it still isn't!).

Some of these applications had a hard-coded SGML declaration.

An early goal of DocBook was exchange of documents between partners
(that might be using different SGML tools).

The docbook.dcl file was designed with the goal that any document that
validated against it could be safely exchanged.

| Quoting <URL:http://xml.coverpages.org/wlw14.html>:
| 
|    Care should be used when changing these since creating a variant
|    syntax may make it difficult for some SGML systems to process
|    documents created with that syntax.  The best means of guaranteeing
|    portability between different SGML systems and applications is to
|    use the reference concrete syntax as much as possible.
| 
| One wonders why we need to diverge from the reference concrete syntax
| here.

The declaration shipped with Jade is not the reference concrete syntax.
(Although it's probably expressed in the RCS :-)

| * Document Character set it too restrictive
| 
| As an example, to workaround limitations in the support of KOI-R SDATA
| entities in Jade and OpenJade, KOI-R users have to use unicode
| entities.  With the docbook.dcl file, these entities are disallowed,
| although they are perfectly valid with the implied SP declaration.
| Example of being disallowed:
| 
|   jade:/usr/share/sgml/entities/sgml-iso-entities-8879.1986/ISOcyr1.ent:1:16:E: \
|   "1072" is not a character number in the document character set

Is this workaround being accomplished by editing the file that purports
to be ISOcyr1.ent from ISO 8879? Yuck! Please give those modified entity
sets a different public identifier and store them somewhere else

| * SUBDOC is turned off
| 
| Why is it necessary to disallow SUBDOC in DocBook SGML documents?
| Seems like some authors may wish to use this, even if its not fully
| supported by existing stylesheets.

Is this a stylesheet issue? If you use a subdoc, the stylesheet should
just see the merged document. (Subdoc is a parse-level feature.)

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | The perfect man has no method; or
http://www.oasis-open.org/docbook/ | rather the best of methods, which
Chair, DocBook Technical Committee | is the method of
                                   | no-method.--Shih-T'ao