RE: Appendix structure

[<Cavicchio_Rob@emc.com>]

maxwell [mailto:maxwell@umiacs.umd.edu] wrote:

> The only difference is the <remark> element.  Since <remark>s are more or
> less comments, it seems odd that they would make a difference in the
> validity of the document.  As I'm reading the schema (actually, the verbal
> description at http://www.docbook.org/tdg5/en/html/appendix.html), the
> <remark> element could be replaced by an <annotation>, <bridgehead>,
> <refhistory>, or any of a number of otherwise optional elements; or by a
> <section>, <simplesect>, or <sect1>.  Since I *don't* want any of the
> section-type elements (I really want the appendix to *just* contain a
> glossary), I'm instead using <remark>, which has no effect in my final
> (PDF) output.


I think that the intent is to treat <glossary> as a section-level element. Instead of:

<appendix version="5.0" xmlns="http://docbook.org/ns/docbook";>
    <title>Glossary of Linguistic Terms</title>
  <glossary>
    <title/>
    <glossentry xml:id="glInfix">
	...
    </glossentry>
  </glossary>
</appendix>

I would expect to see this: 

<glossary version="5.0" xmlns="http://docbook.org/ns/docbook";>
    <title>Glossary of Linguistic Terms</title>
    <glossentry xml:id="glInfix">
	...
    </glossentry>
</glossary>


A section is typically required to have some content before a child section occurs; that's why the <remark> element makes a difference. Of course in pure XML semantics, <remark> has no special meaning, so it is not surprising that its effect on the validity of the document is equivalent to having a <para> or some other element there. Not sure about RELAX NG schema, but in a W3C conforming schema it is pretty difficult to require something *other* than a <remark> yet still allow <remark> elements to be interspersed anywhere. So yeah, maybe ideally that's how it would be set up, but the fact that it's not is probably a limitation of the underlying technology.


*************************
Rob Cavicchio
Principal Technical Writer
EMC Captiva
EMC Corporation
10145 Pacific Heights Boulevard, 6th Floor
San Diego, CA 92121-4234

P: (858) 320-1208
F: (858) 320-1010
E: cavicchio_rob@emc.com

The opinions expressed here are my personal opinions. Content published here is not read or approved in advance by EMC and does not necessarily reflect the views and opinions of EMC.