Re: Can we attack the 'not enough libraries' thing straight on?

> -----Original Message-----
> From: NAKAMURA, Hiroshi [mailto:[e-mail]]
> Sent: Monday, January 27, 2003 12:14 AM
> To: ruby-talk ML
> Subject: Re: Can we attack the 'not enough libraries' thing straight on?
> # Back to the style issue, we have a plan to introduce
> # wiki-like feature to RAA.  That's for linking projects
> # and for adding comments of users.

I've been working on a topic map wiki at www.ruby-doc.org/wiki/topicwiki.rb

It differs from the standard wiki in that it allows more specific annotations of links.
For example, a wiki page about Rimport could contain links to wiki pages about Rexml and Rdoc, with the linking markup indicating
that these are dependencies.  Other wiki page links might be annotated to indicate a reference to online documentation, or a
reference to where book information may be found.

In a conventional wiki, one would know that there was a link from one page to another, or a link to an external site, but would not
know what that link meant without some active interpretation of the English text.  The use of TM notation makes the wiki content
more accessible to machine parsing, with greater semantic information.

The use of TM notation means the wiki pages can be used to generate an XTM (XML Topic Map) feed:
www.ruby-doc.org/wiki/wtm/RDP.xtm

The XTM could be used to create a browsable index of ruby apps, libs, docs, dependencies, and so on.

As an aside, topic maps have been applied to CPAN
http://www.topicmapping.com/cpan/

The ruby-doc.org topic map is a bit less ambitious than the CPAN project.  I'm trying to balance ease of use with robust topic
mapping.  Users shouldn't have to think /too/ much about topic maps when adding a page or updating information.  Still, since
content can be annotated to indicate types of associations among wiki pages and external links, some thought must be used to ensure
reasonable consistency.

The biggest differences between a conventional wiki and a topic map wiki is that, whereas a conventional wiki tends to be itself the
repository of information, a topic map wiki serves mainly to define associations among topics, and to refer to external sources of
information.

So, the main goal of the ruby-doc.org topic map wiki is to map out Ruby documentation and resources, though defining associations
among Ruby apps and libs is easy enough.

It is more like a book index rather than a book.  There are already many Ruby resources, but a thorough index is lacking, and the
topic map wiki might help generate such an index.

Some good introduction to topic maps are:

XML.com: What Are Topic Maps?
http://www.xml.com/pub/a/2002/09/11/topicmaps.html

The TAO of Topic Maps
http://www.ontopia.net/topicmaps/materials/tao.html

The XTM 1.0 Spec
http://www.topicmaps.org/xtm/1.0/


Now, to my knowledge, there are no Ruby apps for browsing/processing XTM, but there is a good, free Java application (it runs
servlets via a local install of Tomcat) called The Omnigator:
http://www.ontopia.net/download/freedownload.html

and, for a truly whiz-bang interface, TMNav:
http://sourceforge.net/projects/tm4j

The latter uses  TouchGraph (http://www.touchgraph.com/) for navigation, to give you an idea of the interface.  Even with the
currently sparse XTM produced by the wiki it's fun to see the topics and associations so neatly displayed.  (Something like this
built using Ruby and Fox would be spiffy ...)

BTW, I've seen a Ruby app called "Topiq" that apparently deals with topic maps, but it doesn't appear to do anything with XTM, and
it's coupled to mod_ruby/eruby and SQLite, which has so far prevented me from doing more than perusing the source code.

The topic map wiki is still pretty alpha; the XTM produced is not normalized, default topics types and associations could be better,
and I'm still unsure of the TM markup notation.  Plus, defining good topics and associations is often non-trivial.

I've considered having the wiki interpret LTM (linear topic map notation) or AsTMa= (acronym for something or other), two
alternative TM notation formats, though their syntax may conflict with conventional wiki notation and ordinary usage of brackets and
parenthesis.  Still, there are advantages to using something already well-defined, and avoiding the creation of yet another markup
language.

A wiki makes a good starting point for a community-driven topic map because wiki pages map nicely to topic map topics, and the wiki
concept is easy enough for most people to get their heads around.  Ideally, adding TM features shouldn't break this ease of use and
familiar conceptual model.


James Britt