forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nicola Ken Barozzi" <nicola...@apache.org>
Subject Re: DTD questions
Date Fri, 31 May 2002 12:27:23 GMT
From: "David Crossley" <crossley@indexgeo.com.au>

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

I disagree.
Frames make it easy to bring down the load on the server, by keeping common
components on the client.
In webapps, like the one we are doing at work for supply chain management
(www.intexti.it), it made the whole system faster and gives the user a much
better sensation.

Would you like it is your native program window needed repainting and
flickered at every action you do?

> However, the DTD needs
> to be general enough to be used in various situations.

+100

> >    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.
> http://www.krysalis.org/forrest/document-v11.html
>
> 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.

What about the discussion we had about having only *one* link tag?
http://nagoya.apache.org/eyebrowse/ReadMsg?listName=forrest-dev@xml.apache.o
rg&msgId=339180
http://nagoya.apache.org/eyebrowse/ReadMsg?listName=forrest-dev@xml.apache.o
rg&msgId=339459
http://nagoya.apache.org/eyebrowse/ReadMsg?listName=forrest-dev@xml.apache.o
rg&msgNo=252


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

Which brings us back to the naming of the dtds.
I *really* want to see the current DTD labelled as dev somehow, to prevent
this (at least in part).

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

http://www.xmlhack.com/read.php?item=1667

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

+1

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

And get the validation target in the Ant build working correctly <hint hint>

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

+1

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

I find it harder to write stylesheets for the docbook way.
I also don't see the need for using markup in titles; personally I've never
seen it used AFAIR.

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

1 link tag... pleeeease ;-)

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

wireless? ;-P

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

+10

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

+1
Have it output also any useful info to where the tag is, and what it is.

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

Ahem... anyone else? ;-)

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message