Hi forresters,
I got some questions regarding the current DTDs:
- The document-v11 has link, jump and fork for expressing links.
The difference between the link and the jump element makes
only sense if frames are used. Do you expect the xdocs will be ever
used in a frames environment?
I believe the intention was:
link: project internal
jump: other apache projects
fork: non-apache ressources
I get the impression this has been muddled over time.
Clarifications?
- The stylesheet document2html has the following template:
<xsl:template match="jump">
<a href="{@href}#{@anchor}">
<xsl:apply-templates/>
</a>
</xsl:template>
Unfortunately, there is no @anchor attribute defined for jump in the
DTD. This makes validation a bit of a farce. Moreover, if no anchor
is specified in the source, an empty fragment specifier is generated.
I have the feeling this could be bad or even illegal, in any case it
looks as if someone has been sloppy. I'd suggest to add some checks:
<xsl:template match="jump">
<xsl:choose>
<xsl:when test="@anchor and not(contains(@href,'#'))">
<a href="{@href}#{@anchor}">
<xsl:apply-templates/>
</a>
</xsl:when>
<xsl:when test="@anchor and contains(@href,'#')">
<xsl:message terminate="yes">Cannot have a fragment
specifier in href if anchor is also given</xsl:message>
</xsl:when>
<xsl:when test="@href">
<a href="{@href}">
<xsl:apply-templates/>
</a>
</xsl:when>
<xsl:otherwise>
<xsl:message terminate="yes">Either href or ancor must
be specified</xsl:message>
</xsl:otherwise>
<xsl:choose>
</xsl:template>
So, how should the issue with @anchor be handled?
- In particular within a FAQ, how should a crosslink to another question be
handled? I used <jump anchor="svghangs"> and
<faq>
<anchor id="svghangs">
<question>...
Yes, the faq element can have an id, but the faq2document doesn't
handle it. There is already an anchor generated for links from the
question index, but it is generated from the position (bad for links
from the outside). Having two anchors doesn't hurt, but it's ugly.
And, of course, anchor is not allowed at the point shown by the DTD.
- Many elements have a title attribute, in particular sections,
including FAQ sections. This precludes using markup in titles, in
particular <code>, <em> and a yet to invent <keyword> element (for
indexing, an obviously interesting feature for FAQs). I'd suggest
deprecating the title attribute and introducing a title child
element. Whether DocBook is about to be reinvented or not is a
question I will not ask here.
- The FAQ DTD has a part element for structuring the FAQ. This sounds
rather artificial. What's wrong with faqsection?
<plug>
With namespaces and XSchema, FAQ specific elements could have their own
namespace. This allows faq:section elements.
</plug>
- There is still a template for the connect element.
<plug>
With XSchema, an XSLT based tool could perform some primitive checks
on the style sheet, it could warn if templates matching removed elements
are still there.
</plug>
- I'd also suggest to add a catch-all template to document2html in
order to avoid nasty surprises caused by unhandled elements:
<xsl:template match="*" priority="-2">
<xsl:if test="$check-all">
<xsl:message terminate="yes">Unexpected element</xsl:message>
</xsl:if>
<xsl:apply-templates/>
</xsl:template>
- The document DTD has some hooks for augmenting certain element
content. In the FAQ DTD the faq.mod is included after the
document.mod. This makes it impossible to use the hooks from within
the faq.mod. Is it planned to use the hooks for something, and if
so, what are the guidelines for this? Should there be a separate
faq.local.mod for local definitions, or should the faq.mod use for
this?
Comments?
J.Pietschmann
|