DocBook

(I posted this to the docbook mailing list, and Jirka Kosek suggested I
submit an RFE.)

The documentation for DB 5 (I believe this goes back to 4.4) appears to be
inconsistent, or at least misleading, wrt the appearance of indexterms
inside footnotes.

According to the DocBook 5 spec, indexterms can appear in footnotes (See
http://www.docbook.org/tdg5/en/html/indexterm.singular.html "indexterm
(db.indexterm.singular)"; I'm not worried about the startofrange/endofrange
kind of indexterm.) Specifically, the indexterm spec says that footnote is
one of the
possible parents of indexterm, and the footnote page confirms that
indexterm can be a child of footnote.

However, the spec also says (over in the page about footnotes,
http://www.docbook.org/tdg5/en/html/footnote.html, under "Additional
constraints") that "indexterm must not occur in the descendants of
footnote." Taking these two things together, I would understand the
intention to be that the structure
<footnote>
<para>
...<indexterm.../>
</para>
</footnote>
is forbidden. But that raises the question of where in footnotes
indexterms *can* appear; between the footnote and the para inside the
footnote?

I've asked this question (where can indexterms appear in footnotes) on
several forums. The only response I've gotten is that the "Additional
constraints" forbid the appearance of indexterms *anywhere* inside
footnotes. Indeed, XMLmind gives exactly this result: no matter where you
try to put an indexterm inside a footnote, you get an error (from their
Schematron checker, not from their RelaxNG grammar). But if indexterms
*are* forbidden anywhere inside footnotes, then why are indexterms listed
in the spec as a possible child of footnote (and footnotes as possible
parents of indexterms)? Why not just not list them as possible
parent/child?

My own interpretation is that indexterms are supposed to be allowed as
immediate children of footnotes, i.e. in a sister relationship with para,
but not inside the para(s). But I have no idea why there should be such a
restriction; what's wrong with having an indexterm inside a para inside a
footnote?

Summary: I believe that either indexterms should be allowed anywhere inside
footnotes (including in the descendants of footnotes), or else they should
be allowed nowhere under footnotes. If this is done, then the "Additional
constraint" will be unnecessary for indexterms.

(I am agnostic about whether the "Additional constraints" should be used
for the other elements that are currently disallowed under the descendants
of footnotes, or whether those should be replaced by simply disallowing
them under footnotes. Perhaps there is some reason for allowing them but
having the constraints, although the constraints are then subject to the
same potential misinterpretation. The reason for these constraints should
at least be explained and/or exemplified.)