[mcclim-cvs] CVS mcclim/Doc

[thenriksen]

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

Modified Files:
	Makefile 
Added Files:
	makeimages.sh mcclim.texi sheet-hierarchy.tex 
Removed Files:
	manual.tex 
Log Message:
Converted McCLIM User's Guide to Texinfo format, but extracted one
math-heavy (and not very user-oriented) chapter to an external LaTeX
document (sheet-hierarchy.tex).


--- /project/mcclim/cvsroot/mcclim/Doc/Makefile	2003/07/16 17:49:39	1.3
+++ /project/mcclim/cvsroot/mcclim/Doc/Makefile	2006/11/11 15:33:21	1.4
@@ -1,11 +1,17 @@
-NAME=manual
+NAME=mcclim
+NAME2=sheet-hierarchy
 
-TEXFILES=$(NAME).tex $(shell ./tex-dependencies $(NAME).tex)
+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
 
-all : $(NAME).ps
+all : $(NAME).ps $(NAME2).ps
 
 %.pstex: %.fig
 	fig2dev -Lpstex -m 0.75  $< $@
@@ -13,12 +19,24 @@
 %.pstex_t: %.fig %.pstex
 	fig2dev -Lpstex_t -m 0.75 -p $(basename $<).pstex $< $@
 
-$(NAME).dvi: $(TEXFILES) $(PSTEX_T) $(VERBATIM)
+$(NAME).dvi: $(TEXIFILES) $(TARGETIMAGES)
+	texi2dvi $(NAME).texi
+
+$(NAME2).dvi: $(NAME2).tex $(PSTEX_T) $(VERBATIM)
 	latex $<
-#	makeindex $(NAME)
+	makeindex $(NAME)
 	latex $<
 
-$(NAME).ps: $(NAME).dvi $(PSTEX)
+$(TARGETIMAGES):
+	sh ./makeimages.sh "$(IMAGES)" "$(IMAGETARGETTYPES)"
+
+$(NAME).html: $(TEXIFILES)
+	makeinfo --html $<
+
+$(NAME).ps: $(NAME).dvi
+	dvips $< -o
+
+$(NAME2).ps: $(NAME2).dvi $(PSTEX)
 	dvips $< -o
 
 view: $(NAME).ps
@@ -29,5 +47,5 @@
 
 spotless:
 	make clean
-	rm -f *.ps *.dvi *.pstex *.pstex_t *.toc *.idx *.ilg *.ind
-
+	rm -f *.ps *.dvi *.pstex *.pstex_t *.toc *.idx *.ilg *.ind *pdf \
+*ky *pg *tmp *tp *tps *vr *fn *fns *info

--- /project/mcclim/cvsroot/mcclim/Doc/makeimages.sh	2006/11/11 15:33:21	NONE
+++ /project/mcclim/cvsroot/mcclim/Doc/makeimages.sh	2006/11/11 15:33:21	1.1
#!/bin/sh

# Go through a list of image files and make sure that a version of
# each image exists in every format specified by a list of file
# types. Uses ImageMagick. If first argument is -e, to not convert,
# but print a list of the files that are supposed to exist after the
# script has run.
if [ "$1" == "-e" ]; then
    NOCREATE="true"
    IMAGES="$2"
    IMAGETARGETTYPES="$3"
else
    IMAGES=$1
    IMAGETARGETTYPES=$2
fi

for FILE in $IMAGES; do
    if [ -f "$FILE" ]; then
        RAWFILE=${FILE%.*}
        for TYPE in $IMAGETARGETTYPES; do
            FILETOMAKE=$RAWFILE.$TYPE
            if [ "$NOCREATE" == "true" ]; then
                echo $FILETOMAKE
            else
                if [ ! -f "$FILETOMAKE" ]; then
                    convert $FILE $FILETOMAKE
                fi
            fi
        done
    else
        echo The file $FILE does not exist.
    fi
done--- /project/mcclim/cvsroot/mcclim/Doc/mcclim.texi	2006/11/11 15:33:21	NONE
+++ /project/mcclim/cvsroot/mcclim/Doc/mcclim.texi	2006/11/11 15:33:21	1.1
% @c -*- Coding: utf-8; Mode: Texinfo -*-
% @c Note that Texinfo does not support UTF-8. Please do not use literal
% @c UTF-8 characters in this document.
\input texinfo

@setfilename mcclim
@settitle McCLIM User's Manual

@set MCCLIMVERSION 0.9.3

@copying
Copyright @copyright{} 2004,2005,2006 the McCLIM hackers.
@end copying

@dircategory Common Lisp
@direntry
* McCLIM User's Manual: (mcclim). A free implementation of CLIM.
@end direntry

