reference updates, including diagrams
authoradam <adam@megacz.com>
Tue, 30 Mar 2004 23:15:12 +0000 (23:15 +0000)
committeradam <adam@megacz.com>
Tue, 30 Mar 2004 23:15:12 +0000 (23:15 +0000)
darcs-hash:20040330231512-5007d-015a0b17990c27e93e20e57b6712e401217b8474.gz

Makefile
doc/ibex-doc.xml [new file with mode: 0644]
doc/reference/alignmentpoint.pdf [new file with mode: 0644]
doc/reference/grid.pdf [new file with mode: 0644]
doc/reference/layout.pdf [new file with mode: 0644]
doc/reference/lifecycle.pdf [new file with mode: 0644]
doc/reference/offscreen.pdf [new file with mode: 0644]
doc/reference/pdftricks.sty [new file with mode: 0644]
doc/reference/reference.xml [moved from doc/reference.xml with 66% similarity]
doc/reference/threeviews.pdf [new file with mode: 0644]

index 993e66e..d09fcb1 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -379,8 +379,9 @@ propose-patch:
 commit: propose-patch
        darcs push --and-apply xwt@xwt.org:/var/www/org/ibex/core/
 
 commit: propose-patch
        darcs push --and-apply xwt@xwt.org:/var/www/org/ibex/core/
 
