Return-Path: <j3322ptm@yahoo.de>
Mailing-List: contact forrest-dev-help@xml.apache.org; run by ezmlm
Delivered-To: mailing list forrest-dev@xml.apache.org
Received: (qmail 99721 invoked from network); 29 May 2002 19:53:55 -0000
Received: from mail.datazug.ch (212.4.65.100)
  by daedalus.apache.org with SMTP; 29 May 2002 19:53:55 -0000
Received: from yahoo.de [212.4.77.228] by mail.datazug.ch with ESMTP
  (SMTPD32-7.10) id A1DB66C8026A; Wed, 29 May 2002 21:54:03 +0200
Message-ID: <3CF53216.7020208@yahoo.de>
Date: Wed, 29 May 2002 21:55:02 +0200
From: "J.Pietschmann" <j3322ptm@yahoo.de>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.0rc1) Gecko/20020417
X-Accept-Language: en-us, en
MIME-Version: 1.0
To: forrest-dev@xml.apache.org
Subject: Referring to ressources and Topic Maps
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

Hello forresters,

while writing some FAQ stuff I got a few questions about the DTDs and
style sheets.

The first problem is that I refer to various ressources, both
documents within the project and external URLs. I'm somewhat uneasy to
hardcode the URL in a <jump href="..."> everywhere for two reasons:

1. Internal projects: A href refers to a .html document, which is not
    appropriate if a PDF booklet is built from the xdocs. The link
    should refer to an abstract ressource name which is mapped onto a
    HTTP URL during the final HTML generation. In a booklet it
    could/should be transformed into an internal PDF link.

2. External URLs: These have often a tendency to change, even if
    slightly only. Going through all documents and replace the URLs
    after a spec is updated to a new version or a FAQ has been moved
    seems to be a drudgery that ought to be avoided.

Interestingly, some (many?) projects already have a ressources.xml
document, which lists URLs and some descriptions, possibly structured
in sections.

My idea was to formalize the ressources.xml into providing a mapping
from abstract ressource names to URLs, both for internal and external
ressources. This sounds like a topic map. However, a formal topic map
lacks a section structure and inline description.

  A synthesis could be to use a topic map which defines abstract names
and points into the xdoc sources for internal ressources and defines
the hrefs for external URLs. The point is that the topic map is to be
used for resolving the abstract names into <a href=".."> links during
HTML generation. The ressources.xml also pulls in URLs from the topic
map as all other documents.

(topic maps: http://www.topicmaps.org/xtm/index.html)

Some sample code how this could look like:

XML
  ...look into the <topic name="XSL FAQ">XSL FAQ</topic> ...
  ...check <topic name="limitations">FOP limitations</topic> for...
  ...the problem is that there are <topic
    name="inline-background-not-implemented">limitations</topic> for
     specifying ...

Topic map:
  <topicMap>
    <topic id="XSL FAQ">
      <occurence>
        <resourceRef xlink:href="http://www.dpawson.co.uk/xsl"/>
      </occurence>
    </topic>
    <topic id="limitations">
      <instanceOf><topicRef xlink:href="#projectRessource"/></instanceOf>
      <occurence>
        <resourceRef xlink:href="limitations.xml"/>
      </occurence>
    </topic>
    <topic id="inline-background-not-implemented">
      <instanceOf><topicRef xlink:href="#projectRessource"/></instanceOf>
      <occurence>
        <resourceRef xlink:href="limitations.xml#inline-background-not-implemented"/>
      </occurence>
    </topic>
    <topic id="projectRessource">
    </topic>
  </topicMap>

XSL

  <xsl:variable name="topic-map" select="document('topicmap.xml')/topicMap"/>

  <xsl:template match="topic">
    <xsl:variable name="occurence"
      select="$topic-map/topic[id=current()/@name]/occurence"/>
    <xsl:choose>
      <xsl:when test="count($occurence)=1">
        <xsl:choose>
          <xsl:when test="$occurence/../instanceOf[
                  topicRef/@xlink:href='#projectRessource']">
           <!-- project internal ressource -->
           <xsl:variable name="url"
            select="$occurence/ressourceRef/@xlink:href"/>
           <xsl:variable name="base"
            select="substring-before($url,'#')"/>
           <xsl:variable name="fragment"
            select="substring-after($url,'#')"/>
           <xsl:choose>
             <!-- transform extension -->
             <xsl:when
               test="substring($base,string-length($base) - 4)='.xml'">
              <xsl:choose>
                <xsl:when test="$fragment">
                  <a href="{substring($base,1,string-length($base)
                             - 4)}html#{$fragment}">
                    <xsl:apply-templates/>
                  </a>
                </xsl:when>
                <xsl:otherwise>
                  <a href="{substring($base,1,string-length($base)
                              - 4)}html">
                    <xsl:apply-templates/>
                  </a>
                </xsl:otherwise>
              </xsl:choose>
             </xsl:when>
             <xsl:otherwise>
              <xsl:message terminate="yes">Unexpected
               URL extension for internal ressource</xsl:message>
             </xsl:otherwise>
           </xsl:choose>
          </xsl:when>
          <xsl:otherwise>
           <!-- external ressource -->
           <a href="$occurence/ressourceRef/@xlink:href">
             <xsl:apply-templates/>
           </a>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:when>
      <xsl:otherwise>
       <xsl:message terminate="yes">No or ambiguous
        ressource locations</xsl:message>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

(Beware: untested)
Refinement: If the content of the topic element is empty, a title
text could be pulled in from the topic map.

Comments?

If something could be agreed on, I'd try implement it in the FOP
documentation.

J.Pietschmann