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

5 files changed, 47 insertions, 12 deletions

diff --git a/conf/dokuwiki.php b/conf/dokuwiki.php
index bd9c4d4eb..444a18fdc 100644
--- a/conf/dokuwiki.php
+++ b/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 */
 
diff --git a/inc/common.php b/inc/common.php
index 72f6fde12..251fbcdc3 100644
--- a/inc/common.php
+++ b/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);
diff --git a/inc/format.php b/inc/format.php
index 8e953fade..fe4b6fa72 100644
--- a/inc/format.php
+++ b/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']);
 
diff --git a/inc/parser.php b/inc/parser.php
index 0fe04afba..e14c5bcd5 100644
--- a/inc/parser.php
+++ b/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;
+}
+
 ?>
diff --git a/inc/template.php b/inc/template.php
index 8f8c6f9dc..ab135e95f 100644
--- a/inc/template.php
+++ b/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 ' &raquo; ';
-    tpl_link(wl($crumb),noNS($crumb),'class="breadcrumbs" title="'.$crumb.'"');
+    tpl_link(wl($id),$name,'class="breadcrumbs" title="'.$id.'"');
   }
 }