[graphic-forms-cvs] r336 - trunk/docs/manual
junrue at common-lisp.net
junrue at common-lisp.net
Tue Oct 17 03:54:17 UTC 2006
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 © 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 © 2006, Jack D. Unrue <jdunrue at gmail dot com>
+ </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® 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>
More information about the Graphic-forms-cvs
mailing list