Fixed some variable references in the docstrings.

New file docgen.el generated DocBook command documentation from the
source code. It's very rough at the moment, but kind of works. It
needs a lot of tweaking to get the looks right.

Run with "emacs -batch -l ./docgen.el -f lyskom-docgen" in the source
directory. This will generate a file named DOC.xml that should work
with DocBoot 4.2.


Detailed changes:
> 2003-01-08  David Byers  <david.byers@swipnet.se>
>
> 	* filter.el (kom-super-jump): Fixed problem with prefix arg.
>
> 	* faqs.el: Fixed some invalid variable references in the new
> 	docstrings.
>
> 	* commands1.el: Fixed some invalid variable references in the new
> 	docstrings.
>
> 	* faqs.el: Fixed some invalid variable references in the new
> 	docstrings.

src/ChangeLog

+2003-01-08  David Byers  <david.byers@swipnet.se>
+
+	* filter.el (kom-super-jump): Fixed problem with prefix arg.
+
+	* faqs.el: Fixed some invalid variable references in the new
+	docstrings.
+
+	* commands1.el: Fixed some invalid variable references in the new
+	docstrings.
+
+	* faqs.el: Fixed some invalid variable references in the new
+	docstrings.
+
 2003-01-08  David Byers  <davby@ida.liu.se>
 
 	* utilities.el (lyskom-month-limits): Wrong number of days for

src/commands1.el

