doc: Fix DocBook XML validity

doc: Fix DocBook XML validity

The main problem is that DocBook SGML allows indexterm elements just
about everywhere, but DocBook XML is stricter.  For example, this common
pattern

    <varlistentry>
     <indexterm>...</indexterm>
     <term>...</term>
     ...
    </varlistentry>

needs to be changed to something like

    <varlistentry>
     <term>...<indexterm>...</indexterm></term>
     ...
    </varlistentry>

See also bb4eefe7bf518e42c73797ea37b033a5d8a8e70a.

There is currently nothing in the build system that enforces that things
stay valid, because that requires additional tools and will receive
separate consideration.