TclWiki Public API

BPT: I'll start things off by offering as one alternative the interface found in JC's format.tcl in his wikit.tkd distribution:

  proc TextToStream {text} -> stream   
  proc StreamToTk {stream infoProc} -> {{tagged-text} {urls}}   
  proc StreamToHTML {stream cgiPrefix infoProc} -> {{html} {urls}}
  proc StreamToRefs {stream infoProc} -> {pageNum ...}

• The "Text" format is a Wiki-like one you can edit with a text editor.
• The "Tk" format can insert styled text information in a text widget.
• The "HTML" format is the format generated for display by a browser.
• The "Refs" format is a list with details about embedded references.
• The "Stream" format is a Tcl list, it's only used as interim format.

infoProc appears to be a function that takes as input a link name and outputs a 3 element list: page_id, page_name, and page_modify_date

cgiPrefix is the URL prefix used to construct html links

Bryan I'm not sure I like that for a public API -- it requires two steps to format the text -- convert it to a stream, then convert the stream to tk, html or whatever.

I think we need something simpler for the public API. Here's an idea I'm pulling from thin air as I type...

    ::Wiki::format ?-format format? ?-link procname? $data

where format is one of "html" to start, with others as time permits (eg: "xml", "man", etc). -link lets you define a proc for link validation -- each link is passed to the proc and the proc either returns 1 for a known link, or 0 for an unknown link, so the render will know how to format it.

To render in a widget we'd use a different API:

    ::Wiki::render -window window ?-link procname? $data

It is assumed that window is a text widget, though it might be nice to support rendering in a canvas, too.

Now, internally, we could keep the original api to do all the dirty work, since it seems to work fairly well.

We also need an API to get at the links, so something like this might work:

    ::Wiki::links $data

which would return a list of links in some sort of easily parsable format. The list should distinguish the type of link (wiki, http) and whether it is brief (eg: [1]) or not.

BPT: Is it safe to assume the marking up of a link will be the same for all applications? Maybe the -link procname argument should be a function that actually generates the markup for a link?