[mcclim-cvs] CVS mcclim/Doc

[thenriksen]

Update of /project/mcclim/cvsroot/mcclim/Doc
In directory clnet:/tmp/cvs-serv9563

Modified Files:
	mcclim.texi drei.texi Makefile 
Added Files:
	make-tempfiles.sh make-docstrings.lisp docstrings.lisp 
	DOCBUILDING 
Log Message:
Added new doc-building system that extracts docstrings from McCLIM
itself. Inspired by SBCL.


--- /project/mcclim/cvsroot/mcclim/Doc/mcclim.texi	2006/11/14 18:44:27	1.2
+++ /project/mcclim/cvsroot/mcclim/Doc/mcclim.texi	2006/12/21 12:22:02	1.3
@@ -52,6 +52,7 @@
 @end macro
 
 @alias gloss = i
+ at alias func = code
 @alias class = code
 @alias package = code
 @alias gadget = code
@@ -107,7 +108,7 @@
 Index
 * Concept Index::
 * Variable Index::
-* Function Index::
+* Function And Macro Index::
 @end menu
 
 @node Introduction
@@ -2299,18 +2300,18 @@
 cosmetic fixes to McCLIM and also worked on a GTK-like gadget set.  He
 finally started work to get the OpenGL backend operational.
 
- at node {Concept Index}
- at unnumbered {Concept Index}
+ at node Concept Index
+ at unnumbered Concept Index
 
 @printindex cp
 
- at node {Variable Index}
- at unnumbered {Variable Index}
+ at node Variable Index
+ at unnumbered Variable Index
 
 @printindex vr
 
- at node {Function And Macro Index}
- at unnumbered {Function And Macro Index}
+ at node Function And Macro Index
+ at unnumbered Function And Macro Index
 
 @printindex fn
 
