Version 4 of Wikit Reference Formatting

Updated 2003-09-03 11:55:56

This page describes modifications to format.tcl to allow labels to be specified in references to internal and external pages.

The new formatting rules for references are:

1. You can refer to another page by putting its name in square brackets like this: [TITLE]. To specify a label use: [TITLE|LABEL].
2. URLs will automatically be recognized and converted into a hyperlink: http://your.site/contents.html . To specify a label use http://your.site/contents.html |LABEL (without the space before the |).

The patch is against Wikit version: 2003/08/20 19:06:22 68261-69214

Warning: I haven't programmed regularly for the last 5 years, still don't fully understand the data structures format.tcl uses, and haven't yet adequately tested the patch. Test and use at your own peril. :-)

03sep03 jcw - I've added some comments at the end.

Patch (format.tcl)

---

 417a418,439
 >     proc TextToTitle {text} {
 >         set result $text
 >         set index [string first "|" $text]
 >         
 >         if {$index > 0} {
 >             set result [string range $text 0 [expr $index - 1]]
 >         }
 >         return $result
 >     }
 > 
 > 
 >     proc TextToLabel {text} {
 >         set result $text
 >         set index [string first "|" $text]
 >         
 >         if {$index > 0} {
 >             set result [string range $text [expr $index + 1] [expr [string length $text] - 1]]
 >         }
 >         return $result
 >     }
 > 
 >     
 469a492,493
 >             set title [TextToTitle $text]
 >             set label [TextToLabel $text]
 478c502
 <                     lappend urls g $n $text
 ---
 >                     lappend urls g $n $title
 483c507
 <                         lappend result $text $tags
 ---
 >                         lappend result $label $tags
 487c511
 <                     set info [lindex [$ip $text] 2]
 ---
 >                     set info [lindex [$ip $title] 2]
 490c514
 <                         lappend result \[ $tags $text $base \] $tags
 ---
 >                         lappend result \[ $tags $label $base \] $tags
 494c518
 <                     lappend result $text $tags
 ---
 >                     lappend result $label $tags
 498c522
 <                     lappend urls u $n $text
 ---
 >                     lappend urls u $n $title
 507c531
 <                     lappend result $text $tags
 ---
 >                     lappend result $label $tags
 635a660,661
 >             set title [TextToTitle $text]
 >             set label [TextToLabel $text]
 652c678
 <                     set info [$ip $text]
 ---
 >                     set info [$ip $title]
 666c692
 <                                 [quote $text] $html_frag(_a)
 ---
 >                                 [quote $label] $html_frag(_a)
 673c699
 <                             [quote $text] \
 ---
 >                             [quote $label] \
 678,679c704,705
 <                             $html_frag(a_) $text $html_frag(tc) \
 <                             [quote $text] $html_frag(_a)
 ---
 >                             $html_frag(a_) $title $html_frag(tc) \
 >                             [quote $label] $html_frag(_a)
 773c799,801
 <             set info [$ip $text]
 ---
 >             set title [TextToTitle $text]
 >             set label [TextToLabel $text]
 >             set info [$ip $title]

---

03sep03 jcw - I have two comments on this. Main one is that of the three ways in which linking is supported in this wiki, I suggest only adding the "| text" label trick on urls of the form:

  ... [http://blah | blurb] ...

The reason for this is that right now, one always knows what clicking on a link does:

1. if it looks like an url, that's where it goes
2. if it has no brackets, hyperlinks are always within this wiki
3. if it shows in brackets, then you cannot assume the link is local

The label rules you're introducing break this model. I'd rather not introduce the ability to have a link show as a page title which turns out not to be one, nor for example to click on what looks like an url, but ends up being a completely different one. Hence my suggestion to only allow labeling bracketed external urls.

My other comment is about the use of pipe as separator. Souns like a good choice, but to break fewer cases of current url's having "|" in them, I suggest splitting on "<space> | <space>", and on taking the very last such occurrence. Code to do this could be:

    # Split "url | tag" into two parts, if they exist.
    # Based on code written by AKG, see http://mini.net/tcl/9733

    proc SplitTitle {text} {
      if {[regexp {(.*)\s\|\s(.*)} $text - a b]} {
        set a [string trim a]
        set b [string trim b]
        if {$a ne "" && $b ne ""} {
          return [list $a $b]
        }
      }
      return [list $text $text]
    }

If someone wants to pursue this and figure out how to make the changes in format.tcl, please do... I'll be happy to integrate such a patch.