Use first heading as page name in links.

I just read "Don't make me think!" by Steve Krug, about
web usability, and I liked its common sense a lot.
One message was that every page should have a title,
and that it should literally match what you click to
get there.

This patch tries to automate that for Dokuwiki. In wiki
page links, it will fetch the first heading (the title)
and use it as the name in links (unless an explicit other
name is defined in the link). The same is done for
the breadcrumbs (at least the default ones). I believe
all this should make navigation  easier. The feature
is enabled/disabled with a configuration variable
called $conf['useheading'].

TO DO: more testing. Check whether the first heading is
at a unique high level (probably easier when true parsing
will be used.) Check hierarchical breadcrumbs. Perhaps
omit the title from the automatic table of contents,
and perhaps adapt the toc intentation of the lower
level headings.

darcs-hash:20050326130557-45605-bf7fdaf29e61924f2631af1bb95177ee0415c24d.gz

conf/dokuwiki.php

@@ -36,6 +36,7 @@ $conf['maxtoclevel'] = 3;                 //Up to which level include into AutoT
 $conf['maxseclevel'] = 3;                 //Up to which level create editable sections (max. 5)
 $conf['camelcase']   = 0;                 //Use CamelCase for linking? (I don't like it) 0|1
 $conf['deaccent']    = 1;                 //convert accented chars to unaccented ones in pagenames?
+$conf['useheading']  = 0;                 //use the first heading in a page as its name
 
 /* Antispam Features */
 

inc/common.php

@@ -119,18 +119,29 @@ function breadcrumbs(){
     $crumbs = array();
   }
   //we only save on show and existing wiki documents
-  if($ACT != 'show' || !@file_exists(wikiFN($ID))){
+  $file = wikiFN($ID);
+  if($ACT != 'show' || !@file_exists($file)){
     $_SESSION[$conf['title']]['bc'] = $crumbs;
     return $crumbs;
   }
+
+  // page names
+  $name = noNS($ID);
+  if ($conf['useheading']) {
+    // get page title
+    $title = getFirstHeading(io_readFile($file));
+    if ($title) {
+      $name = $title;
+    }
+  }
+
   //remove ID from array
-  $pos = array_search($ID,$crumbs);
-  if($pos !== false && $pos !== null){
-    array_splice($crumbs,$pos,1);
+  if (isset($crumbs[$ID])) {
+    unset($crumbs[$ID]);
   }
 
   //add to array
-  $crumbs[] =$ID;
+  $crumbs[$ID] = $name;
   //reduce size
   while(count($crumbs) > $conf['breadcrumbs']){
     array_shift($crumbs);

inc/format.php

@@ -89,17 +89,19 @@ function format_link_wiki($link){
   list($link['url'],$hash) = split('#',$link['url'],2);
   $hash = cleanID($hash);
 
-  //use link without namespace as name
-  if(empty($link['name'])) $link['name'] = preg_replace('/.*:/','',$link['url']);
-  $link['name'] = htmlspecialchars($link['name']);
-
   $link['url'] = cleanID($link['url']);
   $link['title'] = $link['url'];
 
-  //set class depending on existance
+  //set class and name depending on file existence and content
   $file = wikiFN($link['url']);
   if(@file_exists($file)){
     $link['class']="wikilink1";
+    if ($conf['useheading'] && empty($link['name'])) {
+      $title = getFirstHeading(io_readFile($file));
+      if ($title){
+	$link['name'] = $title;
+      }
+    }
   }else{
     if($conf['autoplural']){
       //try plural/nonplural
@@ -122,6 +124,10 @@ function format_link_wiki($link){
     }
   }
 
+  //if no name yet, use link without namespace
+  if(empty($link['name'])) $link['name'] = preg_replace('/.*:/','',$link['url']);
+  $link['name'] = htmlspecialchars($link['name']);
+
   //construct the full link
   $link['url'] = wl($link['url']);
 

inc/parser.php

@@ -838,4 +838,21 @@ function mediaformat($text){
 	return format_link_build($link);
 }
 
+/**
+ * Get first heading, to be used as a page title
+ *
+ * @author Jan Decaluwe <jan@jandecaluwe.com>
+ */
+function getFirstHeading($text){
+  $title = '';
+  $lines = split("\n",$text);
+  foreach($lines as $line){
+    if(preg_match('/^\s*==+(.+?)==+\s*$/',$line,$matches)){
+      $title = $matches[1];
+      break;  
+    }
+  }
+  return $title;
+}
+
 ?>

inc/template.php

@@ -273,9 +273,9 @@ function tpl_breadcrumbs(){
 
   $crumbs = breadcrumbs(); //setup crumb trace
   print $lang['breadcrumb'].':';
-  foreach ($crumbs as $crumb){
+  foreach ($crumbs as $id => $name){
     print ' » ';
-    tpl_link(wl($crumb),noNS($crumb),'class="breadcrumbs" title="'.$crumb.'"');
+    tpl_link(wl($id),$name,'class="breadcrumbs" title="'.$id.'"');
   }
 }