forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <>
Subject Re: DTD questions
Date Fri, 31 May 2002 09:02:02 GMT
J.Pietschmann wrote:
> 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 sure hope not - frames yuk. However, the DTD needs
to be general enough to be used in various situations.

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

I have been confused over these for ages. Steven, and then i,
tried to demonstrate the differences in the Forrest demo
document-v11.html ... Rather than try to express the differences
here, please look at the demo document.

Your ideas about their use are somewhat different,
but not orthogonal.

I will edit that document over the weekend to bring in
some of the clarifications that you have provided.

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

The anchor attribute for jump was in the document-v10 DTD.
It was somehow missed when the document-v11 started to happen.

This makes me concerned that other things are also inconsistent
in the DTD. In the Cocoon project i saw some inconsistencies
with DTDs too. It seems that the faq-v10.dtd took a backwards
step between C1=>C2 ... perhaps an old copy was used.

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

I would prefer to see proper XML validation via RELAX NG
happening. Then the stylesheets can rely on the XML stream
and be less verbose.

Of course, your solution addresses the current need, so is good.

>      <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 anchor must
>             be specified</xsl:message>
>          </xsl:otherwise>
>        <xsl:choose>
>       </xsl:template>
>    So, how should the issue with @anchor be handled?

First of all get it back into the DTD and jump/anchor handling
back into all of the stylesheets. We should perhaps implement
your abovementioned validation routine via stylesheet until we
get thorough XML validation happening.

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

I too am not happy with generated anchors - they are always
changing, so you cannot link from another document to a specific
FAQ. I was pleased to see your recent Topic Map thread, and will
try to comment there.

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

You provide very sound reasons. There was some discussion
on forrest-dev around February - i cannot find it quickly.

> - The FAQ DTD has a part element for structuring the FAQ. This sounds
>    rather artificial. What's wrong with faqsection?

Mmmm .. Not sure happened with that. The Cocoon-1/faq.dtd
had faqsection. Then Cocoon-2/faq.dtd dropped it (perhaps
accidently). Then Forrest/faq.dtd brings it back differently.

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

Is the <connect> element still relevant? There is still
confusion over the purpose of link|jump|connect and differences
between DTD v10 and v11 in this area. Does anyone know what
the <connect> is/was used for? Is it safe to drop it in DTD v11?

I did a UNIX find/grep through Cocoon and Forrest xdocs and it
is not used anywhere. (There was one unlinked C2 doc at
xdocs/css/testdoc.xml that looks useful. It too has a message
"FIXME: what is this 'connect' thing for".)

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

Great idea. That would help with stylesheet maintenance.

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

OK. I will add that in over the weekend.

If you have patches for anything else then please send them
via forrest-dev list.

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

I am a bit lost on that - perhaps someone else can answer.

View raw message