Author: junrue Date: Mon Aug 13 01:52:39 2007 New Revision: 473

Modified: trunk/README.txt trunk/docs/manual/README.txt trunk/docs/manual/introduction.xml Log: miscellaneous doc updates

Modified: trunk/README.txt ============================================================================== --- trunk/README.txt (original) +++ trunk/README.txt Mon Aug 13 01:52:39 2007 @@ -73,16 +73,12 @@ compute height from that. The gfg:text-extent function does return the correct width.

-5. The implementation of GFW:COMPUTE-SIZE for GFW:FLOW-LAYOUT does not - account for non-negative values for width or height hints when the - :WRAP style is specified. Several of the flow-layout unit tests - are currently failing because of this problem. - -6. If a Graphic-Forms application is launched from within SLIME with +5. If a Graphic-Forms application is launched from within SLIME with SBCL as the backend (which is currently single-threaded on Win32), further SLIME commands will be 'pipelined' until the Graphic-Forms - main message loop exits. The best workaround is to use the REPL - from a command prompt window. + main message loop exits. If/when SBCL gains multi-threading support + on Win32, then the Graphic-Forms library code will be updated to + launch a separate thread, as is currently done for Allegro and LispWorks.

How To Configure and Build @@ -91,6 +87,9 @@ NOTE: in a future release, this library will be packaged for delivery via asdf-install.

+NOTE: the following steps are only suggestions provided as a default +procedure for people new to Graphic-Forms or Common Lisp. + 1. [OPTIONAL] Install ImageMagick 6.2.6.5-Q16 (note in particular that it is the Q16 version that is needed, not the Q8 version). The default installation directory is "c:/Program Files/ImageMagick-6.2.6-Q16/".

Modified: trunk/docs/manual/README.txt ============================================================================== --- trunk/docs/manual/README.txt (original) +++ trunk/docs/manual/README.txt Mon Aug 13 01:52:39 2007 @@ -1,52 +1,52 @@ - -The Programming Reference source consists of XML-based source files, -some of which are DocBook files and others which are transformed -into DocBook, along with custom XSLT and CSS files, and a catalog -file for resolving URIs. Several utilities comprise the translation -process from sources into HTML Help (CHM) format. - -Before anything else, you should install a version of GNU Make -for Windows, since the docs build process is managed with a -makefile. Just install MSYS or Cygwin, if you haven't already. - -Next, you will need a version of xsltproc and its dependencies. The -version of xsltproc that I have had success using is available from: - - http://www.zlatkovic.com/libxml.en.html - -Download and install the following packages: - - - libxslt-1.1.17.win32.zip - - libxml2-2.6.26.win32.zip - - iconv-1.9.2.win32.zip - - zlib-1.2.3.win32.zip - -Note: I did not have success with libxslt from GnuWin32 so I would not -recommend using that version. - -Third, you will need the hhc.exe command-line compiler from the -HTML Help Workshop, available here: - - http://go.microsoft.com/fwlink/?LinkId=14188 - -Make sure that your PATH is updated so that the executables and DLLs -obtained from downloading all of those packages can be found. - -In order to translate from DocBook into HTML Help source and then into -a CHM file, open a command prompt and cd into the docs/manual -subdirectory underneath where you installed the Graphic-Forms source. - -Modify the URI values in catalog.xml to suit your particular -environment, then run make on Makefile. A file named -graphic-forms-<version>.chm is created in the current directory. -<version> is the version of Graphic-Forms. Double-click on the -CHM file and start enjoying the Programming Reference :-) - - -More information about configuring DocBook and xsltproc, as well -as a quick tutorial on the whole process, see these links: - - http://www.pnotepad.org/devlog/archives/000173.html - http://www.codeproject.com/winhelp/docbook_howto.asp - -[the end] + +The Programming Reference source consists of XML-based source files, +some of which are DocBook files and others which are transformed +into DocBook, along with custom XSLT and CSS files, and a catalog +file for resolving URIs. Several utilities comprise the translation +process from sources into HTML Help (CHM) format. + +Before anything else, you should install a version of GNU Make +for Windows, since the docs build process is managed with a +makefile. Just install MSYS or Cygwin, if you haven't already. + +Next, you will need a version of xsltproc and its dependencies. The +version of xsltproc that I have had success using is available from: + + http://www.zlatkovic.com/libxml.en.html + +Download and install the following packages: + + - libxslt-1.1.17.win32.zip + - libxml2-2.6.26.win32.zip + - iconv-1.9.2.win32.zip + - zlib-1.2.3.win32.zip + +Note: I did not have success with libxslt from GnuWin32 so I would not +recommend using that version. + +Third, you will need the hhc.exe command-line compiler from the +HTML Help Workshop, available here: + + http://go.microsoft.com/fwlink/?LinkId=14188 + +Make sure that your PATH is updated so that the executables and DLLs +obtained from downloading all of those packages can be found. + +In order to translate from DocBook into HTML Help source and then into +a CHM file, open a command prompt and cd into the docs/manual +subdirectory underneath where you installed the Graphic-Forms source. + +Modify the URI values in catalog.xml to suit your particular +environment, then run make on Makefile. A file named +graphic-forms-<version>.chm is created in the current directory. +<version> is the version of Graphic-Forms. Double-click on the +CHM file and start enjoying the Programming Reference :-) + + +More information about configuring DocBook and xsltproc, as well +as a quick tutorial on the whole process, see these links: + + http://www.pnotepad.org/devlog/archives/000173.html + http://www.codeproject.com/winhelp/docbook_howto.asp + +[the end]