@titlepage
@title{McCLIM User's Manual}

@sp 5
@center @titlefont{The Users Guide}
@sp 2
@center @titlefont{and}
@sp 2
@center @titlefont{API Reference}
@sp 2

@page
@vskip 0pt plus 1filll
@insertcopying

@end titlepage

@iftex
@contents
@end iftex

@macro glossentry{ENTRY}
@b{\ENTRY\}
@cindex \ENTRY\
@end macro

@macro func{NAME}
@t{\NAME\}
@findex \NAME\
@end macro

@macro fmacro{MACRO}
@func{\MACRO\}
@end macro

@macro genfun{FUN}
@func{\FUN\}
@end macro

@alias gloss = i
@alias class = t
@alias gadget = t
@alias pane = t
@alias initarg = t
@alias methcomp = t
@alias slot = t
@alias longref = t
@alias cl = t
@alias initarg = t

@ifnottex
@node Top
@top McCLIM User's Manual
@insertcopying
@end ifnottex

@menu
* Introduction::

Getting started
* CLIM Demos and Applications:: 
* The First Application:: 
* Using presentation types::

User Manual 
* Using views:: 
* Using command tables::

Reference Manual
* Concepts:: 
* Windowing system drawing functions:: 
* CLIM drawing functions:: 
* Panes:: 
* Output Protocol:: 
* Command Processing::

Extensions
* Output Protocol Extensions:: 
* Output Recording Extensions:: 
* Drawing Two-Dimensional Images::
* File Selector Gadget::
* PostScript Backend::

Utility Programs 
* Listener:: 
* Inspector::

Auxilliary Material 
* Glossary::
* Development History::

Index
* Concept Index::
* Function Index::
@end menu

@node Introduction
@chapter Introduction
@cindex Ehtoota

CLIM is a large layered software system that allows the user to
customize it at each level.  The most simple ways of using CLIM is to
directly use its top layer, which contains application frames, panes,
and gadgets, very similar to those of traditional windowing system
toolkits such as GTK, Tk, and Motif.

But there is much more to using CLIM.  In CLIM, the upper layer with
panes and gadgets is written on top of a basic layer containing more
basic functionality in the form of sheets.  Objects in the upper layer
are typically instances of classes derived from those of the lower
layer.  Thus, nothing prevents a user from adding new gadgets and panes
by writing code that uses the sheet layer.

Finally, since CLIM is written in Common Lisp, essentially all parts of
it can be modified, replaced, or extended.

For that reason, a user's manual for CLIM must contain not only a
description of the protocols of the upper layer, but also of all
protocols, classes, functions, macros, etc. that are part of the
specification.

@menu
* Standards::
* How CLIM Is Different::
@end menu

@node Standards
@section Standards

This manual documents McCLIM @value{MCCLIMVERSION} which is a mostly
complete implementation of the CLIM 2.0 specification and its revision
2.2. To our knowledge version~2.2 of the CLIM specification is only
documented in the ``CLIM 2 User's Guide'' by Franz. While that document
is not a formal specification, it does contain many cleanups and is
often clearer than the official specification; on the other hand, the
original specification is a useful reference. This manual will note
where McCLIM has followed the 2.2 API.
@cindex Specification

Also, some protocols mentioned in the 2.0 specification, such as parts
of the incremental redisplay protocol, are clearly internal to CLIM and
not well described.  It will be noted here when they are partially
implemented in McCLIM or not implemented at all.

@node How CLIM Is Different
@section How CLIM Is Different

Many new users of CLIM have a hard time trying to understand how it
works and how to use it.  A large part of the problem is that many such
users are used to more traditional GUI toolkits, and they try to fit
CLIM into their mental model of how GUI toolkits should work.

But CLIM is much more than just a GUI toolkit, as suggested by its name,
it is an @emph{interface manager}, i.e. it is a complete mediator
between application ``business logic'' and the way the user interacts
with objects of the application.  In fact, CLIM doesn't have to be used
with graphics output at all, as it contains a large collection of
functionality to manage text.
@cindex Interface manager

Traditional GUI toolkits have an @emph{event loop}.
@cindex Event loop
Events are delivered to GUI elements called @emph{gadgets} (or
@emph{widgets}), and the programmer attaches @emph{event handlers} to
those gadgets in order to invoke the functionality of the application
logic.  While this way of structuring code is sometimes presented as a
virtue (``Event-driven programming''), it has an unfortunate side
effect, namely that event handlers are executed in a null context, so
that it becomes hard to even remember two consecutive events.  The
effect of event-driven programming is that applications written that way
have very rudimentary interaction policies.

At the lowest level, CLIM also has an event loop, but most application
programmers never have any reason to program at that level with CLIM.
Instead, CLIM has a @emph{command loop} 
@cindex Command loop
at a much higher level than the event loop.  At each iteration of the
command loop:

@enumerate
@item
 A command is acquired.  You might satisfy this demand by clicking on a
  menu item, by typing the name of a command, by hitting some kind of
  keystroke, by pressing a button, or by pressing some visible object
  with a command associated with it;
@item
 Arguments that are required by the command are acquired.  Each argument
    is often associated with a @emph{presentation type}, and visible
    objects of the right presentation type can be clicked on to satisfy
    this demand.  You can also type a textual representation of the
    argument, using completion, or you can use a context menu;
@item
 The command is called on the arguments, usually resulting in some
    significant modification of the data structure representing your
    application logic;
@item
 A @emph{display routine} is called to update the views of the
  application logic.  The display routine may use features such as
  incremental redisplay.
@end enumerate

Instead of attaching event handlers to gadgets, writing a CLIM
application therefore consists of:

@itemize @bullet
@item
 writing CLIM commands that modify the application data structures
  independently of how those commands are invoked, and which may take
  application objects as arguments;
@item
 writing display routines that turn the application data structures (and
  possibly some "view" object) into a collection of visible
  representations (having presentation types) of application objects;
@item
 writing completion routines that allow you to type in application
  objects (of a certain presentation type) using completions;
@item
 independently deciding how commands are to be invoked (menus, buttons,
  presentations, textual commands, etc).
@end itemize

By using CLIM as a mediator of command invocation and argument
acquisition, you can obtain some very modular code.  Application logic
is completely separate from interaction policies, and the two can evolve
separately and independently.

@c @node Getting Started
@c @part Getting Started

@node CLIM Demos and Applications
@chapter CLIM Demos and Applications
@cindex Demo applications

@menu
* Running the Demos::
* McCLIM Installation and Usage Tips::
@end menu

@node Running the Demos
@section Running the Demos

The McCLIM source distribution comes with a number of demos and
applications.  They are intended to showcase specific CLIM features,
demonstrate programming techniques or provide useful tools.

These demos and applications are available in the @t{Examples} and
@t{Apps} subdirectories of the source tree's root directory.
Instructions for compiling, loading and running some of the demos are
included in the files with the McCLIM installation instructions for your
Common Lisp implementation. See for example the file @t{INSTALL} if you
use Allegro CL, @t{INSTALL.CMU} for CMUCL, @t{INSTALL.OPENMCL} for
OpenMCL, and so on.

Below is a complete list of the McCLIM demos and applications, sorted in
alphabetical order.  Each entry provides a short description of what the
program does, with instructions for compiling and running it if not
mentioned in the general installation instructions.

@table @t
@item Apps/Listener
CLIM-enabled Lisp listener.  See the compilation and execution
instructions in @t{Apps/Listener/README}.
@item Examples/address-book.lisp
Simple address book.  See McCLIM's installation instructions.
@item Examples/calculator.lisp
Simple desk calculator.  See McCLIM's installation instructions.
@item Examples/clim-fig.lisp
Simple paint program.  You can run it by evaluating this form at the
Lisp prompt:
@lisp
(clim-demo::clim-fig)
@end lisp
@item Examples/colorslider.lisp
Interactive color editor.  See McCLIM's installation instructions.
@item Examples/demodemo.lisp
Demonstrates different pane types.  You can compile it by evaluating:
@lisp
(compile-file "Examples/demodemo.lisp")
@end lisp
Then load it with:
@lisp
(load "Examples/demodemo")
@end lisp
Finally, run it with:
@lisp
(clim-demo::demodemo)
@end lisp
@item Examples/goatee-test.lisp
Text editor with Emacs-like key bindings.  See McCLIM's installation
instructions.
@item Examples/menutest.lisp
Displays a window with a simple menu bar.  See McCLIM's installation
instructions.
@item Examples/postscript-test.lisp
Displays text and graphics to a PostScript file.  Run it with:
@lisp
(clim-demo::postscript-test)
@end lisp
The resulting file @t{ps-test.ps} is generated in the current directory
and can be displayed by a PostScript viewer such as @t{gv} on Unix-like
systems.
@item Examples/presentation-test.lisp
Displays an interactive window in which you type numbers that are
successively added.  When a number is expected as input, you can either
type it at the keyboard, or click on a previously entered number. Run it
with:
@lisp
(clim:run-frame-top-level (clim:make-application-frame
                           'clim-demo::summation))
@end lisp
@item Examples/sliderdemo.lisp
Apparently a calculator demo (see above).  Compile with:
@lisp
(compile-file "Examples/sliderdemo.lisp")
@end lisp
Load with:
@lisp
(load "Examples/sliderdemo")
@end lisp
Run with:
@lisp
(clim-demo::slidertest)
@end lisp
@item Examples/stream-test.lisp
Interactive command processor that echoes its input.  Run with:
@lisp
(clim-demo::run-test)
@end lisp
@end table

The following programs are currently @b{known not to work}:
@itemize @bullet
@item
 @t{Examples/fire.lisp}
@item
 @t{Examples/gadget-test-kr.lisp}
@item
 @t{Examples/gadget-test.lisp}
@item
 @t{Examples/puzzle.lisp}
@item
 @t{Examples/traffic-lights.lisp}
@item
 @t{Examples/transformations-test.lisp}
@end itemize

@node McCLIM Installation and Usage Tips
@section McCLIM Installation and Usage Tips

[1945 lines skipped]
--- /project/mcclim/cvsroot/mcclim/Doc/sheet-hierarchy.tex	2006/11/11 15:33:21	NONE
+++ /project/mcclim/cvsroot/mcclim/Doc/sheet-hierarchy.tex	2006/11/11 15:33:21	1.1

[2451 lines skipped]