[topicmapmail] variantName for resourceRef?

[Murray Altheim]

[a short tutorial follows...]

Thomas B. Passin wrote:
> [Ashish Mahabal]
> 
>>In some of my topic maps, I have rather long URLs as resourceRefs since I
>>pass CGI-BIN URLs using parameters as parameters to another fully
>>quoted CGI-BIN URL. These look too verbose when displayed completely.
>>An example can be seen at:
> 
> http://avyakta.caltech.edu:8090/omnigator/models/topic_complete.jsp?tm=galaxies_s.xtm&id=astrostat
> 
>>under occurrence instances. (This topic map allows one to explore
>>parameters in different astronomical catalogs, and through this
>>external reference also allows one to run some statistical functions on
>>choice columns of the astronomical catalogs.)
>>
>>Is there a way to shorten what is displayed by somehow using a fit-all
>>string like "Astrostats" instead of the whole URL?
>
> You could define entities in an internal DTD -
> 
> <!ENTITY astro
> "http://avyakta.caltech.edu:8090/omnigator/models/topic_complete.jsp">
> 
> ...
> <resourceRef xlink:href='&astro;?tm=galaxies_s.xtm&id=astrostat'/>
> 
> Remember, in the parsed xml document, the entities get replaced by their
> replacement text so you have not really changed anything about the URL.

Just to amplify Tom's reply, this is called the "internal subset" in SGML
and XML, and works on a per-document basis -- each document may optionally
have markup declarations (e.g., for elements, attributes and entities)
as part of its DOCTYPE declaration. If you want to generalize this, you
can put those markup declarations into a file, consider it as a DTD
"module" (this is considered part of the document's "prolog"), then
declare and instantiate the module. Parameter entities (e.g., "%foo;")
operate only within the prolog (the DTD; external and internal subsets),
whereas general entities (e.g., "&foo;") are used oth within the
prolog and within the document instance (the "document" to most people).

I'll show examples of both:

   1. single file usage using internal subset

   This example shows an internal subset that declares a general entity
   for a URL ("&myURL;") that can be reused. Note that any markup characters
   in your URLs (like the ampersand) will have to be escaped in their entity
   declarations.


     <?xml version="1.0"?>
     <!DOCTYPE topicMap PUBLIC "-//TopicMaps.Org//DTD XML Topic Map (XTM) V1.0//EN"
                               "xtm1.dtd" [
       <!-- begin internal subset -->
       <!ENTITY astro "http://avyakta.caltech.edu:8090/omnigator/models/topic_complete.jsp">
     ]>
     <topicMap xmlns="http://www.topicmaps.org/xtm/1.0/"
         xmlns:xlink="http://www.w3.org/1999/xlink">

       <topic id="astro34">
         <subjectIdentity>
            <resourceRef xlink:href="&astro;?tm=galaxies_s.xtm&amp;id=astrostat" />
         </subjectIdentity>
         ...
       </topic>
       ...
     </topicMap>


   2. repeated usage of above using an external "DTD module"

   This example shows an external entity that declares one or more
   general entities can be reused. In this way, if you make any
   changes to the module, all XTM files that use it will likewise
   be affected (e.g., if you have hundreds of XTM files using a
   set of declarations, you won't have to maintain each of their
   internal subsets; a change to the module is a change to all
   that reference entities declared by them).

   :::: contents of file "mydecls.mod" :::::::::::::::

     <!ENTITY astro "http://avyakta.caltech.edu:8090/omnigator/models/topic_complete.jsp">

   :::: contents of XTM file "astros.xtm" ::::::::::::

     <?xml version="1.0"?>
     <!DOCTYPE topicMap PUBLIC "-//TopicMaps.Org//DTD XML Topic Map (XTM) V1.0//EN"
                               "xtm1.dtd" [
       <!-- declare and instantiate the module -->
       <!ENTITY md SYSTEM "mydecls.mod">
       %md;
     ]>
     <topicMap xmlns="http://www.topicmaps.org/xtm/1.0/"
         xmlns:xlink="http://www.w3.org/1999/xlink">

       <topic id="astro34">
         <subjectIdentity>
            <resourceRef xlink:href="&astro;?tm=galaxies_s.xtm&amp;id=astrostat" />
         </subjectIdentity>
         ...
       </topic>
       ...
     </topicMap>

----

This kind of thing should work in ANY compliant XML processor,
i.e., this is all part of XML 1.0. And of course, it can be
used for all sorts of things. You could build an XTM document
from a bunch of reusable components, etc.

It's kinda late so I may have made a syntax error, but hopefully
you'll get the idea. (and my apologies if this info wasn't new to
you; it may be helpful to others.)

Murray

......................................................................
Murray Altheim                    http://kmi.open.ac.uk/people/murray/
Knowledge Media Institute
The Open University, Milton Keynes, Bucks, MK7 6AA, UK               .

                                                Moonlight slanting
                                                  through all the
                                                  bamboo forest...
                                                and nightingale song
                                                          -- Basho