-reference: build/class/org/ibex/util/XML.class build/class/org/ibex/util/Doc.class doc/reference.xml
-       cd doc; java -cp ../build/class org.ibex.util.Doc < reference.xml > reference.tex
-       cd doc; pdflatex reference.tex
-       open doc/reference.pdf
+doc/%.pdf: build/class/org/ibex/util/XML.class build/class/org/ibex/util/Doc.class doc/%.xml
+       cd $(@D); java -cp ../../build/class org.ibex.util.Doc slides < `basename $*`.xml > `basename $*`.tex
+       cd $(@D); pdflatex `basename $*`.tex
+       open doc/$*.pdf
+
 
 
diff --git a/doc/ibex-doc.xml b/doc/ibex-doc.xml
new file mode 100644 (file)
index 0000000..05e49d9
--- /dev/null
@@ -0,0 +1,204 @@
+<ibex-doc title="The Ibex Documentation Format" author="Adam Megacz" email="adam@ibex.org">
+
+<section title="Introduction">
+
+  <section title="Another Document Format?">
+
+  Foo.    
+
+  </section>
+
+  <section title="Goals">
+
+    <heading title="Applications"/>
+
+    IbexDoc targets four primary documentation tasks:
+
+    <list>
+
+        Books, Manuals and references
+
+        Articles
+
+        Literate Programming (documentation embedded in source code)
+
+        Presentation Slides
+
+        Web pages, including WikiWebs
+
+    </list>
+
+    <heading title="Separating Semantics from Aesthetics"/>
+
+    The goal of separating <i>markup</i> from <i>content</i> has been
+    around for a long time in the document world.  For some reason it
+    never succeeded.  The problem is that:
+
+    <list>
+        The purpose of content is to convey semantic meaning.
+
+        Some markup and formatting carries semantic meaning.
+    </list>
+
+    For example, consider italicization.  Adding or removing
+    italicization can actually affect the meaning of a piece of text.
+    Therefor italicization (or rather "emphasis") is part of the
+    <i>content</i> of a document.
+
+    IbexDoc recognizes this and does not attempt to use XML for
+    anything that might carry semantic meaning.  Effectively, you can
+    remove all XML tags from an IbexDoc file without altering the
+    meaning of the text (although it might be rather hard to discern
+    the meaning with all the text jumbled together!)
+
+  </section>
+</section>
+  <section title="Tags">
+
+      <definition term="doc">
+          (title subtitle logo license options(toc,index) logo)
+          </definition>
+
+      <definition term="author">
+          (email, name)
+          </definition>
+
+      <definition term="abstract">
+               changes
+          </definition>
+
+      <definition term="appendix">
+          (contains sections, must appear once at EOF)
+          </definition>
+
+      <definition term="section">
+          (title)
+          </definition>
+
+      <definition term="heading">
+          ..
+          </definition>
+
+      <definition term="definition">
+          ..
+          </definition>
+
+      <definition term="property">
+          (a different kind of list?)
+          </definition>
+
+      <definition term="remark">
+          ..
+          </definition>
+
+      <definition term="image">
+          ..
+          </definition>
+
+      <definition term="figure">
+          ..
+          </definition>
+
+      <definition term="code">
+          ..
+          </definition>
+
+      <definition term="pre">
+          ..
+          </definition>
+
+      <definition term="link">
+          ..
+          </definition>
+
+      <definition term="math">
+          ..
+          </definition>
+
+      <definition term="define">
+          ..
+          </definition>
+
+      <definition term="footnote">
+          ..
+          </definition>
+
+  </section>
+
+  <section title="Text Formatting">
+
+  <pre>
+
+     **italics**
+     __boldface__
+     ||typewriter||
+
+     blank lines become paragraph breaks
+
+     # 1
+        # 1.1
+           # 1.1.1
+
+     - 
+        -
+           -
+
+     \\     -   backslash
+     \0x??  -   unicode
+     \amp
+     \lt
+     \gt
+     \quot
+     \apos
+
+  </pre>
+
+  </section>
+
+  <section title="To Do">
+      <list>
+          tables
+
+          plugins (charts, graphs, diagrams)
+
+          wiki-style links
+
+          slides
+          <list>
+              slide breaks
+
+              overlays
+
+              2-column
+
+              different diagram layouts
+
+              color
+
+              persistent outline
+
+              watermark/logo
+          </list>
+      </list>
+
+      <heading title="JavaDoc Features We Like"/>
+      <pre>
+
+          /** */
+          ///      
+          ///&lt;
+          @param
+          @throws
+          @see
+          @link, autolinking (wiki-style?) of other classes/modules
+          @return
+          @deprecated
+          @since
+          @author?
+          package-level overview (but it's lame to put it in a separate file)
+          inheritance
+
+      </pre>
+  </section>
+    
+</ibex-doc>
\ No newline at end of file
diff --git a/doc/reference/alignmentpoint.pdf b/doc/reference/alignmentpoint.pdf
new file mode 100644 (file)
index 0000000..82b5cd4
Binary files /dev/null and b/doc/reference/alignmentpoint.pdf differ
diff --git a/doc/reference/grid.pdf b/doc/reference/grid.pdf
new file mode 100644 (file)
index 0000000..219d379
Binary files /dev/null and b/doc/reference/grid.pdf differ
diff --git a/doc/reference/layout.pdf b/doc/reference/layout.pdf
new file mode 100644 (file)
index 0000000..853b40d
Binary files /dev/null and b/doc/reference/layout.pdf differ
diff --git a/doc/reference/lifecycle.pdf b/doc/reference/lifecycle.pdf
new file mode 100644 (file)
index 0000000..940e482
Binary files /dev/null and b/doc/reference/lifecycle.pdf differ
diff --git a/doc/reference/offscreen.pdf b/doc/reference/offscreen.pdf
new file mode 100644 (file)
index 0000000..769be64
Binary files /dev/null and b/doc/reference/offscreen.pdf differ
diff --git a/doc/reference/pdftricks.sty b/doc/reference/pdftricks.sty
new file mode 100644 (file)
index 0000000..68ae554
--- /dev/null
@@ -0,0 +1,363 @@
+%
+% pdftricks.sty 
+%
+% Copyright (c) 2001, Radhakrishnan CV <cvr@river-valley.com>
+%                     Rajagopal CV <cvr3@river-valley.com>
+%                     http://www.river-valley.com
+%
+% River Valley Technologies, Software Technology Park,
+% Trivandrum, India 695034
+%
+% Tel: +91 471 33 7501/7502
+%
+%                     Antoine Chambert-Loir 
+%                     <chambert@math.polytechnique.fr>
+%                     http://www.math.polytechnique.fr/~chambert
+%
+% Ecole polytechnique, Palaiseau Cedex, France
+% 
+%
+% This program 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
+% of the License, or (at your option) any later version.
+%
+% This program 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 this program (gpl.txt); if not, write to the Free
+% Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+% MA  02111-1307, USA.
+%
+% $Id: pdftricks.sty,v 1.15 2001/09/30 11:21:23 cvr Exp $
+%
+\NeedsTeXFormat{LaTeX2e}
+\def\Fileversion$#1: #2 ${\gdef\fileversion{#2}}
+\def\Filedate$#1: #2 #3 ${\gdef\filedate{#2}}
+\Fileversion$Revision: 1.15 $
+\Filedate$Date: 2001/09/30 11:21:23 $
+\ProvidesPackage{pdftricks}
+   [\filedate\space\fileversion\space psTricks support in PDF (CVRACL)]
+\PackageWarningNoLine{pdftricks}
+   {****************************************\MessageBreak
+    Package pdftricks v,\fileversion\space loaded\MessageBreak
+    [psTricks support in PDF (CVR, ACL)]\MessageBreak
+    ****************************************}
+\RequirePackage{graphicx,color}
+\newif\if@debug\@debugfalse
+\newif\ifPDFTshell
+\newif\ifPDFTnopdf
+\newif\ifnoprocess \noprocessfalse
+\newif\ifmiktex \miktexfalse
+\DeclareOption{debug}{\@debugtrue}
+\DeclareOption{noshell}{\PDFTshellfalse}
+\DeclareOption{shell}{\PDFTshelltrue}
+\DeclareOption{miktex}{\global\miktextrue}  
+\ExecuteOptions{shell}
+\ProcessOptions\relax
+\ifPDFTshell
+% we must set it to false if \write18 doesn't work.
+% Hack given by Thierry Bouche (Thanks !)
+\def\tmpfile{/tmp/w18-test-\the\year\the\month\the\day\the\time} 
+\ifmiktex%
+ \immediate\write18{rem >"\tmpfile"}%%%%%% LDL-2
+\else
+ \immediate\write18{touch \tmpfile} %%%%%% LDL-1
+\fi
+\ifmiktex
+ \IfFileExists{\tmpfile.}{\PDFTshelltrue}{\PDFTshellfalse} %%%%%% LDL-4
+\else
+ \IfFileExists{\tmpfile}{\PDFTshelltrue}{\PDFTshellfalse}  %%%%%% LDL-3
+\fi
+\fi
+\ifPDFTshell
+  \PackageWarningNoLine{pdftricks}
+   {****************************************\MessageBreak
+    Using \csname write\endcsname18 capability \MessageBreak
+    for producing PDF-figures.  \MessageBreak
+    ****************************************}
+\else
+  \PackageWarningNoLine{pdftricks}
+   {****************************************\MessageBreak
+    No \csname write\endcsname18 capability.\MessageBreak
+    You'll have to run a script by yourself!\MessageBreak
+    ****************************************}
+\fi
+
+% warning! the definition of FIGURES if pst2pdf must be set accordingly !!
+\def\PDFTfigname{\jobname-fig\thepsfig}
+\def\PDFTWarning#1#2{\if@debug\PackageWarning{#1}{#2}\fi}
+\def\PDFTWarningNoLine#1#2{\if@debug\PackageWarningNoLine{#1}{#2}\fi}
+\def\makeinnocent#1{\catcode`#1=12 }
+\def\csarg#1#2{\expandafter#1\csname#2\endcsname}
+\def\latexname{lplain}\def\latexename{LaTeX2e}
+\newwrite\PDFStream
+
+\long\def\ProcessStream#1% start it all of
+   {\begingroup%
+    \def\CurrentStream{#1}%
+    \let\do\makeinnocent \dospecials 
+    \makeinnocent\^^L% and whatever other special cases
+    \endlinechar`\^^M \catcode`\^^M=12 \xStream}
+{\catcode`\^^M=12 \endlinechar=-1 %
+ \gdef\xStream#1^^M{%
+    \expandafter\ProcessStreamLine}
+ \gdef\ProcessStreamLine#1^^M{\def\test{#1}
+      \csarg\ifx{End\CurrentStream Test}\test
+          \edef\next{\noexpand\EndOfStream{\CurrentStream}}%
+      \else \ThisStream{#1}\let\next\ProcessStreamLine
+      \fi \next}
+}
+\long\def\streaminfo{\string\end{document}}
+\def\CSstringmeaning#1{\expandafter\CSgobblearrow\meaning#1}
+\def\CSstringcsnoescape#1{\expandafter\CSgobbleescape\string#1}
+{\escapechar-1
+\expandafter\expandafter\expandafter\gdef
+  \expandafter\expandafter\expandafter\CSgobblearrow
+    \expandafter\string\csname macro:->\endcsname{}
+}
+\def\CSgobbleescape#1{\ifnum`\\=`#1 \else #1\fi}
+\def\WriteStreamLine#1{\def\CStmp{#1}%
+    \immediate\write\PDFStream{\CSstringmeaning\CStmp}}
+
+\def\AfterIncludedStream
+   {\immediate\closeout\PDFStream  %changed on 2001/1/20
+    \relax
+    }%
+\def\BeforeIncludedStream
+   {\stepcounter{psfig}\xdef\PDFCutFile{\PDFTfigname.tex}%
+    \message{Opening PDFStream=\PDFCutFile}%
+    \immediate\openout\PDFStream=\PDFCutFile
+    \immediate\write\PDFStream{\string\documentclass{article}}
+    \immediate\write\PDFStream{\string\input\space tmp.inputs}
+    \immediate\write\PDFStream{\string\pagestyle{empty}}
+    \immediate\write\PDFStream{\string\usepackage{amssymb,amsbsy}}
+    \immediate\write\PDFStream{\string\begin{document}}
+    \let\ThisStream\WriteStreamLine}
+\long\def\specialstream #1#2#3{%
+     \message{Special stream '#1'}%
+    \csarg\def{After#1Stream}{#2\AfterIncludedStream#3}%
+    \csarg\def{#1}{\BeforeIncludedStream\relax
+          \ProcessStream{#1}}%
+    \PDFEndDef{#1}}
+\def\EndOfStream#1{\endgroup\end{#1}%
+    \csname After#1Stream\endcsname}
+\def\PDFEndDef#1{{\escapechar=-1\relax
+    \csarg\xdef{End#1Test}{\string\\end\string\{#1\string\}}%
+    }}
+%%
+%% The real meat of psfile manipulation starts here.
+%%
+%%
+\AtEndDocument{\endPShook%
+      \ifPDFTnopdf
+        \PackageWarningNoLine{pdftricks}
+        {******************************************\MessageBreak
+         Some PDF files of images were not found.\MessageBreak
+         Run the script `pst2pdf' before the next\MessageBreak
+         run of pdfLaTeX\MessageBreak
+         ******************************************}
+       \fi
+}
+\gdef\endPShook{}
+\def\noprocess{\global\noprocesstrue
+  \PackageWarning{pdftricks}
+        {******************************************\MessageBreak
+           Figure Number: \PDFTfigname\space is not processed \MessageBreak
+         ******************************************\MessageBreak}
+}
+\specialstream{pdfpic}{%
+         \immediate\write\PDFStream{\streaminfo}}
+        {\psgraphicsinclude\global\noprocessfalse}
+\newcounter{psfig}
+\newif\if@pdfGINwidth
+\newif\if@pdfGINheight
+\newif\if@pdfGINscale
+\long\gdef\psgraphicsinclude{%
+  \@ifundefined{Fig\thepsfig}
+  {\PDFTWarningNoLine{pdftricks}
+    {******************************************\MessageBreak
+     ************ Processing Fig: \thepsfig\space**********\MessageBreak
+    ******************************************}
+  }
+  {\noprocess}
+   \ifPDFTshell\ifnoprocess\relax\else
+    \IfFileExists{\PDFTfigname.tex}{%
+     \immediate\write18{latex -interaction=batchmode \PDFTfigname}
+  \PDFTWarningNoLine{pdftricks}
+    {******************************************\MessageBreak
+     \PDFTfigname.tex converted to \PDFTfigname.dvi\MessageBreak
+     ******************************************}
+    }{}
+    \IfFileExists{\PDFTfigname.dvi}{%
+     \immediate\write18{dvips -o \PDFTfigname.ps \PDFTfigname}
+     \immediate\write18{ps2eps -f \PDFTfigname.ps}
+  \PDFTWarningNoLine{pdftricks}
+    {******************************************\MessageBreak
+     \PDFTfigname.eps generated\MessageBreak
+     ******************************************}
+    }{}
+    \IfFileExists{\PDFTfigname.eps}{%
+      \immediate\write18{epstopdf \PDFTfigname.eps}
+  \PDFTWarningNoLine{pdftricks}
+    {******************************************\MessageBreak
+     \PDFTfigname.eps converted to \PDFTfigname.pdf\MessageBreak
+     ******************************************}
+    }{}
+    \ifmiktex%
+    \immediate\write18{del \PDFTfigname.aux \PDFTfigname.dvi \PDFTfigname.log \PDFTfigname.eps}     %%%%%% LDL-6
+    \else
+    \immediate\write18{rm \PDFTfigname.aux \PDFTfigname.dvi \PDFTfigname.log \PDFTfigname.eps} %%%%%% LDL-5
+   \fi\fi
+   \fi
+  \IfFileExists{\PDFTfigname.pdf}%
+     {\begin{center}
+     \bgroup\fboxsep\@PDFboxsep\fboxrule\@PDFboxrule%
+      \color{\@PDFgraphiccolor}%
+      \fcolorbox{\@PDFgraphiclinecolor}{\@PDFgraphicbackground}%
+     {\if@pdfGINwidth%
+       \includegraphics[width=\@PDFgraphicwidth]{\PDFTfigname}\else%
+      \if@pdfGINheight%
+       \includegraphics[height=\@PDFgraphicheight]{\PDFTfigname}\else%
+      \if@pdfGINscale%
+       \includegraphics[scale=\@PDFgraphicscale]{\PDFTfigname}\else%
+       \includegraphics{\PDFTfigname}\fi\fi\fi%
+     }\egroup\end{center}%
+      \global\@pdfGINwidthfalse\let\@PDFgraphicwidth\relax
+      \global\@pdfGINheightfalse\let\@PDFgraphicheight\relax
+      \global\@pdfGINscalefalse\let\@PDFgraphicscale\relax
+      }{\PDFTnopdftrue}
+   \gdef\@PDFgraphiclinecolor{white}
+   \gdef\@PDFgraphicbackground{white}
+   \gdef\@PDFboxsep{0pt}
+   \gdef\@PDFboxrule{0pt}
+}
+\definecolor{gray30}{gray}{.70}
+\definecolor{gray10}{gray}{.90}
+\RequirePackage{keyval}
+\def\configure[#1][#2]{\setkeys{#1}{#2}
+  \PDFTWarning{pdftricks}{Reconfigured #1 parameter(s)\MessageBreak  #2\MessageBreak}
+  }
+\define@key{pdfgraphic}{width}     {\gdef\@PDFgraphicwidth{#1}\global\@pdfGINwidthtrue}
+\define@key{pdfgraphic}{height}    {\gdef\@PDFgraphicheight{#1}\global\@pdfGINheighttrue}
+\define@key{pdfgraphic}{scale}     {\gdef\@PDFgraphicscale{#1}\global\@pdfGINscaletrue}
+\define@key{pdfgraphic}{color}     {\gdef\@PDFgraphiccolor{#1}}
+\define@key{pdfgraphic}{linecolor} {\gdef\@PDFgraphiclinecolor{#1}}
+\define@key{pdfgraphic}{background}{\gdef\@PDFgraphicbackground{#1}}
+\define@key{pdfgraphic}{linewidth} {\gdef\@PDFboxrule{#1}}
+\define@key{pdfgraphic}{rulesep}   {\gdef\@PDFboxsep{#1}}
+\gdef\@PDFgraphiccolor{black}
+\gdef\@PDFgraphiclinecolor{white}
+\gdef\@PDFgraphicbackground{white}
+\gdef\@PDFboxrule{0pt}
+\gdef\@PDFboxsep{0pt}
+%%
+%% Tweak to grab all the packages used in the master doc.
+%% This forces you to load pdftricks as the first package.
+%%
+\newenvironment{psinputs}{\begingroup
+ \newwrite\CVinputs
+ \immediate\openout\CVinputs=tmp.inputs
+  \def\usepackage{\@ifnextchar[\@CVUsepackage\@@CVUsepackage}
+  \def\@CVUsepackage[##1]##2{\immediate\write\CVinputs%
+     {\string\usepackage[##1]{##2}}}
+  \def\@@CVUsepackage##1{\immediate\write\CVinputs%
+     {\string\usepackage{##1}}}
+ }
+ {\endgroup\immediate\closeout\CVinputs}
+%%
+%% Arrays to keep the fig numbers
+%%
+\newcounter{arraylength}%
+\newcounter{ArrayIndex}%
+\newcounter{zeroCtr}%
+\newcounter{recordCtr}
+\setcounter{recordCtr}{1}
+\newcounter{Ctr}
+\def\DeclareArray#1{\Array{#1}[0]{}}%
+%
+\def\Array#1[#2]#3{%
+      \expandafter\gdef\csname #1#2\endcsname{#3}%
+      \expandafter\gdef\csname #1\endcsname[##1]{\csname #1##1\endcsname}}%
+%
+\def\getArraylength#1{\setcounter{arraylength}{0}%
+   \loop\expandafter\ifx\csname #1\thearraylength\endcsname\relax%
+   \else\stepcounter{arraylength}\repeat}%
+%
+\def\addToArray#1#2{\setcounter{arraylength}{0}%
+   \loop\expandafter\ifx\csname #1\thearraylength\endcsname\relax%
+   \else\stepcounter{arraylength}\repeat%
+   \Array{#1}[\thearraylength]{#2}}%
+%
+\def\clearArray#1{\getArraylength{#1}%
+   \loop\ifnum\c@arraylength >0%
+   \global\expandafter\let\csname #1\thearraylength\endcsname\relax%
+   \addtocounter{arraylength}{-1}\repeat}%
+%
+\long\def\ArrayIterator#1#2{%
+   \setcounter{ArrayIndex}{1}\getArraylength{#1}%
+   \setcounter{zeroCtr}{\c@arraylength}%
+   \loop\ifnum\c@ArrayIndex<\c@zeroCtr{#2}%
+   \stepcounter{ArrayIndex}\repeat%
+}%
+\def\@nnil{\@nil}
+\def\@empty{}
+\def\@cvrstop#1\@@#2{}
+%%
+%% Equivalent of \@tfor and \@for where any delimiter can be 
+%% provided instead of LaTeX's default comma character
+%%
+\long\def\cvr@delimfor#1#2#3{\DeclareArray{#1}\clearArray{#1}%
+   \long\def\@icvrloop##1#2##2\@@##3{\def##3{##1}\ifx ##3\@nnil%
+   \expandafter\@cvrstop \else\addToArray{#1}{##1}%
+    \relax\expandafter\@icvrloop\fi##2\@@##3}%
+   \long\def\@cvrloop##1#2##2#2##3\@@##4{\addToArray{#1}{##1}%
+   \def##4{##1}\ifx ##4\@nnil \else%
+    \def##4{##2}\def\y@y{##2}\ifx\y@y\@nnil\else%
+         \addToArray{#1}{##2}\fi\ifx ##4\@nnil \else%
+      \@icvrloop ##3\@@##4\fi\fi}%
+  \expandafter\def\expandafter\@fortmp\expandafter{#3}%
+  \ifx\@fortmp\@empty \else%
+    \expandafter\@cvrloop#3#2\@nil#2\@nil\@@\@ee@\fi}%
+%
+% Dont look into the following code. It is harmful
+% for your eyes and brain as well.
+%
+\newcounter{f@irstCtr}
+\newcounter{s@econdCtr}
+\long\gdef\NoProcess[#1]{%
+   \long\def\@i@@noprocess##1,##2\@@##3{\def##3{##1}\ifx ##3\@nnil%
+   \expandafter\@cvrstop \else
+      \expandafter\hyphencheck##1-@-*[*]
+    \relax\expandafter\@i@@noprocess\fi##2\@@##3}%
+   \long\def\@@@noprocess##1,##2,##3\@@##4{
+      \expandafter\hyphencheck##1-@-*[*]
+   \def##4{##1}\ifx ##4\@nnil \else%
+    \def##4{##2}\def\y@y{##2}\ifx\y@y\@nnil\else%
+      \expandafter\hyphencheck##2-@-*[*]
+         \fi\ifx ##4\@nnil \else%
+      \@i@@noprocess ##3\@@##4\fi\fi}%
+  \expandafter\def\expandafter\@fortmp\expandafter{#1}%
+  \ifx\@fortmp\@empty \else%
+    \expandafter\@@@noprocess#1,\@nil,\@nil\@@\@ee@\fi}%
+\def\d@d#1[*]{}
+\def\hyphencheck#1-#2-#3{\def\r@r{@}\def\s@s{*}\edef\c@c{#3}
+   \ifx\c@c\r@r
+   \setcounter{f@irstCtr}{#1}
+   \setcounter{s@econdCtr}{#2}
+   \stepcounter{s@econdCtr}
+   \loop\ifnum\thes@econdCtr > \thef@irstCtr% 
+      \expandafter\edef\csname Fig\thef@irstCtr\endcsname{TRUE}
+      \stepcounter{f@irstCtr}
+   \repeat%
+   \else\ifx\c@c\s@s% 
+      \expandafter\edef\csname Fig#1\endcsname{TRUE}
+   \fi\fi\d@d}
+
+%%
+%%
+%% End of file `pdftricks.sty'
+%%
similarity index 66%
rename from doc/reference.xml
rename to doc/reference/reference.xml
index 15b8da4..4850109 100644 (file)
@@ -1,8 +1,8 @@
 <ibex-doc title="The Ibex Reference" subtitle="Nitrogen Release" author="Adam Megacz" email="adam@ibex.org">
 
 <!-- ----------------------------------------------------------------------- -->
 <ibex-doc title="The Ibex Reference" subtitle="Nitrogen Release" author="Adam Megacz" email="adam@ibex.org">
 
 <!-- ----------------------------------------------------------------------- -->
-<section title="Preface">
-    
+<section title="Introduction">
+
     <i>
     If you are reading the html version of this document and are
     thinking of printing it out, you might be interested in the nicely
     <i>
     If you are reading the html version of this document and are
     thinking of printing it out, you might be interested in the nicely
     aspect of the environment that the Ibex Core provides to client
     applications, from the bottom up. If you want to be an Ibex expert,
     this is the right document to read. It is assumed that you are already
     aspect of the environment that the Ibex Core provides to client
     applications, from the bottom up. If you want to be an Ibex expert,
     this is the right document to read. It is assumed that you are already
-    familiar with XML and with either JavaScript or ECMAscript. If
-    you are not familiar with ECMAscript, some reference materials are
-    provided in <link appendix="G"/>
-    
-    The <i>wildebeest sequence</i> (how the Ibex Core gets onto the
-    client's computer, and how it knows where to download the initial
-    <t>.ibex</t> from) is not described in this document, since it
-    will be different for every platform that Ibex is ported to.
+    familiar with XML and with either JavaScript or ECMAscript.
     
     If you need to use or rely on some behavior you notice in the Ibex
     Core, but which is not clearly defined here, please post to <link
     
     If you need to use or rely on some behavior you notice in the Ibex
     Core, but which is not clearly defined here, please post to <link
   
     <definition term="The Core">
          Ibex itself; the native code (or Java bytecode) that runs on
   
     <definition term="The Core">
          Ibex itself; the native code (or Java bytecode) that runs on
-         the client.  This term does not include the <i>wildebeest</i>
+         the client.  This term does not include the <i>Wildebeest</i>
          or the <i>UI</i></definition>
   
     <definition term="The UI / The Application">
          or the <i>UI</i></definition>
   
     <definition term="The UI / The Application">
-         a set of files (mostly XML, JavaScript, and PNG images)
-         bundled up in a zip archive, ending with the "..ibex"
+         A set of files (mostly XML, JavaScript, and PNG images)
+         bundled up in a zip archive, ending with the "<t>.ibex</t>"
          extension.  Together, these files specify the appearance and
          extension.  Together, these files specify the appearance and
-         behavior of the application's user interface.  Sometimes
-         we'll refer to this as the ".ibex" to be clear that we're
-         talking about the actual zip archive, rather than its visual
-         appearance when rendered on the screen.</definition>
+         behavior of the application's user interface.
+         </definition>
   
     <definition term="The Server">
          We will use the term "the server" to refer to any other
   
     <definition term="The Server">
          We will use the term "the server" to refer to any other
          to. Note that it is possible for the client and server to be
          the same machine.</definition>
   
          to. Note that it is possible for the client and server to be
          the same machine.</definition>
   
-    <definition term="The Wildebeest">
-         this is a very small piece of code that is downloaded the
+    <definition term="Wildebeest">
+         This is a very small piece of code that is downloaded the
          first time a client uses Ibex. It downloads the Ibex core,
          verifies its signature, and launches it with the appropriate
          first time a client uses Ibex. It downloads the Ibex core,
          verifies its signature, and launches it with the appropriate
-         parameters indicating where to find the initial UI.  The
+         parameters indicating where to find the initial UI.
          Wildebeest works differently on every platform, and is outside
          the scope of this document.</definition>
   
          Wildebeest works differently on every platform, and is outside
          the scope of this document.</definition>
   
         We will use the terms JavaScript and ECMAScript
         interchangeably in this document.  The Ibex interpreter is not
         completely ECMA-compliant, however (see <link
         We will use the terms JavaScript and ECMAScript
         interchangeably in this document.  The Ibex interpreter is not
         completely ECMA-compliant, however (see <link
-        appendix="C"/> for details).  </definition>
-  </section>
-</section>
-    
-<section title="Surfaces">
-
-  Each top-level window in an Ibex UI is called a
-  <i>surface</i>. There are two kinds of surfaces: <i>frames</i>,
-  which usually have a platform-specific titlebar and border, and
-  <i>windows</i>, which never have any additional platform-specific
-  decorations.
-    
-  Whenever we refer to the size or position of a surface, we are
-  referring to the size or position of the UI-accessible portion of the
-  surface; this does not include any platform-specific decorations. This
-  means that if you set the position of a frame to (0,0), the
-  platform-specific titlebar will actually be off the screen on most
-  platforms (it will be above and to the left of the top-left corner of
-  the screen).
-    
-  Surfaces are not actual JavaScript objects; you cannot obtain a
-  reference to a surface.  However, each surface is uniquely identified
-  by its <i>root box</i>, described in the next section.
-    
-</section>
+        appendix="ECMAscript compliance"/> for details).
+        </definition>
 
 
-<section title="Boxes">
+  </section>
 
 
-  A <i>box</i> is the fundamental unit from which all Ibex user
-  interfaces are built.  Boxes can contain other boxes (known as
-  <i>children</i>).  Each Surface has a single box associated with it
-  called the <i>root box</i>; the root box and its children (and its
-  children's children, and so on) form the surface's <i>box tree</i>.
-    
-  There are three ways to think of a box: as a rendered visualization on
-  the screen (the "Visual Representation"), as a JavaScript object (the
-  "Object Representation"), and as an XML tag (the "XML
-  Representation").
-    
-  FIXME: diagram here
-    
-  All three representations are equally valid, and being able to figure
-  out what an action in one representation would mean in terms of the other
-  two representations is crucial to a solid understanding of Ibex.
-    
-  <section title="The Object Representation">
+  <section title="Life Cycle of an Ibex Application">
+  
+    <image url="lifecycle.pdf" caption="The Lifecycle of an Ibex Application"/>
+
+    A user typically begins an Ibex session by clicking on a link to
+    an Ibex application.  This link serves the {\tt launch.html} file
+    to the user's browser, which in turn downloads the appropriate
+    {\it Wildebeest} -- currently either an ActiveX Control
+    (Win32/MSIE), XPInstaller (Mozilla), or Signed Applet (all
+    others).
+
+    The Wildebeest downloads the appropriate core for the user's
+    machine and verifies its digital signature.  It then launches the
+    core, which downloads the UI (an <t>.ibex</t> archive), loads it,
+    applies the <t>main.t</t> template (found in the archive), and
+    renders it onto the screen, running any associated JavaScript
+    code.
+      
+    The user interacts with the application by clicking and moving the
+    mouse, and by pressing keys on the keyboard.  These actions trigger
+    fragments of JavaScript code which are designated to handle events.
+    This JavaScript code can then relay important information back to the
+    server using XML-RPC or SOAP, or it can modify the structure and
+    properties of the user interface to change its appearance, thereby
+    giving feedback to the user.
+      
+    The Ibex core quits when the last remaining surface has been destroyed.
 
 
-    Each box is a full-fledged ECMAscript object, and can store key-value
-    pairs as properties.  Some of these keys have special meaning, which
-    will be explained later.  Each box's numeric properties hold its
-    <i>child boxes</i>. 
-    
   </section>
 
   </section>
 
-  <section title="The Visual Representation">
 
 
-    Each box occupies a rectangular region on the surface.  The visual
-    appearance of a surface is created by rendering each box in its tree.
-    Unless the <t>clip</t> attribute is <t>false</t>, each box will
-    clip its childrens' visual representations to its own, so that the
-    children appear "confined to" the parent.  Children are rendered after
-    their parents so they appear "on top of" their parents (they obscure
-    them).
-    
-    Each box has two major visual components, each with subcomponents:
-    
-    FIXME: diagram
-    
+  <section title="Surfaces">
+  
+    <image url="offscreen.pdf" width="2in"
+           caption="An Ibex surface positioned at (83,0)"/>
+    Each top-level window in an Ibex UI is called a
+    <i>surface</i>. There are two kinds of surfaces: <i>frames</i>,
+    which usually have a platform-specific titlebar and border, and
+    <i>windows</i>, which never have any additional platform-specific
+    decorations.
+    
+    Whenever we refer to the size or position
+    of a surface, we are referring to the size or position of the
+    UI-accessible portion of the surface; this does not include any
+    platform-specific decorations. This means that if you set the
+    position of a frame to (0,0), the platform-specific titlebar will
+    actually be off the screen on most platforms (it will be above and
+    to the left of the top-left corner of the screen).
+
+    Surfaces are not actual JavaScript objects; you cannot obtain a
+    reference to a surface.  However, each surface is uniquely identified
+    by its <i>root box</i>, described in the next section.
+      
+  </section>
+  
+  <section title="Boxes">
+  
+    A <i>box</i> is the fundamental unit from which all Ibex user
+    interfaces are built.  Boxes can contain other boxes (referred to as
+    its <i>children</i>).  Each surface has a single box associated with
+    it called the <i>root box</i>; the root box and its children (and
+    its children's children, and so on) form the surface's <i>box
+    tree</i>.
+     
+    There are three ways to think of a box:
     <list>
     <list>
-        A <b>path</b>, which consists of zero or more lines and
-        curves.  The path may be filled with a color, gradient, or
-        texture, and may be stroked with a line of a given thickness
-        and color.  If the path is not specified, it defaults to the
-        perimiter of the box.
-
-        <list>
-            The path has an associated <b>strokecolor</b>, which is a
-            color
-
-            The path has an associated <b>strokewidth</b>, which is a
-            number specifying the width of the stroke.
-            
-            The path also has a <b>fill</b>, which is either a color, gradient, or
-            texture
-        
-            A single line of <b>text</b>, which can be rendered in
-            different fonts, colors, and sizes.
-        </list>
-
-        The text has an associated <b>font</b>, which currently can be
-        any font supported by the <link url="http://www.freetype.org"
-        text="FreeType2"/> library.
-            
-        The text also has an associated <b>fontsize</b>
-            
-        The text is drawn in an associated <b>textcolor</b>
-
+  
+        As a rendered visualization on the screen (the "<i>Visual Representation</i>")
+  
+        As a JavaScript object (the "<i>Object Representation</i>")
+  
+        As as an XML tag (the "XML Template Representation").
+  
     </list>
 
     </list>
 
-    These eight components plus the size of a box fully specify its
-    appearance.  Every single box you see in Ibex is drawn only on the
-    basis of these components and its size.
-    
+    <image url="threeviews.pdf" caption="The three representations of an Ibex box"/>
+  
+    All three representations are equally valid, and being able to
+    figure out what an action in one representation would mean in terms
+    of the other two representations is crucial to a solid understanding
+    of Ibex.
+      
   </section>
   </section>
+</section>
+  
+<section title="The XML Template Representation">
+
+  A template (discussed in the next section) is an XML file which acts
+  as a blueprint for constructing a tree of boxes.  We call this
+  construction process <i>applying</i>, since unlike
+  <i>instantiation</i> in object-oriented programming systems, you
+  always apply a template to a pre-existing box, and you can apply
+  multiple templates to the same box.
+
+  Each XML tag corresponds to a single box, or to another template
+  which will be applied to that box.  For example, a <t>scrollbar</t>
+  template, when applied, will construct a tree of boxes which has the
+  visual appearance and behavior of a scrollbar.
+    
+  Although it is useful to think of the XML tags as being boxes, keep
+  in mind that the XML representation is only a blueprint for
+  constructing a tree of JavaScript objects.  Once the template has
+  been instantiated, the XML is effectively "thrown away", and
+  JavaScript code is free to alter the boxes.  Once the process of
+  applying a template is complete, Ibex completely forgets the fact
+  that it has applied a particular template to a particular box.  One
+  consequence of this approach is that if you think of templates as
+  classes, then Ibex has no equivalent for Java's <t>instanceof</t>
+  operator.
+
+  Each template is an XML document whose root element is
+  <t>&lt;ibex></t>.  Here is a sample template file:
 
 
-  <section title="The XML Representation">
+  <pre>
+  <ibex xmlns:lib="ibex.lib">
 
 
-    A template (discussed in the next section) is an XML file which acts
-    as a blueprint for constructing a tree of boxes.  We call this
-    construction process <i>applying</i>, since unlike
-    <i>instantiation</i>, you always apply a template to a pre-existing
-    box, and you can apply multiple templates to the same box.  Each XML
-    tag corresponds to a single box, or to another template which will be
-    applied to that box.  For example, a <t>scrollbar</t> template, when
-    applied, will construct a tree of boxes which has the visual
-    appearance and behavior of a scrollbar.
-    
-    Although it is useful to think of the XML tags as being boxes, keep in
-    mind that the XML representation is only a blueprint for constructing
-    a tree of JavaScript objects.  Once the template has been
-    instantiated, the XML is effectively "thrown away", and JavaScript code is
-    free to alter the boxes.
-    
-  </section>
-</section>
+      <meta:doc>
+          This is a cool widget.
+      </meta:doc>
 
 
-<section title="Templates">
+      // this code is executed only once
+      static = { instances : [] };
 
 
-  Each template is an XML document whose root element
-  is <t>&lt;ibex></t>.  Any text content of the root element is
-  ignored, and may safely be used for comments.  The root element may
-  have any of the following elements as children, each of which may
-  appear no more than once, and which must appear in this order:
-    
-  Here is a sample Ibex file:
-    
-  <pre>
-  <ibex xmlns="ibex.widget" xmlns:lib="ibex.lib">
-      This is a sample Ibex file. Text up here is ignored.
-      Copyright (C) 2004 Mustapha Mond.
-      <static>
-          // code here will be executed only once
-      </static>
-      <template cols="5">
-          <box id="container"/>
-          <checkbox/>
-          <box>
-              /* This has to be commented out or else it
-                 will be treated as a script */
+      // this element applies the ibex.lib.focusable template
+      <lib:focusable/>
+
+      <ui:box cols="5">
+          static.instances.push(thisbox);
+          <ui:box id="container"/>
+          <ui:checkbox/>
+          <ui:box>
               <lib:scrollbar/>
               <lib:scrollbar/>
-          </box>
-      </template>
+          </ui:box>
+      </ui:box>
   </ibex>
   </pre>
   </ibex>
   </pre>
-    
-  <heading title="Applying an XML Tag to a Box"/>
 
 
-    The following description of the box application is extremely detailed
-    and precise; it is intended for UI designers who need to know the
-    exact order in which each event happens.  FIXME:
-    easier description.  While this whole process sounds very
-    complex, it actually works pretty intuitively. The description below
-    is given in great detail since most applications will wind up being
-    unintentionally dependent on subtle features of this process.
-    However, most of the time you can just pretend that the XML tags and
-    the boxes are the same thing.
-    
-    To apply an XML tag <t><b>X</b></t> to a box <t><b>B</b></t>, perform the following
-    operations, in this order:
-    
-    <list type="ordered">
+  The following two namespaces are predefined and need not be declared
+  using <t>xmlns</t>:
 
 
-        Allocate a fresh scope <t><b>s</b></t> whose parent scope is
-        <t><b>b</b></t>.
-        
-        Process each child element or text segment of <t><b>X</b></t> in the
-        order they appear in the document: For each <i>text
-        segment</i> <t><b>t</b></t>:
+  <definition term="meta">
+      <t>http://xmlns.ibex.org/meta</t>
 
 
-        <list>
-            Treat <t><b>t</b></t> a JavaScript script, and execute it
-            with <t><b>s</b></t> as the root scope.
-        </list>
+      This will be referred to as the "<t>meta</t> namespace" in the
+      remainder of this document.
+      </definition>
 
 
-        For each child element <t><b>x</b></t> of
-        <t><b>x</b></t>:
+  <definition term="ui">
+      <t>http://xmlns.ibex.org/ui</t>
 
 
-        <list>
-            Create a new box <t><b>b</b></t>.
-            
-            If the name of tag <t><b>x</b></t> is not "<t>box</t>" (in the
-            default XML namespace), prepend the tag's namespace
-            identifier uri (if any) to the name of the tag, and use
-            the result as a key to retrieve a property from the root
-            stream (defined later).  Interpret the resulting stream as
-            a template and apply that template to <t><b>b</b></t>.
-            
-            (recursively) apply <t><b>x</b></t> to <t><b>b</b></t>.
-            
-            If <t><b>x</b></t> has an <t>id</t> attribute, declare a variable
-            in <t><b>s</b></t> whose name is the value of the <t>id</t>
-            attribute, prefixed with the <t>$</t> character, and whose
-            value is <t><b>b</b></t>
-            
-            Copy any <t>$</t>-variables created during the application
-            of <t><b>x</b></t> into scope <t><b>s</b></t>.
-            
-            Append <t><b>b</b></t> as the last child of <t><b>b</b></t>.
-        </list>
-        
-        Apply any attributes on <t><b>x</b></t> to <t><b>b</b></t>, except for
-        <t>id</t>.  Since XML specifies that the order of attributes
-        cannot be significant, Ibex processes attributes in
-        alphabetical order by attribute name.  For example, if
-        <t><b>x</b></t> has the attribute <t>foo="bar</t>", then the
-        equivalent of the statement <t>B.foo="bar";</t> will be
-        performed, with the following exceptions:
+      This will be referred to as the "<t>ui</t> namespace" in the
+      remainder of this document.
+      </definition>
 
 
-        <list>
-            If the value portion of the attribute is the string
-            "<t>true</t>", put the boolean <t>true</t>. If the
-            value is "<t>false</t>", put the boolean <t>false</t>.
-        
-            If the value is a valid ECMAscript number, put it as a
-            number (instead of a string).
-                 
-            If the value begins with a dollar sign (<t>$</t>),
-            retrieve the value of the corresponding variable in
-            <t><b>s</b></t> and use that value instead.
-         
-            If the value begins with a dot (<t>.</t>), prepend the
-            attributes' namespace identifier uri (if any) and
-            interpret the remainder as a property to be retrieved from
-            the root stream (defined later).
-        </list>
-    </list>
+  Additionally, the default namespace for the document will be set to
+  the template's package FIXME.
 
 
-    The last two steps are referred to as the <i>initialization</i> of the
-    node.  There are two important aspects of this ordering to be aware of:
-             
-    <list type="unordered">
-
-        A given box will be fully initialized before its parent is
-        given a reference to that box.  This way, parents can be
-        certain that they will never wind up accessing a box when it
-        is in a partially-initialized state.
-        
-        Attributes are applied <i>after</i> scripts are run so that
-        the attributes will trigger any <i>traps</i> (defined later)
-        placed by the script.
-
-    </list>
-    
-</section>
-
-<section title="Life Cycle of an Ibex Application">
-
-  A user begins by specifying the URL of an Ibex application run.
-  Usually this is done by visiting a web page which uses the
-  <i>wildebeest</i> to install the core if it is not already on the user's
-  machine, but you can also supply the URL on the command line.
-    
-  The Ibex Core downloads the .ibex for the application, loads it, applies
-  the <t>main.ibex</t> template and renders it onto the screen, running
-  any associated ECMAscript code.
-    
-  The user interacts with the application by clicking and moving the
-  mouse, and by pressing keys on the keyboard.  These actions trigger
-  fragments of JavaScript code which are designated to handle events.
-  This JavaScript code can then relay important information back to the
-  server using XML-RPC or SOAP, or it can modify the structure and
-  properties of the user interface to change its appearance, thereby
-  giving feedback to the user.
-    
-    
-  DIAGRAM: graphic here showing the circular feedback cycle.
-    
-    
-  The Ibex core quits when the last remaining surface has been destroyed.
-    
-</section>
+  <section title="Static Code">
 
 
-<!-- ----------------------------------------------------------------------- -->
-<section title="Layout and Rendering">
+    If the root <t>&lt;ibex&gt;</t> element contains any non-whitespace
+    text content, this text is interpreted as JavaScript code and is
+    executed the first time the template is referenced.  This code is
+    executed in a fresh scope containing two predefined properties:
+  
+    <definition term="ibex">
+      The Ibex Object (described in <ref section="The Ibex Object"/>)
+      </definition>
+  
+    <definition term="static">
+      A reference to this template's <i>static object</i>, which is
+      initially <t>null</t>.  The static object can be accessed (read
+      and written) from both static scripts as well as instance
+      scripts in a particular template. FIXME
+      </definition>
 
 
-    The size and position of every other box is determined
-    by its properties, its childrens' sizes, and its parent's size and position.
-    Box layout and rendering happens in four phases: <i>packing</i>,
-    <i>constraining</i>, <i>placing</i>, and <i>rendering</i>.  The Core is careful to only
-    perform a phase on a box if the box has changed in a way that
-    invalidates the work done the last time that phase was performed.
-      The
-    packing and constraining phases are performed in a single traversal of
-    the tree (packing is preorder, constraining is postorder), and the
-    placing and rendering phases are performed in a second traversal of
-    the tree (first placing, then rendering, both preorder).
-    
-    For brevity, the rest of this chapter deals only with width and
-    columns.  Height and rows is treated identically and independently.
-    Also, it is important to note that the term <i>minimum width</i> is
-    not the same thing as the property <t>minwidth</t>, although they
-    are closely related.
-    
-  <section title="The size of the root box">
-
-    When the user resizes a window, Ibex changes the root box's
-    <t>maxwidth</t> and <t>maxheight</t> to match the size chosen by
-    the user and then determines the root box's size using the same sizing
-    rules it uses for other boxes.
-    
-    Ibex will always attempt to prevent the
-    user from making the surface smaller than the root box's
-    <t>minwidth</t> and <t>minheight</t>.  If the <t>hshrink</t> or
-    <t>vshrink</t> flag is set, Ibex will try to prevent the user from
-    resizing the surface at all.  However, not all platforms give Ibex
-    enough control to do this.
-    
     </section>
     </section>
+  
+  <section title="Metadata">
 
 
-  <section title="The alignment point">
-
-    When talking about positioning, we will often refer to the
-    <i>alignment point</i>.
-    
-    <list type="unordered">
-
-        If the <t>align</t> property is "<t>center</t>", then the
-        alignment point is the center of the box.
-        
-        If the <t>align</t> property is "<t>topleft</t>",
-        "<t>bottomleft</t>", "<t>topright</t>", or
-        "<t>bottomright</t>", then the alignment point is
-        corresponding corner of the box.
-        
-        If the <t>align</t> property is "<t>top</t>",
-        "<t>bottom</t>", "<t>right</t>", or "<t>left</t>", then
-        the alignment point is middle of the corresponding edge of the
-        box.
-
+    Any immediate children of the root element which are in the
+    <t>meta</t> namespace are treated as metadata and are exempted from
+    the rest of the template application process.  Currently only one
+    type of metadata element is defined:
+  
+    <list>
+        <t>&lt;meta:doc&gt;</t>: structured documentation for the
+        template.
     </list>
 
     </list>
 
-    FIXME: diagram
-    
-    When positioning a child box, the alignment point is determined by the
-    <i>parent's</i> <t>align</t> property.  When positioning a visual
-    element (a texture, path, or text string) within a box, the alignment
-    point is determined by the <i>box's own</i> <t>align</t> property.
-    
-    A simple way to think about this is that whenever there are two boxes
-    involved in the decision, you should use the parent's alignment point.
-    
-    </section>
-
-  <section title="Packing">
-
-    of <i>cells</i> is created within the parent.  If the parent's
-    <t>cols</t> property is set to 0, the cell grid has an infinite
-    number of columns.  Either <t>cols</t> or <t>rows</t> must be
-    zero, but not both.
-        
-    If a child's <t>visible</t> property is <t>false</t>, it does
-    not occupy any cells (and is not rendered).  Otherwise, each child
-    occupies a rectangular set of cells <t>child.colspan</t> cells
-    wide and <t>child.rowspan</t> cells high.
-        
-    The Core iterates over the cells in the grid in the following
-    order: if <t>rows</t> is 0, the Core iterates across each column
-    before proceeding to the next row; otherwise rows come before
-    columns.  At each cell, the Core attempts to place the <i>first
-    remaining unplaced child's</i> top-left corner in that cell (with
-    the child occupying some set of cells extending down and to the
-    right of that cell).  If the parent has a fixed number of columns
-    and the child's <t>colspan</t> exceeds that limit, the child is
-    placed in column zero regardless, but only occupies the available
-    set of cells (it does not "hang off the end" of the box).
-    
-    <image url="image/layout.png"/>
-    
-    <pre>
-    <box cols="3">
-        <box id="1" />
-        <box id="2" rowspan="2" />
-        <box id="3" colspan="2" />
-        <box id="4" />
-        <box id="5" colspan="2" />
-    </box>
-    </pre>
-    
-    Notes on the layout example:
-    
-    <list type="ordered">
+  </section>
 
 
-        Box '3' doesn't fit in the gap after '2', nor in the gaps either
-        side of '2' on the next row, hence it is pushed onto the 3rd row.
+  <section title="Other Elements">
 
 
-        Box '4' would fit in the gaps around '2', but must be placed
-        <i>after</i> it's preceeding box, '3'.
+    All remaining children of the root element are treated as elements
+    to be <i>applied</i> to the box, in the order in which they appear
+    in the file using the following procedure.
+  
+    <remark text="While this process outlined below sounds very
+                  complex, it actually works pretty intuitively. The
+                  description below is given in great detail since
+                  most applications will wind up being unintentionally
+                  dependent on subtle features of this process.
+                  However, most of the time you can just pretend that
+                  the XML tags and the boxes are the same thing."/>
+
+      <heading title="Intuitive Description"/>
+
+      ... FIXME
+
+      During a box initialization, script-private references to a
+      box's descendants with <t>id</t> attributes are placed on the
+      box. These references allow scripts on that box to easily refer
+      to descendant nodes created by the template in which the script
+      appears. For example, these two blocks of code have exactly the
+      same effect:
+      
+      <pre>
+      <ui:box>                           <ui:box>
+          <ui:box id="foo"/>                 <ui:box/>
+          $foo.color = "red";             var $foo = this[0];
+                                          $foo.color = "red";
+      </ui:box>                          </ui:box>
+      </pre>
+
+      <heading title="Precise Description"/>
+  
+      To apply an XML tag <t><b>x</b></t> to a box <t><b>b</b></t>, perform the following
+      operations, in this order:
+      
+      <list type="ordered">
+  
+          Allocate a fresh scope <t><b>s</b></t> whose parent scope is
+          <t><b>b</b></t>.
+          
+          Process each child element or text segment of <t><b>x</b></t>
+          in the order they appear in the document:
+  
+          <list>
+  
+              Treat each text segment <t><b>t</b></t> as JavaScript code
+              and execute it with <t><b>s</b></t> as the root scope.
+  
+              For each child element <t><b>x'</b></t> of <t><b>x</b></t>:
+  
+              <list>
+                  Create a new box <t><b>b'</b></t>.
+                  
+                  If the name of tag <t><b>x'</b></t> is not
+                  "<t>box</t>" in the <t>ui</t> namespace, prepend the
+                  tag's namespace identifier uri (if any) to the name of
+                  the tag, and use the result as a key to retrieve a
+                  property from the root stream (defined later).
+                  Interpret the resulting stream as a template and apply
+                  that template to <t><b>b'</b></t>.
+                  
+                  (recursively) apply <t><b>x'</b></t> to <t><b>b'</b></t>.
+                  
+                  If <t><b>x'</b></t> has an <t>id</t> attribute, declare a variable
+                  in <t><b>s</b></t> whose name is the value of the <t>id</t>
+                  attribute, prefixed with the <t>$</t> character, and whose
+                  value is <t><b>b'</b></t>
+                  
+                  Copy any <t>$</t>-variables created during the application
+                  of <t><b>x'</b></t> into scope <t><b>s</b></t>.
+                  
+                  Append <t><b>b'</b></t> as the last child of <t><b>b</b></t>.
+              </list>
+          </list>
+          
+          Apply any attributes on <t><b>x</b></t> to <t><b>b</b></t>, except for
+          <t>id</t>.  Since XML specifies that the order of attributes
+          cannot be significant, Ibex processes attributes in
+          alphabetical order by attribute name.  For example, if
+          <t><b>x</b></t> has the attribute <t>foo="bar"</t>, then the
+          equivalent of the statement <t>B.foo="bar";</t> will be
+          performed, with the following exceptions:
+  
+          <list>
+              If the value portion of the attribute is the string
+              "<t>true</t>", put the boolean <t>true</t>. If the
+              value is "<t>false</t>", put the boolean <t>false</t>.
+          
+              If the value is a valid ECMAscript number, put it as a
+              number (instead of a string).
+                   
+              If the value begins with a dollar sign (<t>$</t>),
+              retrieve the value of the corresponding variable in
+              <t><b>s</b></t> and use that value instead.
+           
+              If the value begins with a dot (<t>.</t>), prepend the
+              attributes' namespace identifier uri (if any) and
+              interpret the remainder as a property to be retrieved from
+              the root stream (defined later).
+          </list>
+      </list>
+
+      <heading title="Initialization Invariants"/>  
+
+      The last two steps are referred to as the <i>initialization</i> of the
+      node.  There are two important aspects of this ordering to be aware of:
+               
+      <list type="unordered">
+  
+          A given box will be fully initialized before its parent is
+          given a reference to that box.  This way, parents can be
+          certain that they will never wind up accessing a box when it
+          is in a partially-initialized state.
+          
+          Attributes are applied <i>after</i> scripts are run so that
+          the attributes will trigger any <i>traps</i> (defined later)
+          placed by the script.
+  
+      </list>
 
 
-    </list>
+  </section>
     
     
-    </section>
-
-  <section title="Constraining">
-
-    <list type="ordered">
-        
-        Each box's minimum width is computed recursively as the
-        maximum of:
-
-        <list>
-            Its <t>minwidth</t>
-             
-            The width of the box's <t>text</t> (after applying the
-            box's <t>transform</t>).
-             
-            The width of the box's path (after applying the box's
-            <t>transform</t>) <i>if the box is <t>packed</t></i>.
-             
-            The width of the bounding box enclosing the box's cells.
-        </list>
-        
-        The minimum width of each cell is computed as the minimum
-        width of the box occupying it divided by the box's
-        <t>colspan</t>.
-        
-        If a box's <t>hshrink</t> property is set to
-        <t>true</t>, the box's maximum width is the same as its
-        minimum width; otherwise it is the box's
-        <t>maxwidth</t>.
-        
-        The maximum width of each cell is the <t>maxwidth</t> of
-        the box occupying it divided by the box's
-        <t>colspan</t>.
-
-    </list>
-
-    </section>
-
-  <section title="Placing">
-
-    <list type="ordered">
-        
-        Each column's <i>actual width</i> is set to the maximum
-        <i>minimum width</i> of all the cells in that column.
-        <b>NOTE:</b> although a column or row can be sized smaller
-        than its "minimum width" or larger than its "maximum width", a
-        box will <i>never</i> be smaller than its <t>minwidth</t> or
-        larger than its <t>maxwidth</t>.
-        
-        Each column's maximum width is the largest maximum width of
-        the cells in that column, but no smaller than the column's
-        minimum width.
-        
-        The <i>slack</i> is the difference between the parent's width
-        and the sum of its columns' actual width.  The slack is
-        divided equally among the columns.  Any column which has
-        exceeded its maximum width is set to its maximum width, and
-        the difference is returned to the slack.  This process is
-        repeated until the slack is zero or all columns are at their
-        maximum width.
-        
-        Next, the rows and columns are positioned within the parent
-        box.  The rows and columns are transformed according to the
-        parent's <t>transform</t> property, and the bounding box of
-        the resulting cells are placed such that the cells' alignment
-        point coincides with the parent's alignment point (both
-        alignment points are determined by the parent's <t>align</t>
-        property).  FIXME: diagram
-    
-        <b>Packed boxes:</b> Each packed box's actual position
-        and size is then set to the aggregation of the actual sizes of
-        the cells it spans.  If this size exceeds the box's maximum
-        width, the box is sized to its maximum width and centered
-        horizontally within the space occupied by its cells.
-
-        <b>Non-packed boxes</b>: each non-packed box is transformed
-        according to the parent's <t>transform</t> property and then
-        positioned so that its alignment point is <t>(child.x,
-        child.y)</t> pixels from the parent's alignment point (both
-        alignment points are determined by the parent's <t>align</t>
-        property).
-        
-    </list>
+</section>
 
 
-    </section>
+<!-- ----------------------------------------------------------------------- -->
+<section title="Layout and Rendering">
 
 
+    <section title="Visual Components">
+  
+      Each box occupies a rectangular region on the surface.  The visual
+      appearance of a surface is created by rendering each box in its tree.
+      Unless the <t>clip</t> attribute is <t>false</t>, each box will
+      clip its childrens' visual representations to its own, so that the
+      children appear "confined to" the parent.  Children are rendered after
+      their parents so they appear "on top of" their parents.
+      
+      Each box has two major visual components, each with subcomponents:
+      
+      FIXME: diagram
+      
+      <definition term="path">
+  
+          A box's <t>path</t> consists of zero or more lines and curves.
+          The path may be filled with a color, gradient, or texture, and
+          may be stroked with a line of a given thickness and color.  If
+          the path is not specified, it defaults to the perimiter of the
+          box.  [<i>Note: Vector Graphics support (including the ability
+          to set the <t>path</t> property to anything other than the
+          default) is currently not implemented</i>].
+  
+          A path also has:
+  
+          <list>
+              an associated <t>strokecolor</t>, which is a color
+  
+              an associated <t>strokewidth</t>, which is a number
+              specifying the width of the stroke.  [<i>Note: Vector
+              Graphics support (including the <t>strokewidth</t>
+              property) is currently not implemented</i>]
+              
+              a <t>fill</t>, which is either a color, gradient, or
+              texture
+          </list>        
+          </definition>
+  
+      <definition term="text">
+  
+          Each box also has a single line of <t>text</t>, whose
+          appearance is determined by its:
+  
+          <list>
+              associated <t>font</t>, which can be any font supported by
+              the <link url="http://www.freetype.org" text="FreeType2"/>
+              library.
+              
+              an associated <t>fontsize</t> in <i>pixels</i>
+              
+              an associated <t>textcolor</t>
+          </list>
+          </definition>
+  
+      These eight components plus the size of a box fully specify its
+      appearance.  Every single box you see in Ibex is drawn only on the
+      basis of these components and its size.
+    </section>  
+
+    <section title="Size and Position">
+
+      The size and position of every box is determined by its
+      properties, its childrens' sizes, and its parent's size and
+      position.  Box layout and rendering happens in four phases:
+      <i>packing</i>, <i>constraining</i>, <i>placing</i>, and
+      <i>rendering</i>.  The Core is careful to only perform a phase on
+      a box if the box has changed in a way that invalidates the work
+      done the last time that phase was performed.  The packing and
+      constraining phases are performed in a single traversal of the
+      tree (packing is preorder, constraining is postorder), and the
+      placing and rendering phases are performed in a second traversal
+      of the tree (first placing, then rendering, both preorder).
+      
+      For brevity, the rest of this chapter deals only with width and
+      columns.  Height and rows is treated identically and independently.
+      Also, it is important to note that the term <i>minimum width</i> is
+      not the same thing as the property <t>minwidth</t>, although they
+      are closely related.
+      
+      <heading title="The Size of the Root Box"/>
+  
+      When the user resizes a window, Ibex changes the root box's
+      <t>maxwidth</t> and <t>maxheight</t> to match the size chosen by
+      the user and then determines the root box's size using the same sizing
+      rules it uses for other boxes.
+      
+      Ibex will always attempt to prevent the
+      user from making the surface smaller than the root box's
+      <t>minwidth</t> and <t>minheight</t>.  If the <t>hshrink</t> or
+      <t>vshrink</t> flag is set, Ibex will try to prevent the user from
+      resizing the surface at all.  However, not all platforms give Ibex
+      enough control to do this.
+      
+      <image url="alignmentpoint.pdf" caption="The effect of alignment points on layout" width="3in"/>
+    <heading title="The alignment point"/>
+  
+      When talking about positioning, we will often refer to the
+      <i>alignment point</i>.
+      
+          If the <t>align</t> property is "<t>center</t>", then the
+          alignment point is the center of the box.
+          
+          If the <t>align</t> property is "<t>topleft</t>",
+          "<t>bottomleft</t>", "<t>topright</t>", or
+          "<t>bottomright</t>", then the alignment point is
+          corresponding corner of the box.
+          
+          If the <t>align</t> property is "<t>top</t>",
+          "<t>bottom</t>", "<t>right</t>", or "<t>left</t>", then
+          the alignment point is middle of the corresponding edge of the
+          box.
+  
+      When positioning a child box, the alignment point is determined by
+      the <i>parent's</i> <t>align</t> property.  When rendering a
+      visual element (a texture, path, or text string) within a box, the
+      alignment point is determined by the <i>box's own</i> <t>align</t>
+      property.
+      
+      A simple way to think about this is that whenever there are two boxes
+      involved in the decision, you should use the parent's alignment point.
+      
+    <section title="Packing">
+  
+      A grid of <i>cells</i> is created within the parent.  If the
+      parent's <t>cols</t> property is set to 0, the cell grid has an
+      infinite number of columns.  Either <t>cols</t> or <t>rows</t>
+      must be zero, but not both.
+          
+      If a child's <t>visible</t> property is <t>false</t>, it does
+      not occupy any cells (and is not rendered).  Otherwise, each child
+      occupies a rectangular set of cells <t>child.colspan</t> cells
+      wide and <t>child.rowspan</t> cells high.
+          
+      The Core iterates over the cells in the grid in the following
+      order: if <t>rows</t> is 0, the Core iterates across each column
+      before proceeding to the next row; otherwise rows come before
+      columns.  At each cell, the Core attempts to place the <i>first
+      remaining unplaced child's</i> top-left corner in that cell
+      (with the child occupying some set of cells extending down and
+      to the right of that cell).  If the parent has a fixed number of
+      columns and the child's <t>colspan</t> exceeds that limit, the
+      child is placed in column zero regardless, but only occupies the
+      available set of cells (it does not "hang off the end" of the
+      box).  <image url="layout.pdf" width="1in"/>
+      
+      <pre>
+      <ui:box cols="3">
+          <ui:box id="1" />
+          <ui:box id="2" rowspan="2" />
+          <ui:box id="3" colspan="2" />
+          <ui:box id="4" />
+          <ui:box id="5" colspan="2" />
+      </ui:box>
+
+
+
+      </pre>
+      
+      </section>
+  
+    <section title="Constraining">
+  
+          Each box's minimum width is computed recursively as the
+          maximum of:
+  
+          <list>
+              Its <t>minwidth</t>
+               
+              The width of the box's <t>text</t> (after applying the
+              box's <t>transform</t>) [<i>Note: Vector Graphics support
+              (including the <t>transform</t> property) is currently not
+              implemented</i>].
+               
+              The width of the box's path (after applying the box's
+              <t>transform</t>) <i>if the box is <t>packed</t></i>.
+               
+              The width of the bounding box enclosing the box's cells.
+          </list>
+          
+          The minimum width of each cell is computed as the minimum
+          width of the box occupying it divided by the box's
+          <t>colspan</t>.
+          
+          If a box's <t>hshrink</t> property is set to
+          <t>true</t>, the box's maximum width is the same as its
+          minimum width; otherwise it is the box's
+          <t>maxwidth</t>.
+          
+          The maximum width of each cell is the <t>maxwidth</t> of
+          the box occupying it divided by the box's
+          <t>colspan</t>.
+    </section>  
+
+    <section title="Placing">
+  
+          Each column's <i>actual width</i> is set to the maximum
+          <i>minimum width</i> of all the cells in that column.
+          <b>NOTE:</b> although a column or row can be sized smaller
+          than its "minimum width" or larger than its "maximum width", a
+          box will <i>never</i> be smaller than its <t>minwidth</t> or
+          larger than its <t>maxwidth</t>.
+          
+          Each column's maximum width is the largest maximum width of
+          the cells in that column, but no smaller than the column's
+          minimum width.
+  
+          A value <t>k</t> is chosen such that when each column's width
+          is set to <t>min(maximum width, max(minimum width, k))</t>,
+          the sum of all the column widths equals the parent's width.
+          If no such value exists, positive or negative infinity is used
+          (whichever is appropriate).  Each column is then set to the
+          width dictated by <t>k</t>.
+          
+          Next, the rows and columns are positioned within the parent
+          box.  The rows and columns are transformed according to the
+          parent's <t>transform</t> property [<i>Note: Vector Graphics
+          support (including the <t>transform</t> property) is currently
+          not implemented</i>]., and the bounding box of the resulting
+          cells are placed such that the cells' alignment point
+          coincides with the parent's alignment point (both alignment
+          points are determined by the parent's <t>align</t> property).
+      
+          <image url="grid.pdf" caption="Positioning grid cells"/>
+
+          <b>Packed boxes:</b> Each packed box's actual position
+          and size is then set to the aggregation of the actual sizes of
+          the cells it spans.  If this size exceeds the box's maximum
+          width, the box is sized to its maximum width and centered
+          horizontally within the space occupied by its cells.
+  
+          <b>Non-packed boxes</b>: each non-packed box is transformed
+          according to the parent's <t>transform</t> property and then
+          positioned so that its alignment point is <t>(child.x,
+          child.y)</t> pixels from the parent's alignment point (both
+          alignment points are determined by the parent's <t>align</t>
+          property).
+          
+      </section>
+  </section>
+  
   <section title="Rendering">
 
     Boxes are rendered in a depth-first, pre-order traversal.  Note that
   <section title="Rendering">
 
     Boxes are rendered in a depth-first, pre-order traversal.  Note that
         
         If the box's <t>transform</t> property is non-null, the
         coordinate space is transformed accordingly for the rest of
         
         If the box's <t>transform</t> property is non-null, the
         coordinate space is transformed accordingly for the rest of
-        this phase and for the rendering of all children.
+        this phase and for the rendering of all children.  [<i>Note:
+        Vector Graphics support (including the <t>transform</t>
+        property) is currently not implemented</i>].
         
         If the box is packed and has a non-<t>null</t> path, the
         path is translated such that the alignment point of the path's
         
         If the box is packed and has a non-<t>null</t> path, the
         path is translated such that the alignment point of the path's
         alignment points are determined by the box's <t>align</t>
         property).
         
         alignment points are determined by the box's <t>align</t>
         property).
         
-        The box's children are rendered (pre-prder traversal).
+        The box's children are rendered (pre-order traversal).
 
     </list>
     
 
     </list>
     
 <!-- ----------------------------------------------------------------------- -->
 <section title="Box Properties">
 
 <!-- ----------------------------------------------------------------------- -->
 <section title="Box Properties">
 
+  Each box is a full-fledged ECMAscript object, and can store
+  key-value pairs as properties.  Some of these keys have special
+  meaning, which will be explained later.  Each box's numeric
+  properties hold its <i>child boxes</i>.
+
   <section title="Rendering Properties">
 
     Every box has several special properties which control how it is
   <section title="Rendering Properties">
 
     Every box has several special properties which control how it is
     put will be ignored.
     
     <property name="strokecolor" type="string" default="clear">
     put will be ignored.
     
     <property name="strokecolor" type="string" default="clear">
+
              If the value is a 5-character hex string (<t>#RGB</t>),
              7-character hex string (<t>#RRGGBB</t>), 9-character hex
              string (<t>#AARRGGBB</t>), the box's stroke color will be set
              to that color. 
              If the value is a 5-character hex string (<t>#RGB</t>),
              7-character hex string (<t>#RRGGBB</t>), 9-character hex
              string (<t>#AARRGGBB</t>), the box's stroke color will be set
              to that color. 
-             If the value is one of the <link url="http://www.color.org/ICC-1A_1999-04.PDF" text="ICC"/> colors
-             (the same set of color names supported by SVG), the stroke
-             color be set to that color.
-             If the value is <t>null</t>, the stroke color will be set to
-             clear (<t>#00000000</t>).
+
+             If the value is one of the <link
+             url="http://www.color.org/ICC-1A_1999-04.PDF"
+             text="ICC"/> colors (the same set of color names
+             supported by SVG), the stroke color be set to that color.
+
+             If the value is <t>null</t>, the stroke color will be set
+             to clear (<t>#00000000</t>).
              </property>
     
     <property name="strokewidth" type="int" default="1">
              </property>
     
     <property name="strokewidth" type="int" default="1">
     
     <property name="text" type="string" default='""'>
             The box's text; writing <t>null</t> to this property sets it
     
     <property name="text" type="string" default='""'>
             The box's text; writing <t>null</t> to this property sets it
-            to "<t></t>".
+            to <t>""</t>.
             </property>
     
             </property>
     
-    <property name="font" type="stream" default=".ibex.font.sansserif">
+    <property name="textcolor" type="number" default="black">
+            The color in which to render the font; accepts the same values as <t>strokecolor</t>.
+            </property>
+
+    <property name="font" type="stream" default=".ibex.ui.font.sansserif">
             When an object is written to this property, its stream is read
             When an object is written to this property, its stream is read
-            using the <link url="http://www.freetype.org" text="freetype2
-            library"/>, and the resulting font is used to render the
+            using the <link url="http://www.freetype.org" text="FreeType 2 library"/>,
+            and the resulting font is used to render the
             box's <t>text</t>.
             </property>
             
     <property name="fontsize" type="number" default="10">
             The size (in points) to render the text.
             </property>
             box's <t>text</t>.
             </property>
             
     <property name="fontsize" type="number" default="10">
             The size (in points) to render the text.
             </property>
-            
-    <property name="textcolor" type="number" default="black">
-            The color in which to render the font; accepts the same values as <t>strokecolor</t>.
-            </property>
     
     </section>
 
     
     </section>
 
         its children and the bounding box of its path.
         </property>
     
         its children and the bounding box of its path.
         </property>
     
-    <property name="x" type="integer" default="varies">
+    <property name="x y" type="integer" default="varies">
         If the box is a root box, this is the (x/y)-coordinate of the
         surface; otherwise it is the distance between the parent's
         alignment point and this box's alignment point.
         </property>
     
         If the box is a root box, this is the (x/y)-coordinate of the
         surface; otherwise it is the distance between the parent's
         alignment point and this box's alignment point.
         </property>
     
-    <property name="globalx" type="integer" default="varies">
-        The distance between this box's (left/top) edge and the root
-        box's (left/top) edge. A put to this property has the same
-        effect as a put to the (<t>x</t>/<t>y</t>) property,
-        except that it is relative to the root box rather than to this
-        box's parent. FIXME is this fakeable?  How is
-        distance measured?
-        </property>
-    
-    <property name="minwidth" type="integer" default="0">
+    <property name="minwidth minheight" type="integer" default="0">
         The desired minimum width and height.
         </property>
     
         The desired minimum width and height.
         </property>
     
-    <property name="maxwidth" type="integer" default="ibex.maxint">
+    <property name="maxwidth maxheight" type="integer" default="ibex.ui.maxdim">
         The desired maximum width and height.
         </property>
     
         The desired maximum width and height.
         </property>
     
-    <property name="width" type="integer" default="varies">
-        When read, this is the (width/height) of this box.  Writing to
-        this property is equivalent to writing to <i>both</i> the
-        minimum and maximum (width/height).
+    <property name="width height" type="integer">
+        When read, this is the current (width/height) of this box.
+        Writing to this property is equivalent to writing to
+        <i>both</i> the minimum and maximum (width/height).
         </property>
     
         </property>
     
-    <property name="cols" type="integer" default="0">
+    <property name="cols rows" type="integer" default="0">
         The number of (columns/rows) in which to lay out the children of this
         box.  If set to zero, the number of (columns/rows) is unconstrained.
         Either <t>rows</t> or <t>cols</t> must be zero.  If
         The number of (columns/rows) in which to lay out the children of this
         box.  If set to zero, the number of (columns/rows) is unconstrained.
         Either <t>rows</t> or <t>cols</t> must be zero.  If
         <t>rows</t> is set to <t>0</t>, and vice versa.
         </property>
     
         <t>rows</t> is set to <t>0</t>, and vice versa.
         </property>
     
-    <property name="colspan" type="integer" default="1">
+    <property name="colspan rowspan" type="integer" default="1">
         The number of (columns/rows) that this box spans within its parent.
         </property>
     
         The number of (columns/rows) that this box spans within its parent.
         </property>
     
         </property>
     
     <property name="visible" type="boolean" default="true">
         </property>
     
     <property name="visible" type="boolean" default="true">
-        If set to false, this box will be rendered as if its width and
-        height were zero. If this is a root box, the associated surface
-        will be hidden.
-        When reading from this property, the value
-        <t>false</t> will be returned if this box <i>or any of its
-        ancestors</i> is not visible.  Thus it is possible to write
-        <t>true</t> to a box's <t>visible</t> property and then
-        read back <t>false</t>.
+        If set to <t>false</t>, this box will be rendered as if its
+        width and height were zero. If this is a root box, the
+        associated surface will be hidden.
+
+        When reading from this property, the value <t>false</t> will
+        be returned if this box <i>or any of its ancestors</i> is not
+        visible.  Thus it is possible to write <t>true</t> to a box's
+        <t>visible</t> property and then read back <t>false</t>.
         </property>
     
     <property name="packed" type="boolean" default="true">
         </property>
     
     <property name="packed" type="boolean" default="true">
-         The layout strategy for this box.
+        The layout strategy for this box.  If set to <t>true</t>, the
+        box occupies no cells and is laid out independently of its
+        siblings.
         </property>
     
     </section>
 
   <section title="Child Control Properties">
     
         </property>
     
     </section>
 
   <section title="Child Control Properties">
     
-    During a box initialization, script-private references to a box's
-    descendants with <t>id</t> attributes are placed on the box. These
-    references allow scripts on that box to easily refer to descendant
-    nodes created by the template in which the script appears. For
-    example, these two blocks of code have exactly the same effect:
-    
-    <pre>
-    <box>                     <box>
-        <box id="foo"/>           <box/>
-        $foo.color = "red";       var $foo = this[0];
-                                  $foo.color = "red";
-    </box>                    </box>
-    </pre>
-    
-    The following special properties control how a box's children are laid
-    out.  If a box has a non-null redirect target, reads and writes to these
-    properties will be forwarded to the redirect target.
-    
-    The <t>redirect</t> attribute is very useful for hiding the
-    internal structure of a widget, and for allowing widgets to act as
-    "smart" containers for other widgets. For example, a menu widget might
-    have an invisible child as its redirect target; this way, when boxes
-    representing items on the menu are added as children of the menu
-    widget, they do not appear until the menu is pulled down.
+    <property name="redirect" type="box" default="thisbox">
+        Writing to this property sets the box's redirect target. This
+        property cannot be read from, and can only be written to if
+        the value being written is a <i>descendant</i> of the current
+        value.
+
+        If a box has a non-null redirect target, reads and writes to
+        any of the other properties in this section will be forwarded
+        to the redirect target.
+
+        The <t>redirect</t> attribute is very useful for hiding the
+        internal structure of a widget, and for allowing widgets to act as
+        "smart" containers for other widgets. For example, a menu widget might
+        have an invisible child as its redirect target; this way, when boxes
+        representing items on the menu are added as children of the menu
+        widget, they do not appear until the menu is pulled down.
+        </property>
     
     <property name="numeric properties" type="int" default="">
         The <i>n</i>th child of box <t>b</t> can be accessed by reading from
     
     <property name="numeric properties" type="int" default="">
         The <i>n</i>th child of box <t>b</t> can be accessed by reading from
         The number of children this box has.
         </property>
     
         The number of children this box has.
         </property>
     
-    <property name="redirect" type="box" default="thisbox">
-        Writing to this property sets the box's redirect
-        target. This property cannot be read from, and can only be
-        written to once.
-        </property>
-    
+   
     <property name="surface" type="" default="null">
     <property name="surface" type="" default="null">
+        FIXME
         If this box has a parent, this property returns
         <t><i>parent</i>.surface</t>; otherwise it returns null.
         This property is a simple building block that the widget
         If this box has a parent, this property returns
         <t><i>parent</i>.surface</t>; otherwise it returns null.
         This property is a simple building block that the widget
     
     <property name="cursor" type="string" default="null">
         The shape that the cursor should take when inside this
     
     <property name="cursor" type="string" default="null">
         The shape that the cursor should take when inside this
-        box. Valid values are: "<t>default </t> " , "<t>wait</t>",
+        box. Valid values are: "<t>default</t>" , "<t>wait</t>",
         "<t>crosshair</t>", "<t>text</t>", "<t>hand</t>", and
         "<t>move</t>", as well as resizing cursors"<t>east</t>",
         "<t>west</t>", "<t>north</t>", "<t>south</t>",
         "<t>crosshair</t>", "<t>text</t>", "<t>hand</t>", and
         "<t>move</t>", as well as resizing cursors"<t>east</t>",
         "<t>west</t>", "<t>north</t>", "<t>south</t>",
         "<t>default</t>" cursor will be used.
         </property>
 
         "<t>default</t>" cursor will be used.
         </property>
 
-    <property name="mouse.x" type="integer" default="varies">
-         The (horizontal/vertical) distance between the mouse cursor and this
-         box's (left/top) edge. Puts to this property are ignored. This
-         value will not be updated if the mouse is outside the root
-         box of the surface and no button was pressed when it left.
-        </property>
-    
-    <property name="mouse.inside" type="boolean" default="false">
-        True if the mouse is inside the rendered region of this box or
-        any of its children. This value will be false if the mouse is
-        inside a portion of this box which is covered up by one of
-        this box's siblings, or one of its ancestors' descendants. Puts
-        to this value are ignored.
-        </property>
-    
     <property name="static" type="object" default="N/A">
         Reading from this property will return the parent scope used
         to execute the <t><static/></t> block of the template
     <property name="static" type="object" default="N/A">
         Reading from this property will return the parent scope used
         to execute the <t><static/></t> block of the template
         has no effect.
         </property>
 
         has no effect.
         </property>
 
-    <property name="childadded" type=" " default=" ">
-
-        These properties are meant to be trapped on FIXME defined later?. Placing a trap on
-        <t>childadded/childremoved</t> lets a box receive
-        notification when a child is added/removed. In either
-        situation, the child will be passed as an argument to the trap
-        function <i>after</i> the addition or removal has been
-        performed.
-
-        Note that if the parent's redirect target is set to another
-        box, these traps will only be invoked when children are
-        manipulated by reading and writing to the parent.  Reads and
-        writes directly to the redirect target will <i>not</i> trigger
-        the traps.
-
-        Note also that these traps are still triggered if a box's
-        <t>redirect</t> target is <i>null</i>.  This is useful for
-        boxes that need to accept children and then relocate them
-        elsewhere.
+    <property name="distanceto()" type="function" default=" ">
+        This property is actually a function; invoking
+        <t>box.distanceto(otherbox)</t> will return an object with two
+        properties, <t>x</t> and <t>y</t>, containing the horizontal
+        and vertical distance between the two boxes (negative if
+        <t>otherbox</t> is to the left of / above <t>box</t>).  This
+        can be used to determine the relative placement of two boxes
+        on different branches of the box tree.
         </property>
         </property>
-    
-    </section>
 
 
-  <section title="Notification Properties">
-    
-    The following properties are used to notify a box of changes specific
-    to that particular box.
-    
-    <property name="Enter">
-        The value <t>true</t> is written to this property when the mouse enters the box.
-        </property>
-    
-    <property name="Leave">
-        The value <t>true</t> is written to this property when the mouse leaves the box.
-        </property>
-    
-    <property name="SizeChange">
-        The value <t>true</t> is put to this property after the size
-        of this box changes.
-        </property>
-    
     </section>
 
   <section title="Root Box Properties">
     </section>
 
   <section title="Root Box Properties">
     <property name="Close">
         When the user attempts to close a surface, the value
         <t>true</t> will be put to this property. Scripts may trap
     <property name="Close">
         When the user attempts to close a surface, the value
         <t>true</t> will be put to this property. Scripts may trap
-        this property FIXME defined later? to
-        prevent the window from closing. Putting the value
+        this property to prevent the window from closing. Putting the
+        value
         <t>true</t> to this property on a root box has the same
         effect as putting <t>null</t> to the <t>thisbox</t>
         property.
         <t>true</t> to this property on a root box has the same
         effect as putting <t>null</t> to the <t>thisbox</t>
         property.
     
     <property name="icon">
         The surface's icon. This is usually displayed on the titlebar of a
     
     <property name="icon">
         The surface's icon. This is usually displayed on the titlebar of a
-        window. The value should be the stream name of a PNG image. Note
+        window.  The value should be an object whose stream is a PNG image. Note
         that not all platforms support this property.
         </property>
     
         that not all platforms support this property.
         </property>
     
 <!-- ----------------------------------------------------------------------- -->
 <section title="Streams">
     
 <!-- ----------------------------------------------------------------------- -->
 <section title="Streams">
     
-  <section title="Every object has a stream...">
+    <heading title="Every object has a stream..."/>
 
     Every object has a <i>stream</i> associated with it.  A stream is a
     sequence of bytes that can be read or written to.
 
     Every object has a <i>stream</i> associated with it.  A stream is a
     sequence of bytes that can be read or written to.
     be an .ibex template which, when applied, will fully reconstitute the
     box's state.
     
     be an .ibex template which, when applied, will fully reconstitute the
     box's state.
     
-    </section>
-
-  <section title="...but streams are not objects">
+    <heading title="...but streams are not objects"/>
     
     Despite the ubiquity of streams, you cannot actually reference a
     stream, since it is not an object.  Instead, you simply reference the
     
     Despite the ubiquity of streams, you cannot actually reference a
     stream, since it is not an object.  Instead, you simply reference the
     just shorthand for saying to perform those actions on the object the
     stream belongs to.
     
     just shorthand for saying to perform those actions on the object the
     stream belongs to.
     
-    </section>
-
   <section title="Creating Streams from URLs">
     
     You can create a stream from a URL by calling
   <section title="Creating Streams from URLs">
     
     You can create a stream from a URL by calling
 
   <section title="Static Blocks">
 
 
   <section title="Static Blocks">
 
+    FIXME
+
     You can access variables within the static block of a template by
     appending a double period (<t>..</t>) and the variable name to the
     stream used to load that template:
     
     <pre>
     You can access variables within the static block of a template by
     appending a double period (<t>..</t>) and the variable name to the
     stream used to load that template:
     
     <pre>
-    <!-- org/ibex/themes/monopoly/scrollbar.ibex -->
+    <!-- org/ibex/themes/linux/scrollbar.ibex -->
             foo = 12;
     ...
     // elsewhere
             foo = 12;
     ...
     // elsewhere
-    ibex.log.print(org.ibex.themes.monopoly.scrollbar..foo);   // prints "12"
+    ibex.log.print(org.ibex.themes.linux.scrollbar..foo);  // prints "12"
     </pre>
     
     </section>
     </pre>
     
     </section>
     You can read a UTF-8 encoded string from a stream like this:
     
     <pre>
     You can read a UTF-8 encoded string from a stream like this:
     
     <pre>
-    var myString = ibex.stream.fromUTF(ibex.stream.url("utf8:this is a test"));
+    var myString = ibex.stream.fromUTF(ibex.stream.url("utf8:testing..."));
     </pre>
     You can also parse XML from a stream using SAX like this:
     
     <pre>
     ibex.stream.xml.sax(
     </pre>
     You can also parse XML from a stream using SAX like this:
     
     <pre>
     ibex.stream.xml.sax(
-        ibex.stream.url("http://foo.com/foo.xml"),
-            { beginElement : function(tagname, attributeKeyValuePairs) { ... },
-              endElement   : function(tagname) { ... },
-              content      : function(contentString) { ... }
-              whitespace   : function(whitespaceString) { ... }
-            });
+      ibex.stream.url("http://foo.com/foo.xml"),
+        { beginElement : function(tagname, attributeKeyValuePairs) { ... },
+          endElement   : function(tagname) { ... },
+          content      : function(contentString) { ... }
+          whitespace   : function(whitespaceString) { ... }
+        });
     </pre>
     
     </section>
     </pre>
     
     </section>
 
   <heading title="Logging"/>
 
 
   <heading title="Logging"/>
 
-    <property name="ibex.log.debug(m, o)">
-        log the debug message <i>m</i>, optionally dumping object
+    <property name="ibex.log.debug(m1, ... mn)">
+        log the debug messages <i>m1</i> through <i>mn</i>.
         <i>o</i>
         </property>
 
         <i>o</i>
         </property>
 
-    <property name="ibex.log.info(m, o)">
-        log the informational message <i>m</i>, optionally dumping
-        object <i>o</i>
+    <property name="ibex.log.info(m1, ... mn)">
+        log the info messages <i>m1</i> through <i>mn</i>.
         </property>
 
         </property>
 
-    <property name="ibex.log.warn(m, o)">
-        log the warning message <i>m</i>, optionally dumping object
-        <i>o</i>
+    <property name="ibex.log.warn(m1, ... mn)">
+        log the warning messages <i>m1</i> through <i>mn</i>.
         </property>
 
         </property>
 
-    <property name="ibex.log.error(m, o)">
-        log the error message <i>m</i>, optionally dumping object
-        <i>o</i>
+    <property name="ibex.log.error(m1, ... mn)">
+        log the error messages <i>m1</i> through <i>mn</i>.
         </property>
 
     <heading title="User Interface"/>
         </property>
 
     <heading title="User Interface"/>
 
   <heading title="Networking"/>
 
 
   <heading title="Networking"/>
 
-    <property name="ibex.net.http">
-        not yet implemented
-        </property>
-
     <property name="ibex.net.rpc.xml(u)">
         return an XML-RPC call object with endpoint URL <i>u</i>
         </property>
     <property name="ibex.net.rpc.xml(u)">
         return an XML-RPC call object with endpoint URL <i>u</i>
         </property>
     that property is written to.
     
     <pre>
     that property is written to.
     
     <pre>
-    <box>
+    <ui:box>
         foo ++= function(z) {
            ibex.log.info("foo is " + z);
         }
         foo ++= function(z) {
            ibex.log.info("foo is " + z);
         }
-    </box>
+    </ui:box>
     </pre>
 
     If another script were to set the property "<t>foo</t>"
     </pre>
 
     If another script were to set the property "<t>foo</t>"
     is applied to multiple traps. For example:
     
     <pre>
     is applied to multiple traps. For example:
     
     <pre>
-    <box>
+    <ui:box>
         func ++= function(z) {
             ibex.log.info("called trap " + trapname);
         }
         foo ++= func;
         bar ++= func;
         func ++= function(z) {
             ibex.log.info("called trap " + trapname);
         }
         foo ++= func;
         bar ++= func;
-    </box>
+    </ui:box>
     </pre>
     
   <section title="Removing Traps">
     </pre>
     
   <section title="Removing Traps">
     function you added as a trap:
     
     <pre>
     function you added as a trap:
     
     <pre>
-    <box>
+    <ui:box>
         var myfunc = function(z) { /* ... */ }
         // add the trap
         func ++= myfunc;
         // ...
         // remove the trap
         func --= myfunc;
         var myfunc = function(z) { /* ... */ }
         // add the trap
         func ++= myfunc;
         // ...
         // remove the trap
         func --= myfunc;
-    </box>
+    </ui:box>
     </pre>
     
     </section>
 
   <heading title="Multiple Traps on the Same Property"/>
 
     </pre>
     
     </section>
 
   <heading title="Multiple Traps on the Same Property"/>
 
-    When the property is <i>written</i> to, each of the trap functions placed
-    on it will be invoked in the opposite order that they were placed on
-    the box -- the most recently placed trap will execute first. This
-    last-to-first execution of traps is called <i>cascading</i>. After the
-    last trap is invoked, the value is stored on the box (remember, boxes
-    are objects, so they can hold properties just like all other
-    ECMAscript objects).
+    When the trapped property is <i>written</i> to, each of the trap
+    functions placed on it will be invoked in the opposite order that
+    they were placed on the box -- the most recently placed trap will
+    execute first. This last-to-first execution of traps is called
+    <i>cascading</i>. After the last trap is invoked, the value is
+    stored on the box (remember, boxes are objects, so they can hold
+    properties just like all other ECMAscript objects).
     
   <section title="Manual Cascades">
 
     
   <section title="Manual Cascades">
 
     lower traps), you can use <t>cascade</t>. For example:
     
     <pre>
     lower traps), you can use <t>cascade</t>. For example:
     
     <pre>
-    <box color="black">
+    <ui:box color="black">
         color ++= function(c) {
             ibex.log.info("refusing to change colors!");
             cascade = "black";
         }
         color ++= function(c) {
             ibex.log.info("refusing to change colors!");
             cascade = "black";
         }
-    </box>
+    </ui:box>
     </pre>
 
     This effectively creates a box whose color cannot be changed, and
     </pre>
 
     This effectively creates a box whose color cannot be changed, and
     Do <i>not</i> try to do something like this:
     
     <pre>
     Do <i>not</i> try to do something like this:
     
     <pre>
-    <box color="black">
+    <ui:box color="black">
         color ++= function(z) {
             color = "black";      // INFINITE LOOP! BAD!!!
         }
         color ++= function(z) {
             color = "black";      // INFINITE LOOP! BAD!!!
         }
-    </box>
+    </ui:box>
     </pre>
     To prevent automatic cascading, return <t>true</t> from your function:
     
     <pre>
     </pre>
     To prevent automatic cascading, return <t>true</t> from your function:
     
     <pre>
-    <box color="black">
+    <ui:box color="black">
         color ++= function(z) {
             return true;          // the box's color will not change
         }
         color ++= function(z) {
             return true;          // the box's color will not change
         }
-    </box>
+    </ui:box>
     </pre>
 
     </section>
     </pre>
 
     </section>
     also do not automatically cascade.
     
     <pre>
     also do not automatically cascade.
     
     <pre>
-    <box>
+    <ui:box>
         doublewidth <t>++=</t> function() { return 2 * width; }
         doublewidth <t>++=</t> function() { return 2 * width; }
-    </box>
+    </ui:box>
     </pre>
 
     If another script attempts to read from the <t>doublewidth</t>
     </pre>
 
     If another script attempts to read from the <t>doublewidth</t>
     You can manually cascade on read traps as well:
     
     <pre>
     You can manually cascade on read traps as well:
     
     <pre>
-    <box>
+    <ui:box>
         text <t>++=</t> function() { return "my text is " + cascade; }
         text <t>++=</t> function() { return "my text is " + cascade; }
-    </box>
+    </ui:box>
     </pre>
 
     Read traps are only rarely needed -- most of the time a write trap
     </pre>
 
     Read traps are only rarely needed -- most of the time a write trap
     Properties"/> except for <t>childadded</t>,
     <t>childremoved</t> and <t>surface</t>.  FIXME: remove?
     
     Properties"/> except for <t>childadded</t>,
     <t>childremoved</t> and <t>surface</t>.  FIXME: remove?
     
-  <heading title="Exceptions and Traps "/>
+  <heading title="Exceptions and Traps"/>
 
     If an uncaught exception is thrown from a trap, Ibex will log the
     exception, but will <i>not</i> propagate it to the code which
 
     If an uncaught exception is thrown from a trap, Ibex will log the
     exception, but will <i>not</i> propagate it to the code which
     example prints out "first second third fourth" in that order.
     
     <pre>
     example prints out "first second third fourth" in that order.
     
     <pre>
-    <box>
+    <ui:box>
         _Press1 ++= function(b) { ibex.log.info("first"); }
          Press1 ++= function(b) { ibex.log.info("fourth"); }
         _Press1 ++= function(b) { ibex.log.info("first"); }
          Press1 ++= function(b) { ibex.log.info("fourth"); }
-        <box>
+        <ui:box>
           _Press1 ++= function(b) { ibex.log.info("second"); }
            Press1 ++= function(b) { ibex.log.info("third"); }
           _Press1 ++= function(b) { ibex.log.info("second"); }
            Press1 ++= function(b) { ibex.log.info("third"); }
-        </box>
-    </box>
+        </ui:box>
+    </ui:box>
     </pre>
 
     In general, you should use the <i>non-underscore</i> names to respond
     </pre>
 
     In general, you should use the <i>non-underscore</i> names to respond
     This will immediately cease the propagation of the event.  This is how
     you would indicate that an event has been "handled".
     
     This will immediately cease the propagation of the event.  This is how
     you would indicate that an event has been "handled".
     
-  <heading title="Enter and Leave"/>
+  <heading title="Non-Propagating Events"/>
 
 
-    Ibex will trigger the <t>Enter</t> and <t>Leave</t> properties as
-    it walks down the tree, based on the position of the mouse (or the
-    faked position if the <t>mouse</t> property has been written to).
-    However, <t>Enter</t> and <t>Leave</t> are not events since they
-    do not implicitly cascade up or down the tree.
+    Ibex uses the following events to notify a box about changes that
+    only matter to that particular box.  These events do not propagate
+    either up or down the tree.
+
+    <property name="Enter Leave">
+        The value <t>true</t> is written to this property when the mouse (enters/leaves) the box.
+        </property>
+    
+    <property name="SizeChange">
+        The value <t>true</t> is put to this property after the size
+        of this box changes.
+        </property>
+
+    <property name="ChildChange">
+        When a child is added or removed, that child is written to
+        this property.  The write is always performed <i>after</i> the
+        addition or removal, so these two cases can be distinguished
+        by checking <t>indexof(child)</t>.
+
+        Note that if the parent's redirect target is set to another
+        box, this trap will only be invoked when children are
+        manipulated by reading and writing to the parent.  Reads and
+        writes directly to the redirect target will <i>not</i> trigger
+        this trap.
+
+        Note also that this traps is still triggered if a box's
+        <t>redirect</t> target is <i>null</i>.  This is useful for
+        boxes that need to accept children and then relocate them
+        elsewhere.
+        </property>
     
   <section title="Listing of Events">
     
     
   <section title="Listing of Events">
     
-    <property name="Press1 / Press2 / Press3">
+    <property name="Press1 Press2 Press3">
         Indicates that the use has pressed a mouse button.  On
         platforms with three mouse buttons, the <i>middle</i> button
         is button 3 -- this ensures that applications written to only
         Indicates that the use has pressed a mouse button.  On
         platforms with three mouse buttons, the <i>middle</i> button
         is button 3 -- this ensures that applications written to only
         platforms.
         </property>
     
         platforms.
         </property>
     
-    <property name="Release1 / Release2 / Release3">
+    <property name="Release1 Release2 Release3">
         Indicates that the use has released a mouse button.
         </property>
     
         Indicates that the use has released a mouse button.
         </property>
     
-    <property name="Click1 / Click2 / Click3">
+    <property name="Click1 Click2 Click3">
         Indicates that the user has pressed and released the
         mouse button without moving the mouse much (exactly how
         much is platform-dependent).
         </property>
     
         Indicates that the user has pressed and released the
         mouse button without moving the mouse much (exactly how
         much is platform-dependent).
         </property>
     
-    <property name="DoubleClick1 / DoubleClick2 / DoubleClick3">
+    <property name="DoubleClick1 DoubleClick2 DoubleClick3">
         Indicates that the user has clicked the 
         mouse button twice within a short period of time (exactly how long is platform-dependent).
         </property>
         Indicates that the user has clicked the 
         mouse button twice within a short period of time (exactly how long is platform-dependent).
         </property>
         </property>
     
     <property name="KeyPressed KeyReleased">
         </property>
     
     <property name="KeyPressed KeyReleased">
+
         A string is written to this property when a key is pressed or
         released If the key was any other key, a multi-character
         string describing the key will be put. For simplicity, we use
         the VK_ constants in the <link
         url="http://java.sun.com/products/jdk/1.1/docs/api/java.awt.event.KeyEvent.html#VK_0"
         A string is written to this property when a key is pressed or
         released If the key was any other key, a multi-character
         string describing the key will be put. For simplicity, we use
         the VK_ constants in the <link
         url="http://java.sun.com/products/jdk/1.1/docs/api/java.awt.event.KeyEvent.html#VK_0"
-        text=" Java 1.1 API java.awt.event.KeyEvent class"/>. When a
+        text=" Java 1.1 API java.awt.event.KeyEvent class"/>.  When a
         key is pressed or released, the string put will be the portion
         of its VK_ constant after the underscore, all in lower case.
         key is pressed or released, the string put will be the portion
         of its VK_ constant after the underscore, all in lower case.
-        If the shift key was depressed immediately before the event
-        took place, then the string will be capitalized. Special
+
+        <list>
+        If the shift key was depressed immediately before the
+        event took place, then the string will be capitalized. Special
         keynames are also capitalized; shift+home is reported as
         keynames are also capitalized; shift+home is reported as
-        "<t>HOME</t>". Symbols are capitalized as they appear on the
+        "<t>HOME</t>".  Symbols are capitalized as they appear on the
         keyboard; for example, on an American QWERTY keyboard, shift+2
         keyboard; for example, on an American QWERTY keyboard, shift+2
-        is reported as "<t>@</t>".  If the alt, meta, or command key
-        was depressed immediately before this key was pressed, then
-        the string will be prefixed with the string "<t>A-</t>". If
-        the control key was depressed while this key was pressed, then
-        the string will be prefixed with the string "<t>C-</t>". If
-        both alt and control are depressed, the string is prefixed
-        with "<t>C-A-</t>".  Ibex does not distinguish between a key
-        press resulting from the user physically pushing down a key,
-        and a 'key press' resulting from the keyboard's typematic
-        repeat. In the rare case that an application needs to
-        distinguish between these two events, it should watch for
-        KeyReleased messages and maintain an internal key-state
-        vector.
+        is reported as "<t>@</t>".
+
+        If the alt, meta, or command key was depressed immediately
+        before this key was pressed, then the string will be prefixed
+        with the string "<t>A-</t>". If the control key was depressed
+        while this key was pressed, then the string will be prefixed
+        with the string "<t>C-</t>". If both alt and control are
+        depressed, the string is prefixed with "<t>C-A-</t>".
+
+        Ibex does not distinguish between a key press resulting from
+        the user physically pushing down a key, and a 'key press'
+        resulting from the keyboard's typematic repeat. In the rare
+        case that an application needs to distinguish between these
+        two events, it should watch for KeyReleased messages and
+        maintain an internal key-state vector.
+        </list>
         </property>
 
     </section>
         </property>
 
     </section>
     
     Ibex supports HTTP Basic and Digest authentication. To use
     authentication, pass <t>ibex.net.rpc.xml()</t> a URL in the form
     
     Ibex supports HTTP Basic and Digest authentication. To use
     authentication, pass <t>ibex.net.rpc.xml()</t> a URL in the form
-    <t>http[s]://user:password@hostname/</t>.  Ibex will use Digest
-    authentication if the server supports it; otherwise it will use
-    Basic authentication.  Please be aware that many XML-RPC server
-    implementations contain a <link
-    url="http://www.ibex.org/faq.html#auth" text="broken implementation of Basic authentication"/>.
+
+    <pre>
+       http[s]://user:password@hostname/
+    </pre>
+
+    Ibex will use Digest authentication if the server supports it;
+    otherwise it will use Basic authentication.  Please be aware that
+    many XML-RPC server implementations contain a <link
+    url="http://www.ibex.org/faq.html#auth" text="broken
+    implementation of Basic authentication"/>.
     
     </section>
 
     
     </section>
 
     the proper key on the target box.
     
     <pre>
     the proper key on the target box.
     
     <pre>
-    <box>
+    <ui:box>
         _KeyPressed = function(k) { ibex.log.info("first"); }
          KeyPressed = function(k) { ibex.log.info("sixth"); }
         $recipient.target = $target;
         _KeyPressed = function(k) { ibex.log.info("first"); }
          KeyPressed = function(k) { ibex.log.info("sixth"); }
         $recipient.target = $target;
-        <box id="recipient">
+        <ui:box id="recipient">
             _KeyPressed = function(k) {
                 ibex.log.info("second");
                 thisbox.target.KeyPressed = k;
             _KeyPressed = function(k) {
                 ibex.log.info("second");
                 thisbox.target.KeyPressed = k;
                 return true;
             }
              KeyPressed = function(k) { ibex.log.info("fifth"); }
                 return true;
             }
              KeyPressed = function(k) { ibex.log.info("fifth"); }
-            <box id="excluded">
+            <ui:box id="excluded">
                 _KeyPressed = function(k) {
                    ibex.log.info("this never happens");
                 }
                 _KeyPressed = function(k) {
                    ibex.log.info("this never happens");
                 }
-            </box>
-        </box>
-        <box id="target"> 
+            </ui:box>
+        </ui:box>
+        <ui:box id="target"> 
             _KeyPressed = function(k) { ibex.log.info("third"); }
              KeyPressed = function(k) { ibex.log.info("fourth"); }
             _KeyPressed = function(k) { ibex.log.info("third"); }
              KeyPressed = function(k) { ibex.log.info("fourth"); }
-        </box>
-    </box>
+        </ui:box>
+    </ui:box>
     </pre>
 
     </section>
     </pre>
 
     </section>
     and doing so squanders scarce public IPv4 addresses. As such, the onus
     is on the administrators of such machines to explicitly block access
     to clients reporting a <t>User-Agent:</t> header beginning with the
     and doing so squanders scarce public IPv4 addresses. As such, the onus
     is on the administrators of such machines to explicitly block access
     to clients reporting a <t>User-Agent:</t> header beginning with the
-    three characters "<t>Ibex</t>".
+    four characters "<t>IBEX</t>".
     
   <heading title="Malicious UI attempts to trick user into divulging secret information"/>
     
     
   <heading title="Malicious UI attempts to trick user into divulging secret information"/>
     
         The token <t>..</t> is equivalent to <t>[""]</t>.
     
         Trapping
         The token <t>..</t> is equivalent to <t>[""]</t>.
     
         Trapping
-    
+
         Cloning
     
         Extended <t>catch</t> syntax.  The following code:
         Cloning
     
         Extended <t>catch</t> syntax.  The following code:
 <!-- ----------------------------------------------------------------------- -->
 <appendix title="Logging and Command Line Invocation">
     
 <!-- ----------------------------------------------------------------------- -->
 <appendix title="Logging and Command Line Invocation">
     
-    Very early in the loading process, Ibex begins logging messages about
-    what it is doing.  Where this output is logged to differs by platform;
-    currently it goes to standard output when running inside a JVM, and to
-    <t>$TMPDIR\ibex-log.txt</t> on Win32 (where <t>$TMPDIR</t> is the
-    value returned by <t>GetTempPath()</t>). The logs contain a lot of
-    valuable debugging information and performance hints; if you are
-    having trouble developing an Ibex application, be sure to check the
-    logs.
-    
+    <pre>
+    Usage: ibex [-lawp] [ url | file | directory ]
+        -l [level]      set logging level to { debug, info (default), warn, error, silent }
+        -l rpc          log all XML-RPC and SOAP conversations
+        -l user@host    email log to user@host
+        -l host:port    emit log to TCP socket
+        -l [file]       write log to a file on disk
+        -a              check assertions
+        -w <window-id>  reserved for libibex
+        -p              dump profiling information [not yet supported]
+    </pre>
+
     If Ibex encounters a serious problem before it starts logging
     information, or if it is unable to open the log file, it will abort
     immediately with a critical abort, which will be displayed on the
     console for POSIX-native cores and in a dialog box for JVM-based and
     Win32-native cores.
     If Ibex encounters a serious problem before it starts logging
     information, or if it is unable to open the log file, it will abort
     immediately with a critical abort, which will be displayed on the
     console for POSIX-native cores and in a dialog box for JVM-based and
     Win32-native cores.
-    
-    You can invoke Ibex directly from the command line during
-    development. When using a JVM, the invocation format is:
-    
-    <pre>    
-  java -jar path-to-ibex-jar [-sv] source-location [initial-template]
-    </pre>
-    
-    Where <t><i>path-to-ibex-jar</i></t> is the path to <t>ibex.jar</t>,
-    which can be downloaded <link url="http://www.ibex.org/dist/ibex.jar" text="here"/>.
-    
-    On Win32, the invocation format is:
-    
-    <pre>
-    ibex.exe [-v] source-location [initial-template]
-    </pre>
-    
-    The file <t>ibex.exe</t> is placed in Windows' ActiveX cache
-    directory the first time Ibex is used on the machine. The ActiveX
-    cache location depends on what version of Windows you are using;
-    on newer versions of Windows it is <t>C:\WINDOWS\DOWNLOADED
-    PROGRAM FILES\</t>. You can also extract <t>ibex.exe</t> from
-    <t>ibex.cab</t>, which is available <link
-    url="http://www.ibex.org/dist/ibex.cab" text="here"/>.
+
+    Note that Microsoft Windows does not provide any mechanism for
+    redirecting standard input/output of an application which is not
+    compiled as a "console application".  Therefore, Ibex is compiled
+    as a "console application", and will open a console window when
+    invoked.  To inhibit this console window, provide a logging
+    destination (file, port, etc).
     
     The <t><i>source-location</i></t> parameter can be either the path
     
     The <t><i>source-location</i></t> parameter can be either the path
-    to an .ibex archive, the http url of an .ibex archive, or the path to a
-    directory comprising an unpacked .ibex archive.
+    to an <t>.ibex</t> archive, the http url of an <t>.ibex</t>
+    archive, or the path to a directory comprising an unpacked
+    <t>.ibex</t> archive.
     
     The <t><i>initial-template</i></t> parameter is the stream name of
     a template to be used as the initial template. If ommitted, it
     
     The <t><i>initial-template</i></t> parameter is the stream name of
     a template to be used as the initial template. If ommitted, it
diff --git a/doc/reference/threeviews.pdf b/doc/reference/threeviews.pdf
new file mode 100644 (file)
index 0000000..0840c40
Binary files /dev/null and b/doc/reference/threeviews.pdf differ