Skip to content

GitLab

Commit 4edd2adb authored by David Byers's avatar David Byers
Browse files

Moved docgen.el 

Detailed changes:
parent 62445630
Hide whitespace changes
Inline Side-by-side
src/docgen.el deleted 100644 → 0
View file @ 62445630
;;;;; -*-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
;;;;
;;; TO DO
;;;
;;; Variable documentation requires considerably more flexibility
;;; than command documentation:
;;;
;;; * Generate segmentedlist elements. Look for two-column
;;; indented parts in the documentation.
;;;
;;; * Highlight code (e.g. `t', `nil', `other' usw. Handle
;;; references to elisp functions and elisp variables.
;;;
;;; * Format examples. I don't think we can do this consistently
;;; without any markup. MAybe by looking for indented blocks
;;; where some line in a block does not match a segmentedlist
;;; format.
;;;
;;; In variables, warn for undocumented (no **) def-kom-vared
;;; variables that start with kom-
;;;
;;; Generate DTD fragments so we can use entities for command and
;;; variable references (e.g. &fn:kom-mark-text;) in XML.
;;;
;;; Read templates from a file, so we don't hard-code the
;;; format here.
;;;
;;; Specify output file on the command line.
;;;
;;; Specify lyskom.elc on the command line.
;;;
;;; Read a list of external references from a file. Ideally we'd read
;;; and parse the actual XML, but that is probably too much work. We
;;; need to map references like lyskom-read-text-no-prefix-arg to the
;;; actual ID to link to. Specify this file on the command line too.
;;;
;;; Do variable documentation.
;;;
;;; Write or find a stylesheed that doesn't suck. Mainly paragraph
;;; spacing is way too big, and the period after section numbers is
;;; just plain wrong. Maybe this can be fixed by setting parameters to
;;; the DSSSL processor -- see
;;; /usr/share/sgml/docbook/stylesheet/dsssl/modular/print/dbparam.dsl
;;; for all available parameters. %para-sep% is interesting.
;;;
(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 "&" "&"))
(setq s (replace-in-string s "<" "&lt;"))
(setq s (replace-in-string s ">" "&gt;"))
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-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 "\
<section id=\"fn:%s\"><title>%s [%s]</title>
<informaltable frame=\"topbot\">
<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
</section>\n\n"
command
name-en
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)))))
(defun lyskom-docgen-generate-missing-anchors ()
(lyskom-docgen-princ "<section><title>Dummy anchors</title><para>\n")
(lyskom-traverse fn (set-difference lyskom-docgen-xrefd-functions
lyskom-docgen-found-functions)
(lyskom-docgen-princ
(format "<anchor id=\"fn:%s\" />Missing target: %s; \n" 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; \n" var var)))
(lyskom-docgen-princ "</para></section>\n"))
(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")
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment