[graphic-forms-cvs] r336 - trunk/docs/manual

Author: junrue Date: Mon Oct 16 23:54:16 2006 New Revision: 336

Added: trunk/docs/manual/Makefile trunk/docs/manual/catalog.xml trunk/docs/manual/graphic-forms.css trunk/docs/manual/graphic-forms.xml trunk/docs/manual/graphic-forms.xsl trunk/docs/manual/introduction.xml trunk/docs/manual/legal.xml Modified: trunk/docs/manual/README.txt Log: transitioning to DocBook/XSL

Added: trunk/docs/manual/Makefile ============================================================================== --- (empty file) +++ trunk/docs/manual/Makefile Mon Oct 16 23:54:16 2006 @@ -0,0 +1,20 @@ +# -*- Mode: Makefile; tab-width: 3; indent-tabs-mode: t -*- +# +# Makefile +# +# Copyright (c) 2006, Jack D. Unrue +# + +docs: + xsltproc --nonet graphic-forms.xsl graphic-forms.xml + -hhc htmlhelp.hhp + +clean: + find . ( -name "*~" -o -name "*.html" -o -name "*.hhk" -o -name "*.hhc" -o -name "*.hhp" ) -exec rm {} ; + +scrub: clean + find . -name "*.chm" -exec rm {} ; + +# +# TODO: implement an upload target +#

Modified: trunk/docs/manual/README.txt ============================================================================== --- trunk/docs/manual/README.txt (original) +++ trunk/docs/manual/README.txt Mon Oct 16 23:54:16 2006 @@ -1,10 +1,55 @@

-The files in this directory are edited and compiled via a tool that generates -output in two formats: HTML Help (CHM) and Javascript-enabled HTML. +The Programming Reference source consists of XML-based DocBook files, +custom XSLT and CSS files, and a catalog file for resolving URIs. Two +sets of utilities are used to translate the sources into HTML Help +(CHM) format.

-The specific tool currently used is WinCHM, which is a shareware application -available from http://www.softany.com/winchm/ As of October 2006, Softany -provides a near-fully-functional evaluation version for download. +First, you will need a version of xsltproc and its dependencies. The +version of xsltproc that I have had success using is available from:

-The feature set and quality of this tool are not satisfactory, so I may -decide to migrate to something else in the future. + 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. + +Second, 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 where you installed the Graphic-Forms source. + +Modify the URI values in catalog.xml to suit your particular +environment, then run the following commands (note that I am using +MSYS, so these are run from my bash prompt, translate appropriately +if you are in a Windows CMD prompt): + +% export XML_CATALOG_FILES=catalog.xml +% xsltproc --nonet graphic-forms.xsl graphic-forms.xml +% hhc htmlhelp.hhp + +Then double-click on graphic-forms.chm and you should see the +Programming Reference appear. + +The provided Makefile automates the above commands. + + +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]

Added: trunk/docs/manual/catalog.xml ============================================================================== --- (empty file) +++ trunk/docs/manual/catalog.xml Mon Oct 16 23:54:16 2006 @@ -0,0 +1,11 @@ +<?xml version="1.0"?> +<!-- + graphic-forms.xsl + + Copyright (c) 2006, Jack D. Unrue +--> +<!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> + +<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> + <uri name="htmlhelp.xsl" uri="c:/projects/third_party/docbook-xsl-1.71.0/htmlhelp/htmlhelp.xsl" /> +</catalog>

Added: trunk/docs/manual/graphic-forms.css ============================================================================== --- (empty file) +++ trunk/docs/manual/graphic-forms.css Mon Oct 16 23:54:16 2006 @@ -0,0 +1,31 @@ +h2.title { + font-size: 16; + font-family: { Arial, Helvetica, sans-serif; } + font-weight: Bold; +} + +h2.subtitle { + font-size: 16; + font-family: { Arial, Helvetica, sans-serif; } +} + +p.title, h3 { + font-size: 14; + font-family: { Arial, Helvetica, sans-serif; } + font-weight: Bold; +} + +div.footer { + font-size: 9; + font-family: { Arial, Helvetica, sans-serif; } +} + +div.itemizedlist { + font-size: 12; + font-family: { Arial, Helvetica, sans-serif; } +} + +a, p.normal, span.productname { + font-size: 12; + font-family: { Arial, Helvetica, sans-serif; } +}

