Utilities: New perl program to extract hooks

A new perl program, list-hooks.pl, now extracts the full list of hook
and function variables in Org, for inclusion into Worg's org-hooks.org.

Also, add a docstring to a few hooks that did not have one.

UTILITIES/list-hooks.pl

@@ -0,0 +1,32 @@
+#!/usr/bin/perl
+@files = glob("lisp/org-*.el");
+unshift @files,"lisp/org.el";
+
+print "* Hooks and Function variables\n\n";
+
+foreach $file (@files) {
+  ($file1 = $file) =~ s|.*/||;
+  open IN,"<$file" or die "Cannot open file $file\n";
+  while (<IN>) {
+    if (/^\((defvar|defcustom)\s+(org-.*?-(hook|functions?)\b)/) {
+      $deftype = $1;
+      $name = $2;
+      $_=<IN> while (not m/^\s*"/);
+      $doc = $_;
+      while (not m/(?<!\\)"\)?\s*$/) {
+	$_=<IN>;
+	$doc .=$_;
+      }
+      $doc =~ s/\A\s*"//;
+      $doc =~ s/"\)?\s*\Z//;
+      print "** =$name=\n";
+      print "Defined in: /$file1/\n";
+      print "#+begin_example\n";
+      @lines = split(/\n/,$doc);
+      @lines = map { $_ = "    " . $_ } @lines;
+      $doc = join("\n",@lines);
+      print "$doc\n";
+      print "#+end_example\n";
+    }
+  }
+}

lisp/org-agenda.el

@@ -1057,7 +1057,8 @@ works you probably want to add it to `org-agenda-custom-commands' for good."
 (defvar org-agenda-show-log nil)
 (defvar org-agenda-redo-command nil)
 (defvar org-agenda-query-string nil)
-(defvar org-agenda-mode-hook nil)
+(defvar org-agenda-mode-hook nil
+  "Hook for org-agenda-mode, run after the mode is turned on.")
 (defvar org-agenda-type nil)
 (defvar org-agenda-force-single-file nil)
 

lisp/org.el

@@ -3364,7 +3364,8 @@ This variable is set by `org-before-change-function'.
   "Every change indicates that a table might need an update."
   (setq org-table-may-need-update t))
 (defvar org-mode-map)
-(defvar org-mode-hook nil)
+(defvar org-mode-hook nil
+  "Mode hook for Org-mode, run after the mode was turned on.")
 (defvar org-inhibit-startup nil)        ; Dynamically-scoped param.
 (defvar org-agenda-keep-modes nil)      ; Dynamically-scoped param.
 (defvar org-table-buffer-is-an nil)