--- /project/mcclim/cvsroot/mcclim/Doc/drei.texi	2006/11/14 18:44:27	1.1
+++ /project/mcclim/cvsroot/mcclim/Doc/drei.texi	2006/12/21 12:22:02	1.2
@@ -8,10 +8,9 @@
 @cindex text-field
 
 Drei - an acronym for @i{Drei Replaces EINE's Inheritor} - is one of the
-editor substrates provided by McCLIM. It is currently disabled by
-default (instead, a somewhat less sophisticated editor substrate,
-Goatee, is used), but it can be activated by evaluating @code{(setf
-clim-internals::*use-goatee* nil)}.
+editor substrates provided by McCLIM. Drei is activated by default, but
+if it gives you problem, you can disable it by evaluating @code{(setf
+clim-internals::*use-goatee* t)}.
 
 @menu
 * Drei Concepts::               The core Drei concepts and design philosophy.
@@ -126,12 +125,7 @@
 @node External API
 @section External API
 
- at deftp {Class} drei
-
-The abstract Drei class that maintains standard Drei editor state. It
-should not be directly instantiated, a subclass implementing specific
-behavior should be used instead.
- at end deftp
+ at include class-drei-drei.texi
 
 @deftp {@class{drei} Initarg} {:editable-p}
 Whether or not the Drei instance will be editable. If @cl{NIL}, the
@@ -145,94 +139,19 @@
 an attempt is made to insert a newline character.
 @end deftp
 
- at deffn {Generic Function} {view} drei
- at deffnx {Generic Function} {(setf view)} view drei
- at findex view
-The CLIM view that will be used whenever @var{drei} is being
-displayed. During redisplay, the @cl{stream-default-view} of the editor
-pane will be temporarily bound to this value.
- at end deffn
-
- at deffn {Generic Function} {kill-ring} drei
- at deffnx {Generic Function} {(setf kill-ring)} kill-ring drei
- at findex view
-
-The kill ring object used by @var{drei}.
- at end deffn
-
- at deffn {Generic Function} {previous-command} drei
- at deffnx {Generic Function} {(setf previous-command)} command drei
- at findex previous-command
-
-The previous command executed by @var{drei}.
- at end deffn
-
- at deffn {Generic Function} {minibuffer} drei
- at deffnx {Generic Function} {(setf minibuffer)} pane drei
- at findex minibuffer
-
-The minibuffer associated with @var{drei}. This may be @cl{NIL}.
- at end deffn
+ at include macro-drei-handling-drei-conditions.texi
 
- at defmac {handling-drei-conditions} &body body
- at findex handling-drei-conditions
-
-Evaluate `body' while handling Drei user notification signals. The
-handling consists of displaying their meaning to the user in the
-minibuffer. This is the macro that ensures conditions such as
- at cl{motion-before-end} does not land the user in the debugger.
- at end defmac
-
- at defmac {with-bound-drei-special-variables} {((drei-instance &key current-buffer current-window current-mark current-point current-syntax kill-ring minibuffer command-parser partial-command-parser previous-command prompt) &body body)}
-
-Evaluate @var{body} with Drei special variables bound to their proper
-values, taken from @var{drei-instance}. The keyword arguments can be
-used to provide forms that will be used to obtain values for the
-respective special variables instead of the default. This macro binds
-all of the special variables listed in @ref{Special Variables}, but also
-some CLIM special variables needed for ESA-style command parsing.
- at end defmac
-
- at defmac {performing-drei-operations} {((drei &rest args &key with-undo (update-syntax t) (redisplay t)) &body body)}
-
-Provide various Drei convenience services around the evaluation of
- at var{body}. This macro provides a convenient way to perform some
-operations on a Drei, and make sure that they are properly reflected in
-the undo tree, that the Drei is redisplayed, the syntax updated,
-etc. Exactly what is done can be controlled via the keyword
-arguments. Note that if @var{:with-undo'} is false (the default), the
- at emph{entire} undo history will be cleared after @var{body} has been
-evaluated. This macro expands into a call to
- at cl{invoke-performing-drei-operations}.
- at end defmac
-
- at deffn {Generic Function} {invoke-performing-drei-operations} {(drei continuation &key with-undo update-syntax redisplay)}
-
-Implement the behavior of @cl{performing-drei-operations}.
- at end deffn
+ at include macro-drei-with-bound-drei-special-variables.texi
 
- at deffn {Generic Function} {execute-drei-command} drei command
+ at include macro-drei-performing-drei-operations.texi
 
-Execute @var{command} for @var{drei}. This is the standard function for
-executing Drei commands - it will take care of reporting to the user if
-a condition is signalled, updating the syntax, setting the
- at cl{previous-command} of @var{drei} and recording the operations
-performed by @var{command} for undo.
- at end deffn
+ at include fun-drei-invoke-performing-drei-operations.texi
 
- at defmac {accepting-from-user} ((drei) &body body)
-Modidfy @var{drei} and the environment so that calls to @cl{accept} can
-be done to arbitrary streams from within @var{body}. Or, at least, make
-sure the Drei instance will not be a problem. When Drei calls a command,
-it will be wrapped in this macro, so it should be safe to use
- at cl{accept} within Drei commands. This macro expands into a call to
- at cl{invoke-accepting-from-user}
- at end defmac
+ at include macro-drei-accepting-from-user.texi
 
- at deffn {Generic Function} {invoke-accepting-from-user} {(drei continuation)}
+ at include fun-drei-invoke-accepting-from-user.texi
 
-Implement the behavior of @cl{performing-drei-operations}.
- at end deffn
+ at include fun-drei-execute-drei-command.texi
 
 @node Standard Drei Variants
 @section Standard Drei Variants
@@ -292,370 +211,112 @@
 @node General Buffer Protocol Parts
 @subsubsection General Buffer Protocol Parts
 
- at deftp {Protocol Class} buffer
-
-The base class for all buffers.  A buffer conceptually contains a
-large array of arbitrary objects.  Lines of objects are separated by
-newline characters.  The last object of the buffer is not
-necessarily a newline character.
- at end deftp
-
- at deftp {Class} standard-buffer
-
-The standard instantiable class for buffers.  A subclass of buffer.
- at end deftp
-
- at deftp {Protocol Class} mark
-
-The base class for all marks.
- at end deftp
-
- at deftp {@class{buffer} Initarg} :buffer
-
-The :buffer initarg is mandatory because no mark can exist without a
-buffer.
- at end deftp
-
- at deftp {@class{buffer} Initarg} :offset
-
-If an :offset initarg is given that is less than zero or greater than
-the size of the buffer, a no-such-offset condition is signaled. When the
-:offset initarg is not given, it defaults to zero.
- at end deftp
-
- at deftp {Protocol Class} left-sticky-mark
-
-A subclass of mark.  A mark of this type will "stick" to the object
-to the left of it, i.e. when an object is inserted at this mark, the
-mark will be positioned to the left of the object.
- at end deftp
-
- at deftp {Protocol Class} right-sticky-mark
-
-A subclass of mark.  A mark of this type will "stick" to the object
-to the right of it, i.e. when an object is inserted at this mark, the
-mark will be positioned to the right of the object.
- at end deftp
-
- at deffn {Generic Function} {clone-mark} mark &optional stick-to
-
-Clone a mark.  By default (when stick-to is NIL) the same type of mark
-is returned.  Otherwise stick-to is either :left, indicating that a
-left-sticky-mark should be created, or :right indicating that a
-right-sticky-mark should be created.
- at end deffn
-
- at deffn {Generic Function} {buffer} mark
-
-Return the buffer that the mark is positioned in.
- at end deffn
+ at include class-drei-buffer-buffer.texi
 
- at deftp {Error Condition} no-such-offset
+ at include class-drei-buffer-standard-buffer.texi
 
-This condition is signaled whenever an attempt is made to access an
-object that is before the beginning or after the end of the buffer.
- at end deftp
+ at include class-drei-buffer-mark.texi
 
- at deftp {Error Condition} offset-before-beginning
+ at include class-drei-buffer-left-sticky-mark.texi
 
-This condition is signaled whenever an attempt is made to access
-buffer contents that is before the beginning of the buffer.
-This condition is a subclass of no-such-offset
- at end deftp
+ at include class-drei-buffer-right-sticky-mark.texi
 
- at deftp {Error Condition} offset-after-end
+ at include fun-drei-buffer-offset.texi
 
-This condition is signaled whenever an attempt is made to access
-buffer contents that is after the end of the buffer.
-This condition is a subclass of no-such-offset
- at end deftp
+ at include fun-drei-buffer-setf-offset.texi
 
- at deftp {Error Condition} invalid-motion
+ at include fun-drei-buffer-clone-mark.texi
 
-This condition is signaled whenever an attempt is made to move a mark
-before the beginning or after the end of the buffer.
- at end deftp
+ at include fun-drei-buffer-buffer.texi
 
- at deftp {Error Condition} motion-before-beginning
+ at include condition-drei-buffer-no-such-offset.texi
 
-This condition is signaled whenever an attempt is made to move a mark
-before the beginning of the buffer.
-This condition is a subclass of invalid-motion.
- at end deftp
+ at include condition-drei-buffer-offset-before-beginning.texi
 
- at deftp {Error Condition} motion-after-end
+ at include condition-drei-buffer-offset-after-end.texi
 
-This condition is signaled whenever an attempt is made to move a mark
-after the end of the buffer.
-This condition is a subclass of invalid-motion.
- at end deftp
+ at include condition-drei-buffer-invalid-motion.texi
 
- at deffn {Generic Function} {size} buffer
+ at include condition-drei-buffer-motion-before-beginning.texi
 
-Return the number of objects in the buffer.
- at end deffn
+ at include condition-drei-buffer-motion-after-end.texi
 
- at deffn {Generic Function} {number-of-lines} buffer
+ at include fun-drei-buffer-size.texi
 
-Return the number of lines of the buffer, or really the number of
-newline characters.
- at end deffn
+ at include fun-drei-buffer-number-of-lines.texi
 
 @node Operations Related To The Offset Of Marks
 @subsubsection Operations Related To The Offset Of Marks
 
- at deffn {Generic Function} {offset} mark
-
-Return the offset of the mark into the buffer.
- at end deffn
-
- at deffn {Generic Function} {(setf offset)} offset mark
-
-Set the offset of the mark into the buffer.  A motion-before-beginning
-condition is signaled if the offset is less than zero. A
-motion-after-end condition is signaled if the offset is greater than
-the size of the buffer.
- at end deffn
-
- at deffn {Generic Function} {forward-object} mark &optional (count 1)
-
-Move the mark forward the number of positions indicated by count.
-This function could be implemented by an incf on the offset of the
-mark, but many buffer implementations can implement this function much
-more efficiently in a different way.  A motion-before-beginning
-condition is signaled if the resulting offset of the mark is less than
-zero. A motion-after-end condition is signaled if the resulting offset
-of the mark is greater than the size of the buffer.
- at end deffn
-
- at deffn {Generic Function} {backward-object} mark &optional (count 1)
-
-Move the mark backward the number of positions indicated by count.
-This function could be implemented by a decf on the offset of the
-mark, but many buffer implementations can implement this function much
-more efficiently in a different way. A motion-before-beginning
-condition is signaled if the resulting offset of the mark is less than
-zero. A motion-after-end condition is signaled if the resulting offset
-of the mark is greater than the size of the buffer.
- at end deffn
-
- at deffn {Generic Function} {mark<} mark1 mark2
+ at include fun-drei-buffer-forward-object.texi
 
-Return t if the offset of mark1 is strictly less than that of mark2.
-An error is signaled if the two marks are not positioned in the same
-buffer.  It is acceptable to pass an offset in place of one of the
-marks.
- at end deffn
-
- at deffn {Generic Function} {mark<=} mark1 mark2
-
-Return t if the offset of mark1 is less than or equal to that of
-mark2.  An error is signaled if the two marks are not positioned in
-the same buffer.  It is acceptable to pass an offset in place of one
-of the marks.
- at end deffn
-
- at deffn {Generic Function} {mark>} mark1 mark2
-
-Return t if the offset of mark1 is strictly greater than that of
-mark2.  An error is signaled if the two marks are not positioned in
-the same buffer.  It is acceptable to pass an offset in place of one
-of the marks.
- at end deffn
-
- at deffn {Generic Function} {mark>=} mark1 mark2
-
-Return t if the offset of mark1 is greater than or equal to that of
-mark2.  An error is signaled if the two marks are not positioned in
-the same buffer.  It is acceptable to pass an offset in place of one
-of the marks.
- at end deffn
-
- at deffn {Generic Function} {mark=} mark1 mark2
-
-Return t if the offset of mark1 is equal to that of mark2.  An error
-is signaled if the two marks are not positioned in the same buffer.
-It is acceptable to pass an offset in place of one of the marks.
- at end deffn
-
- at deffn {Generic Function} {beginning-of-buffer} mark
-
-Move the mark to the beginning of the buffer.  This is equivalent to
-(setf (offset mark) 0)
- at end deffn
+ at include fun-drei-buffer-backward-object.texi
 
- at deffn {Generic Function} {end-of-buffer} mark
+ at include fun-drei-buffer-mark=.texi
 
-Move the mark to the end of the buffer.
- at end deffn
-
- at deffn {Generic Function} {beginning-of-buffer-p} mark
-
-Return t if the mark is at the beginning of the buffer, nil
-otherwise.
- at end deffn
-
- at deffn {Generic Function} {end-of-buffer-p} mark
-
-Return t if the mark is at the end of the buffer, nil otherwise.
- at end deffn
+ at include fun-drei-buffer-mark-lt.texi
 
- at deffn {Generic Function} {beginning-of-line} mark
+ at include fun-drei-buffer-mark-lt=.texi
 
-Move the mark to the beginning of the line.  The mark will be
-positioned either immediately after the closest preceding newline
-character, or at the beginning of the buffer if no preceding newline
-character exists.
- at end deffn
-
- at deffn {Generic Function} {end-of-line} mark
+ at include fun-drei-buffer-mark-gt.texi
 
-Move the mark to the end of the line. The mark will be positioned
-either immediately before the closest following newline character, or
-at the end of the buffer if no following newline character exists.
- at end deffn
+ at include fun-drei-buffer-mark-gt=.texi
 
- at deffn {Generic Function} {beginning-of-line-p} mark
+ at include fun-drei-buffer-beginning-of-buffer.texi
 
-Return t if the mark is at the beginning of the line (i.e., if the
-character preceding the mark is a newline character or if the mark is
-at the beginning of the buffer), nil otherwise.
- at end deffn
+ at include fun-drei-buffer-end-of-buffer.texi
 
- at deffn {Generic Function} {end-of-line-p} mark
+ at include fun-drei-buffer-beginning-of-buffer-p.texi
 
-Return t if the mark is at the end of the line (i.e., if the character
-following the mark is a newline character, or if the mark is at the
-end of the buffer), nil otherwise.
- at end deffn
+ at include fun-drei-buffer-end-of-buffer-p.texi

[1819 lines skipped]
--- /project/mcclim/cvsroot/mcclim/Doc/Makefile	2006/11/14 18:44:27	1.5
+++ /project/mcclim/cvsroot/mcclim/Doc/Makefile	2006/12/21 12:22:03	1.6
@@ -1,51 +1,93 @@
-NAME=mcclim
-NAME2=sheet-hierarchy
+# This Makefile has been cribbed from SBCL.
+MCCLIMTEXI:=mcclim.texi
+DOCFILES:=*.texi
+TMPTYPES:=aux cp cps fn fns ky log pg toc tp tps vr vrs
+TMPFILES:=$(foreach target,mcclim,$(foreach type,$(TMPTYPES),$(target).$(type)))
+PSFILES=mcclim.ps
+PDFFILES=mcclim.pdf
+INFOFILE=mcclim.info
+HTMLDIRS=$(basename $(MCCLIMTEXI))
+# Place where generated documentation ends up. The value of
+# DOCSTRINGDIR has to end with a slash or you lose (it's passed to
+# Lisp's `pathname' function).
+DOCSTRINGDIR="docstrings/"
+I_FLAGS=-I $(DOCSTRINGDIR)
+
+# SBCL_SYSTEM is an optional argument to this make program. If this
+# variable is set, its contents are used as the command line for
+# invoking SBCL.
+
+# When passing a non-standard SBCL_SYSTEM, be sure to set the
+# environment variable SBCL_HOME to a useful value, as well.
+
+ifeq ($(MAKEINFO),)
+  MAKEINFO:=makeinfo
+endif
+
+ifeq ($(TEXI2PDF),)
+  TEXI2PDF:=texi2pdf
+endif
+
+ifeq ($(DVIPS),)
+  DVIPS:=dvips
+endif
+
+.PHONY: all
+all: ps pdf info html
+
+.PHONY: dist
+dist: html pdf
+
+# html documentation; output in $(HTMLDIRS)
+.PHONY: html
+html: html-stamp
+
+html-stamp: $(DOCFILES) docstrings
+	@rm -rf $(HTMLDIRS)
+	$(MAKEINFO) $(I_FLAGS) --html $(HTMLDIRS)
+	touch html-stamp
+
+# Postscript documentation
+.PHONY: ps
+ps: $(PSFILES)
+
+%.ps: %.dvi
+	dvips -o $@ $<
+
+# DVI generation
+%.dvi: %.texi $(DOCFILES) docstrings
+	texi2dvi $(I_FLAGS) $<
+
+# PDF documentation
+.PHONY: pdf
+pdf: $(PDFFILES)
+
+%.pdf: %.texi $(DOCFILES) docstrings
+	texi2pdf $(I_FLAGS) $<
+
+# info docfiles
+.PHONY: info
+info: $(INFOFILE)
+
+%.info: %.texi $(DOCFILES) docstrings
+	$(MAKEINFO) $(I_FLAGS) --output=$(INFOFILE) $<
+
+# Texinfo docstring snippets
+.PHONY: docstrings
+docstrings: tempfiles-stamp
+
+tempfiles-stamp:
+	DOCSTRINGDIR=$(DOCSTRINGDIR) PACKAGES=$(PACKAGES) sh make-tempfiles.sh "$(SBCL_SYSTEM)" && touch tempfiles-stamp
+
+
+.PHONY: clean
+clean: 
+	rm -f *~ *.bak *.orig \#*\# .\#* texput.log *.fasl
+	rm -rf $(HTMLDIRS) $(DOCSTRINGDIR)
+	rm -f variables.texi
+	rm -f $(PSFILES) $(PDFFILES) html-stamp tempfiles-stamp
+	rm -f $(TMPFILES) $(INDEXFILES)
+	rm -f mcclim.info mcclim.info-*
 
-TEXFILES=$(NAME2).tex $(shell ./tex-dependencies $(NAME2).tex)
-PSTEX_T=$(shell ./strip-dependence inputfig $(TEXFILES))
-VERBATIM=$(shell ./strip-dependence verbatimtabinput $(TEXFILES))
-PSTEX=$(subst .pstex_t,.pstex,$(PSTEX_T))
-IMAGES=ex2.eps inspect-as-cells.eps inspect-object-1.eps \
-inspect-object-2.eps inspect-object-3.eps native.fig
-IMAGETARGETTYPES=gif png eps
-TARGETIMAGES=$(shell sh ./makeimages.sh -e "$(IMAGES)" "$(IMAGETARGETTYPES)")
-TEXIFILES=$(NAME).texi drei.texi
-
-all : $(NAME).ps $(NAME2).ps
-
-%.pstex: %.fig
-	fig2dev -Lpstex -m 0.75  $< $@
-
-%.pstex_t: %.fig %.pstex
-	fig2dev -Lpstex_t -m 0.75 -p $(basename $<).pstex $< $@
-
-$(NAME).dvi: $(TEXIFILES) $(TARGETIMAGES)
-	texi2dvi $(NAME).texi
-
-$(NAME2).dvi: $(NAME2).tex $(PSTEX_T) $(VERBATIM)
-	latex $<
-	makeindex $(NAME)
-	latex $<
-
-$(TARGETIMAGES):
-	sh ./makeimages.sh "$(IMAGES)" "$(IMAGETARGETTYPES)"
-
-$(NAME).html: $(TEXIFILES)
-	makeinfo --html $(NAME).texi
-
-$(NAME).ps: $(NAME).dvi
-	dvips $< -o
-
-$(NAME2).ps: $(NAME2).dvi $(PSTEX)
-	dvips $< -o
-
-view: $(NAME).ps
-	gv -antialias -scale 1 $<
-
-clean:
-	rm -f *.aux *.log *~
-
-spotless:
-	make clean
-	rm -f *.ps *.dvi *.pstex *.pstex_t *.toc *.idx *.ilg *.ind *pdf \
-*ky *pg *tmp *tp *tps *vr *fn *fns *info
+.PHONY: distclean
+distclean: clean

--- /project/mcclim/cvsroot/mcclim/Doc/make-tempfiles.sh	2006/12/21 12:22:03	NONE
+++ /project/mcclim/cvsroot/mcclim/Doc/make-tempfiles.sh	2006/12/21 12:22:03	1.1
#!/bin/sh

# Create Texinfo snippets from the documentation of exported symbols.

# I (Troels Henriksen) cribbed this script from SBCL.
#
# This software is in the public domain and is provided with
# absolutely no warranty. See the COPYING and CREDITS files for more
# information.

if [ -z "$1" ]
then

    sbclsystem=$SBCL_PWD/../../src/runtime/sbcl
    sbclcore=$SBCL_PWD/../../output/sbcl.core
    if [ -e $sbclsystem ] && [ -e $sbclcore ]
    then
        SBCLRUNTIME="$sbclsystem --core $sbclcore"
    else
        SBCLRUNTIME="`which sbcl`"
    fi
else
    SBCLRUNTIME="$1"
fi

SBCL="$SBCLRUNTIME --noinform --no-sysinit --no-userinit --noprint --disable-debugger"

# Output directory.  This has to end with a slash (it's interpreted by
# Lisp's `pathname' function) or you lose.  This is normally set from
# Makefile.
DOCSTRINGDIR="${DOCSTRINGDIR:-docstrings/}"

echo /creating docstring snippets from SBCL=\'$SBCLRUNTIME\' for packages \'$PACKAGES\'
$SBCL <<EOF
(require :asdf)
(push (pathname "$SYSTEMSDIR") asdf:*central-registry*)
(asdf:oos 'asdf:load-op :cl-ppcre)
(asdf:oos 'asdf:load-op :mcclim)
(load "docstrings.lisp")
(defvar *output-dir* "$DOCSTRINGDIR")
(load "make-docstrings.lisp")
(sb-ext:quit)
EOF
--- /project/mcclim/cvsroot/mcclim/Doc/make-docstrings.lisp	2006/12/21 12:22:03	NONE
+++ /project/mcclim/cvsroot/mcclim/Doc/make-docstrings.lisp	2006/12/21 12:22:03	1.1
(cl:defvar *output-dir* #P"docstrings/")

(cl:defvar *mcclim-documentee*
  (cl:make-instance 'cl-docextractor:documentee
                    :name "McCLIM"
                    :output-directory *output-dir*
                    :packages '(:clim :drei :drei-buffer :drei-undo :drei-kill-ring
                                :drei-base :drei-abbrev :drei-syntax :drei-motion
                                :drei-editing :drei-core :esa :clim-extensions)
                    :ignored-packages '(:clim-internals)
                    :filetype "texi"))

(cl-docextractor:document *mcclim-documentee*)
--- /project/mcclim/cvsroot/mcclim/Doc/docstrings.lisp	2006/12/21 12:22:03	NONE
+++ /project/mcclim/cvsroot/mcclim/Doc/docstrings.lisp	2006/12/21 12:22:03	1.1
;;; -*- Mode: Lisp -*-

;;;; A docstring extractor for arbitrary CL systems, cribbed from
;;;; SBCL. Creates @include-ready documentation from the docstrings of
;;;; exported symbols of specified packages.

;;;; Written by Rudi Schlatte <rudi at constantly.at>, mangled by
;;;; Nikodemus Siivola, brought to McCLIM by Troels Henriksen.

;;;; TODO
;;;; * Verbatim text
;;;; * Quotations
;;;; * Method documentation untested
;;;; * Method sorting, somehow
;;;; * Index for macros & constants?
;;;; * This is getting complicated enough that tests would be good
;;;; * Nesting (currently only nested itemizations work)
;;;; * doc -> internal form -> texinfo (so that non-texinfo format are also
;;;;   easily generated)

;;;; FIXME: The description below is no longer complete. This
;;;; should possibly be turned into a contrib with proper documentation.

;;;; Formatting heuristics (tweaked to format SAVE-LISP-AND-DIE sanely):
;;;;
;;;; Formats SYMBOL and `symbol' as @code{symbol} if SYMBOL exists in
;;;; the current package, or @var{symbol} if symbol is in the argument
;;;; list of the defun / defmacro.
;;;;
;;;; Lines starting with * or - that are followed by intented lines
;;;; are marked up with @itemize.
;;;;
;;;; Lines containing only a SYMBOL that are followed by indented
;;;; lines are marked up as @table @code, with the SYMBOL as the item.

(eval-when (:compile-toplevel :load-toplevel :execute)
  (require 'sb-introspect))

(defpackage :cl-docextractor
  (:use :cl :sb-mop :cl-ppcre)
  (:shadow #:documentation)
  (:export #:documentee #:document)
  (:documentation
   "Tools to generate Texinfo documentation from docstrings."))

(in-package :cl-docextractor)

(defclass documentee ()
  ((%name :accessor name
          :initarg :name
          :type string
          :initform "Unnamed"
          :documentation "The name of the thing to be
documented.")
   (%output-directory :accessor output-directory
                      :initarg :output-directory
                      :type pathname
                      :initform (error "An output directory must be provided"))
   (%packages :accessor packages
              :initarg :packages
              :initform '()
              :documentation "The packages to extract docstrings from.")
   (%ignored-packages :accessor ignored-packages
                      :initarg :ignored-packages
                      :initform '()
                      :documentation "A list of packages whose
contents will be ignored when printing class-precedence-lists.")
   (%output-filetype :accessor output-filetype
                     :initarg :filetype
                     :initform "texinfo"
                     :documentation "The file type used for the
output files."))
  (:documentation "A `documentee' is a set of packages to create
Texinfo documentation from, a number of rules describing how to
parse the docstrings and an output pathname."))

;;;; various specials and parameters

(defvar *texinfo-output*)
(defvar *texinfo-variables*)
(defvar *documentation-package*)

(defvar *verbose-output* t
  "If true, print status information to `*standard-output*' while
running.")

(defparameter *documentee* nil
  "Bound to the `documentee' object currently being worked on.")

(defparameter *documentation-types*
  '(compiler-macro
    function
    method-combination
    setf
    ;;structure  ; also handled by `type'
    type
    variable)
  "A list of symbols accepted as second argument of `documentation'")

(defparameter *character-replacements*
  '((#\* . "star") (#\/ . "slash") (#\+ . "plus")
    (#\< . "lt") (#\> . "gt"))
  "Characters and their replacement names that `alphanumize' uses. If
the replacements contain any of the chars they're supposed to replace,
you deserve to lose.")

(defparameter *characters-to-drop* '(#\\ #\` #\')
  "Characters that should be removed by `alphanumize'.")

(defparameter *texinfo-escaped-chars* "@{}"
  "Characters that must be escaped with #\@ for Texinfo.")

(defparameter *itemize-start-characters* '(#\* #\-)
  "Characters that might start an itemization in docstrings when
  at the start of a line.")

(defparameter *symbol-characters* "ABCDEFGHIJKLMNOPQRSTUVWXYZ*:-+&"
  "List of characters that make up symbols in a docstring.")

(defparameter *symbol-delimiters* " ,.!?;")

(defparameter *ordered-documentation-kinds*
  '(package type structure condition class macro))

;;;; utilities

(defun flatten (list)
  (cond ((null list)
         nil)
        ((consp (car list))
         (nconc (flatten (car list)) (flatten (cdr list))))
        ((null (cdr list))
         (cons (car list) nil))
        (t
         (cons (car list) (flatten (cdr list))))))

(defun whitespacep (char)
  (find char #(#\tab #\space #\page)))

(defun setf-name-p (name)
  (or (symbolp name)
      (and (listp name) (= 2 (length name)) (eq (car name) 'setf))))

(defgeneric specializer-name (specializer))

(defmethod specializer-name ((specializer eql-specializer))
  (list 'eql (eql-specializer-object specializer)))

(defmethod specializer-name ((specializer class))
  (class-name specializer))

(defun specialized-lambda-list (method)
  ;; courtecy of AMOP p. 61
  (let* ((specializers (method-specializers method))
         (lambda-list (method-lambda-list method))
         (n-required (length specializers)))
    (append (mapcar (lambda (arg specializer)
                      (if  (eq specializer (find-class 't))
                           arg
                           `(,arg ,(specializer-name specializer))))
                    (subseq lambda-list 0 n-required)
                    specializers)
           (subseq lambda-list n-required))))

(defun required-arguments (lambda-list)
  "Return the required arguments of `lambda-list'. Will not work
if &env or the like is the first parameter."
  (loop for parameter in lambda-list
       until (find parameter lambda-list-keywords)
       collecting parameter))

(defun string-lines (string)
  "Lines in STRING as a vector."
  (coerce (with-input-from-string (s string)
            (loop for line = (read-line s nil nil)
               while line collect line))
          'vector))

(defun indentation (line)
  "Position of first non-SPACE character in LINE."
  (position-if-not (lambda (c) (char= c #\Space)) line))

(defun docstring (x doc-type)
  (cl:documentation x doc-type))

(defun flatten-to-string (list)
  (format nil "~{~A~^-~}" (flatten list)))

(defun alphanumize (original)
  "Construct a string without characters like *`' that will f-star-ck
up filename handling. See `*character-replacements*' and
`*characters-to-drop*' for customization."
  (let ((name (remove-if (lambda (x) (member x *characters-to-drop*))
                         (if (listp original)
                             (flatten-to-string original)
                             (string original))))
        (chars-to-replace (mapcar #'car *character-replacements*)))
    (flet ((replacement-delimiter (index)

[684 lines skipped]
--- /project/mcclim/cvsroot/mcclim/Doc/DOCBUILDING	2006/12/21 12:22:03	NONE
+++ /project/mcclim/cvsroot/mcclim/Doc/DOCBUILDING	2006/12/21 12:22:03	1.1

[718 lines skipped]