forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "J.Pietschmann" <>
Subject DTD questions
Date Wed, 29 May 2002 19:56:01 GMT
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.

- The stylesheet document2html has the following template:
         <xsl:template match="jump">
                 <a href="{@href}#{@anchor}">
   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:when test="@anchor and not(contains(@href,'#'))">
                 <a href="{@href}#{@anchor}">
         <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 test="@href">
                 <a href="{@href}">
           <xsl:message terminate="yes">Either href or ancor must
            be specified</xsl:message>
   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
     <anchor id="svghangs">
   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?
  With namespaces and XSchema, FAQ specific elements could have their own
  namespace. This allows faq:section elements.

- There is still a template for the connect element.
  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.

- 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>

- 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



View raw message