Modified: trunk/docs/manual/introduction.xml ============================================================================== --- trunk/docs/manual/introduction.xml (original) +++ trunk/docs/manual/introduction.xml Mon Aug 13 01:52:39 2007 @@ -1,188 +1,179 @@ -<!-- - introduction.xml - - Copyright (c) 2006-2007, Jack D. Unrue ---> -<chapter id="introduction"> - <title>Introduction</title> - <indexterm><primary>Introduction</primary></indexterm> - - <bridgehead renderas="sect2">Background</bridgehead> - <para role="normal"> - Graphic-Forms is a user interface library implemented in Common Lisp - focusing on the Windows platform. Graphic-Forms is licensed under the - terms of the BSD License. The goal is to provide a Common Lisp-based - toolkit for developing GUI applications on Windows. GUI features are - encapsulated by a thin abstraction layer offering a Lisp-friendly - programming interface. The library can be extended via Common Lisp - bindings for system APIs. - </para> - <para role="normal"> - Why implement another UI toolkit? I believe that there is still room - for improvement in this area, especially where declarative and dynamic - approaches are concerned. Also, there are relatively few Windows GUI - programming resources for Common Lisp. Long-term goals for this project - may include implementing an application framework on top of the toolkit, - a rapid UI development language, a UI design tool, or some combination - thereof. - </para> - <para role="normal"> - The remainder of this chapter provides basic information for programmers - that want to use Graphic-Forms in their projects as well as contributors. - </para> - <para role="normal"> - <emphasis role="bold">Caution:</emphasis> The information provided in this - manual is subject to change. The author and contributors reserve the right - to make API changes unless and until the interfaces are deemed stable, at - which time a policy for backwards compatibility will be published. - </para> - - <bridgehead renderas="sect2">Project Website</bridgehead> - <para role="normal"> - <ulink url="http://common-lisp.net/project/graphic-forms/"/> - </para> - - <section> - <title>Prerequisites</title> - <bridgehead renderas="sect2">Supported Common Lisp Implementations</bridgehead> - <itemizedlist mark="bullet" spacing="compact"> - <listitem>Allegro CL 8.0</listitem> - <listitem>CLISP 2.40 or later</listitem> - <listitem>LispWorks 4.4.6</listitem> - <listitem> - SBCL 1.0.5 or later - <footnote> - <para role="small"> - a small patch to enable the stdcall calling convention for callbacks - is temporarily bundled with Graphic-Forms, see - <filename>src/external-libraries/sbcl-callback-patch/</filename> - </para> - </footnote> - </listitem> - </itemizedlist> - - <bridgehead renderas="sect2">Supported Windows Versions</bridgehead> - <itemizedlist mark="bullet" spacing="compact"> - <listitem>XP SP2</listitem> - <listitem> - Vista - <footnote> - <para role="small"> - testing on RC1 is in-progress - </para> - </footnote> - </listitem> - </itemizedlist> - - - <variablelist><title>Required Libraries (downloaded separately)</title> - <varlistentry> - <term><productname>ASDF</productname></term> - <listitem> - <ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf"/> - <para role="normal"> - Note that ASDF is bundled with Allegro CL and SBCL. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><productname>CFFI</productname></term> - <listitem> - <ulink url="http://common-lisp.net/project/cffi"/> - <para role="normal" /> - </listitem> - </varlistentry> - <varlistentry> - <term><productname>Closer to MOP</productname></term> - <term><productname>lw-compat</productname></term> - <listitem> - <ulink url="http://common-lisp.net/project/closer/downloads.html"/> - <para role="normal" /> - </listitem> - </varlistentry> - </variablelist> - - <variablelist><title>Required Libraries (bundled with Graphic-Forms)</title> - <varlistentry> - <term><productname>Practical Common Lisp Chapter08 and Chapter24</productname></term> - <listitem> - <ulink url="http://www.gigamonkeys.com/book/practicals-1.0.3.tar.gz"/> - <para role="normal" /> - </listitem> - </varlistentry> - <varlistentry> - <term><productname>lisp-unit</productname></term> - <listitem> - <ulink url="http://www.cs.northwestern.edu/academics/courses/325/readings/lisp-unit.html"/> - <para role="normal" /> - </listitem> - </varlistentry> - </variablelist> - - <variablelist><title>Optional Libraries (downloaded separately)</title> - <varlistentry> - <term><productname>ImageMagick</productname></term> - <listitem> - <ulink url="http://imagemagick.org/script/binary-releases.php#windows"/> - <para role="normal"> - Install the Q16 version and push the keyword symbol - <filename>:load-imagemagick-plugin</filename> onto - <emphasis>*features*</emphasis> before executing ASDF. - </para> - </listitem> - </varlistentry> - </variablelist> - - <bridgehead renderas="sect2">Building the Library</bridgehead> - <para role="normal"> - Please see the <filename>README.txt</filename> file included in the - distribution for instructions on how to load the ASDF system, run - unit-tests, and demo programs. - </para> - </section> - - <section> - <title>Support and Feedback</title> - <variablelist><title>Mailing Lists</title> - <varlistentry> - <term><productname>Announcements</productname></term> - <listitem> - <ulink url="http://www.common-lisp.net/mailman/listinfo/graphic-forms-announce"/> - <para/> - </listitem> - </varlistentry> - <varlistentry> - <term><productname>Developers</productname></term> - <listitem> - <ulink url="http://www.common-lisp.net/mailman/listinfo/graphic-forms-devel"/> - <para/> - </listitem> - </varlistentry> - <varlistentry> - <term><productname>Source control</productname></term> - <listitem> - <ulink url="http://www.common-lisp.net/mailman/listinfo/graphic-forms-cvs"/> - <para/> - </listitem> - </varlistentry> - </variablelist> - - <variablelist><title>Bug Reports and Patches</title> - <varlistentry> - <term><productname>Bug reports</productname></term> - <listitem> - <ulink url="http://sourceforge.net/tracker/?group_id=163034&amp;atid=826145"/> - <para/> - </listitem> - </varlistentry> - <varlistentry> - <term><productname>Patch submissions</productname></term> - <listitem> - <ulink url="http://sourceforge.net/tracker/?group_id=163034&amp;atid=826147"/> - <para/> - </listitem> - </varlistentry> - </variablelist> - </section> - -</chapter> +<!-- + introduction.xml + + Copyright (c) 2006-2007, Jack D. Unrue +--> +<chapter id="introduction"> + <title>Introduction</title> + <indexterm><primary>Introduction</primary></indexterm> + + <bridgehead renderas="sect2">Background</bridgehead> + <para role="normal"> + Graphic-Forms is a user interface library implemented in Common Lisp + focusing on the Windows platform. Graphic-Forms is licensed under the + terms of the BSD License. The goal is to provide a Common Lisp-based + toolkit for developing GUI applications on Windows. GUI features are + encapsulated by a thin abstraction layer offering a Lisp-friendly + programming interface. The library can be extended via Common Lisp + bindings for system APIs. + </para> + <para role="normal"> + Why implement another UI toolkit? I believe that there is still room + for improvement in this area, especially where declarative and dynamic + approaches are concerned. Also, there are relatively few Windows GUI + programming resources for Common Lisp. Long-term goals for this project + may include implementing an application framework on top of the toolkit, + a rapid UI development language, a UI design tool, or some combination + thereof. + </para> + <para role="normal"> + The remainder of this chapter provides basic information for programmers + that want to use Graphic-Forms in their projects as well as contributors. + </para> + <para role="normal"> + <emphasis role="bold">Caution:</emphasis> The information provided in this + manual is subject to change. The author and contributors reserve the right + to make API changes unless and until the interfaces are deemed stable, at + which time a policy for backwards compatibility will be published. + </para> + + <bridgehead renderas="sect2">Project Website</bridgehead> + <para role="normal"> + <ulink url="http://common-lisp.net/project/graphic-forms/"/> + </para> + + <section> + <title>Prerequisites</title> + <bridgehead renderas="sect2">Supported Common Lisp Implementations</bridgehead> + <itemizedlist mark="bullet" spacing="compact"> + <listitem>Allegro CL 8.0</listitem> + <listitem>CLISP 2.40 or later</listitem> + <listitem>LispWorks 5.0.1</listitem> + <listitem> + SBCL 1.0.5 or later + <footnote> + <para role="small"> + a small patch to enable the stdcall calling convention for callbacks + is temporarily bundled with Graphic-Forms, see + <filename>src/external-libraries/sbcl-callback-patch/</filename> + </para> + </footnote> + </listitem> + </itemizedlist> + + <bridgehead renderas="sect2">Supported Windows Versions</bridgehead> + <itemizedlist mark="bullet" spacing="compact"> + <listitem>XP SP2</listitem> + </itemizedlist> + + <variablelist><title>Required Libraries (downloaded separately)</title> + <varlistentry> + <term><productname>ASDF</productname></term> + <listitem> + <ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf"/> + <para role="normal"> + Note that ASDF is bundled with Allegro CL and SBCL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><productname>CFFI</productname></term> + <listitem> + <ulink url="http://common-lisp.net/project/cffi"/> + <para role="normal" /> + </listitem> + </varlistentry> + <varlistentry> + <term><productname>Closer to MOP</productname></term> + <term><productname>lw-compat</productname></term> + <listitem> + <ulink url="http://common-lisp.net/project/closer/downloads.html"/> + <para role="normal" /> + </listitem> + </varlistentry> + </variablelist> + + <variablelist><title>Required Libraries (bundled with Graphic-Forms)</title> + <varlistentry> + <term><productname>Practical Common Lisp Chapter08 and Chapter24</productname></term> + <listitem> + <ulink url="http://www.gigamonkeys.com/book/practicals-1.0.3.tar.gz"/> + <para role="normal" /> + </listitem> + </varlistentry> + <varlistentry> + <term><productname>lisp-unit</productname></term> + <listitem> + <ulink url="http://www.cs.northwestern.edu/academics/courses/325/readings/lisp-unit.html"/> + <para role="normal" /> + </listitem> + </varlistentry> + </variablelist> + + <variablelist><title>Optional Libraries (downloaded separately)</title> + <varlistentry> + <term><productname>ImageMagick</productname></term> + <listitem> + <ulink url="http://imagemagick.org/script/binary-releases.php#windows"/> + <para role="normal"> + Install the Q16 version and push the keyword symbol + <filename>:load-imagemagick-plugin</filename> onto + <emphasis>*features*</emphasis> before executing ASDF. + </para> + </listitem> + </varlistentry> + </variablelist> + + <bridgehead renderas="sect2">Building the Library</bridgehead> + <para role="normal"> + Please see the <filename>README.txt</filename> file included in the + distribution for instructions on how to load the ASDF system, run + unit-tests, and demo programs. + </para> + </section> + + <section> + <title>Support and Feedback</title> + <variablelist><title>Mailing Lists</title> + <varlistentry> + <term><productname>Announcements</productname></term> + <listitem> + <ulink url="http://www.common-lisp.net/mailman/listinfo/graphic-forms-announce"/> + <para/> + </listitem> + </varlistentry> + <varlistentry> + <term><productname>Developers</productname></term> + <listitem> + <ulink url="http://www.common-lisp.net/mailman/listinfo/graphic-forms-devel"/> + <para/> + </listitem> + </varlistentry> + <varlistentry> + <term><productname>Source control</productname></term> + <listitem> + <ulink url="http://www.common-lisp.net/mailman/listinfo/graphic-forms-cvs"/> + <para/> + </listitem> + </varlistentry> + </variablelist> + + <variablelist><title>Bug Reports and Patches</title> + <varlistentry> + <term><productname>Bug reports</productname></term> + <listitem> + <ulink url="http://sourceforge.net/tracker/?group_id=163034&amp;atid=826145"/> + <para/> + </listitem> + </varlistentry> + <varlistentry> + <term><productname>Patch submissions</productname></term> + <listitem> + <ulink url="http://sourceforge.net/tracker/?group_id=163034&amp;atid=826147"/> + <para/> + </listitem> + </varlistentry> + </variablelist> + </section> + +</chapter>