Added: trunk/docs/manual/graphic-forms.xml ============================================================================== --- (empty file) +++ trunk/docs/manual/graphic-forms.xml Mon Oct 16 23:54:16 2006 @@ -0,0 +1,26 @@ +<?xml version="1.0"?> +<!-- + graphic-forms.xml + + Copyright (c) 2006, Jack D. Unrue +--> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[ + <!ENTITY legal SYSTEM "legal.xml"> + <!ENTITY introduction SYSTEM "introduction.xml"> +]> + +<book> + <title>Graphic-Forms</title> + <subtitle>Programming Reference (version 0.6)</subtitle> + + <bridgehead renderas="sect2"> + A user interface toolkit for the Windows platform. + </bridgehead> + + + &legal; + &introduction; + + <index id="index"/> +</book>

Added: trunk/docs/manual/graphic-forms.xsl ============================================================================== --- (empty file) +++ trunk/docs/manual/graphic-forms.xsl Mon Oct 16 23:54:16 2006 @@ -0,0 +1,28 @@ +<?xml version="1.0"?> +<!-- + graphic-forms.xsl + + Copyright (c) 2006, Jack D. Unrue +--> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:import href="htmlhelp.xsl"/> + <xsl:param name="chapter.autolabel" select="0"/> + <xsl:param name="chunk.first.sections" select="1"/> + <xsl:param name="chunk.section.depth" select="2"/> + <xsl:param name="generate.legalnotice.link" select="0"/> + <xsl:param name="generate.toc" /> + <xsl:param name="html.stylesheet" select="'graphic-forms.css'"/> + <xsl:param name="htmlhelp.button.hideshow" select="0"/> + <xsl:param name="htmlhelp.button.forward" select="1"/> + <xsl:param name="htmlhelp.button.next" select="0"/> + <xsl:param name="htmlhelp.button.prev" select="0"/> + <xsl:param name="htmlhelp.chm" select="'graphic-forms.chm'"/> + <xsl:param name="htmlhelp.hhc.folders.instead.books" select="0"/> + <xsl:param name="htmlhelp.show.advanced.search" select="1"/> + <xsl:template name="user.footer.navigation"> + <hr/> + <div class="footer"> + Copyright &#x00A9; 2006, Jack D. Unrue + </div> + </xsl:template> +</xsl:stylesheet>

Added: trunk/docs/manual/introduction.xml ============================================================================== --- (empty file) +++ trunk/docs/manual/introduction.xml Mon Oct 16 23:54:16 2006 @@ -0,0 +1,132 @@ +<!-- + introduction.xml + + Copyright (c) 2006, Jack D. Unrue +--> +<chapter> + <title>Introduction</title> + + <bridgehead renderas="sect2">Background</bridgehead> + <para role="normal"> + <indexterm><primary>Introduction</primary></indexterm> + 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>CLISP 2.38 or later</listitem> + <listitem>LispWorks 4.4.6</listitem> + <listitem>SBCL 0.9.15 or later</listitem> + </itemizedlist> + + <bridgehead renderas="sect2">Supported Windows Versions</bridgehead> + <itemizedlist mark="bullet" spacing="compact"> + <listitem>XP SP2</listitem> + <listitem>Vista</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 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> + <bridgehead renderas="sect2">Foo</bridgehead> + </section> + +</chapter>

Added: trunk/docs/manual/legal.xml ============================================================================== --- (empty file) +++ trunk/docs/manual/legal.xml Mon Oct 16 23:54:16 2006 @@ -0,0 +1,48 @@ +<!-- + legal.xml + + Copyright (c) 2006, Jack D. Unrue +--> +<chapter> + <title>Legal Notices</title> + <para> + Copyright &#x00A9; 2006, Jack D. Unrue &lt;jdunrue at gmail dot com&gt; + </para> + <para role="normal"> + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + </para> + <para role="normal"> + 1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + </para> + <para role="normal"> + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + </para> + <para role="normal"> + 3. Neither the names of the authors nor the names of its contributors may + be used to endorse or promote products derived from this software without + specific prior written permission. + </para> + <para> + THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE AUTHORS AND CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + </para> + + <bridgehead renderas="sect2">Trademarks</bridgehead> + <para role="normal"> + Windows&#x00ae; is a registered trademark of Microsoft Corporation. LispWorks + is a trademark of LispWorks Ltd. All other trademarks used are owned by their + respective owners. + </para> +</chapter>