You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by "J.Pietschmann" <j3...@yahoo.de> on 2002/05/29 21:55:02 UTC
Referring to ressources and Topic Maps
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
Re: Referring to ressources and Topic Maps
Posted by Jeff Turner <je...@socialchange.net.au>.
On Wed, May 29, 2002 at 09:55:02PM +0200, J.Pietschmann wrote:
> Hello forresters,
...
> 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.
That would rock :)
Today, a mini-TM to map abstract resources to concrete locations..
Tomorrow, a TM per project, defining concepts in the documentation..
Then add some cross-project TMs defining global concepts..
.. and you could merge them all together, and create some impressive
'What's Related' links alongside every page.
--Jeff
> Comments?
>
> If something could be agreed on, I'd try implement it in the FOP
> documentation.
>
> J.Pietschmann
Re: Referring to ressources and Topic Maps
Posted by Robert Koberg <ro...@koberg.com>.
Sylvain Wallez wrote:
> Thinking out loud...
> It looks like the XML version of a Wiki text. Could it be possible
> that a set of xdocs and the associated topic map could be
> automatically generated from a Wiki base ?
>
I have an example that has served me well. It is pretty simple in
concept, but can let you manage many things in the transformation. Every
transformation is applied against a the site.xml document below. I use a
transformation to find the page nodeset and folder nodeset to get the
pertinent info to bring everything together. A few more things:
- a ContentHandler can figure out the first page of the site on entry by
going to the root folder and finding it's @index_page.
- the nav is setup in a way similar to what I posted a few days ago
where you recurse over the data to find paths to (virtual or not) pages.
- columns are left in to indicate a page layout. Empty columns can be
excluded.
- content can cascade down from the folder level to all pages in the folder
- convenience information is stored as attributes at the page and folder
level
- XSLs can be set at the folder level for a page to default to or can be
overriden at the page level
- I go back and forth on this, but, currently, I only generate something
that has the @gen=true and @status=certified
- article XML is placed in order in a column on the page (folder content
on top)
- article XML refences a content piece by filename and ID
[see content.xml below the following]
- content is ordered in content.xml as a mirror to folders in site.xml
to allow for some organization of the content for reresentation in a GUI
- more comments inline in the content.xml example below
* it might be too much of a pain to edit something like this without a
GUI... but it allows for easy GUI creation and is easy for a non
technical person to understand because it is like their filesystem.
======================================
site.xml
-----------------
<config id="www_1_0" title="liveSTORYBOARD" subtitle="website"
use_tool_style="1" nav_col="narrow_left">
<folder id="f1" index_page="pindex" display_label_link="true"
xsl_fileref="basic-3col.xsl" label="Home" name="en_us" pager="false"
snailtrail="true" gen="false" status="certified">
<col type="narrow_left"/>
<col type="wide_center"/>
<col type="narrow_right"/>
<page file_ext=".html" id="pindex" display_label_link="true"
xsl_fileref="default" label="Home" title="Welcome to liveSTORYBOARD"
toc="false" metadata="false" gen="false" status="editorial">
<col type="narrow_left"/>
<col type="wide_center">
<art_xml id="cindex.xml"/>
<art_xml id="c1772621156.xml"/>
<art_xml id="c41168064.xml"/>
</col>
<col type="narrow_right">
<art_xml id="c766821139.xml"/>
</col>
</page>
<folder id="f61944265" index_page="p423161157"
display_label_link="true" xsl_fileref="basic-2col.xsl" label="Products"
name="Products" pager="true" snailtrail="true" gen="false"
status="editorial">
<col type="narrow_left"/>
<col type="wide_center"/>
<col type="narrow_right">
<art_xml id="c1429697858.xml"/>
</col>
<page file_ext=".html" id="p423161157" display_label_link="true"
xsl_fileref="basic-3col.xsl" label="liveSTORYBOARD"
title="liveSTORYBOARD: An XML Content Management System" toc="false"
metadata="false" gen="false" status="editorial">
<col type="narrow_left"/>
<col type="wide_center">
<art_xml id="c205527826.xml"/>
<art_xml id="c41168064.xml"/>
<art_xml id="c1845444322.xml"/>
<art_xml id="c840847831.xml"/>
</col>
<col type="narrow_right"/>
</page>
<page file_ext=".html" id="p1998841236"
display_label_link="true" xsl_fileref="default" label="Feature List"
title="liveSTORYBOARD Feature List" toc="false" metadata="false"
gen="false" status="editorial">
<col type="narrow_left"/>
<col type="wide_center">
<art_xml id="c1407836277.xml"/>
</col>
<col type="narrow_right"/>
</page>
</folder>
</folder>
</config>
==============================================
content.xml
-----------------------
<config context="lsb" id="lsb_1_0">
<content id="f1">
<!-- content is checked out by user abc123 -->
<art_xml label="Related Links (home)" id="c766821139.xml"
lock="abc123" status="editorial"/>
<!-- content has been QA'd and is ready for live deployment -->
<art_xml label="Contact" id="c1366807863.xml" lock="certified"
status="certified"/>
<content id="f348554045">
<art_xml label="Site Administrators" id="c1627103600.xml"
lock="certified" status="certified"/>
<!-- content is currently in QA -->
<art_xml label="Editors" id="c1442852231.xml" lock="qa"
status="qa"/>
<art_xml label="Developers" id="c395560268.xml" lock="qa"
status="qa"/>
<!-- content is checked in and available for editing by people with
appropriate perms -->
<art_xml label="Designers" id="c282474740.xml" lock="false"
status="editorial"/>
<art_xml label="Related links (designers)"
id="c261372502.xml" lock="false" status="editorial"/>
</content>
<content id="f335818482">
<art_xml label="CM Resources from third parties"
id="c156555022.xml" lock="def123" status="editorial"/>
<art_xml label="CM Resources from liveSTORYBOARD"
id="c2052566953.xml" lock="def123" status="editorial"/>
</content>
</content>
</config>
Re: Referring to ressources and Topic Maps
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Diana Shannon wrote:
> One thing that concerns me about Wiki approaches is addressing i18n
> needs. If you could generate topic maps and xdocs from a Wiki base, as
> Sylvain suggests, on a periodic basis, it would help.
Don't make the second step before the first. My question
was: Is it a good idea to use abstract ressource identifiers
in the xdocs and a topic map to map them onto real URL, and
pull the real data, possibly mangled, into the presentation
form of the docs during the final XSL transformation?
J.Pietschmann
Re: Referring to ressources and Topic Maps
Posted by Diana Shannon <te...@mac.com>.
On Thursday, May 30, 2002, at 09:21 AM, Sylvain Wallez wrote:
>> 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 ...
>
>
> Thinking out loud...
> It looks like the XML version of a Wiki text. Could it be possible that
> a set of xdocs and the associated topic map could be automatically
> generated from a Wiki base ?
One thing that concerns me about Wiki approaches is addressing i18n
needs. If you could generate topic maps and xdocs from a Wiki base, as
Sylvain suggests, on a periodic basis, it would help.
Diana
Re: Referring to ressources and Topic Maps
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
J.Pietschmann wrote:
> 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 ...
Thinking out loud...
It looks like the XML version of a Wiki text. Could it be possible that
a set of xdocs and the associated topic map could be automatically
generated from a Wiki base ?
Sylvain
--
Sylvain Wallez
Anyware Technologies Apache Cocoon
http://www.anyware-tech.com mailto:sylvain@apache.org