@@ -768,12 +768,12 @@ supervisor of the conference or of the member being removed."
 
 (def-kom-command kom-sub-self (&optional conf)
   "Resign your membership of a conference. If
-`kom-unsubscribe-make-passive' is set, them resigning once converts
+`kom-unsubscribe-makes-passive' is set, them resigning once converts
 your membership to a passive membership and resigning twice removes
 the membership completely (if the server supports passive
 memberships).
 
-See `kom-unsubscribe-make-passive'."
+See `kom-unsubscribe-makes-passive'."
   (interactive)
   (lyskom-sub-member 
    (blocking-do 'get-conf-stat lyskom-pers-no)
@@ -2489,7 +2489,7 @@ today's name is controlled by `kom-show-namedays'."
 
 With a positive prefix argument ARG, list sessions who have been
 active in the last ARG minutes. With a positive zero prefix argument
-\(i.e. `0', not `-0'), list all visible sessions. With a negative
+\(i.e. \"0\", not \"-0\"), list all visible sessions. With a negative
 nonzero prefix argument ARG, list both visible and invisible sessions
 who have been active in the last -ARG minutes. With a negative zero
 prefix argument (C-u -), list all sessions.
@@ -2515,7 +2515,7 @@ particular cnoference.
 
 With a positive prefix argument ARG, list sessions who have been
 active in the last ARG minutes. With a positive zero prefix argument
-\(i.e. `0', not `-0'), list all visible sessions. With a negative
+\(i.e. \"0\", not \"-0\"), list all visible sessions. With a negative
 nonzero prefix argument ARG, list both visible and invisible sessions
 who have been active in the last -ARG minutes. With a negative zero
 prefix argument \(C-u -), list all sessions.
@@ -2555,7 +2555,7 @@ particular conference.
 
 With a positive prefix argument ARG, list sessions who have been
 active in the last ARG minutes. With a positive zero prefix argument
-\(i.e. `0', not `-0'), list all visible sessions. With a negative
+\(i.e. \"0\", not \"-0\"), list all visible sessions. With a negative
 nonzero prefix argument ARG, list both visible and invisible sessions
 who have been active in the last -ARG minutes. With a negative zero
 prefix argument \(C-u -), list all sessions.
@@ -2593,7 +2593,7 @@ Several variables affect display. See `kom-show-where-and-what',
 
 With a positive prefix argument ARG, list sessions who have been
 active in the last ARG minutes. With a positive zero prefix argument
-\(i.e. `0', not `-0'), list all visible sessions. With a negative
+\(i.e. \"0\", not \"-0\"), list all visible sessions. With a negative
 nonzero prefix argument ARG, list both visible and invisible sessions
 who have been active in the last -ARG minutes. With a negative zero
 prefix argument \(C-u -), list all sessions.
@@ -2974,7 +2974,7 @@ and client software.
 
 With a positive prefix argument ARG, list sessions who have been
 active in the last ARG minutes. With a positive zero prefix argument
-\(i.e. `0', not `-0'), list all visible sessions. With a negative
+\(i.e. \"0\", not \"-0\"), list all visible sessions. With a negative
 nonzero prefix argument ARG, list both visible and invisible sessions
 who have been active in the last -ARG minutes. With a negative zero
 prefix argument \(C-u -), list all sessions."
@@ -3884,7 +3884,7 @@ DO-ADD: NIL if a comment should be subtracted.
 (def-kom-command kom-add-footnote (text-no-arg)
   "Add a text as a footnote to another text. This command is used to
 add a text as a footnote to another text after both have been created.
-If you want to write a new footnote, use `kom-write-footnot' instead.
+If you want to write a new footnote, use `kom-write-footnote' instead.
 
 This command accepts text number prefix arguments (see
 `lyskom-read-text-no-prefix-arg')."

src/docgen.el

+;;;;; -*-coding: iso-8859-1;-*-
+;;;;;
+;;;;; $Id$
+;;;;; Copyright (C) 1991-2002  Lysator Academic Computer Association.
+;;;;;
+;;;;; This file is part of the LysKOM Emacs LISP client.
+;;;;; 
+;;;;; LysKOM is free software; you can redistribute it and/or modify it
+;;;;; under the terms of the GNU General Public License as published by 
+;;;;; the Free Software Foundation; either version 2, or (at your option) 
+;;;;; any later version.
+;;;;; 
+;;;;; LysKOM is distributed in the hope that it will be useful, but WITHOUT
+;;;;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+;;;;; FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+;;;;; for more details.
+;;;;; 
+;;;;; You should have received a copy of the GNU General Public License
+;;;;; along with LysKOM; see the file COPYING.  If not, write to
+;;;;; Lysator, c/o ISY, Linkoping University, S-581 83 Linkoping, SWEDEN,
+;;;;; or the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, 
+;;;;; MA 02139, USA.
+;;;;;
+;;;;; Please mail bug reports to bug-lyskom@lysator.liu.se. 
+;;;;;
+;;;; ================================================================
+;;;; ================================================================
+;;;;
+;;;; File: docgen.el
+;;;;
+;;;; Generate documentation data for inclusion in the user manual
+;;;;
+
+(require 'cl)
+
+
+(defvar lyskom-docgen-external-refs
+  '((lyskom-read-text-no-prefix-arg . lyskom-read-text-no-prefix-arg)))
+
+(defvar lyskom-docgen-errors nil)
+
+(defvar lyskom-docgen-found-variables nil)
+(defvar lyskom-docgen-found-functions nil)
+
+(defvar lyskom-docgen-xrefd-variables nil)
+(defvar lyskom-docgen-xrefd-functions nil)
+
+
+(defun lyskom-docgen-error (fmt &rest args)
+  (apply 'message fmt args)
+  (setq lyskom-docgen-errors (cons (apply 'format fmt args)
+                                     lyskom-docgen-errors)))
+
+(defun lyskom-docgen-report-errors ()
+  (when nil
+    (lyskom-traverse msg (nreverse lyskom-docgen-errors)
+      (message msg))))
+
+(defun lyskom-docgen-princ (str)
+  (insert str))
+
+(defun lyskom-docgen-fixup-sgml (str)
+  (when str
+    (let ((s str))
+      (setq s (replace-in-string s "<" "&lt;"))
+      (setq s (replace-in-string s ">" "&lt;"))
+      (setq s (replace-in-string s "&" "&amp;"))
+      s)))
+
+(defun lyskom-docgen-get-name (fn lang)
+  (let ((lyskom-language lang))
+    (lyskom-command-name fn)))
+
+(defun lyskom-docgen-get-doc (fn)
+  (let ((doc (documentation fn)))
+    (when (and doc (string-match "Lisp documentation:" doc))
+      (setq doc (substring doc 0 (match-beginning 0))))
+    (lyskom-docgen-transform-refs fn (lyskom-docgen-fixup-sgml doc))))
+
+(defun lyskom-docgen-transform-refs (fn doc)
+  (if doc
+      (let ((result "")
+            (start 0))
+        (while (string-match "`\\(.*?\\)'" doc start)
+          (setq result (concat result (substring doc start (match-beginning 0))))
+          (let ((sym (intern (match-string 1 doc))))
+            (cond 
+             ((assq sym lyskom-docgen-external-refs)
+              (setq result
+                    (concat result
+                            (format "<xref linkend=\"%s\" />" 
+                                    (cdr (assq sym lyskom-docgen-external-refs))))))
+             ((fboundp sym)
+              (unless (memq sym lyskom-commands)
+                (lyskom-docgen-error "%s: reference to non-command %s" fn sym))
+              (setq result
+                    (concat result
+                            (format "<link linkend=\"fn:%s\"><command>%s</command></link> (<link linkend=\"fn:%s\"><function>%s</function></link>)"
+                                    sym
+                                    (lyskom-docgen-get-name fn 'en)
+                                    sym
+                                    sym)))
+              (setq lyskom-docgen-xrefd-functions 
+                    (add-to-list 'lyskom-docgen-xrefd-functions sym)))
+             ((boundp sym)
+              (setq result
+                    (concat result
+                            (format "<link linkend=\"var:%s\">%s</link>"
+                                    sym sym)))
+              (setq lyskom-docgen-xrefd-variables 
+                    (add-to-list 'lyskom-docgen-xrefd-variables sym)))
+             (t (lyskom-docgen-error "%s: undefined reference to %s" fn sym)
+                (setq result (concat result 
+                                     "`"
+                                     (match-string 1 doc)
+                                     "'"))))
+            (setq start (match-end 0))))
+        (setq result (concat result (substring doc start)))
+        (concat "      <para>\n"
+                (replace-in-string result "\n\n+" "\n      </para>\n      <para>\n")
+                "\n      </para>\n")
+        )
+    (lyskom-docgen-error "%s: No documentation!" fn)
+    "<para>Undocumented.</para>"))
+
+(defun lyskom-docgen-format-key-sequence (binding)
+  (mapconcat
+   (lambda (x) 
+     (format "<keycap>%s</keycap>" 
+             (lyskom-docgen-fixup-sgml (key-description x))))
+   binding " "))
+
+
+(defun lyskom-docgen-2 ()
+  (lyskom-docgen-princ "<variablelist>\n")
+  (lyskom-traverse command lyskom-commands
+    (let* ((name-sv (lyskom-docgen-get-name command 'sv))
+           (name-en (lyskom-docgen-get-name command 'en))
+           (bind-sv (where-is-internal command lyskom-sv-mode-map))
+           (bind-en (where-is-internal command lyskom-en-mode-map))
+           (doc-en (lyskom-docgen-get-doc command)))
+      (lyskom-docgen-princ
+       (format "\
+  <varlistentry>
+    <term><anchor id=\"fn:%s\" />%s</term>
+    <listitem>
+      <informaltable frame=\"top\">
+        <tgroup cols=\"2\">
+          <tbody valign=\"top\">
+            <row>
+              <entry>English name</entry>
+              <entry>%s</entry>
+            </row>
+            <row>
+              <entry>English binding</entry>
+              <entry>%s</entry>
+            </row>
+            <row>
+              <entry>Swedish name</entry>
+              <entry>%s</entry>
+            </row>
+            <row>
+              <entry>Swedish binding</entry>
+              <entry>%s</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+%s
+    </listitem>
+  </varlistentry>\n\n" 
+               command 
+               command 
+               name-en
+               (lyskom-docgen-format-key-sequence bind-en)
+               name-sv
+               (lyskom-docgen-format-key-sequence bind-sv)
+               doc-en))
+      (setq lyskom-docgen-found-functions
+            (cons command lyskom-docgen-found-functions))))
+  (lyskom-docgen-princ "</variablelist>\n\n"))
+
+(defun lyskom-docgen-generate-missing-anchors ()
+  (lyskom-docgen-princ "<para>")
+  (lyskom-traverse fn (set-difference lyskom-docgen-xrefd-functions
+                                      lyskom-docgen-found-functions)
+    (lyskom-docgen-princ
+     (format "<anchor id=\"fn:%s\" />Missing target: %s;" fn fn)))
+
+  (lyskom-traverse var (set-difference lyskom-docgen-xrefd-variables
+                                       lyskom-docgen-found-variables)
+        (lyskom-docgen-princ
+         (format "<anchor id=\"var:%s\" />Missing target: %s;" var var)))
+  (lyskom-docgen-princ "</para>"))
+
+
+
+(defun lyskom-docgen ()
+  (let ((buf (get-buffer-create "*LysKOM DOCGEN*")))
+    (set-buffer buf)
+    (set-language-environment 'latin-1)
+    (set-buffer-multibyte nil)
+    (lyskom-docgen-princ "
+<?xml version='1.0' encoding='iso-8859-1' ?>
+<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.2//EN\"
+               \"docbook/dtd/xml/4.2/docbookx.dtd\">
+<book lang=\"en\">
+  <chapter>
+    <title>Command Reference</title>
+
+    <para>
+      This chapter describes all commands in LysKOM. Commands are
+      listed in alphabetical order by english name.
+    </para>
+")
+    (let ((lyskom-docgen-errors nil))
+      (unwind-protect
+          (lyskom-docgen-2)
+        (lyskom-docgen-report-errors)))
+    (lyskom-docgen-generate-missing-anchors)
+    (lyskom-docgen-princ "\
+<section id=\"lyskom-read-text-no-prefix-arg\">
+  <title>Dummy</title>
+  <para>Dummy</para>
+</section>\n")
+    (lyskom-docgen-princ "</chapter></book>")
+    (write-file "DOC.xml")))
+
+
+
+(load-file "./lyskom.elc")
+
+

src/faqs.el

@@ -136,7 +136,7 @@ do this. To add a FAQ, use `kom-add-server-faq'."
 
 (def-kom-command kom-del-faq ()
   "Remove a FAQ from a conference. To add a FAQ, use
-`kom-add-conf-faq'."
+`kom-add-faq'."
   (interactive)
   (let* ((conf-stat (lyskom-read-conf-stat 'conf-to-del-faq
                                            '(conf pers) nil nil t)))

src/filter.el

@@ -572,9 +572,9 @@ user is a member of.
 
 To change existing filters, use `kom-filter-edit'.
 
-This command accepts text number prefix arguments (see
+This command accepts text number prefix arguments \(see
 `lyskom-read-text-no-prefix-arg')."
-  (interactive (lyskom-read-text-no-prefix-arg 'super-jump-q))
+  (interactive (list (lyskom-read-text-no-prefix-arg 'super-jump-q)))
   (if (or (null lyskom-current-text)
           (zerop lyskom-current-text))
       (lyskom-insert-string 'have-to-read)

src/review.el

@@ -103,7 +103,7 @@ conference. This can also be accomplished by using `kom-review-by-to'
 and specifying zero texts.
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive)
   (lyskom-tell-internat 'kom-tell-review)
@@ -116,7 +116,7 @@ performed with `kom-review-by-to'. The review will be resumed where
 the previous review finished.
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive "P")
   (if (not lyskom-have-review)
@@ -177,7 +177,7 @@ texts, review the last N texts instead of the first (you can use
 `kom-review-by-to' instead.
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive "P")
   (lyskom-tell-internat 'kom-tell-review)
@@ -195,7 +195,7 @@ texts, review the last N texts instead of the first (you can use
 `kom-review-first' instead.
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive "P")
   (lyskom-review-by-to (or count
@@ -980,7 +980,7 @@ oldest to newest, review newest to oldest instead. When reviewing
 newest to oldest, change to oldest to newest.
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive)
   (cond
@@ -1017,7 +1017,7 @@ This command accepts text number prefix arguments \(see
 `lyskom-read-text-no-prefix-arg').
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive (list (lyskom-read-text-no-prefix-arg 'review-tree-q)))
   (lyskom-tell-internat 'kom-tell-review)
@@ -1043,7 +1043,7 @@ This command accepts text number prefix arguments \(see
 `lyskom-read-text-no-prefix-arg').
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive (list (lyskom-read-text-no-prefix-arg 'find-root-q)))
   (lyskom-tell-internat 'kom-tell-review)
@@ -1083,7 +1083,7 @@ This command accepts text number prefix arguments \(see
 `lyskom-read-text-no-prefix-arg').
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive (list (lyskom-read-text-no-prefix-arg 'find-root-review-q)))
   (lyskom-tell-internat 'kom-tell-review)
@@ -1191,7 +1191,7 @@ review priorities are set, and the setting of
 `kom-higher-priority-breaks'.
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive)
   (lyskom-tell-internat 'kom-tell-review)
@@ -1219,7 +1219,7 @@ all review-related functions."
 read commands that have been suspended by reviewing.
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive)
   (if (read-list->all-entries lyskom-reading-list)
@@ -1258,7 +1258,7 @@ all review-related functions."
   "Cancel all active and suspended review commands.
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive)
   (let ((found nil))
@@ -1291,7 +1291,7 @@ This command accepts text number prefix arguments \(see
 `lyskom-read-text-no-prefix-arg').
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive (list (lyskom-read-text-no-prefix-arg 'review-comments-q)))
   (lyskom-tell-internat 'kom-tell-review)
@@ -1359,7 +1359,7 @@ After reviewing a number of texts, this will show the N texts
 read prior to that.
 
 See `kom-review-uses-cache', `kom-review-priority' and
-`kom-review-marks-texts-read' for information on settings that affect
+`kom-review-marks-texts-as-read' for information on settings that affect
 all review-related functions."
   (interactive 
    (list 

src/slow.el

@@ -229,7 +229,8 @@ If the completion was not exact it returns nil."
 
 
 (defun kom-slow-mode ()
-  "Starts the slow-command-mode."
+  "Starts the slow-command-mode. In this mode you write commands in the
+main LysKOM buffer instead of using keyboard shortcuts."
   (interactive)
   (lyskom-start-of-command 'kom-slow-mode)
   (unless lyskom-slow-mode
@@ -240,7 +241,9 @@ If the completion was not exact it returns nil."
   (lyskom-end-of-command))
 
 (defun kom-quick-mode ()
-  "Starts the quick-command-mode."
+  "Starts the quick command mode. This is the standard mode for LysKOM,
+where you use keyboard shortcuts for most commands, and the \"x\" prefix
+for all other commands."
   (interactive)
   (lyskom-start-of-command 'kom-quick-mode)
   (when lyskom-slow-mode