Initial version of AH TOC: build a static table of contents.

- do not add anchors to headings or link to them
- do not add "top" links to headings
- force code/pre in help pages to clear: right to avoid the TOC running into them.
- TODO: use a theme function to format the TOC
- TOTO: include a fold/unfold link on the TOC

ah_toc.css

@@ -0,0 +1,58 @@
+/**
+ * @file
+ * TOC styles for advanced_help
+ *
+ * @copyright Ouest Systèmes Informatiques (OSInet)
+ *
+ * @license Licensed under the General Public License version 2 and later.
+ *
+ * $Id$
+ */
+
+@CHARSET "UTF-8";
+
+div.ah-toc {
+  border: thin solid silver;
+  float: right;
+  margin-left: 1em;
+  margin-bottom: 0.5em;
+  padding: 0;
+}
+
+/**
+ * Avoid having the TOC run into preformatted blocks if the initial block of
+ * text is not high enough.
+ *
+ * This extends a rule in advanced_help/help.css
+ */
+div.advanced-help-topic code, div.advanced-help-topic pre {
+  clear: right; 
+}
+
+div.ah-toc ul {
+  list-style-type: none;
+  margin: 0.5em;
+}
+
+div.ah-toc * {
+  margin-bottom: 0 ;
+  margin-top: 0;
+  padding: 0;
+  background: none; /* remove excess list formatting from themes like garland */
+}
+
+/**
+ * h2 is not present in a normal page hierarchy.
+ * Therefore h3 is at the first indent level too.
+ */
+.ah-toc .h2 { margin-left: 0; }
+.ah-toc .h3 { margin-left: 0;}
+.ah-toc .h4 { margin-left: 1em; }
+.ah-toc .h5 { margin-left: 2em; }
+.ah-toc .h6 { margin-left: 3em; }
+.ah-toc .h7 { margin-left: 4em; }
+
+.ah-toc center { 
+   border-bottom: solid thin silver;
+   padding: 0.5em; 
+}

ah_toc.info

@@ -0,0 +1,5 @@
+name = AH TOC
+description = "Automatically built table of contents in Advanced Help pages"
+core = 6.x
+php = 5.2
+dependencies[] = advanced_help

ah_toc.install

@@ -0,0 +1,23 @@
+<?php
+// $Id$
+/**
+ * @file
+ * Installer for AH TOC
+ *
+ * @copyright Ouest Systèmes Informatiques (OSInet)
+ *
+ * @license Licensed under the General Public License version 2 and later.
+ */
+
+/**
+ * Implementation of hook_update_N().
+ *
+ * Just enough to have an actual version number
+ */
+function ah_toc_update_6000() {
+  $ret[] = array(
+    'success' => TRUE,
+    'query'   => 'Settings schema version',
+  );
+  return $ret;
+}

ah_toc.js

@@ -0,0 +1,53 @@
+// $Id$
+/**
+ * @file
+ * TOC builder for advanced_help pages
+ *  
+ * @copyright Ouest Systèmes Informatiques (OSInet)
+ *
+ * @license Licensed under the General Public License version 2 and later.
+ */
+
+/**
+ * Build a TOC div from the Hn elements in a given context
+ * 
+ * Extract the H[1-7] list in DOM order manually: with jQuery < 1.4,
+ * neither $('h1, h2...') nor .add() return in DOM order, hence the use
+ * of filter() on a * selector instead.
+ * 
+ * @return jQuery
+ *   A list of the headings in the page
+ */
+function buildToc() {
+
+  var contextSelector = 'div.advanced-help-topic';
+  var context = $(contextSelector);
+  var elements = $('*', contextSelector).filter(function (index) {
+    return ['H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'H7'].indexOf(this.nodeName) != -1;
+  });
+
+  /**
+   * Only build the toc if there 2 headings or more in the page
+   */
+  if (elements.length <= 1) {
+    return;
+  }
+
+  // Build the headings list
+  var list = "<ul>\n";
+  elements.each(function() {
+    list += '<li class="' + this.nodeName.toLowerCase() + '">'
+        + $(this).text() + "</li>\n";
+  })
+  list += "</ul>\n";
+
+  // Avoid creating multiple TOCs if this function is called several times
+  $('div.ah-toc', context).remove(); 
+  
+  // @TODO use a theme function
+  context.prepend('<div class="ah-toc"><center>Contents</center></div>');
+  $('div.ah-toc').append(list);
+  return elements;
+}
+
+$(buildToc);

ah_toc.module

@@ -0,0 +1,50 @@
+<?php
+// $Id$
+/**
+ * @file
+ * Automatically adds a table of contents block on advanced_help pages.
+ *
+ * @copyright Ouest Systèmes Informatiques (OSInet)
+ *
+ * @license Licensed under the General Public License version 2 and later.
+ */
+
+/**
+ * Module name
+ * @var string
+ */
+define('AH_TOC_MODULE', 'ah_toc');
+
+/**
+ * Implementation of hook_help().
+ *
+ *  @return string
+ */
+function ah_toc_help($section, $arg) {
+
+  if ($section == 'admin/help#'. AH_TOC_MODULE) {
+    $ret = t('The AH Table Of Contents module automatically builds a table of contents block on advanced_help pages. This building is done entirely client-side using jQuery.');
+  }
+  else {
+    $ret = NULL;
+  }
+
+  return $ret;
+}
+
+/**
+ * Implementation of hook_init().
+ *
+ * Add the AH TOC CSS and JS only on AH pages, and not on main AH index page.
+ *
+ * @return void
+ */
+function ah_toc_init() {
+  if (arg(0) != 'help') {
+    return;
+  }
+
+  $path = drupal_get_path('module', AH_TOC_MODULE);
+  drupal_add_js($path  .'/'. AH_TOC_MODULE .'.js');
+  drupal_add_css($path .'/'. AH_TOC_MODULE .'.css');
+}