Import XaoS r489 (trunk after version 3.5)

11 files changed, 13961 insertions, 0 deletions

diff --git a/doc/Makefile.in b/doc/Makefile.in
new file mode 100644
index 0000000..b5114d2
--- /dev/null
+++ b/doc/Makefile.in
@@ -0,0 +1,36 @@
+all: doc
+
+doc: xaos.info dvi ../AUTHORS
+
+xaos.texinfo: xaos.geninfo ../help/xaos.hlp
+	./mktexi
+
+xaos.info: xaos.texinfo
+	makeinfo --no-split xaos.texinfo --force
+
+xaosdev.info: xaosdev.texinfo
+	makeinfo --no-split xaosdev.texinfo --force
+
+xaos.dvi: xaos.texinfo
+	tex xaos.texinfo
+	texindex xaos.??
+	tex xaos.texinfo
+
+xaosdev.dvi: xaosdev.texinfo
+	tex xaosdev.texinfo
+	texindex xaosdev.??
+	tex xaosdev.texinfo
+
+dvi: xaos.dvi xaosdev.dvi
+	rm -f xaos.aux xaos.cp xaos.fn xaos.ky xaos.log xaos.pg xaos.toc \
+	 xaos.tp xaos.vr xaosdev.aux xaosdev.cp xaosdev.cps xaosdev.fn \
+	 xaosdev.fns xaosdev.ilg xaosdev.ind xaosdev.ky xaosdev.kys \
+	 xaosdev.log xaosdev.pg xaosdev.pgs xaosdev.toc xaosdev.tp \
+	 xaosdev.tps xaosdev.vr xaosdev.vrs xaos.cps xaos.fns xaos.kys \
+	 xaos.pgs xaos.tps xaos.vrs
+
+../AUTHORS: xaos.info
+	./mkauthors > ../AUTHORS
+
+clean:
+	rm -f xaos.info xaos.texinfo xaos.dvi xaosdev.dvi # ../AUTHORS
diff --git a/doc/XaoS.lsm b/doc/XaoS.lsm
new file mode 100644
index 0000000..488f6d1
--- /dev/null
+++ b/doc/XaoS.lsm
@@ -0,0 +1,27 @@
+Begin3
+Title:          XaoS - a fast portable real-time interactive fractal zoomer/morpher
+Version:        3.4
+Entered-date:   Sep 28 2008
+
+Description:    XaoS is a fast portable real-time interactive fractal zoomer.
+		It displays the Mandelbrot set (among other escape
+		time fractals) and allows you to zoom smoothly into the fractal.
+		Various coloring modes are provided for both the points inside 
+		and outside the selected set. In addition, switching between 
+		Julia and Mandelbrot fractal types is provided. The first 
+		version was a poorly written Mandelbrot viewer by Thomas later 
+		modified by Jan to support high frame-rate zooming. Other 
+		additions were later made including autopilot (for those of 
+		you without driver licenses), palette changing, PNG saving, 
+		and fractal inversion.
+Keywords:       X11 fractal realtime zoom mandelbrot newton
+		julia autopilot demo
+Author:         jh@ucw.cz (Jan Hubicka)
+		thomas@tivoli.com (Thomas Marsh)
+Maintained-by:  kovzol@particio.com (Zoltan Kovacs)
+Primary-site:   xaos.sf.net
+Platform:       GNU/Linux or any UNIX with X11 and ANSI C compiler,
+		Microsoft Windows (95, 98, XP), Mac OS X
+Copying-policy: GNU GENERAL PUBLIC LICENSE
+		All rights reserved by the author
+End
diff --git a/doc/mkauthors b/doc/mkauthors
new file mode 100755
index 0000000..3ed729a
--- /dev/null
+++ b/doc/mkauthors
@@ -0,0 +1,13 @@
+#!/bin/sh
+echo "AUTHORS
+-------
+
+This file is autogenerated from help/xaos.hlp.
+If you add a new feature to XaoS or fix a bug,
+please edit help/xaos.hlp and run \"cd doc; make\".
+
+This list is ordered alphabetically."
+
+cat -v xaos.info | sed "1,/C Credits/ d;/C.0.1/,\$ d" | \
+ sed s/*//g | sed s/"(alphabetically)"/""/ |
+ sed s/Note// | sed s/"lists::."/""/ | sed s/"\^_"//
diff --git a/doc/mktexi b/doc/mktexi
new file mode 100755
index 0000000..86a66b6
--- /dev/null
+++ b/doc/mktexi
@@ -0,0 +1,5 @@
+#!/bin/sh
+set -e
+echo "Generating xaos.texinfo..."
+awk '/##.*##/ {system("sh ../help/conv "$3" "$4" <../help/xaos.hlp ");};
+     /.*/ {print $0}'  <xaos.geninfo >xaos.texinfo
diff --git a/doc/texi2rest.py b/doc/texi2rest.py
new file mode 100755
index 0000000..58fd5cd
--- /dev/null
+++ b/doc/texi2rest.py
@@ -0,0 +1,593 @@
+#!/usr/bin/python
+"""
+NAME
+====
+
+texi2rest - Convert texinfo xml represenation to reStructuredText
+
+SYNOPSIS
+========
+
+texi2rest *xmlfile* > *restfile*
+
+DESCRIPTION
+===========
+
+``texi2rest`` is based on ``xhtml2rest`` by Antonios Christofides. He
+included the following disclaimer for his program, and it applies
+equally to mine: far from being a decent and complete program, this is
+only something to begin with, which hopefully processes the given UTF-8
+texinfo xml file and produces reStructuredText "source code" in the
+standard output.
+
+Before processing the texinfo file, you must convert it to xml using
+the makeinfo command:
+
+    makeinfo --xml *texifile*
+
+    texi2rest *xmlfile* > *restfile*
+
+LIMITATIONS
+===========
+
+I am writing this specifically to convert the XaoS project's
+documentation. I do not plan to implement full conversion of every 
+texinfo directive--only the ones used in the documentation I am trying
+to convert. Hopefully other interested parties will contribute further
+improvements.
+
+
+META
+====
+
+``texi2rest`` was hacked together by J.B. Langston, 
+jb-langston@austin.rr.com, based on ``xhtml2rest`` by
+Antonios Christofides, anthony@itia.ntua.gr.
+
+Revision: $Revision: 3753 $
+
+The code and this text is hereby placed in the public domain.
+"""
+
+import xml.dom.minidom
+import re
+import sys
+import textwrap
+import math
+import UserList
+import warnings
+import codecs
+
+###############################################################################
+# Configuration: these values change the behavior of the conversion
+
+# Texinfo commands that generate emphasis markup (i.e., *text*)
+EMPHASIS_COMMANDS = ('emph', 'i', 'slanted', 'var')
+
+# Texinfo commands that generate strong markup (i.e., **text**)
+STRONG_COMMANDS = ('strong', 'b')
+
+# Texinfo commands that generate literal markup (i.e.,``text``)
+LITERAL_COMMANDS = ('code', 'verb' 'tt')
+
+# Texinfo commands that map to reST roles of the same name (i.e., :role:`text`)
+VERBATIM_COMMANDS = ('dfn', 'file', 'command', 'option', 'kbd', 'samp', 'math')
+
+# Texinfo commands that map to differnet reStructuredText roles (i.e., :role:`text`)
+MAPPED_COMMANDS = {
+    'env': 'envvar', 
+    'key': 'kbd', 
+    'cite': 'title' 
+}
+
+# Texinfo commands that do not generate any markup, but preserve nested text
+IGNORED_COMMANDS = ('url', 'sc', 'r', 'sansserif', 'titlefont', 'dmn', 'logo', 'punct')
+
+# Texinfo commands that are deleted from output, including nested text
+DELETED_COMMANDS = ()
+
+# Map of Texinfo section commands to section underline/overline characters
+# Single character indicates underline only; double characters indicates overline+underline
+SECTION_COMMANDS = {
+    # level 1
+    'top': '**',
+    'chapter': '**',
+    'unnumbered': '**',
+    'appendix': '**',
+    # level 2
+    'section': '=',
+    'unnumberedsec': '=',
+    'appendixsec': '=',
+    # level 3
+    'subsection': '-',
+    'unnumberedsubsec': '-',
+    'appendixsubsec': '-',
+    # level 4
+    'subsubsection': '^',
+    'unnumberedsubsubsec': '^',
+    'appendixsubsubsec': '^',
+}
+
+
+###############################################################################
+
+###############################################################################
+# Global variables. I know. I'm terribly sorry. Please get rid of them.
+
+# 'unindent' is used by list items. A li list item is always indented, but its
+# first line is "unindented" and contains the number or bullet. However, it was
+# difficult for the li node to tell its #text contents (which may be deeply
+# nested) to use that.  So it just places the number or bullet, which must be 4
+# characters, like " 1. ", in "unindent". The first text to be rendered uses
+# the unindent and then sets it to empty again.
+
+unindent = ''
+hyperlinks = {} # text-target pairs found in "a href" elements
+###############################################################################
+
+class Ditem:
+    """A document item; usually a node, but can be a block of text
+    resulting from processing adjacent inline items. If it is a node,
+    it is usually the BlockDitem subclass; if it is text, it is
+    normally a plain Ditem."""
+    def __init__(self, text):
+        self.text = text    # Contained text (empty for BlockDitem)
+        self.type = ''      # tag for block node, empty for inline
+        self.indentlevel = 0  # 0 - unindented; 1 - indented; etc.
+    def __repr__(self):
+        return self.__class__.__name__+'("""'+self.text+'""")'
+    def propagate_indents(self):
+        "Propagates indent level recursively to children"
+        pass
+    def maxwidth(self):
+        "Width it will occupy if allowed to render on infinite width"
+        self.remove_white_space()
+        return len(self.text) + 4*self.indentlevel
+    def minwidth(self):
+        "Width it will occupy if wrapped as much as possible"
+        wordlens = [len(x) for x in self.text.split()]
+        if wordlens: return max(wordlens) + 4*self.indentlevel
+        else: return 0
+    def format(self, width):
+        """Returns contents formatted so as not to exceed specified
+        width, if possible"""
+        global unindent
+        if(self.type=='pre'): raise Exception, "What are we doing here?"
+        self.remove_white_space()
+        # Quick hack to fix a problem. Do we begin with '* '?
+        while len(self.text)>=2 and self.text[1]==' ' and self.text[0] in '*-':
+            # It may be mistaken for a bullet list. Strip it.
+            self.text = self.text[2:]
+        if width < self.minwidth(): width = self.minwidth()
+        # The textwrap module has the nasty habit of breaking at hyphens. So
+        # we'll do a nasty hack: find a character that does not exist in the
+        # text, replace all hyphens with that character, ok, you get the point.
+        hyphensurrogate = ''
+        for c in '!@#$%^&*~':
+            if self.text.find(c)<0:
+                hyphensurrogate = c
+                break
+        if not hyphensurrogate: raise Exception, "Houston we have a problem"
+        text = self.text.replace('-', hyphensurrogate)
+        wrapper = textwrap.TextWrapper(
+            initial_indent=((4*self.indentlevel)-len(unindent))*' '+unindent,
+            subsequent_indent=4*self.indentlevel*' ',
+            width=width, break_long_words = False)
+        unindent = ''
+        text = wrapper.fill(text)
+        text = text.replace(hyphensurrogate, '-')
+        return text
+    def empty(self):
+        "Returns true if contains nothing"
+        return not self.text
+    def remove_white_space(self):
+        "Removes extra white space"
+        self.text = re.sub('\s+', ' ', self.text).strip()
+    def canmerge(self):
+        "Tells whether it's possible to merge this Ditem with adjacent ones"
+        return True
+    def merge(self, aditem):
+        """If possible, merges aditem, which should be an adjacent Ditem that
+        comes after this one."""
+        if not self.canmerge() or not aditem.canmerge(): return False
+        if len(self.text)>0 and self.text[-1] == '_' and len(aditem.text)>0 \
+            and aditem.text[0] not in """ \n\t:.,!=/|;"'?<>[]{}()""":
+            # Leave space after link if not followed by punctuation
+            self.text = self.text + ' ' + aditem.text
+        else:
+            self.text = self.text + aditem.text
+        return True
+
+class BlockDitem(Ditem):
+    "A Ditem which contains other Ditems"
+    def __init__(self, type):
+        Ditem.__init__(self, '')
+        self.type = type
+        self.children = []  # Contained Ditems
+    def __repr__(self):
+        return self.__class__.__name__+'("'+self.type+'"); children = '+repr(self.children)
+    def maxwidth(self):
+        childmaxwidths = [x.maxwidth() for x in self.children]
+        return childmaxwidths and max(childmaxwidths) or 0
+    def minwidth(self):
+        childminwidths = [x.minwidth() for x in self.children]
+        return childminwidths and max(childminwidths) or 0
+    def propagate_indents(self):
+        for x in self.children:
+            x.indentlevel = self.indentlevel
+            x.propagate_indents()
+    def format(self, width):
+        if width < self.minwidth(): width = self.minwidth()
+        results = [x.format(width) for x in self.children]
+        results = [x for x in results if x]
+        return "\n\n".join(results)
+    def empty(self):
+        return not (self.children)
+    def canmerge(self):
+        return False
+
+class PreDitem(Ditem):
+    "A Ditem representing a literal block"
+    def maxwidth(self):
+        return max([len(x) for x in self.text.split('\n')])
+    def minwidth(self):
+        return self.maxwidth() # Literal block; width's given
+    def remove_white_space(self):
+        pass
+    def format(self, width):
+        result = '::\n\n'
+        for x in self.text.split('\n'):
+            result = result + '    ' + x + '\n'
+        result = result + '..\n\n'
+        return result
+    def canmerge(self):
+        return False
+
+class HeadingDitem(BlockDitem):
+    "A Ditem representing an h1, h2, ..., h9"
+    def __init__(self, type):
+        BlockDitem.__init__(self, type)
+    def minwidth(self):
+        return self.maxwidth()  # Headings don't wrap
+    def format(self, width):
+        assert(len(self.children)==1)
+        text = self.children[0].format(32767)
+        uldict = {
+            'chapter':    '**', 'section':       '=', 'subsection':       '-', 'subsubsection':       '^',
+            'unnumbered': '**', 'unnumberedsec': '=', 'unnumberedsubsec': '-', 'unnumberedsubsubsec': '^',
+            'appendix':   '**', 'appendixsec':   '=', 'appendixsubsec':   '-', 'appendixsubsubsec':   '^'
+        }
+        underliner = uldict[self.type]
+        if len(underliner) == 2:
+            return len(text)*underliner[0] + '\n' + text + '\n' + len(text)*underliner[0]
+        else:
+            return text + '\n' + len(text)*underliner[0]
+
+class BlockQuoteDitem(BlockDitem):
+    "A Ditem representing a blockquote"
+    def __init__(self, type):
+        BlockDitem.__init__(self, type)
+    def propagate_indents(self):
+        self.indentlevel = self.indentlevel + 1
+        BlockDitem.propagate_indents(self)
+
+class ListDitem(BlockDitem):
+    "A Ditem representing an ol, ul, or dl"
+    def __init__(self, type):
+        BlockDitem.__init__(self, type)
+    def format(self, width):
+        # First pass the list type and order to the children
+        order = 1
+        for x in self.children:
+            if isinstance(x, ListItemDitem):
+                x.listtype = self.type
+                x.order = order
+                order = order+1
+        # And then process normally
+        return BlockDitem.format(self, width)
+        
+class ListItemDitem(BlockDitem):
+    "A Ditem representing a li, dt, or dd"
+    def __init__(self, type):
+        BlockDitem.__init__(self, type)
+        self.listtype = None
+        self.order = 0
+    def minwidth(self):
+        if self.type == 'definitionterm': return self.maxwidth()  # Don't wrap dt
+        else: return BlockDitem.minwidth(self)
+    def propagate_indents(self):
+        if self.type in ('item', 'definitionitem'):
+            self.indentlevel = self.indentlevel + 1
+        BlockDitem.propagate_indents(self)
+    def format(self, width):
+        global unindent
+        if self.type == 'item' and self.listtype == 'enumerate':
+            unindent = ('%d. ' % (self.order)).ljust(4)
+        elif self.type == 'item' and self.listtype == 'itemize':
+            unindent = '*   '
+        return BlockDitem.format(self, width)
+
+class RenderedColumn:
+    "Width information about a column being rendered"
+    def __init__(self, minwidth, maxwidth):
+        self.minwidth = minwidth
+        self.maxwidth = maxwidth
+        self.curwidth = maxwidth
+        self.fixedwidth = 0
+    def logwidth(self):
+        if self.maxwidth==0: return 0
+        else: return math.log(self.maxwidth)
+    def update(self, minwidth, maxwidth):
+        "Replaces minwidth/maxwidth if greater"
+        self.minwidth = minwidth>self.minwidth and minwidth or self.minwidth
+        self.maxwidth = maxwidth>self.maxwidth and maxwidth or self.maxwidth
+        self.curwidth = self.maxwidth
+
+class RenderedColumns(UserList.UserList):
+    "A list of RenderedColumn"
+    def __init__(self, alist):
+        self.data = alist
+    def totalWidth(self):
+        "Returns total table width"
+        return reduce(lambda x,y: x+y, [z.curwidth for z in self.data]) \
+            + len(self.data) + 1
+    def sumLogWidth(self):
+        "Returns sum of logwidth for nonfixed columns"
+        return reduce(lambda x,y: x+y,
+            [x.logwidth()*(1-x.fixedwidth) for x in self.data])
+    def distributeWidthDifference(self, width):
+        "Step 4 of w3m table rendering algorithm"
+        # Note: The use of math.ceil below is because I'd rather have a
+        # suboptimal width (a few characters less than requested width) rather
+        # than go find what to do with rounding.
+        w = self.totalWidth() - width
+        assert(w>0)
+        repeat_distribution = 1
+        while repeat_distribution:
+            repeat_distribution = 0
+            for x in self.data:
+                if x.fixedwidth: continue
+                if x.curwidth - math.ceil(w*x.logwidth()/self.sumLogWidth()) < \
+                    x.minwidth:
+                        x.curwidth = x.minwidth
+                        x.fixedwidth = 1
+                        w = self.totalWidth() - width
+                        repeat_distribution=1
+                        break
+        # Now that the we finished finding which columns need to be fixed to
+        # their minimum width, perform the distribution once again, without
+        # checking, and actually change remaining column widths
+        for x in self.data:
+            if x.fixedwidth: continue
+            x.curwidth = x.curwidth - math.ceil(w*x.logwidth()/self.sumLogWidth())
+    
+def tablehrule(colwidths, rule='-'):
+    "Returns a horizontal table separator for given column widths"
+    result = '+'
+    for x in colwidths:
+        result = result + rule * x + '+'
+    return result
+
+class TableDitem(BlockDitem):
+    def __init__(self, type):
+        BlockDitem.__init__(self, type)
+    def format(self, width):
+        # Uses table rendering algorithm of w3m
+        # (http://www.w3m.org/story.html), but ignoring width attribute
+        # Step 1 
+        columns = RenderedColumns([RenderedColumn(x.minwidth(),
+            max(x.maxwidth(), 1)    # A column can't be smaller than 1 character
+            ) for x in self.children[0].children])
+        for x in self.children:
+            for i in range(len(columns)):
+                if (len(x.children)<=i): continue # Skip empty columns
+                columns[i].update(x.children[i].minwidth(), x.children[i].maxwidth())
+        # Step 2 (width attribute) ignored
+        # Step 3 (already done - list was created with maxwidth)
+        # Step 4
+        if columns.totalWidth() > width: columns.distributeWidthDifference(width)
+        # OK, column widths are now calculated
+        colwidths = [int(x.curwidth) for x in columns]
+        result = tablehrule(colwidths) + '\n'
+        usedheadbodysep = False
+        for tr in self.children:
+            result = result + tr.format(colwidths)
+            rule = '-'
+            if not usedheadbodysep and tr.children[0].type == 'th' \
+                                        and tr!=self.children[-1]:
+                rule = '='
+                usedheadbodysep = True
+            result = result + tablehrule(colwidths, rule) + '\n'
+        return result
+
+class TrDitem(BlockDitem):
+    def __init__(self, type):
+        BlockDitem.__init__(self, type)
+    def maxwidth(self):
+        return reduce(lambda x,y: x+y,
+            [x.maxwidth() for x in self.children]) + len(self.children) + 1
+    def minwidth(self):
+        return reduce(lambda x,y: x+y,
+            [x.minwidth() for x in self.children]) + len(self.children) + 1
+    def format(self, colwidths):
+        columns = []       # List of lists of lines
+        maxlinecount = 0   # Num of lines in vertically largest column
+        for i in range(len(colwidths)):
+            if len(self.children)<=i: lines = [ '' ]
+            else: lines = self.children[i].format(colwidths[i]).split('\n')
+            lines = [x + ' ' * (colwidths[i]-len(x)) for x in lines] # Pad to col len
+            maxlinecount = max(maxlinecount, len(lines))
+            columns.append(lines)
+        # Pad vertically
+        for i in range(len(columns)):
+            for j in range(maxlinecount-len(columns[i])):
+                columns[i].append(' ' * colwidths[i])
+        result = '' 
+        # Add vertical separators
+        for i in range(maxlinecount):
+            result = result + '|'
+            for j in range(len(columns)):
+                result = result + columns[j][i] + '|'
+            result = result + '\n'
+        return result
+
+def handleNodeList(nodelist):
+    "Processes given nodes; merges them if possible; returns ditem list"
+    ditems = []
+    curditem = Ditem('')
+    for node in nodelist:
+        aditem = handleNode(node)
+        if curditem.merge(aditem): continue
+        ditems.append(curditem)
+        curditem = aditem
+    if not curditem.empty(): ditems.append(curditem)
+    return ditems
+
+def handleNode(node):
+    if node.nodeType == node.TEXT_NODE:
+        return handleText(node)
+    elif node.nodeName in EMPHASIS_COMMANDS:
+        return handleEmphasis(node)
+    elif node.nodeName in STRONG_COMMANDS:
+        return handleStrong(code)
+    elif node.nodeName in LITERAL_COMMANDS:
+        return handleLiteral(node)
+    elif node.nodeName in VERBATIM_COMMANDS:
+        return handleVerbatimCommand(node)
+    elif node.nodeName in MAPPED_COMMANDS:
+        return handleMappedCommand(node)
+    elif node.nodeName in IGNORED_COMMANDS:
+        return handleIgnoredCommand(node)
+    elif node.nodeName in DELETED_COMMANDS:
+        return handleDeletedCommand(node)
+    elif node.hasChildNodes():
+        contents = handleNodeList(node.childNodes)
+        if len(contents) == 1: return contents[0]
+        if len(contents) == 0: return Ditem('')
+        result = BlockDitem(node.nodeName)
+        result.children = contents
+        return result
+    return Ditem('')
+
+def processChildren(node):
+    if node.hasChildNodes():
+        return handleNodeList(node.childNodes)
+    else:
+        return ()
+
+def mergeChildren(node):
+    contents = processChildren(node)
+    if len(contents)>1: raise Exception('Unexpected block elements')
+    if contents: return contents[0]
+    else: return Ditem('')
+
+def handleEmphasis(node):
+    result = mergeChildren(node)
+    result.type = node.nodeName
+    if result.text:
+        result.text = '*' + result.text + '*'
+    return result
+
+def handleStrong(node):
+    result = mergeChildren(node)
+    result.type = node.nodeName
+    if result.text:
+        result.text = '**' + result.text + '**'
+    return result
+
+def handleLiteral(node):
+    result = mergeChildren(node)
+    result.type = node.nodeName
+    if result.text:
+        result.text = '``' + result.text + '``'
+    return result
+
+def handleVerbatimCommand(node):
+    result = mergeChildren(node)
+    result.type = node.nodeName
+    if result.text:
+        result.text = ':' + node.nodeName + ':`' + result.text + '`'
+    return result
+
+def handleMappedCommand(node):
+    result = mergeChildren(node)
+    result.type = node.nodeName
+    if result.text:
+        result.text = ':' + MAPPED_COMMANDS[node.nodeName] + ':`' + result.text + '`'
+    return result
+
+def handleIgnoredCommand(node):
+    result = mergeChildren(node)
+    result.type = node.nodeName
+    return result
+
+def handleDeletedCommand(node):
+    result = ''
+    result.type = node.nodeName
+    return result
+
+def handleText(node):
+    return Ditem(node.data)
+
+def handleAnchor(node):
+    result = mergeChildren(node)
+    result.type = node.nodeName
+    result.text = result.text.strip()
+    if result.text == '': return result
+    target = node.getAttribute('href').strip()
+    result.text = re.sub('\s+', ' ', result.text)
+    result.text = ':ref:`'+result.text+' <'+target+'>`'
+    return result
+
+def handleHeading(node):
+    contents = mergeChildren(node)
+    if contents.empty(): return contents
+    result = HeadingDitem(node.parentNode.nodeName)
+    result.children.append(contents)
+    return result
+
+def handleGenericBlock(node):
+    result = BlockDitem(node.nodeName)
+    result.children = processChildren(node)
+    return result
+
+def handleBlockQuote(node):
+    result = BlockQuoteDitem(node.nodeName)
+    result.children = processChildren(node)
+    return result
+
+def handleList(node):
+    result = ListDitem(node.nodeName)
+    result.children = processChildren(node)
+    return result
+
+def handleListItem(node):
+    result = ListItemDitem(node.nodeName)
+    result.children = processChildren(node)
+    return result
+
+def handleTable(node):
+    result = TableDitem(node.nodeName)
+    # Ignore table contents that are not tr
+    result.children = [x
+        for x in processChildren(node) if x.type=='tr']
+    return result
+
+def handleTr(node):
+    result = TrDitem(node.nodeName)
+    # Ignore tr contents that are not th or td
+    result.children = [x
+        for x in processChildren(node) if x.type in ('th', 'td')]
+    return result
+
+def handlePre(node):
+    return PreDitem(mergeChildren(node).text)
+
+dom1 = xml.dom.minidom.parse(sys.argv[1])
+ditem = handleNode(dom1.getElementsByTagName("texinfo")[0])
+ditem.propagate_indents()
+(utf8_encode, utf8_decode, utf8_reader, utf8_writer) = codecs.lookup('utf-8')
+outf = utf8_writer(sys.stdout)
+outf.write(ditem.format(79) + '\n')
+for h in hyperlinks.keys():
+    outf.write('\n.. _`' + h + '`:\n    ' + hyperlinks[h] + '\n')
diff --git a/doc/xaos.6 b/doc/xaos.6
new file mode 100644
index 0000000..59fea28
--- /dev/null
+++ b/doc/xaos.6
@@ -0,0 +1,14 @@
+.TH XaoS 6 "22 Feb 2006" "XaoS" "Demos"
+
+.SH NAME
+xaos - Fast interactive real-time fractal zoomer/morpher
+
+.SH DETAILS
+This manual page is obsolete and no longer maintained.
+Please read the full documentation running
+XaoS. You can start it typing 'xaos'. (Press 'h' 3
+times to get into the help system.)
+.P
+In addition,
+.B xaos --help
+should give a detailed list about the command line options.
diff --git a/doc/xaos.geninfo b/doc/xaos.geninfo
new file mode 100644
index 0000000..42d8d52
--- /dev/null
+++ b/doc/xaos.geninfo
@@ -0,0 +1,283 @@
+\input texinfo   @c -*-texinfo-*-
+
+@c The original files are xaos.geninfo and xaos.hlp. xaos.texinfo is
+@c automatically generated. So make all changes in the orignal files please.
+@c To regenerate xaos.texinfo, please run "mktexinfo".
+
+@c Use A4 paper - If you don't like that, remove the following 3 lines.
+@iftex
+@afourpaper
+@end iftex
+
+@setfilename xaos.info
+@settitle An fast realtime interactive fractal zoomer --- user's manual
+@dircategory Graphics
+@direntry 
+* XaoS: (xaos).               A fast real-time interactive fractal zoomer
+@end direntry
+
+
+@ifinfo
+@copyright{} 1996-2008 Jan Hubicka and the XaoS Development Team
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+@end ifinfo
+
+@c %**end of header
+
+@set VERSION    3.4
+@set DATE       April 17, 2008
+
+@titlepage
+
+@title{XaoS @value{VERSION}}
+@subtitle{A fast real-time interactive fractal zoomer --- User's manual}
+
+@author{Jan Hubi@v cka}
+@tex
+Dukelsk\'ych bojovn\'\i ku 1944 
+@end tex
+@*
+390 03 T@'abor @*
+Czech Republic
+
+Email: @code{jh@@ucw.cz}
+
+@value{DATE}
+
+@page
+@vskip 0pt plus 1filll
+@vskip 0pt plus 1filll
+
+@copyright{} 1996-2008 @tex Jan Hubi\v cka and the XaoS Development Team
+@end tex
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+@end titlepage
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node   Top,    Overview,       (dir),  (dir)
+
+@ifinfo
+@top XaoS @value{VERSION}
+@flushright 1.0
+A real-time interactive fractal zoomer
+User's manual
+@value{DATE}
+@end flushright
+
+This manual contains user documentation about XaoS --- a fast real-time fractal
+zoomer. XaoS uses a development model, so sources are freely available. The
+file @code{xaosdev.texinfo} in the source documentation contains a hacker's
+manual (design overview, algorithm description etc.).
+@end ifinfo
+
+@menu
+* Overview::		What does this software do then?
+* tutorial::		XaoS tutorial
+* controls::		Basic controls
+* video::		How to encode video files
+* format::		XaoS's file format description
+* writehelp::		How to write XaoS help files
+* xshl::		XaoS simple hypertext language
+* drivers::		Driver specific documentation
+* menus::		Functions, menu items and command line parameters
+* about::		Credits
+* support::		Getting Support
+* index::		Function index
+@end menu
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node Overview, tutorial, Top, Top
+
+@chapter Overview
+@menu
+* Why?::		Why yet another fractal generator?
+* What?::		What does this software do then?
+@end menu
+
+@node Why?, What?, Overview, Overview
+@section Why yet another fractal generator?
+
+
+We decided to make XaoS, because all fractal browsers we know of take a
+long time to calculate each image. You may browse nice images
+generated by them but real impressions of fractals --- the self
+similarity and infinite zooming into the nice parts of fractals ---
+can be seen only in animations. There are many programs available that
+make nice animations, but they take a long time to calculate and lots
+of space on disk. Most such animations are quite ugly because their
+authors can't see them without many hours of calculations.
+
+A natural question is: is it possible to generate such animations in
+real-time? The answer was negative for many years, since the Mandelbrot set is
+very computationally expensive. Things are changing. Today's computers
+are fast enough to calculate approx. 10.000 of pixels per frame,
+which is enough 
+for a very low resolution animation (100x100). Several programs doing that
+are available. But 100x100 animation still looks quite ugly. To make
+animation nice you need at least 320x200 pixels. And that is 6 times more!
+One possibility is to wait until computers will be fast enough, but
+it will take many years, and then 320x200 animations will be obsolete
+and everyone will want 1024x768 resolution instead or more.
+
+We found a special algorithm that saves up to 99.98% of calculations during
+zooming by reusing pixels already calculated in previous frames. There were
+some programs doing similiar tricks before but we don't know about any able
+to do zooming interactively with a speed similar to XaoS. Many other tricks
+were later implemented XaoS to achieve yet higher framerates. Now XaoS does
+up to 120 frames per second on a 120Mhz pentium in a fullscreen 320x200
+animation, and calculates an average of 160 (0.24%) pixels per frame. This makes
+XaoS fast enough to achieve its primary goal, realtime animation, but there
+are still many areas that could improve, since more complex fractals,
+higher resolutions, or slower computers still bring many problems.
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node What?, , Why?, Overview
+@comment  node-name,  next,      previous,  up
+@section What does this software do then?
+
+XaoS is a realtime interactive fractal zoomer. This means that it lets you
+zoom smoothly into any place in the fractal you choose without the many hours
+of calculation required by most other fractal generators. It now has many
+other features too, like 13 different fractal types, autopilot, special coloring
+modes, support for various bit depths (8bpp, truecolor, hicolor and realcolor),
+random palette generation, color cycling etc...
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node tutorial, controls, Overview, Top
+@c ## chapter tutorial ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node controls, video, tutorial ,Top
+
+@c ## chapter controls ##
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node video, format, controls ,Top
+
+@c ## chapter video ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node format, writehelp,video ,Top
+@c ## chapter format ##
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node writehelp, xshl,format ,Top
+@c ## chapter writehelp ##
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node xshl, drivers,writehelp ,Top
+@c ## section xshl ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node drivers, menus,xshl ,Top
+@c ## chapter drivers ##
+
+@menu
+* aa::			AA-lib --- high quality ascii art driver
+* BeOS::		BeOS drivers
+* DGA:: 		DGA driver
+* dos::			DOS driver
+* dX-fullscreen::	directX fullscreen driver
+* dX-window::		directX windowed driver
+* ggi::			GGI driver
+* plan9::		plan9 driver
+* SVGAlib::		SVGAlib driver
+* win32::		Win32 driver
+* X11:: 		X11 driver
+@end menu
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node aa, BeOS , ,drivers
+@c ## section aa ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node BeOS, DGA , aa ,drivers
+@c ## section BeOS ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node DGA, dos , BeOS ,drivers
+@c ## section DGA ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node dos, dX-fullscreen , DGA ,drivers
+@c ## section dos ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node dX-fullscreen, dX-window , dos ,drivers
+@c ## section dX-fullscreen ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node dX-window, ggi , dX-fullscreen ,drivers
+@c ## section DX-window ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node ggi, plan9, dX-window ,drivers
+@c ## section ggi ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node plan9, SVGAlib, ggi ,drivers
+@c ## section plan9 ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node SVGAlib, win32, plan9 ,drivers
+@c ## section SVGAlib ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node win32, X11, SVGAlib ,drivers
+@c ## section win32 ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node X11, , win32 ,drivers
+@c ## section X11 ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node menus, about,  drivers,Top
+
+@c ## menus controls ##
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+@comment  node-name,  next,      previous,  up
+@node about, support,menus ,Top
+@c ## appendix about ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node support, index ,about ,Top
+@c ## appendix support ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node index,  ,support ,Top
+@unnumbered Index of functions
+
+@printindex fn
+
+
+@contents
+@bye
diff --git a/doc/xaos.info b/doc/xaos.info
new file mode 100644
index 0000000..5676dc2
--- /dev/null
+++ b/doc/xaos.info
@@ -0,0 +1,3818 @@
+This is xaos.info, produced by makeinfo version 4.11 from xaos.texinfo.
+
+INFO-DIR-SECTION Graphics
+START-INFO-DIR-ENTRY
+* XaoS: (xaos).               A fast real-time interactive fractal zoomer
+END-INFO-DIR-ENTRY
+
+   (C) 1996-2008 Jan Hubicka and the XaoS Development Team
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+
+File: xaos.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)
+
+XaoS 3.4
+********
+
+                                 A real-time interactive fractal zoomer
+                                                          User's manual
+                                                         April 17, 2008
+
+   This manual contains user documentation about XaoS -- a fast
+real-time fractal zoomer. XaoS uses a development model, so sources are
+freely available. The file `xaosdev.texinfo' in the source
+documentation contains a hacker's manual (design overview, algorithm
+description etc.).
+
+* Menu:
+
+* Overview::		What does this software do then?
+* tutorial::		XaoS tutorial
+* controls::		Basic controls
+* video::		How to encode video files
+* format::		XaoS's file format description
+* writehelp::		How to write XaoS help files
+* xshl::		XaoS simple hypertext language
+* drivers::		Driver specific documentation
+* menus::		Functions, menu items and command line parameters
+* about::		Credits
+* support::		Getting Support
+* index::		Function index
+
+
+File: xaos.info,  Node: Overview,  Next: tutorial,  Prev: Top,  Up: Top
+
+1 Overview
+**********
+
+* Menu:
+
+* Why?::		Why yet another fractal generator?
+* What?::		What does this software do then?
+
+
+File: xaos.info,  Node: Why?,  Next: What?,  Prev: Overview,  Up: Overview
+
+1.1 Why yet another fractal generator?
+======================================
+
+We decided to make XaoS, because all fractal browsers we know of take a
+long time to calculate each image. You may browse nice images generated
+by them but real impressions of fractals -- the self similarity and
+infinite zooming into the nice parts of fractals -- can be seen only in
+animations. There are many programs available that make nice
+animations, but they take a long time to calculate and lots of space on
+disk. Most such animations are quite ugly because their authors can't
+see them without many hours of calculations.
+
+   A natural question is: is it possible to generate such animations in
+real-time? The answer was negative for many years, since the Mandelbrot
+set is very computationally expensive. Things are changing. Today's
+computers are fast enough to calculate approx. 10.000 of pixels per
+frame, which is enough for a very low resolution animation (100x100).
+Several programs doing that are available. But 100x100 animation still
+looks quite ugly. To make animation nice you need at least 320x200
+pixels. And that is 6 times more!  One possibility is to wait until
+computers will be fast enough, but it will take many years, and then
+320x200 animations will be obsolete and everyone will want 1024x768
+resolution instead or more.
+
+   We found a special algorithm that saves up to 99.98% of calculations
+during zooming by reusing pixels already calculated in previous frames.
+There were some programs doing similiar tricks before but we don't know
+about any able to do zooming interactively with a speed similar to
+XaoS. Many other tricks were later implemented XaoS to achieve yet
+higher framerates. Now XaoS does up to 120 frames per second on a
+120Mhz pentium in a fullscreen 320x200 animation, and calculates an
+average of 160 (0.24%) pixels per frame. This makes XaoS fast enough to
+achieve its primary goal, realtime animation, but there are still many
+areas that could improve, since more complex fractals, higher
+resolutions, or slower computers still bring many problems.
+
+
+File: xaos.info,  Node: What?,  Prev: Why?,  Up: Overview
+
+1.2 What does this software do then?
+====================================
+
+XaoS is a realtime interactive fractal zoomer. This means that it lets
+you zoom smoothly into any place in the fractal you choose without the
+many hours of calculation required by most other fractal generators. It
+now has many other features too, like 13 different fractal types,
+autopilot, special coloring modes, support for various bit depths
+(8bpp, truecolor, hicolor and realcolor), random palette generation,
+color cycling etc...
+
+
+File: xaos.info,  Node: tutorial,  Next: controls,  Prev: Overview,  Up: Top
+
+2 XaoS tutorial
+***************
+
+This is a brief introduction to the basic XaoS features.
+
+2.1 How to zoom
+===============
+
+The main advantage of XaoS is that after a few seconds' delay to
+calculate the first image, you may choose any point with the mouse and
+press the _left_ button.  The image will start to zoom smoothly into
+the point you choose. You may move the mouse and zoom smoothly into
+interesting areas. By pressing the _middle button_ (or _left+right_
+buttons) you may also _move the image_ using "drag & drop" if you
+missed an interesting place. _Unzooming_ is also possible by using the
+_right button_, but it is much slower because optimizations are not so
+effective as for zooming.
+
+   In case you think that the default _speed_ is boring (it is quite
+slow, to make XaoS smooth on a slow computer) you may change it by
+pressing _arrow up/down_. But faster zooming is more expensive, so if
+the speed is too high you will see little but funny colorful blinking
+rectangles.
+
+2.2 Autopilot
+=============
+
+To make XaoS yet more impressive we made a special autopilot that
+automatically drives into interesting boundaries of the set. So you can
+press `A', play your favorite music, drink coffee and relax. I never
+tried this but it should be really relaxing! Many pictures in the XaoS
+gallery were discovered using the autopilot.
+
+   The autopilot also has some additional features. It turns back when
+the zoomed picture stops being interesting, and is able to spot when
+it's zoomed into a really boring part (or has reached the limit of
+floating point numbers) and restart zooming from the top.
+
+2.3 Various fractal formulae
+============================
+
+XaoS also supports formulae other than the Mandelbrot set. You may
+change _formula_ using the _number keys_ or _SHIFT+letters_.
+
+   On keys `1' to `5' are _Mandelbrot sets of various power_. The
+"normal" Mandelbrot set is on key `1'.
+
+   On key `6' is a fractal called _Newton_. It is Newton's famous
+formula for finding roots.
+
+   On key `7' is the _fourth ordered Newton_ fractal.
+
+   On key `8' is a fractal called _Barnsley_.
+
+   On key `9' is _Barnsley's second_ fractal.
+
+   On key `0' is _Barnsley's third_ fractal.
+
+   With keys `SHIFT-A' you can display a fractal called _octo_. It is a
+fractal that Thomas discovered in fractint.
+
+   With keys `SHIFT-B' you can display a fractal called _Phoenix_. It
+is a very nice and quite famous fractal.
+
+   With keys `SHIFT-C' you can display a fractal called _Magnet_. This
+fractal has quite a complex formula so it is a bit slow.
+
+   With keys `SHIFT-D' you can display the _Magnet2_ fractal.
+
+   The rest of the built-in fractals are accessible through an other
+menu, but you can still use the hotkeys.
+
+   On `SHIFT-E' is a fractal called _Triceratops_ found by Arpad.
+
+   On `SHIFT-F' is a fractal called _Catseye_ found by Arpad.  This is
+more interesting if you change the bailout value.
+
+   On `SHIFT-G' is a fractal called _Mandelbar_. It was in Gnofract4d,
+and they found it at: http://mathworld.wolfram.com/MandelbarSet.html
+
+   On `SHIFT-H' is the _Lambda_ fractal.
+
+   On `SHIFT-I' and `SHIFT-J' are the _Manowar_ and _Spider_ fractals,
+they were found by users of fractint.  (Scott Taylor or Lee Skinner) It
+was on http://spanky.triumf.ca/www/fractint/ taylor_skinner_type.html
+
+   The next 3 fractals are famous classic fractals.
+
+   On `SHIFT-K' is the _Sierpinski_ Gasket.  You can change its shape
+by selecting another Julia seed.  (This is for technical reasons.)
+
+   On `SHIFT-L' is the _Sierpinski Carpet._ It's shape can also be
+changed by selecting another Julia seed.
+
+   On `SHIFT-M' is the _Koch Snowflake._
+
+2.4 Out-coloring modes
+======================
+
+To make fractals yet more interesting, more coloring modes for points
+outside the set are provided. "Classical coloring mode" uses the number
+of iterations that the orbit required to escape to (nearly) infinity.
+You can change this mode from the _Fractal menu_ or by pressing key `C'
+To see more about coloring modes, try the tutorial on Incoloring modes
+from the XaoS features overview.
+
+   Those cryptic names for coloring modes are mathematical formulae,
+where _iter_ means number of iterations, _real_ means real coordinate
+of last orbit, and _imag_ means imaginary coordinate of last orbit.
+
+2.5 In-coloring mode
+====================
+
+In-coloring mode is similar to out-coloring, except that it changes how
+things inside the set are displayed. This can also be changed from the
+_fractal menu_ or by pressing `F'.
+
+   You might also want to see the tutorial on Out-coloring modes from
+the XaoS features overview.
+
+2.6 Planes
+==========
+
+All fractals displayed by XaoS are functions with a complex parameter.
+It can be displayed in the normal complex plane, where x is the real
+part of the number, and y is the imaginary part; but it can also be
+displayed in a number of other planes. You can select the plane to use
+from the _Fractal menu_, or by pressing `I'.
+
+   Like the coloring modes, planes have cryptic names. You guessed it,
+they're mathematical formulae. Here `mu' means coordinates in the normal
+complex plane. If you have coordinates in `1/mu' plane, and you need
+coordinates in the a complex plane (to calculate the Mandelbrot set) you
+simply use the coordinates as mu. Lambda is another plane that can be
+converted to mu using a similar formula.
+
+*mu*
+     normal mode.
+
+*1/mu*
+     Inversion: infinity goes to 0 and 0 goes to infinity.
+
+*1/(mu+0.25)*
+     Similar to inversion, but moves the center outside of the
+     Mandelbrot set so that it looks parabolic.
+
+*lambda*
+     Lambda plane.
+
+*1/lambda*
+     Inversion of lambda plane.
+
+*1/lambda-1*
+     Inversion with moved center.
+
+*1/(mu-1.40115)*
+     A very interesting mode for the Mandelbrot set. It makes small
+     things big, so you can browse the set's details easily.
+
+2.7 Mandelbrot/Julia switching
+==============================
+
+Most of the fractals displayed by XaoS (currently all of them) have two
+forms: Mandelbrot and Julia. Every point in a Mandelbrot set has its
+own Julia set. To see more about this correspondence, try the tutorial
+on Julia set from the Introduction to fractals.
+
+   In the Mandelbrot mode, you can get a corresponding Julia by moving
+the mouse to an interesting point and pressing `M'. To get back press
+`M' again. Some fractals (Barnsley and phoenix) are already in their
+Julia versions, because the Mandelbrot ones are boring. But by pressing
+`M' in such fractal you should get the Mandelbrot version, and by
+choosing another point as the base point and pressing `M' again you
+should get a completely different fractal. The most interesting points
+for Julia sets are at the boundaries of the Mandelbrot set. Most of the
+Julias inside or outside the set are boring.
+
+2.8 Fast Julia preview mode
+===========================
+
+Fast Julia mode is a quick way to find a point to use as a base for the
+Julia set.. Just press `J' and a small Julia set will be displayed in
+the top left corner. Then move the mouse around with button 1
+depressed, and the Julia for the point the mouse is over will be
+automatically generated.
+
+2.9 Palette
+===========
+
+If you think that the default XaoS colors are ugly or you are just
+bored by them you can change it by pressing `P'. XaoS will
+automatically generate random palettes. Many of them look ugly, so
+press `P' again to get another one until you find one you like.
+
+2.10 Filters
+============
+
+Many interesting effects are done by post-calculation filters. *Note
+filter::.  XaoS has filters that do everything from embossing, through
+motion-blurring, right through to turning the fractal into a
+stereogram. To enable them use the `filter menu' or press `E'.
+
+2.11 Palette cycling
+====================
+
+This is a very old trick that makes the Mandelbrot set a little
+flashier. You may enable or disable it using `Y'. In the truecolor
+modes you need to enable the palette emulator filter first. This is done
+via the `E' key, or from the filter menu.
+
+2.12 Changing number of iterations
+==================================
+
+To calculate fractals perfectly, you need an infinite number of
+iterations. XaoS does just the first few of them, so after lots of
+zooming you may get into a place that looks quite boring, and the
+boundaries of the set are rounded, without any interesting details.
+This can be changed by changing the number of iterations:
+
+   Press and hold `arrow right' and wait until iterations are high
+enough.  This may slow down calculation much. To reduce number of
+iterations press `arrow left'.
+
+2.13 Changing resolution
+========================
+
+XaoS usually starts in a low resolution (320x200 or thereabouts) to make
+calculations faster. If you have a fast computer or you need to save
+bigger `.gif' images, you may change the resolution. This can be done
+by pressing `=' in the full screen drivers, or simply by resizing the
+XaoS window.
+
+2.14 Changing driver
+====================
+
+XaoS usually has more than one driver available. You may change it on
+the fly in case you want a different one. For example, XaoS started in
+X11 can be switched at runtime to use the AA driver. This can be done
+from the UI menu.
+
+   This action is bit dangerous, because XaoS can crash during
+initialization if there is some problem with initialization; XaoS tries
+to initialize a new driver, and if it fails it attempts to return back
+to the original. Sometimes this is impossible, and all XaoS can do is
+terminate..
+
+2.15 Other features
+===================
+
+XaoS has many other features, but they don't fit into this tutorial.
+Most of them are available from the menu, so you can experiment with
+them. You might also want to see the _animated tutorials_ from the
+_help menu_, to have an idea what XaoS can do.
+
+
+File: xaos.info,  Node: controls,  Next: video,  Prev: tutorial,  Up: Top
+
+3 Basic controls
+****************
+
+By default the mouse buttons work in the following way:
+
+*left*
+     zoom in
+
+*right*
+     zoom out
+
+*middle*
+     move fractal in a drag-and-drop fashion
+
+   _Note:_ Since most Macs only have one button mice, these controls
+are emulated on Mac OS X using modifier keys. See the help section on
+Mac OS X for details.
+
+   This behavior can change. If you enable rotation, the first button
+is used for rotating fractals. Also, in fast Julia mode, the first
+button is used to change the seed.
+
+   If you don't have a middle button, press both buttons to enable
+emulation.
+
+   After few minutes of zooming you will probably exceed the precision
+and the fractals will get boring. If you are getting strange big
+rectangles on the screen, you probably reached the numeric limit: there
+is no way to avoid this except un-zoom back and choose a different
+area. It doesn't hurt so much, since you have zoomed approximately 64
+051 194 700 380 384 times, so there are quite a lot of areas to
+explore. Algorithms with unlimited precision exist, but they are still
+too slow for real-time zooming.
+
+   The other possibility is that you have reached the iteration limit.
+The fractal is calculated approximately, and in this case you need to
+increase number of iterations used for approximation (and decrease the
+speed in the process).  This is done from the menu or using the arrow
+keys _Left_ and _Right_.
+
+   An _Up_ and _Down_ keys should be used to change zooming speed. Note
+that higher speed costs more and image will be blocky.
+
+   This behavior can also change. With palette cycling enabled, _Left_
+and _Right_ keys change cycling speed; in continuous rotation they
+change rotation speed.
+
+   All other functions are available from the menu, which (in the
+default configuration) are displayed when you move the mouse to the top
+of the screen/window. It is useful to learn the shortcut keys, which are
+shown in gray next to the menu items they trigger.
+
+
+File: xaos.info,  Node: video,  Next: format,  Prev: controls,  Up: Top
+
+4 How to encode video files from XaoS
+*************************************
+
+To create a video, make and `xaf' file first (the easiest way to do
+this is to use the _record_ function in the file menu). Then you need
+to render the animation. XaoS can output sequences of ordinary `PNG'
+images, that can later be used by a video encoder.
+
+4.1 Generating image sequences for video
+========================================
+
+To generate an image sequence, choose _Render Animation_ from the _Misc_
+menu. You can also use the following command on the command line:
+
+     xaos -render [filename] -size 352x240 -antialiasing
+     -renderframerate 24 -basename [basename]
+
+   _File to render_ (`[filename]') is the name of the `xaf' file,
+_Basename_ (`[basename]') is the name used as the base filename for
+rendered images. This should also include the path where you want to
+save the images.  XaoS adds a four digit sequence number and `.png'
+extension to this name automatically.
+
+   You might also want to change the resolution. Make sure that the
+resolution you choose is supported by the video codec you wish to use.
+
+   The framerate can also be altered. Make sure you choose a framerate
+that is supported by the video codec you wish to use.
+
+   _Antialiasing_ (`-antialiasing') is used to produce anti-aliased
+images.  It takes a much longer time and much more memory to calculate
+them, but resulting images are better for video compression and they
+result in a much smaller video file.  (the same is true of _JPEG
+images_)
+
+   On the other hand, the other XaoS rendering option _Always
+Recalculate_ (`-alwaysrecalc') (which disables XaoS's zooming
+optimizations) is _not recommended_. If that's used, the sequence of
+animation then contains quite a lot of extra information, which
+increases size of video file, but because of the codec's lossy
+compression it is hard to see any difference, so it's not worth it.
+
+4.2 Rendered files
+==================
+
+Once you start it, XaoS will generate thousands of frames. They take
+quite a long time to calculate and save, and consume plenty of disk
+space.  (e.g. to render part 1 of the tutorial you need about 60MB and
+half an hour of time).
+
+   All images are named `[basename]framenum.png'. For example
+`intro0001.png' is the first frame of the animation intro. If
+consecutive frames are the same, XaoS doesn't save them, so some frames
+may be missing. If your encoder can't handle that, you will need to
+write a simple script which will fill in the gaps by means of `mv' or
+symbolic linking.
+
+   A list of all filenames is saved into the file `[basename].par',
+where each line is the name of one frame. The names repeat here if
+necessary, so you can use this file to supply filenames to the encoder.
+
+4.3 Encoding videos
+===================
+
+Once XaoS has generated the png files for each frame of the animation,
+you can use a third-party video encoder to convert the sequence of
+images into a video file. We currently recommend the following
+encoders, which support a wide variety of video codecs and file formats:
+*ffmpeg*
+     Available from: `http://ffmpeg.mplayerhq.hu/' Instructions:
+     `http://ffmpeg.mplayerhq.hu/faq.html#SEC12'
+
+*mencoder*
+     Part of mplayer, available from: http://www.mplayerhq.hu/
+     Instructions:
+     `http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-enc-images.html'
+   These are both command line tools. If you prefer a graphical tool,
+you may prefer Quicktime Pro from Apple
+(http://www.apple.com/quicktime/pro/). However, this software costs
+approximately US$30, and the authors of XaoS have no experience with
+it. Although QuickTime may be easier to use, the two free encoders
+above are just as capable once you learn how to use them.
+
+   Note: we used to recommend Berkeley parallel MPEG encoder to encode
+the generated png files into MPEG videos. We have kept the instructions
+mainly for historic purposes.
+
+
+File: xaos.info,  Node: format,  Next: writehelp,  Prev: video,  Up: Top
+
+5 XaoS's file format
+********************
+
+This section describes the format used by XaoS for animations,
+configuration files and saved positions. All these files have a common
+format, designed to be easily readable, to allow manual editing of
+files and easy conversion by other programs.
+
+   I also taken care to make it easily extensible for future versions
+of XaoS so I hope there will not be many incompatibilities between
+various XaoS versions.
+
+   The format is a simple set of commands executed sequentially. XaoS
+does not provide any variables/cycles as usual scripting languages do,
+but future extension to full-blown Scheme should be easy since the
+format uses Scheme-like syntax.  The syntax of every command is:
+
+   `(command_name '_[param1] [param2]_`)'
+
+   where parameters are optional and separated by whitespace (an
+arbitrary number of spaces, tabs and newlines). The parameters can have
+the following types:
+
+*integer*
+     number w/o decimal point (`123')
+
+*float*
+     floating point number in decimal notation with optional exponent
+     (`1.23E2')
+
+*keyword*
+     text started by quote `''. It is used to pass various string
+     constants like formula name (`'mandel') Quote is required for
+     scheme compatibility
+
+*string*
+     Text inside double quotes. The only parameter that should contain
+     whitespace
+
+*boolean*
+     `#t' for true or `#f' for false
+
+   There is a complete description of all XaoS functions (with some
+examples) and an index of functions in the XaoS registry. *Note
+menus::. You may particularly want to read about the animation
+functions. *Note animf::. Also, the following functions are significant:
+
+*load*
+     This function loads and interprets a file. It works similarly to
+     `#include' in C.
+
+*initstate*
+     Available in version 3.0 and above, this function resets XaoS's
+     state to default values. This command should be at the beginning
+     of each animation file, since otherwise some stuff previously
+     enabled by user could cause unexpected effects. State is not reset
+     by default before playing animations since it would make it
+     impossible to write macros. Current versions don't really need
+     macros, but in future versions, when the Scheme programming
+     language will be available, this should be a much more interesting
+     subject.
+
+*usleep*
+     This function waits for a selected amount of time(in usec) before
+     processing the next command. The screen is recalculated and
+     displayed at the beginning of the sleep if necessary. The
+     remaining time is spent by waiting, calculating if necessary, or
+     performing any animation you entered via animation commands.
+
+*wait*
+     Waits until the animation or image rendering is complete. Do not
+     call this function when zoom, or continuous rotation is active
+     otherwise deadlock happens. It is a good idea to call it
+     immediately before text subtitles are displayed, since it looks
+     ugly when they are displayed over a blocky unfinished fractal.
+     Because the degree of blockiness at a given instant is a function
+     of your machine speed, it may look nice for you but ugly for
+     others with slower machines. Also you should call this after an
+     animation is performed, before the switch to another fractal
+     happens; since the switch involves calculation, the screen is
+     stopped for a while and an unfinished fractal there looks ugly.
+     You should also call it, when you want to do something as soon as
+     possible.
+
+   Example:
+
+     ;configure everything for the first frame
+     (inistate)
+     (palette 1 1163254293 0) ;custom palette
+     (cycling #t) ;enable cycling
+     (cyclingspeed 7)
+     (maxiter 276) ;higher number of iterations
+     (range 3) ;default range for solid guessing
+     (usleep 1000000) ;second frame starts here
+     (moveview -1.8101154154614007889 -8.2687205907162041209E-05)
+     ;just move the image
+     (usleep 1000000) ;third frame
+     (morphview -1.8101154154614007889 -8.2687205907162041209E-05
+     6.277210971069452361E-10 6.2772109785334669875E-10)
+     ;10 seconds of zooming into selected
+     rectangle
+     (usleep 100000000)
+
+   The best way to learn XaoS command language is probably to read
+position files and modify them. For example, to create zooming
+animation from the original file:
+
+     (initstate)
+     (defaultpalette 0)
+     (formula 'mandel)
+     (view -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+     9.69332308834E-08)
+
+   Just change the `view' command to `morphview', and add `usleep':
+
+     (initstate)
+     (defaultpalette 0)
+     (formula 'mandel)
+     (morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+     9.69332308834E-08)
+     (usleep 10000000)
+
+   The following code produces Julia morphing in the real axis:
+
+     (initstate)
+     (fastjulia #t)
+     (juliaseed -2 0)
+     (morphjulia 2 0)
+     (usleep 2000000)
+
+   And following is the "rotozooming" animation:
+
+     (initstate)
+     (fastrotate #t)
+     (morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+     9.69332308834E-08)
+     (morphangle 300)
+     (usleep 10000000)
+     (wait)
+     (fastrotate #f)
+
+6 XaoS gallery
+**************
+
+I plan to make a gallery of animations and position files on the XaoS
+home-page, so please send any nice animations and images you created
+using XaoS to the mailing list or upload them to our website.
+
+
+File: xaos.info,  Node: writehelp,  Next: xshl,  Prev: format,  Up: Top
+
+7 How to write XaoS help files
+******************************
+
+XaoS help is stored in the file `help/xaos.hlp'. It is divided into
+parts, each part being started by a _keyword_. In the help file
+keywords are written as `%keyword'
+
+   If you are writing documentation about some command in the XaoS
+function registry, use the same keyword as the name of the command in
+order to make context sensitive help work.
+
+
+File: xaos.info,  Node: xshl,  Next: drivers,  Prev: writehelp,  Up: Top
+
+7.1 xshl
+========
+
+_Xshl_ stands for _XaoS simple hypertext language_. It uses similar
+tags to HTML. It is simpler and more restrictive in order to make it
+easy to parse using various scripts. In C code you can use the library
+present in `src/util/xshl.c' to parse it.
+
+   The following tags are supported:
+
+*head*
+     make headings (should be at the beginning of the page, at least)
+
+*emph*
+     emphasize
+
+*tt*
+     Use non proportional font
+
+*br*
+     Break line
+
+*p*
+     Next paragraph
+
+*dl*
+     Definition list
+
+*dt*
+     Definition tag (should be used only inside a definition list)
+
+*dd*
+     Definition description (should be used only inside a definition
+     list)
+
+*center*
+     align to center
+
+*right*
+     align to right
+
+*red*
+     change color to red (should not be used in help files)
+
+*black*
+     change color to black (should not be used in help files)
+
+*white*
+     change color to white (should not be used in help files)
+
+*a name*
+     link to other help page
+
+*tutor name*
+     activate tutorial
+
+*notex*
+     Ignore this in texinfo manuals
+
+
+File: xaos.info,  Node: drivers,  Next: menus,  Prev: xshl,  Up: Top
+
+8 Platform-specific documentation
+*********************************
+
+XaoS is portable and works on many different platforms. Since not all
+platforms are exactly the same, there are some differences between the
+behavior of XaoS on different platforms. Here is documentation about
+each specific port.
+
+* Menu:
+
+* aa::			AA-lib --- high quality ascii art driver
+* BeOS::		BeOS drivers
+* DGA:: 		DGA driver
+* dos::			DOS driver
+* dX-fullscreen::	directX fullscreen driver
+* dX-window::		directX windowed driver
+* ggi::			GGI driver
+* plan9::		plan9 driver
+* SVGAlib::		SVGAlib driver
+* win32::		Win32 driver
+* X11:: 		X11 driver
+
+
+File: xaos.info,  Node: aa,  Next: BeOS,  Up: drivers
+
+8.1 AA-lib driver
+=================
+
+The AA driver is currently the most advanced and portable driver for
+XaoS.  It is based on AAlib--a high quality ASCII-art library developed
+by the AA-project.  (see `http://aa-project.sf.net')
+
+   It is a fully featured XaoS driver for text mode displays. It
+supports 256 colors and the mouse where possible.
+
+   It also has some extended features available from the UI menu:
+
+*Attributes*
+     AA-lib may use character attributes to improve image quality.  By
+     default it uses normal, dim and bold characters where possible,
+     but you can also enable different attributes like reversed or bold
+     font characters. You may also enable usage of non ansii/reversed
+     characters if your device supports it.
+
+*Font*
+     AA-lib uses a bitmap image of the font to prepare the
+     approximation table used for ASCII art rendering. This bitmap is
+     expected to be same as the one used by your device. AAlib performs
+     detection where possible however some devices (like UNIX text
+     terminals or MDA) do not support this. AAlib has few font images
+     compiled in, so in this case you should try to use one of them to
+     achieve best results.
+
+*Inversion*
+     Some devices use inverse video: use this to get correct results on
+     such devices.
+
+*Dithering mode*
+     Dithering is an way to get more exact color in approximations, by
+     combining more characters; but this method can produce ugly
+     looking noise on certain images.  Use this menu to disable or tune
+     it.
+
+*Palette options*
+     By default AA driver uses the XaoS palette to render images, but
+     it quite often looks ugly on text displays. Here you can choose a
+     special text palette instead. Note that with filters enabled, the
+     results may be rather ugly. This function is available from the
+     _palette menu_.
+
+*Save text screen*
+     The normal save function will generate a PNG image instead of nice
+     ASCII-art. To save ASCII art use this function instead. It
+     supports many text file formats like HTML, ANSI, more, etc... It
+     will also ask you for font and attributes(see above). It is
+     available from the _file menu_.
+
+   The AA-lib driver also provides the full set of standard AA-lib's
+command line options. You may use them to tune parameters like gamma
+correction, and so on.  See `xaos -help' or the AA-lib documentation
+for details.
+
+   The AA driver was written by Jan Hubicka, 1997.
+
+
+File: xaos.info,  Node: BeOS,  Next: DGA,  Prev: aa,  Up: drivers
+
+8.2 BeOS support
+================
+
+XaoS has pretty advanced support for BeOS R4. It works on both PowerPC
+and Intel platforms, supports multithreading, the clipboard, file
+dragging, has native look and feel and can work as an image translator
+from XaoS files to images.
+
+   The first version of the BeOS driver was written by Jens Kilian and
+later extended by Jan Hubicka.
+
+8.2.1 Installation
+------------------
+
+You can start the installation script to do everything for you. If you
+want something special, read this section.
+
+   In order for XaoS to work you need to keep the executable together
+with its data files (`help', `examples', `catalogs' and the `tutorials'
+directory)
+
+   When first started, XaoS registers two new mime types called
+`image/x-xaos-position' for XaoS Position Files and
+`video/x-xaos-animation' for XaoS Animation Files, registers icons for
+them and sets itself as default application.
+
+8.2.2 Available display drivers
+-------------------------------
+
+XaoS supports following drivers:
+
+*BeOS*
+     Standard windowed driver using application server
+
+*DirectWindow*
+     Driver done using Game Kit's direct window class
+
+*WindowScreen*
+     Fullscreen driver.
+
+   By default, XaoS starts in windowed mode and uses the application
+server for output.  You could change the driver to DirectWindow to use
+direct access to video RAM.  Note that this mode is slower in most
+cases, and not supported by some videocards.
+
+   The BeOS driver by default chooses the most similar bitmap supported
+by XaoS to achieve best and fastest results.  In the UI menu you can
+change this default choice to another one if you wish.  Also you can
+ask the BeOS and DirectWindow to resize to fullscreen mode.
+
+   XaoS also supports real fullscreen mode using the BWindowScreen API.
+To switch XaoS to this driver, use the UI menu. If you want to use this
+mode by default, use the `-driver WindowScreen' command line option.
+
+   This driver differs a lot from windowed ones. It use direct access
+to the video card, allowing you to change video mode. Also, the 256
+color mode can access the palette, so it is not dithered like the
+windowed mode.  Because BeOS can't do GUI in fullscreen mode, XaoS uses
+its own toolkit.  I hope you will feel confortable in it.
+
+8.2.3 XaoS as translator
+------------------------
+
+You should be able to open XaoS files in graphics applications such as
+ShowImage or ArtPaing. In Preferences you can find the DataTranslations
+program, that can be used to set the size, type and DPI of the
+resulting image.  Also antialiasing can be enabled.
+
+   Note that _translation can take a while_. So be patient and wait for
+the result.
+
+   If the translator doesn't work, ensure that you have a link to the
+XaoS executable in `/boot/beos/system/add-ons/Translators/'.
+
+
+File: xaos.info,  Node: DGA,  Next: dos,  Prev: BeOS,  Up: drivers
+
+8.3 DGA driver
+==============
+
+This is the driver for DGA (Direct Graphics Architecture) extension
+used by XFree86 X servers. It is pretty new so it could be buggy.
+
+   Bugs/limitations:
+
+*In 8bpp mode, XaoS has problems with the palette with certain window managers*
+     I don't know why this happens. Just let me know what's wrong, or
+     use another window manager.
+
+*Banked modes are not supported.*
+     I don't have any card to test this with, so it doesn't work in the
+     current version.
+
+   DGA driver was written by Jan Hubicka, 1999.
+
+
+File: xaos.info,  Node: dos,  Next: dX-fullscreen,  Prev: DGA,  Up: drivers
+
+8.4 DOS driver
+==============
+
+This is a fully featured driver for DJGPP and allegro.  It supports
+many VGA modes, VESA 1.0--3.0, VBE/AF, S3 and some other cards.
+
+   The following problems may occur:
+
+*Some DPMI servers may cause problems*
+     Some DPMI servers like the one from Novell/Dr/Open DOS are buggy.
+     Use clean DOS instead and XaoS will automatically start `cwsdpmi'.
+     Under Open Dr DOS use `dpmi off' at command line to disable it.
+
+*Higher resolutions don't work*
+     If your videocard has enough memory for the selected resolution,
+     you most probably have an unsupported videocard.  Please use a
+     VESA BIOS extension on this videocard. (See the note about VESA at
+     the end of this section.)
+
+*XaoS needs a coprocessor*
+     I don't distribute a coprocessor library linked into XaoS because
+     it is too slow for a real-time zoomer. Coprocessor emulation will
+     not help, because xaos works in protected mode.
+
+*XaoS needs mouse driver to be usable*
+
+*XaoS works slowly in higher resolution*
+     This could also be caused by Allegro's slow driver or your
+     videocard's VESA BIOS.  You could try some other VESA BIOS
+     extension instead.  Look at the `http://www.talula.demon.co.uk'
+     for the FreeBE project or Scitech Display Doctor package.  (See
+     the note about VESA at the end of this section.)
+
+8.4.1 VESA
+----------
+
+VESA is a standard for using higher resolutions in DOS. Many videocards
+have VESA support in the BIOS so you don't need any additional
+software, while others need support from a special program. Also some
+VESA BIOS implementations are buggy or suboptimal; there are 3
+different versions, version 1.0 is many times slower than 2.0, which
+has support for protected mode and linear framebuffers.  So if you have
+problems with higher resolutions, or some graphics modes are not
+available (like 320x200 truecolor), you might try some software package
+which emulates VESA.
+
+   The most famous VESA emulating program is Scitech Display Doctor. It
+has support for many videocards and is quite reliable. It's
+disadvantage is that it is shareware and works for only 30 days. You
+might also look on `ftp.simtel.net', where there are many VESA
+emulation packages such as `s3vbe' or the new FreeBe project at
+`http://www.talula.demon.co.uk'
+
+   DOS driver was written by Jan Hubicka, 1997.
+
+
+File: xaos.info,  Node: dX-fullscreen,  Next: dX-window,  Prev: dos,  Up: drivers
+
+8.5 DirectX fullscreen driver
+=============================
+
+This is da river for Windows 9x and NT. It is new since version 3.1 and
+because of some oddities of Windows API and kludges in DirectX it may
+be rather unstable. Please report all bugs. In case of problems you
+could use the DOS version of XaoS instead.
+
+   This driver allows the Windows port of XaoS to run in full screen
+mode.  The driver supports 256, 65536 and 16777216 color modes (24bpp
+and 32bpp) in all resolutions supported by DirectX.  You can change
+graphics mode by pressing the `=' key (or by using the UI/Resize menu).
+If the selected mode is not supported, the driver will restore the
+previous setting.
+
+   Use the `-mode WIDTHxHEIGHTxDEPTH' (like `-mode 640x480x16') command
+line option to change graphics mode.
+
+   If you want to start XaoS in DirectX, use the `-driver dX-fullscreen'
+option.
+
+   See the Win32 driver documentation for some more Windows releated
+information.
+
+   DirectX driver was written by Jan Hubicka, Jan Olderdissen and Pavel
+Tzekov, 1999.
+
+
+File: xaos.info,  Node: dX-window,  Next: ggi,  Prev: dX-fullscreen,  Up: drivers
+
+
+File: xaos.info,  Node: ggi,  Next: plan9,  Prev: dX-window,  Up: drivers
+
+8.6 GGI driver
+==============
+
+GGI stands for General Graphics Interface. Part of this project is to
+develop libggi, a portable graphics library, and XaoS's GGI driver uses
+that.  It is experimental, since the API of libggi is not stabilized
+yet.  There are some problems with keyboard handling--the shift key
+doesn't work yet.
+
+   Everything else might work well, but there are no guarantees. It is
+alpha quality software.
+
+   GGI driver was written by Jan Hubicka, 1998.
+
+
+File: xaos.info,  Node: plan9,  Next: SVGAlib,  Prev: ggi,  Up: drivers
+
+8.7 Plan9 driver
+================
+
+Plan9 is a very nice small operating system by the authors of Unix at
+Bell Labs.  It is very incompatible with other operating systems; even
+the C compiler and header files are different, but XaoS should work
+well there (even on the limited free demo installation without any
+POSIX compatibility stuff)
+
+   There are a few limitations: the file selector and image saving
+don't work.  You can save position files and then later render them on
+the other OS, or save screenshots.
+
+   Plan9 terminals also don't provide any way to catch the arrow keys,
+so you can't use them. Use the mouse to navigate in the menus. Also,
+getting the screen resolution is impossible, so use `-pixelwidth' and
+`-pixelheight' instead of `-screenwidth' and `-screenheight'.
+
+   By default XaoS changes the colormap. This will collide with other
+colorful programs like Mortha. You can disable this behavior using
+`-nopalette' switch, but this will slow down XaoS.
+
+   Plan9 driver was written by Jan Hubicka, 1997.
+
+
+File: xaos.info,  Node: SVGAlib,  Next: win32,  Prev: plan9,  Up: drivers
+
+8.8 SVGAlib driver
+==================
+
+This is a driver for Linux SVGAlib. I really like this driver, because
+I much prefer full screen zooming instead of a small 320x320 window in
+X11.  It was one of the first drivers for XaoS and is fully featured.
+The following problems can occur:
+
+*XaoS doesn't initialize graphics mode*
+     when started under users other than root SVGAlib requires root
+     privileges to directly access the hardware. When you really want
+     to start XaoS as a normal user, enable the suid bit (`chmod +s')
+     at XaoS executable.  note that I take care to disable all security
+     holes caused by this bit so I believe it is safe.
+
+*Mouse doesn't work*
+
+*Screen is blank at higher resolutions*
+     Both this problems are probably caused by misconfiguration of
+     SVGAlib. Please configure it in `etc/vga/libvga.cong' or
+     `/usr/local/lib/libvga.conf' GPM can also cause problems. Try to
+     kill it before starting XaoS.
+
+*When I switch console I can't switch back*
+     This is another typical SVGAlib bug. Try to hold `F' key longer
+     than `alt'.  It helps on my computer. On older SVGAlib there was a
+     famous "enter bug" that caused a crash after pressing enter. Try
+     to update to a newer release.
+
+   SVGAlib driver was written by Jan Hubicka, 1997.
+
+
+File: xaos.info,  Node: win32,  Next: X11,  Prev: SVGAlib,  Up: drivers
+
+8.9 Win32 driver
+================
+
+This is a driver for Windows 9x and NT. It is new since version 3.1 and
+because of some oddities of Windows API it may be rather unstable.
+Please report all bugs. In case of problems you could use the DOS
+version of XaoS instead.
+
+   The driver should work in all bit depths, but 16 color mode is not
+natively supported by the XaoS engine. XaoS internally works in 32k
+colors and the result is converted to 16 colors by Windows. Because
+Windows conversion routines are slow and ugly, the result is slow and
+ugly.  Please configure your display to another bit depth to "solve"
+this problem.
+
+   Use `-size WIDTHxHEIGHT' command line option to change the default
+window size.
+
+   This driver also maps to native Windows look and feel. There is a
+small problem with combo boxes in dialogs. They are expected to give
+you a choice between a few strings. The keyboard controls (changing
+choice by arrow keys) work, but mouse selection is broken. If you know
+how to solve this bug, please let me know.
+
+   XaoS is a UNIX application and has many command line options.  Some
+features are not available from the GUI.  Because Windows applications
+can't have normal output, most of the critical messages are displayed
+in message boxes, but some longer messages are omitted. The most
+significant omission is the help about command line options that you
+can find in `doc/cmdopts.txt'.
+
+   One thing that might be confusing is that animation rendering mode
+doesn't display anything, but only renders images. Start the rendering,
+and a message box will inform you that XaoS is entering the calculation
+loop. Relax and wait for the message box signaling the end of the loop.
+
+   Note that XaoS also supports the DirectX API.
+
+   Win32 driver was written by Jan Hubicka, Jan Olderdissen and Pavel
+Tzekov, 1999.
+
+
+File: xaos.info,  Node: X11,  Prev: win32,  Up: drivers
+
+8.10 X11 driver
+===============
+
+This was the first driver done for XaoS. It supports many visuals,
+shared colormaps and MitSHM extension.
+
+   Bugs/limitations:
+
+*XaoS makes some X servers too busy*
+     Sometimes XaoS generates images faster than X can display them.
+     In this case XaoS responds poorly to the mouse, and other
+     applications slow down too. This happens especially often on old
+     R4 servers. Use `-sync' to avoid this problem. Note that `-sync'
+     does `not' make all communication with X asynchronous; it just
+     adds one additional XSync call.  So the slowdown is not as large
+     as you might expect.
+
+*Does not work on all visuals*
+     This driver supports only 8bpp pseudocolor/grayscales, 15,16,24
+     and 32bpp truecolor, 1bpp and 8bpp staticolor visuals.
+
+*Palette rotating does not work for 8bpp pseudocolor w/o private palette*
+
+   X11 driver was written by Jan Hubicka and Thomas Marsh, 1997.
+
+
+File: xaos.info,  Node: menus,  Next: about,  Prev: drivers,  Up: Top
+
+Függelék: A Menus, functions and command line parameters
+**********************************************************
+
+All XaoS functions are referenced by a central function registry. The
+scripting language, menus, dialogs and command line options are built
+from this database. This section contains information about all
+functions available in this registry.
+
+* Menu:
+
+* root::	Root menu
+* animroot::	Animation root menu
+* plc::	Replay only commands
+
+* linemenu::	Line drawing functions
+* animf::	Animation functions
+* time::	Timing functions
+* file::	File
+* edit::	Edit
+* fractal::	Fractal
+* calc::	Calculation
+* mfilter::	Filters
+* ui::	UI
+* misc::	Misc
+* helpmenu::	Help
+* xtextpos::	Horizontal text position
+* ytextpos::	Vertical text position
+* mformula::	Formulae
+* palettemenu::	Palette
+
+
+File: xaos.info,  Node: root,  Next: animroot,  Up: menus
+
+
+File: xaos.info,  Node: animroot,  Next: plc,  Prev: root,  Up: menus
+
+A.1 Animation root menu
+=======================
+
+This menu is displayed at the top of the screen when animation replay
+is active.
+
+* Menu:
+
+* file::	File
+* stopreplay::	Stop replay
+* helpmenu::	Help
+* ui::	UI
+
+
+File: xaos.info,  Node: stopreplay,  Up: animroot
+
+A.1.1 Stop replay
+-----------------
+
+Terminate animation replay.
+
+   _Available as_: menu item
+
+
+File: xaos.info,  Node: plc,  Next: linemenu,  Prev: animroot,  Up: menus
+
+A.2 Replay only commands
+========================
+
+Some commands, such as timing primitives or animation functions, are
+available only in animation files.
+
+* Menu:
+
+* linemenu::	Line drawing functions
+* animf::	Animation functions
+* time::	Timing functions
+* load::	Include file
+
+
+File: xaos.info,  Node: load,  Up: plc
+
+A.2.1 Include file
+------------------
+
+ -- Function: load file
+
+   This function lets you include another file in your script. It works
+similarly to `#include' in C or `load' in Scheme.  The file is searched
+for in the same directory as the current source file.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: linemenu,  Next: animf,  Prev: plc,  Up: menus
+
+A.3 Line drawing functions
+==========================
+
+XaoS has support for drawing lines. These functions are available only
+in animations and could be used to show some parts of fractals or draw
+simple diagrams. See the tutorial "Introduction to fractals" for
+examples of this feature.
+
+   Lines can be drawn in _screen_ coordinates, where 0,0 is the top
+left corner and 1,1 is bottom right, _scaled_ coordinates, which are
+similar, but scaled to keep 0,0--1,1 rectangular, or _Fractal_
+coordinates, to draw a line at an exact position on the screen.
+
+   The color of the line should be specified by the `color' command.
+You might draw an arbitrary number of lines and, later, morph them.
+Each line is identified by a unique numeric key; the current key can be
+set using `linekey'.  Commands for changing lines operate on the line
+with the current key.  (Lines drawn in sequence have consecutive
+numbers.)
+
+   For example:
+
+     (color 'red)
+     (line 'scaled 0.3 0.5 0.7 0.5)
+     (line 'scaled 0.3 0.5 0.7 0.5)
+     (line 'scaled 0.3 0.5 0.3 0.5)
+     (line 'scaled 0.7 0.5 0.7 0.5)
+     (linekey 0)
+     (morphline 'scaled 0.3 0.3 0.7 0.3)
+     (morphline 'scaled 0.3 0.7 0.7 0.7)
+     (morphline 'scaled 0.3 0.3 0.3 0.7)
+     (morphline 'scaled 0.7 0.3 0.7 0.7)
+     (usleep 1000000)
+
+   Creates line morphing to rectangle.
+
+ -- Function: line keyword complex complex
+
+   Draw line between two points.  `keyword' specifies type of
+coordinates and should be one of the following: ``fractal', ``screen'
+or ``scaled'.  This function also increases the line key.
+
+   _Available as_: command
+
+ -- Function: morphline keyword complex complex
+
+   Morph current line to given coordinates.  `keyword' specifies type
+of coordinates and should be one of the following: ``fractal',
+``screen' or ``scaled'.  The line will start moving at the next timing
+command, and reach the final position before the end of it.  This
+function also increases the line key.
+
+   _Available as_: command
+
+ -- Function: morphlastline keyword complex complex
+
+   This function has the same functionality as morphline, but it doesn't
+increase the line key, and touches the line with the previous key. This
+is useful when you want to move a just-drawn line--you don't need to
+set linekey back.
+
+   _Available as_: command
+
+ -- Function: linekey integer
+
+   Set current line key.
+
+   _Available as_: command
+
+ -- Function: clearline
+
+   Clear current line. This function also increases the line key.
+
+   _Available as_: command
+
+ -- Function: clearlines
+
+   Clear all displayed lines. Lines can also be cleared using the
+`clearscreen' or `display' commands available from the Misc menu. *Note
+misc::.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: animf,  Next: time,  Prev: linemenu,  Up: menus
+
+A.4 Animation functions
+=======================
+
+These functions are used to animate fractal state--to zoom, unzoom and
+morph various parameters. They should be used only in animation files.
+Animations are usually performed for a time selected by an immediately
+following timing function. *Note time::.  For example:
+
+     (view 0 0 1 1)
+     (morphview 0 0 2 2)
+     (usleep 5000000)
+
+   Will do a 5 second long unzooming animation.
+
+* Menu:
+
+* animateview::	Animate view
+* smoothmorph::	Smooth morphing
+* morphview::	Morph view
+* morphjulia::	Morph julia
+* moveview::	Move view
+* morphangle::	Morph angle
+* zoom::	Zooming functions
+
+
+File: xaos.info,  Node: animateview,  Next: smoothmorph,  Up: animf
+
+A.4.1 Animate view
+------------------
+
+ -- Function: animateview float float float float
+
+   This function is almost identical to function `view'. *Note uiview::.
+It expects that the view will be changed only slightly, so
+recalculation is done with `ANIMATE' priority. This means that dynamic
+resolution is used by default.
+
+   Viewport is selected by the center and two radiuses (real and
+imaginary). See `view' for more information.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: smoothmorph,  Next: morphview,  Prev: animateview,  Up: animf
+
+A.4.2 Smooth Morphing
+---------------------
+
+ -- Function: morphview keystring starttime endtime
+This function lets you smoothly start and stop morphing. Specify
+starttime and stoptime as nonzero, and morphing will speed up and slow
+down for that number of usecs.
+
+   The keystring is used to select what morphing you want to control.
+It is one of the following:
+*'view*
+     control morphview
+
+*'angle*
+     control morphangle
+
+*'julia*
+     control morphjulia
+
+*'line*
+     control morphline
+
+
+File: xaos.info,  Node: morphview,  Next: morphjulia,  Prev: smoothmorph,  Up: animf
+
+A.4.3 Morph view
+----------------
+
+ -- Function: morphview float float float float
+For the time selected by the next `usleep' or other timing function,
+the viewpoint is smoothly morphed from the current one to that selected
+by `morphview'.
+
+   Viewport is selected by the center and two radiuses (real and
+imaginary). See `view' for more information.
+
+   This function can easily be used for creating zooming/unzooming
+animations using position files.  This is an example position file
+generated by XaoS:
+
+     (initstate)
+     (defaultpalette 0)
+     (formula 'mandel)
+     (view -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+     9.69332308834E-08)
+
+   By replacing the `view' command with `morphview' and adding `usleep'
+you can create a zooming animation:
+
+     (initstate)
+     (defaultpalette 0)
+     (formula 'mandel)
+     (morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+     9.69332308834E-08)
+     (usleep 10000000)
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: morphjulia,  Next: moveview,  Prev: morphview,  Up: animf
+
+A.4.4 Morph Julia
+-----------------
+
+ -- Function: morphjulia complex
+For the time selected by the next `usleep' or other timing function,
+the Julia seed is smoothly interpolated from the current one to that
+selected by `morphjulia'. By default this will cause recalculation of
+the whole screen.  To avoid this, use fast Julia mode. *Note
+fastjulia::.
+
+   A simple animation morphing Julia seed in the X axis:
+
+     (initstate)
+     (fastjulia #t)
+     (juliaseed -2 0)
+     (morphjulia 2 0)
+     (usleep 2000000)
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: moveview,  Next: morphangle,  Prev: morphjulia,  Up: animf
+
+A.4.5 Move view
+---------------
+
+ -- Function: moveview complex
+Smoothly move the image center to another position.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: morphangle,  Next: zoom,  Prev: moveview,  Up: animf
+
+A.4.6 Morph angle
+-----------------
+
+ -- Function: morphangle float
+Smoothly rotate the image to another angle. By default rotation causes
+recalculation of the whole screen. To avoid this you need to enable
+fast rotate mode. *Note rotate::. Don't forget to disable it later,
+since it slows down other animations.
+
+   A simple "rotozooming" animation:
+
+     (initstate)
+     (fastrotate #t)
+     (morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+     9.69332308834E-08)
+     (morphangle 300)
+     (usleep 10000000)
+     (wait)
+     (fastrotate #f)
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: zoom,  Prev: morphangle,  Up: animf
+
+A.4.7 Zooming functions
+-----------------------
+
+The functions for zooming/unzooming were created mainly for recording
+animations. In manually created animation files, it is easier to use
+`morphview'. *Note morphview::.
+
+ -- Function: zoomcenter complex
+   This function sets the center to zoom in on. The center is given as
+a position in fractal coordinates.
+
+   _Available as_: command
+
+ -- Function: zoom
+   Start zooming to the area specified by `zoomcenter'.
+
+   The speed of zooming should be controlled by the function `speed' or
+in a more exact way by `maxstep' and `speedup'.
+
+ -- Function: unzoom
+
+   Start unzooming from the area specified by `zoomcenter'.
+
+   _Available as_: command
+
+ -- Function: stop
+   Stop zooming or unzooming.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: time,  Next: file,  Prev: animf,  Up: menus
+
+A.5 Timing functions
+====================
+
+Timing functions are used to control the animation replay daemon. It
+can wait for a given time, or wait until calculation is complete. The
+animation functions are controlled by such waiting; animations that are
+running while delays start keep running through the delay.
+
+* Menu:
+
+* usleep::	Usleep
+* textsleep::	Wait for text
+* wait::	Wait for complete image
+
+
+File: xaos.info,  Node: usleep,  Next: textsleep,  Up: time
+
+A.5.1 Usleep
+------------
+
+ -- Function: usleep integer
+
+   This function waits for a given amount of time (in usec) before
+processing the next command. The screen is recalculated and displayed
+at the beginning of usleep if necessary necessary. The remaining time
+is spent in waiting or performing animation.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: textsleep,  Next: wait,  Prev: usleep,  Up: time
+
+A.5.2 Wait for text
+-------------------
+
+ -- Function: textsleep
+
+   This function's behavior is very similar to `usleep', but the time
+is calculated from the number of letters currently displayed onscreen.
+If you want to wait just long enough for the user to read the subtitle,
+use this function. The user can alter the replay speed as desired using
+`letterspersec'. *Note letterspersec::. This value can be changed during
+replay with the arrow keys.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: wait,  Prev: textsleep,  Up: time
+
+A.5.3 Wait for complete image
+-----------------------------
+
+ -- Function: wait
+
+   Wait until the image is complete. You should always use this
+function after zooming or unzooming when dynamic resolution is in use.
+This ensures that the image calculation will be complete so the user
+can see the result before the animation continues. It may also be
+useful in combination with filters like motion blur. *Note blur::.
+
+   This function deadlocks if used with animation functions; don't do
+that.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: file,  Next: edit,  Prev: time,  Up: menus
+
+A.6 File
+========
+
+* Menu:
+
+* loadpos::	Load
+* savepos::	Save
+* record::	Record
+* play::	Replay
+* saveimg::	Save image
+* loadexample::	Load random example
+* savecfg::	Save configuration
+* quit::	Quit
+
+
+File: xaos.info,  Node: loadpos,  Next: savepos,  Up: file
+
+A.6.1 Load XaoS position file
+-----------------------------
+
+Load a XaoS position file (`*.xpf').  See the format description for
+more information.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: savepos,  Next: record,  Prev: loadpos,  Up: file
+
+A.6.2 Save XaoS position file
+-----------------------------
+
+ -- Function: savepos file
+
+   Save current state to a XaoS position file (`*.xpf'). This file is
+human-readable, and can easily be improved by hand after saving, or
+used as a base for animations.  See the format description for more
+information.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: record,  Next: play,  Prev: savepos,  Up: file
+
+A.6.3 Record animation
+----------------------
+
+ -- Function: record bool [ file ]
+
+   e Toggle recording to a XaoS animation file (`*.xaf'). This file is
+human-readable, and can easily be improved by hand after recording.
+See the format description for more information.
+
+   From the scripting language, `(record #t)' enables recording, and
+`(record #f)' disables it.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: play,  Next: saveimg,  Prev: record,  Up: file
+
+A.6.4 Replay animation
+----------------------
+
+Replay a XaoS animation file (`.xaf').
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: saveimg,  Next: loadexample,  Prev: play,  Up: file
+
+A.6.5 Save image
+----------------
+
+ -- Function: saveimg file
+
+   Save current state to an image file. This file is in `.png' (portable
+network graphics) format, which can be read by many applications
+varying from graphics programs all the way to Web browsers.
+
+   This function needs an external library called `libpng'. If the
+library wasn't available during compilation, this function is
+unavailable too.  Please see `INSTALL' for more information about
+obtaining libpng and recompiling XaoS.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: loadexample,  Next: savecfg,  Prev: saveimg,  Up: file
+
+A.6.6 Load random example
+-------------------------
+
+ -- Function: loadexample
+
+   Choose random `.xpf' file from the `examples' directory and load it.
+You might use it as the starting point for next exploration.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: savecfg,  Next: quit,  Prev: loadexample,  Up: file
+
+A.6.7 Save configuration
+------------------------
+
+ -- Function: savecfg
+
+   Save current configuration to `~/.xaosrc' (under Unix) or `xaos.cfg'
+(under DOS and Windows). XaoS automatically reloads the configuration
+from this file when it starts.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: quit,  Prev: savecfg,  Up: file
+
+A.6.8 Quit
+----------
+
+ -- Function: quit
+
+   Quit XaoS.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: edit,  Next: fractal,  Prev: file,  Up: menus
+
+A.7 Edit
+========
+
+A fairly ordinary Edit menu.
+
+* Menu:
+
+* undo::	Undo
+* redo::	Redo
+* copy::	Copy
+* paste::	Paste
+
+
+File: xaos.info,  Node: undo,  Next: redo,  Up: edit
+
+A.7.1 Undo
+----------
+
+Undo last operation. `Last operation' is quite hard to define in XaoS
+(where changes are continuous), so it might be surprising.  I hope it
+will do what you want.
+
+   _Available as_: menu item
+
+
+File: xaos.info,  Node: redo,  Next: copy,  Prev: undo,  Up: edit
+
+A.7.2 Redo
+----------
+
+Redo last undone operation. See undo. *Note undo::.
+
+   _Available as_: menu item
+
+
+File: xaos.info,  Node: copy,  Next: paste,  Prev: redo,  Up: edit
+
+A.7.3 Copy
+----------
+
+Copy fractal to clipboard. This is a platform-dependent operation that
+may not have an analogue on your platform (e.g. there is no concept of
+a clipboard under aalib).
+
+   _Available as_: menu item
+
+
+File: xaos.info,  Node: paste,  Prev: copy,  Up: edit
+
+A.7.4 Paste
+-----------
+
+Paste fractal from clipboard. This is a platform-dependent operation
+that may not have an analogue on your platform (e.g. there is no
+concept of a clipboard under aalib).
+
+   _Available as_: menu item
+
+
+File: xaos.info,  Node: fractal,  Next: calc,  Prev: edit,  Up: menus
+
+A.8 Fractal
+===========
+
+This menu contains all functions related to fractal parameters and
+display; you can change things like the formula used, coloring modes,
+seeds and much else.
+
+* Menu:
+
+* formula::	Formula
+* mformula::	formulae
+* incoloring::	Incoloring mode
+* outcoloring::	Outcoloring mode
+* plane::	Plane
+* palettemenu::	Palette
+* uimandelbrot::	Mandelbrot mode
+* uiperturbation::	Perturbation
+* uiview::	View
+* initstate::	Reset to defaults
+* tcolor::	True-color coloring modes
+
+
+File: xaos.info,  Node: formula,  Next: uimandelbrot,  Up: fractal
+
+A.8.1 Formula
+-------------
+
+ -- Function: formula keyword
+
+   Set the current fractal formula. `keyword' should be one of the
+following:
+*'mandel*
+     Standard Mandelbrot set. *Note mandel::.
+
+*'mandel3*
+     Mandelbrot set, power 3. *Note mandel3::.
+
+*'mandel4*
+     Mandelbrot set, power 4.
+
+*'mandel5*
+     Mandelbrot set, power 5.
+
+*'mandel6*
+     Mandelbrot set, power 6.
+
+*'newton*
+     Newton's approximation method. *Note newton::.
+
+*'barnsley*
+     First Barnsley's formula. *Note barnsley::.
+
+*'octo*
+     Fractint's octo. *Note octal::.
+
+*'phoenix*
+     Phoenix. *Note phoenix::.
+
+*'magnet*
+     Magnet. *Note magnet::.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: uimandelbrot,  Next: uiperturbation,  Prev: formula,  Up: fractal
+
+A.8.2 Mandelbrot/Julia mode
+---------------------------
+
+Most fractals rendered by XaoS can be represented as Mandelbrot sets or
+Julias.  Each point in the Mandelbrot set has its own Julia set. To
+learn more about this correspondence, see the tutorial on the Julia set.
+
+   This function switches between Mandelbrot and Julia representations.
+When switching to Julia, you need to set the seed--a point selected
+from the Mandelbrot set.
+
+   If you run this function from the menu, you are prompted for the
+Julia seed as a number. Often, this can be clumsy, and it would be
+easier to specify a point with the mouse pointer. If you hit the `M'
+key instead of using the menu, the current mouse position is used.
+
+   Good seedpoints lie at the boundaries of the Mandelbrot set; other
+seeds usually generate quite a boring fractal. You can also explore
+various seeds at high speed using the Fast Julia mode. *Note
+fastjulia::.
+
+   Not all fractals have Julias, but XaoS can generate fake Julia sets
+for those that do not, which use some Julia-like modification of the
+formula; so this function is currently usable for all fractal types.
+
+   _Available as_: menu item
+
+ -- Function: julia bool
+
+   This function is used to enable/disable julia mode in animation
+files.
+
+   _Available as_: command line option, command
+
+ -- Function: juliaseed complex
+
+   Select the current julia seed.
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: uiperturbation,  Next: uiview,  Prev: uimandelbrot,  Up: fractal
+
+A.8.3 Perturbation
+------------------
+
+Perturbation is a simple trick which changes the point at which orbits
+start.  Traditionally zero is used, but other values can generate
+interesting results too.
+
+   On enabling this function from the menu, you will be asked for a
+complex number specifying the perturbation. It is a toggle; selecting
+it again resets the perturbation to zero without prompting.
+
+   It can be used to specify a complex number representing a point on
+the screen.  If you hit the `B' key instead of using the menu, the
+current mouse position is used. This too is a toggle, so `B' again will
+disable perturbation by setting it to zero.
+
+   This function only has an effect for certain formulae (like the
+Mandelbrot set</a>) and only then in <a uimandelbrot>Mandelbrot mode.
+*Note mandel::.
+
+   _Available as_: menu item
+
+ -- Function: perturbation complex
+
+   This is the scripting-language variation of the perturbation
+function. Instead of toggling, you always specify the perturbation to
+use. Use 0 0 to disable perturbation.
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: bailout,  Next: fastjulia,  Prev: maxiter,  Up: calc
+
+A.8.4 Bailout
+-------------
+
+Bailout is the value which is checked for each point of the orbit if
+the point is far enough from the complex zero point in the current
+iteration.  If the point is far enough, then the iteration immediately
+stops and the starting point on the screen will be painted with a given
+colour, depending on the fractal type and many other settings.
+
+   For the Mandelbrot set this value is 4. Other fractal types usually
+have the same bailout value. For most fractals many bailout values give
+more or less similar output. E.g., for the second order Mandelbrot set
+one can prove that the sequence |z| (z:=z^2+c) tends to infinity if and
+only if |z|>2 for some element z of this sequence.  In XaoS program,
+Bailout value is the square of this 2, i.e. you can change this to any
+value greater than 2 for similar results.
+
+   Other fractal types may use other bailout values. The default is 4
+for each types.
+
+   _Available as_: menu item, command line option, command
+
+ -- Function: bailout float
+
+
+File: xaos.info,  Node: uiview,  Next: initstate,  Prev: uiperturbation,  Up: fractal
+
+A.8.5 View
+----------
+
+Set your current viewpoint in the fractal. This function is useful when
+you have found some interesting coordinates somewhere (on a web page,
+perhaps) and you want to see that position in XaoS.
+
+   In the dialog you will be asked for the _center_, _radius_ and
+_angle_ of the image.
+
+   The center specifies the point which is displayed at the center of
+the screen.  The radius is the radius of a circle around this point;
+XaoS will size the image so that this circle only just fits on the
+screen. The angle gives the rotation of the image in degrees.
+
+   People specify fractal coordinates in many ways. Some people use the
+coordinates of the upper-left and lower-right visible points,
+specifying the coordinates as four numbers x1, y1, x2, y2.  To set the
+same viewpoint in XaoS, set the real portion of the center to
+(x1+x2)/2, the imaginary part of center to (y1+y2)/2, and the radius to
+the greater of x2-x1 and y2-y1.
+
+   Other programs use a zoom factor instead of a radius. For these, you
+can set the radius to 2/zoom.
+
+   _Available as_: menu item
+
+ -- Function: view float float float float
+
+   This function is used to set the visible area of fractal in
+animation files.  It doesn't let let you specify the angle, (for that,
+see the separate function `angle'), but lets you specify an ellipse
+instead of a circle. You can specify both a real and an imaginary
+radius, so you have better control over the area that will be visible.
+XaoS will size the image so that the ellipse only just fits on the
+screen.
+
+   _Available as_: command line option, command
+
+ -- Function: angle float
+
+   Set the rotation angle in degrees. By default this causes
+recalculation of the screen. You can enable the fast rotation mode,
+which lets you rotate the screen without recalculation; but it slows
+down other things, so don't forget to disable it later.
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: initstate,  Next: plane,  Prev: uiview,  Up: fractal
+
+A.8.6 Reset to defaults
+-----------------------
+
+ -- Function: initstate
+
+   This function resets most of XaoS's values to their defaults. It is
+useful when you get lost and want to start from the beginning. It
+should also be used as the first command of every animation file, to
+ensure that the file is always played with the same settings in effect.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: plane,  Next: incoloring,  Prev: initstate,  Up: fractal
+
+A.8.7 Plane
+-----------
+
+ -- Function: plane integer
+
+   All fractals displayed by XaoS are functions with a complex
+parameter.  They can be be displayed in the normal complex plane where
+the `x' coordinate is the real part of the number and the `y' is
+imaginary; but they can also be displayed differently:
+*mu*
+     Normal complex plane (default)
+
+*1/mu*
+     Inversion--infinity is at 0 and 0 is at infinity.
+
+*1/(mu+0.25)*
+     Similar to inversion, but moves the center outside the Mandelbrot
+     set, so it looks parabolic.
+
+*lambda plane, 1/lambda, 1/lambda-1*
+     Lambda plane and its inversion, and with a different center.
+
+*1/(mu-1.40115)*
+     A very interesting mode for the Mandelbrot set, this makes small
+     things large, for easier browsing of the set's details.
+   The tutorial about planes has some examples.
+
+   In the scripting language, the planes are numbered as follows:
+
+*0*
+     mu
+
+*1*
+     1/mu
+
+*2*
+     1/(mu+0.25)
+
+*3*
+     lambda
+
+*4*
+     1/lambda
+
+*5*
+     1/(lambda-1)
+
+*6*
+     1/(mu-1.40115)
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: incoloring,  Next: outcoloring,  Prev: plane,  Up: fractal
+
+A.8.8 Inside coloring mode
+--------------------------
+
+ -- Function: incoloring integer
+
+   Areas inside the set are usually filled in black, but this is only a
+convention; you could color them in differently to make the fractal
+look more interesting.  The only method available to make areas inside
+the set visible is to display the value of the latest orbit as the
+value of each pixel.
+
+   The tutorial on incoloring has more information and examples.
+
+   XaoS has many different ways to show that value. The cryptic names
+of the modes are mathematical formulae, where _real_ means the real
+part of the latest orbit, and _imag_ means the imaginary part. _zmag_
+uses the magnitude of the value. The _Decomposition-like_ method uses
+the angle of the orbit. Also, truecolor incoloring modes are available,
+that display one value in each of the red, blue and green color planes
+(or, for some modes, in each of the hue, saturation and value planes).
+
+   In the scripting language, the incoloring mode is specified by one
+of the following integers:
+
+*0*
+     0 (default)
+
+*1*
+     zmag
+
+*2*
+     Decomposition-like
+
+*3*
+     real/imag
+
+*4*
+     abs(abs(c)-abs(r))
+
+*5*
+     cos(mag)
+
+*6*
+     mag*cos(real^2)
+
+*7*
+     sin(real^2-imag^2)
+
+*8*
+     atan(real*imag*creal*cimag)
+
+*9*
+     squares
+
+*10*
+     Truecolor. To set exact parameters for truecolor coloring use the
+     `tcolor' command.
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: outcoloring,  Next: tcolor,  Prev: incoloring,  Up: fractal
+
+A.8.9 Outside coloring mode
+---------------------------
+
+ -- Function: outcoloring integer
+
+   Outcoloring modes are similar to incoloring modes, but indicate how
+to display the areas outside the set instead. As with incoloring modes,
+the value of the latest orbit can be used to determine the color of
+each pixel, but the default is to use the number of iterations needed
+for the value at that point to become recognisably divergent as the
+color.
+
+   The tutorial on outcoloring has more information and examples.
+
+   The cryptic names of the modes are mathematical formulae, where
+_iter_ means the number of iterations required for the value to become
+recognisably divergent, _real_ means the real part of the latest orbit,
+and _imag_ means the imaginary part. _binary decomposition_ uses a
+different color when the imaginary part of the orbit is lower than
+zero, and _smooth_ attempts to remove stripes and discontinuities.
+Also, truecolor outcoloring modes are available, that display one value
+in each of the red, blue and green color planes (or, for some modes, in
+each of the hue, saturation and value planes).
+
+   In the scripting language, the outcoloring mode is specified by one
+of the following integers:
+
+*0*
+     iter (default)
+
+*1*
+     iter+real
+
+*2*
+     iter+imag
+
+*3*
+     iter+real/imag
+
+*4*
+     iter+real+imag+real/imag
+
+*5*
+     binary decomposition
+
+*6*
+     biomorphs
+
+*7*
+     potential
+
+*8*
+     color decomposition
+
+*9*
+     smooth
+
+*10*
+     True-color outcoloring mode. To set exact parameters for truecolor
+     coloring use `outtcoloring'. *Note tcolor::.
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: tcolor,  Prev: outcoloring,  Up: fractal
+
+A.8.10 Truecolor coloring mode
+------------------------------
+
+ -- Function: intcoloring integer
+
+ -- Function: outtcoloring integer
+
+   Truecolor coloring modes are similar to incolor and outcolor
+coloring modes; but instead of using a palette, they directly calculate
+the red, green and blue components of the color.  This lets you display
+more parameters at once, and produces interesting and often attractive
+results. On 8bpp displays you need to enable the palette emulator
+filter first to see anything, amd the quality won't be so good, as far
+fewer colors are available per parameter.
+
+   The tutorial on truecolor coloring modes has more information and
+examples.
+
+   The cryptic names of the modes are always three mathematical
+formulae (one for each color component), where _real_ means the real
+part of the latest orbit, and _imag_ means the imaginary part.
+
+   To enable inside/outside truecolor coloring mode in the scripting
+language, set `incoloring'/`outcoloring' value to 10 (truecolor coloring
+mode) before (or after) calling `intcoloring' or `outtcoloring'.
+
+   In the scripting language, the coloring mode is specified by one of
+the following integers:
+
+*0*
+     black
+
+*1*
+     re*im sin(re^2) angle
+
+*2*
+     sin(re) sin(im) sin(square)
+
+*3*
+     hsv
+
+*4*
+     hsv2
+
+*5*
+     cos(re^c) cos(im^2) cos(square)
+
+*6*
+     abs(re^2) abs(im^2) abs(square)
+
+*7*
+     re*im re*re im*im
+
+*8*
+     abs(im*cim) abs(re*cre) abs(re*cim)
+
+*9*
+     abs(re*im-csqr) abs(re^2-csqr) abs(im^2-csqr)
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: calc,  Next: mfilter,  Prev: fractal,  Up: menus
+
+A.9 Calculation
+===============
+
+This menu contains functions that control calculation parameters such as
+the maximum iteration count and periodicity checking.
+
+* Menu:
+
+* range::	Solid guessing
+* dynamic::	Dynamic resolution
+* periodicity::	Periodicity checking
+* maxiter::	Iterations
+* bailout::	Bailout
+* fastjulia::	Fast Julia mode
+* dynamic::	Dynamic resolution
+* rotate::	Rotation
+
+
+File: xaos.info,  Node: range,  Next: periodicity,  Up: calc
+
+A.9.1 Solid guessing range
+--------------------------
+
+ -- Function: range integer
+
+   XaoS has a solid guessing optimization: if all corners of a
+rectangle have the same color, it assumes that the whole rectangle is a
+solid colored block, and doesn't calculate points inside the rectangle.
+This optimization saves lots of calculation, but sometimes introduces
+errors. This value alters the maximum size of the rectangle that can be
+guessed at one time. The default value is 3; use 0 to disable the
+optimization.
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: periodicity,  Next: maxiter,  Prev: range,  Up: calc
+
+A.9.2 Periodicity checking
+--------------------------
+
+ -- Function: periodicity bool
+
+   Periodicity checking is one way to speed up the calculation. Areas
+inside the set always need `maxiter' iterations to determine that the
+point is probably inside the set (while it is rare for areas outside to
+need anywhere near that much). Often the orbital trajectory falls into a
+periodic, repeating cycle; if that can be detected, the calculation can
+be stopped early, as there's no way that the orbit can ever leave the
+cycle again (hence it cannot diverge, hence the point must be inside
+the set).
+
+   Implementating this method efficiently is quite problematic. It
+slows down the cases where cycles are not found, because cycle-checking
+is quite hard work and has to take place for all points, even those
+that don't become cyclic.  Because of the inexactness of floating-point
+calculations, the cycles are never exact, so you need to use an error
+value. Higher error values mean that cycles will be detected sooner,
+while lower error values increase the exactness of the calculation.
+Higher values can introduce serious errors, especially at the front of
+the Mandelbrot set. XaoS detects this automatically and corrects for it
+in most cases, but sometimes it might be wrong. Also, other
+optimizations in XaoS (such as boundary tracing) don't give this method
+much of a chance to run, since areas inside the set are usually not
+calculated at all.
+
+   That's why the advantages of this optimization are questionable. You
+should probably experiment with enabling and disabling it. Sometimes
+XaoS is faster with this enabled, sometimes when disabled. Also, this
+method works only when incoloring methods are disabled, and only for
+some fractal types (some fractal types, e.g. newton, don't have any
+concept of an area `inside the set' at all.)
+
+   The tutorial chapter "Escape time fractals" has more information on
+fractal calculation in XaoS, and there is a lengthy section in the
+hacker's manual (`xaosdev.texinfo') devoted to the subject.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: maxiter,  Next: bailout,  Prev: periodicity,  Up: calc
+
+A.9.3 Iterations
+----------------
+
+ -- Function: maxiter integer
+
+   When the fractal set is calculated, a orbital trajectory is examined
+for each point. If the orbit diverges to infinity, the point is outside
+the set.  Otherwise, the point is inside the set. For exact
+calculations, you need to know the entire orbital trajectory, which is
+infinitely long for areas inside the set, so fractals cannot be
+calculated exactly. By default, XaoS calculates at most 170 positions
+(iterations) and then gives up; if the point is still inside the
+bail-out value, it guesses that the point is inside the set.
+
+   When zoomed into a detailed area, especially one close to the set
+boundary, this value could become too low, and the fractal will become
+boring.  You might try increasing this value if you want to get the
+image interesting again; but this necessarily slows down the
+calculation at the same time.
+
+   The tutorial chapter "Escape time fractals" has more information on
+fractal calculation in XaoS, and there is a lengthy section in the
+hacker's manual (`xaosdev.texinfo') devoted to the subject.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: fastjulia,  Next: dynamic,  Prev: bailout,  Up: calc
+
+A.9.4 Fast Julia mode
+---------------------
+
+ -- Function: fastjulia bool
+
+   By default, changing the seed for the Julia set requires
+recalculation of the image (which is quite slow). It's a nice effect to
+change the seed smoothly and show the Julia set morphing as the seed
+changes. XaoS has a special algorithm which can calculate such
+morphings in realtime. It is very inexact, but it is good enough for a
+fast preview.
+
+   If you want to select a good seedpoint, enable fast Julia mode and
+find a nice place by dragging with the first mouse button depressed;
+then change to the Julia mode to see the exact image.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: dynamic,  Next: rotate,  Prev: fastjulia,  Up: calc
+
+A.10 Dynamic resolution
+=======================
+
+ -- Function: fastmode keyword
+
+   XaoS performs many optimizations, but fairly often this is not
+enough. In order to keep a high framerate, XaoS automatically lowers
+the resolution of the image, increasing it when there is time for more
+calculation. This feature is enabled by default when animating, but you
+might also like to enable it for new images (which makes the image
+`come into focus' when it is recalculated from scratch for whatever
+reason), or disable it completely if you don't like it.
+
+   In the scripting languge, the keyword should be one of the following:
+*`'never'*
+     Disable dynamic resolution
+
+*`'animate'*
+     Use only for animations (default)
+
+*`'new'*
+     Use also for new images
+
+
+File: xaos.info,  Node: rotate,  Prev: dynamic,  Up: calc
+
+A.11 Image rotation
+===================
+
+XaoS has support for rotation of the image to any angle. By default,
+changing the angle requires recalculation of the whole screen, but when
+_fast rotation mode_ is enabled, the angle can be changed smoothly.  In
+this mode XaoS calculates a larger non-rotated image and rotates it when
+needed, so it increases memory requirements and slows XaoS down; hence,
+it should be disabled when rotation is not being used.
+
+   The user interface provides two rotation modes--_rotate by mouse_
+which allows the angle to be changed by dragging with the first mouse
+button depressed, and _continuous rotation mode_, where the image is
+rotated clockwise continuously, and the arrow keys can be used to change
+the rotiation speed.
+
+ -- Function: fastrotate bool
+
+   This function is used to enable and disable fast rotation mode.
+_Available as_: command line option, command
+
+A.11.1 Automatic rotation
+-------------------------
+
+ -- Function: autorotate bool
+
+   Use this function to enable continuous rotation. In the scripting
+language you can also use `morphangle' to get an outwardly similar but
+more controllable effect.
+
+ -- Function: rotationspeed float
+
+   Specify the speed of continuous rotation, in degrees per second.
+Negative values are allowed and rotate anticlockwise.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: mfilter,  Next: ui,  Prev: calc,  Up: menus
+
+A.12 Filters
+============
+
+Filters are a post-calculation effect applied to the resulting image.
+They can do things like motion blurring, edge detection, emulation of
+palettes or truecolor on displays that can't handle them, and such
+things. There is a tutorial chapter about them.
+
+* Menu:
+
+* filter::	Filter command
+* edge::	Edge detection
+* edge2::	Edge detection2
+* starfield::	Starfield
+* stereogram::	Random dot stereogram
+* interlace::	Interlace filter
+* blur::	Motion blur
+* emboss::	Emboss
+* palettef::	Palette emulator
+* anti::	Antialiasing
+* truecolor::	Truecolor emulator
+
+
+File: xaos.info,  Node: filter,  Next: edge,  Up: mfilter
+
+A.12.1 Filter command
+---------------------
+
+ -- Function: filter keyword bool
+
+   This command is used to enable or disable filters. *Note mfilter::.
+The _keyword_ specifies the filter to change, and should be one of the
+following:
+
+*`'edge'*
+     Edge detection
+
+*`'edge2'*
+     Edge detection2
+
+*`'starfield'*
+     Starfield
+
+*`'stereogram'*
+     Random dot stereogram
+
+*`'interlace'*
+     Interlace filter
+
+*`'blur'*
+     Motion blur
+
+*`'emboss'*
+     Emboss
+
+*`'palette'*
+     Palette emulator
+
+*`'anti'*
+     Antialiasing
+
+*`'truecolor'*
+     Truecolor
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: edge,  Next: edge2,  Prev: filter,  Up: mfilter
+
+A.12.2 Edge detection
+---------------------
+
+This filter is a standard edge detection algorithm; solid areas are
+filled in black. Some fractals look very interesting with this filter
+(and some areas of some fractals just look like noise). This version of
+the filter produces relatively wide lines, so is useful at higher
+resolutions. The filter edge detection2 makes thinner lines, for the
+low resolution modes.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: edge2,  Next: starfield,  Prev: edge,  Up: mfilter
+
+A.12.3 Edge detection2
+----------------------
+
+This filter is a standard edge detection algorithm; solid areas are
+filled in black. Some fractals look very interesting with this filter
+(and some areas of some fractals just look like noise). This version of
+the filter produces relatively tight lines, so is useful at lower
+resolutions. The filter edge detection makes thinner lines, for the
+high resolution modes.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: starfield,  Next: stereogram,  Prev: edge2,  Up: mfilter
+
+A.12.4 Starfield
+----------------
+
+The starfield filter generates random stars whose density depends on the
+iteration count. Choose your favorite spiral fractal and enable this
+filter to get a Grand Design spiral galaxy :)
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: stereogram,  Next: interlace,  Prev: starfield,  Up: mfilter
+
+A.12.5 Random dot stereogram
+----------------------------
+
+Fractal images are good as a base for random dot stereograms. In case
+you don't know what these are, please point your browser to Google or
+another search engine and find some articles about such images, because
+learning to read such images takes some effort. They make it possible
+to generate three dimensional images on a normal monitor without any
+additional hardware, by exploiting bugs in the human brain (although
+you need two working eyes, and some people never learn to see them;
+they can simply ignore this feature).
+
+   XaoS is able to generate these images in animations, so you may use
+all normal XaoS functions (except palette changing and palette rotation,
+which makes no sense applied to a stereogram). To make the animation yet
+more exciting, XaoS emulates "falling" into the set; while you zoom in,
+your distance from the set drops and drops--but you never hit it; when
+the set reaches the level of your monitor, the distance is changed
+again so you are far away.
+
+   To make this work right, XaoS needs to know the _exact size of your
+monitor_. Because most platforms have no way to determine this, you
+need to use _command line options_ to tune it. If it's not set or is
+wrong, the stereograms will probably be impossible to see (if your
+monitor is too big or resolution too low), or the images will seem to
+be shallow (if your monitor is too small or resolution too high).
+
+   By default XaoS expects my 15" monitor (29.0cm x 21.5 cm). Another
+cause of problems is the virtual screen supported by some windowed
+environments (like some X servers) that makes a program think that the
+resolution is higher than it actually is, and you see only part of this
+extra-large screen.
+
+   The worst thing you could possibly do is to run full-screen XaoS in
+some graphical windowing system (OS/2 on top of Windows or Wine on top
+of Linux, perhaps) where XaoS can't tell the real size of its window at
+all. In such cases, it's normally better (not to mention faster) to run
+XaoS natively, rather than under such an emulation layer.
+
+   The following command line options are provided to specify sizes:
+
+*`-screenwidth', `-screenheight'*
+     Lets you specify the size of your screen in centimeters. Note that
+     you need to specify the size of the visible image on the monitor,
+     not the size with edge borders, or the size of the tube. The
+     simplistic `my monitor is 17", just turn 17" into centimeters'
+     doesn't work; that 17" is a marketing figure and has only a vague
+     connection to reality. Get out a ruler and measure it.
+
+*`-pixelwidth', `-pixelheight'*
+     Lets you specify the exact size of a single pixel, if XaoS cannot
+     determine this for itself from your screen size.
+
+   These options are used by some other parts of XaoS as well, so you
+should use them even when you don't want to see stereograms. You should
+probably write a small starting script (or alias, or shortcut; whatever
+your environment uses) that passes the correct parameters to XaoS.
+
+   If the window is _smaller than 8cm in any direction_, you will
+probably be unable to see anything; make the window bigger.
+
+   The correct way to see XaoS stereograms is:
+*1*
+     Start XaoS with options specifying the exact size of your screen
+     or one pixel on it
+
+*2*
+     Sit 60cm away from monitor
+
+*3*
+     If you use a windowed environment, resize XaoS's window to make it
+     wider than, say, 15 cm.
+
+*4*
+     Enable the filter (by pressing `E')
+
+*5*
+     focus on a point far away from the monitor (try to use your own
+     reflection, if your monitor's not antireflective); the random
+     blurring should eventually fall into the pattern of a Mandelbrot
+     set.
+
+*6*
+     Carefully use your mouse to zoom into interesting areas (it is
+     easy to lose concentration when you are not trained; but you can
+     use the autopilot...)
+
+*7*
+     Enjoy animation :)
+
+   If you still can't see the stereograms, it could be that the
+fractal, or your eye, is deformed. A deformed fractal can be caused by
+your specifying your monitor size wrongly. Visual problems that damage
+depth perception, as well as problems like astigmatism, can make it
+impossible to see stereograms at all.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: interlace,  Next: blur,  Prev: stereogram,  Up: mfilter
+
+A.12.6 Interlace filter
+-----------------------
+
+The interlace filter halves the horizontal resolution, and in each
+frame alternates between drawing only the even and only the odd lines.
+This speeds up the calculation, and in higher resolutions produces a
+motion-blur-like effect.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: blur,  Next: emboss,  Prev: interlace,  Up: mfilter
+
+A.12.7 Motion blur
+------------------
+
+Motion blur mixes the current frame with previous ones to produce a
+motion-blur effect. It might be rather slow in 16bpp truecolor modes.
+The best results can probably be seen in 8bpp modes, so you might want
+to enable the palette filter first.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: emboss,  Next: palettef,  Prev: blur,  Up: mfilter
+
+A.12.8 Emboss
+-------------
+
+This is a standard emboss filter, as seen in programs such as the GIMP
+or Photoshop. It produces especially nice results with the smooth
+outcoloring mode. *Note outcoloring::.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: palettef,  Next: anti,  Prev: emboss,  Up: mfilter
+
+A.12.9 Palette emulator
+-----------------------
+
+XaoS can work in either palette or truecolor mode. Both modes have
+advantages and disadvantages. Palette mode allows effects such as
+palette rotation, while truecolor mode allows smoother incoloring and
+outcoloring modes and the truecolor coloring modes. If your display is
+truecolor, you can enable this filter to get palette emulation (albeit
+not as cheaply as in a real paletted mode).
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: anti,  Next: truecolor,  Prev: palettef,  Up: mfilter
+
+A.12.10 Antialiasing
+--------------------
+
+Antialiasing is a technique to increase image quality by eliminating
+jagged edges. XaoS calculates four values for each pixel (on the
+subpixel boundaries) and uses the average of them for the pixel value.
+
+   This filter slows XaoS down a _lot_ and greatly increases memory
+requirements. It is useful mainly when you want to save images and want
+to make them look as nice as possible. Antialiasing also helps a lot
+when you want to encode JPEG or MPEG files; they are much shorter if
+antialiased (MPEG and JPEG hate jagged edges).
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: truecolor,  Prev: anti,  Up: mfilter
+
+A.12.11 Truecolor emulator
+--------------------------
+
+XaoS can work in either palette or truecolor mode. Both modes have
+advantages and disadvantages. Palette mode allows effects such as
+palette rotation, while truecolor mode allows smoother incoloring and
+outcoloring modes and the truecolor coloring modes. If your display is
+8bpp, you can enable this filter to get truecolor emulation (but,
+obviously, not with as many colors as a real truecolor display).
+
+   More information about filters
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: ui,  Next: misc,  Prev: mfilter,  Up: menus
+
+A.13 UI
+=======
+
+This menu contains functions to control the user interface layer of
+XaoS: zooming speed, the autopilot, realtime status information, and so
+on.
+
+* Menu:
+
+* speed::	Zooming speed
+* letterspersec::	Letters per second
+* autopilot::	Autopilot
+* recalculate::	Recalculate
+* interrupt::	Interrupt
+* nogui::	Disable XaoS's builtin GUI
+* status::	Status
+* ministatus::	Ministatus
+
+
+File: xaos.info,  Node: speed,  Next: letterspersec,  Up: ui
+
+A.13.1 Zooming speed
+--------------------
+
+ -- Function: speed float
+
+   Change zooming speed, where 1 is the default, 2 means twice as fast,
+and so on.
+
+   _Available as_: menu item, command line option, command
+
+   In the scripting language you can use the following functions for
+better control:
+
+ -- Function: maxstep float
+
+   Selects the zooming/unzooming speed. The parameter specifies how
+much of the range will be removed each twentieth of a second; 0 means
+nothing, 1 means everything (the parameter obviously has to be less
+than 1).  Higher values mean faster zooming.
+
+   _Available as_: command
+
+ -- Function: speedup float
+   When zooming/unzooming, every twentieth of a second the `speedup'
+value is added to the current step until `maxstep' is reached.  So this
+value selects the rate at which zooming stops and starts.  Both these
+functions are more for internal use of XaoS then for manually written
+scripts, but they could come in useful nonetheless.
+
+   _Available as_: command
+
+
+File: xaos.info,  Node: letterspersec,  Next: autopilot,  Prev: speed,  Up: ui
+
+A.13.2 Letters per second
+-------------------------
+
+ -- Function: letterspersec integer
+
+   Speed of subtitles for the `textsleep' function.  The user can set
+this value to suit; it can also be changed with the left and right
+arrow keys during animation replay.
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: autopilot,  Next: recalculate,  Prev: letterspersec,  Up: ui
+
+A.13.3 Autopilot
+----------------
+
+ -- Function: autopilot bool
+
+   To make XaoS yet more impressive, we made a special autopilot mode
+that automatically drives into interesting boundaries of the set; you
+should press `A', play your favorite music, drink coffee and relax. I
+never tried this but it should be really relaxing! Many pictures in the
+XaoS gallery were discovered using the autopilot.
+
+   The autopilot also has some additional features. It backtracks if the
+zoomed picture is not interesting anymore, and can detect when it's
+zoomed into really a boring part of the fractal or reached the limit of
+floating point arithmetic on the platform, and restart zooming from the
+top.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: recalculate,  Next: interrupt,  Prev: autopilot,  Up: ui
+
+A.13.4 Recalculate
+------------------
+
+ -- Function: recalculate
+
+   Recalculate current fractal. This should be used when the fractal on
+the screen is strange because of error propagation caused by solid
+guessing. *Note range::.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: interrupt,  Next: nogui,  Prev: recalculate,  Up: ui
+
+A.13.5 Interrupt
+----------------
+
+ -- Function: interrupt
+
+   Interrupt current calculation.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: nogui,  Next: status,  Prev: interrupt,  Up: ui
+
+A.13.6 Disable XaoS's builtin GUI
+---------------------------------
+
+ -- Function: nogui bool
+
+   Disable XaoS menus and dialogs. This function should be used by
+external GUI programs; these manipulate XaoS via a pipe, so the
+internal GUI should be disabled at the same time. See the hacker's
+manual (`xaosdev.texinfo') for more details.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: status,  Next: ministatus,  Prev: nogui,  Up: ui
+
+A.13.7 Status
+-------------
+
+ -- Function: status bool
+
+   Enable/disable status information. This displays some useful
+information about the current fractal, such as viewpoint etc. (In
+low-resolution modes it also almost completely obscures the current
+fractal...)
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: ministatus,  Prev: status,  Up: ui
+
+A.13.8 Ministatus
+-----------------
+
+ -- Function: ministatus bool
+
+   Enable/disable status line. This contains basic information such as
+how much you are zoomed and the framerate.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: misc,  Next: helpmenu,  Prev: ui,  Up: menus
+
+A.14 Misc
+=========
+
+Miscellaneous functions.
+
+* Menu:
+
+* command::	Command
+* renderanim::	Render animation
+* clearscreen::	Clear screen
+* display::	Display fractal
+* text::	Display text
+* color::	Color
+* xtextpos::	Horizontal text position
+* ytextpos::	Vertical text position
+* textposition::	Text position
+* message::	Message
+
+
+File: xaos.info,  Node: command,  Next: renderanim,  Up: misc
+
+A.14.1 Command
+--------------
+
+You can invoke all XaoS functions using a simple command language
+reminiscent of Scheme. This option lets you run a single command. If
+you want to run more than one, you might want to use an XaoS animation
+file instead; they are written in the same language.
+
+   _Available as_: menu item
+
+
+File: xaos.info,  Node: renderanim,  Next: clearscreen,  Prev: command,  Up: misc
+
+A.14.2 Render animation
+-----------------------
+
+Render an animation to image files. See How to encode MPEG files for
+more information.
+
+   _Available as_: menu item,
+
+
+File: xaos.info,  Node: clearscreen,  Next: display,  Prev: renderanim,  Up: misc
+
+A.14.3 Clear screen
+-------------------
+
+ -- Function: clearscreen
+
+   Clear the screen. To display the fractal again, use `display'. *Note
+display::.  This function is mainly useful in tutorials and similar
+animations.
+
+   _Available as_: menu item, command
+
+
+File: xaos.info,  Node: display,  Next: text,  Prev: clearscreen,  Up: misc
+
+A.14.4 Display fractal
+----------------------
+
+ -- Function: display
+
+   Display fractal. This functions reverses the effect of the
+`clearscreen', line drawing and text output functions.
+
+   _Available as_: menu item, command
+
+
+File: xaos.info,  Node: text,  Next: color,  Prev: display,  Up: misc
+
+A.14.5 Display text
+-------------------
+
+ -- Function: text string
+
+   Display the given text on the screen. This function is mainly useful
+in tutorials.  Text should be cleared by printing lots of spaces, or
+using the `clearscreen'</a> or <a display>`display' functions. You
+might also want to use the `textposition' function to select the part
+of the screen to display the text on.
+
+   To wait for the user to read the text, you can use the `textsleep'
+function.
+
+   Example:
+
+     (clearscreen)
+     (textposition 'center 'middle)
+     (text "Welcome into my animation")
+     (textsleep)
+     (display)
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: color,  Next: textposition,  Prev: text,  Up: misc
+
+A.14.6 Color
+------------
+
+ -- Function: color keyword
+
+   Change text and line color. _keyword_ should be one of `'white',
+`'black' and `'red'.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: textposition,  Next: message,  Prev: color,  Up: misc
+
+A.14.7 Text position
+--------------------
+
+ -- Function: textposition keyword keyword
+
+   Select text position. The first keyword specifies the horizontal
+position, the second the vertical position. The horizontal position
+should be one of `'left', `'center', and `'right'.  The vertical should
+be one of `'top', `'middle', and `'bottom'.
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: message,  Prev: textposition,  Up: misc
+
+A.14.8 Message
+--------------
+
+ -- Function: message string
+
+   This function is almost identical to the `text' function, except
+that it uses message catalogs in the `catalog' directory to translate
+messages into other languages. It should be used only in the
+multi-lingual XaoS tutorials.
+
+   _Available as_: command line option, command
+
+
+File: xaos.info,  Node: helpmenu,  Next: xtextpos,  Prev: misc,  Up: menus
+
+A.15 Help
+=========
+
+This menu contains help and tutorials.
+
+
+File: xaos.info,  Node: xtextpos,  Next: ytextpos,  Prev: helpmenu,  Up: menus
+
+A.16 Horizontal text position
+=============================
+
+Select the horizontal position used to display text. *Note text::.  It
+can be placed at the left, in the center or at the right.
+
+
+File: xaos.info,  Node: ytextpos,  Next: mformula,  Prev: xtextpos,  Up: menus
+
+A.17 Vertical text position
+===========================
+
+Select the vertical position used to display text. *Note text::. It can
+be placed at the top, in the middle or at the bottom of the screen.
+
+
+File: xaos.info,  Node: mformula,  Next: palettemenu,  Prev: ytextpos,  Up: menus
+
+A.18 formulae
+=============
+
+Each escape time fractal has its own formula. XaoS supports the
+following formulae:
+
+* Menu:
+
+* mandel::	Mandelbrot
+* mandel3::	Mandelbrot^3
+* octal::	Octal
+* newton::	Newton
+* barnsley::	Barnsley1
+* phoenix::	Phoenix
+* magnet::	Magnet
+
+
+File: xaos.info,  Node: mandel,  Next: mandel3,  Up: mformula
+
+A.18.1 Mandelbrot
+-----------------
+
+The Mandelbrot set is the most famous escape time fractal ever. It has
+the simple formula z=z^2+c. See the tutorial chapter.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: mandel3,  Next: octal,  Prev: mandel,  Up: mformula
+
+A.18.2 Mandelbrot^3--Mandelbrot^6 and Mandelbrot^9
+--------------------------------------------------
+
+The Mandelbrot^3 fractal is a simple modification of the standard
+Mandelbrot set formula, using z=z^3+c instead of z=z^2+c.
+
+   Other derivations of the Mandelbrot set (Mandelbrot^4 and so on) use
+even higher powers. See the tutorial chapter.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: octal,  Next: newton,  Prev: mandel3,  Up: mformula
+
+A.18.3 Octal
+------------
+
+This is a less well-known fractal that Thomas discovered in Fractint.
+It has an interesting shape when displayed in the alternative planes.
+*Note plane::. See the tutorial chapter.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: newton,  Next: barnsley,  Prev: octal,  Up: mformula
+
+A.18.4 Newton
+-------------
+
+This is Newton's approximation method for finding the roots of a
+polynomial. It uses the polynomial x^3=1 and counts the number of
+iterations needed to reach the approximate value of the root. See the
+tutorial chapter.
+
+   This fractal doesn't have Julia sets, but XaoS is able to generate
+Julia-like sets which are also very interesting (they are sometimes
+called "Nova formulae").
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: barnsley,  Next: phoenix,  Prev: newton,  Up: mformula
+
+A.18.5 Barnsley1
+----------------
+
+This is a formula by Michael Barnsley. It produces very nice
+crystalline Julia sets. See the tutorial chapter.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: phoenix,  Next: magnet,  Prev: barnsley,  Up: mformula
+
+A.18.6 Phoenix
+--------------
+
+This formula produces very nice Julia sets.  See the tutorial chapter.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: magnet,  Prev: phoenix,  Up: mformula
+
+A.18.7 Magnet
+-------------
+
+This is a formula that comes from theoretical physics.  It is derived
+from the study of theoretical lattices in the context of magnetic
+renormalization transformations.  See the tutorial chapter.
+
+   _Available as_: menu item, command line option
+
+
+File: xaos.info,  Node: palettemenu,  Prev: mformula,  Up: menus
+
+A.19 Palette
+============
+
+This menu contains functions to change the palette the fractal is
+displayed with.
+
+* Menu:
+
+* defpalette::	Default palette
+* randompalette::	Random palette
+* palette::	Custom palette
+* cycling::	Color cycling
+* shiftpalette::	Shift palette
+
+
+File: xaos.info,  Node: defpalette,  Next: randompalette,  Up: palettemenu
+
+A.19.1 Default palette
+----------------------
+
+ -- Function: defaultpalette number
+
+   Create a default palette. In the scripting language, `number'
+specifies how much the palette is shifted by.
+
+   Note that changing the palette in truecolor modes forces
+recalculation of the whole screen. To avoid this, you can enable the
+palette emulation filter first.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: randompalette,  Next: palette,  Prev: defpalette,  Up: palettemenu
+
+A.19.2 Random palette
+---------------------
+
+ -- Function: randompalette
+
+   Create a random palette. XaoS will automatically pick one of its
+palette-generation algorithms and create one.
+
+   Note that changing the palette in truecolor modes forces
+recalculation of the whole screen. To avoid this, you can enable the
+palette emulation filter first.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: palette,  Next: cycling,  Prev: randompalette,  Up: palettemenu
+
+A.19.3 Custom palette
+---------------------
+
+ -- Function: palette integer integer integer
+
+   A custom palette lets you re-create some of the random palettes. The
+first value specifies the algorithm, which should currently be one of
+the following:
+*0*
+     Default palette
+
+*1*
+     Black to color gradient
+
+*2*
+     Black to color to white gradient
+
+*3*
+     Cubistic-like algorithm.
+   The seed specifies a random seed for the palette; different seeds
+generate different palettes. The last value is the amount by which the
+palette is shifted.
+
+   Note that changing the palette in the truecolor modes forces
+recalculation of the whole screen. To avoid this, you can enable the
+palette emulation filter first.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: cycling,  Next: shiftpalette,  Prev: palette,  Up: palettemenu
+
+A.19.4 Color cycling
+--------------------
+
+ -- Function: cycling bool
+
+   Color cycling is an old and simple effect to animate fractals. The
+Mandelbrot set looks particularly nice when color-cycled. On truecolor
+displays, color cycling fails to initialize (since those displays don't
+have a palette).  You can enable palette emulation filter to make it
+possible.
+
+   _Available as_: menu item, command line option, command
+
+   In the user interface, colors can also be cycled in the opposite
+direction with the "_Reversed color cycling_" function.
+
+   To control the cycling speed, you coan use arrow keys or the "_Color
+cycling speed_" function.
+
+   _Available as_: menu item
+
+ -- Function: cyclingspeed integer
+
+   The parameter specifies the number of skips per second. It can be
+negative to cycle in the opposite direction.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: shiftpalette,  Prev: cycling,  Up: palettemenu
+
+A.19.5 Shift palette
+--------------------
+
+ -- Function: shiftpalette integer
+
+   Shift palette by the specified number of cells. This can be used to
+tune the palette's position on the fractal. You can also use the _Shift
+one forward_ and _Shift one backward_ functions for fine-tuning. Note
+that shifted and rotated palettes could look different on different
+displays (because they may have different palette sizes).
+
+   Shifting the palette on truecolor displays causes a recalculation of
+the screen.  To avoid this, you could use palette emulation filter.
+*Note palettef::.
+
+   _Available as_: menu item, command line option, command
+
+
+File: xaos.info,  Node: about,  Next: support,  Prev: menus,  Up: Top
+
+Függelék: B About XaoS
+************************
+
+Függelék: C Credits
+*********************
+
+(alphabetically)
+*Lucio Henrique de Araujo (lucio.matema@gmail.com)*
+     Brazilian/Portuguese translation
+
+*Samuel Bizien (samuel@bizien.info)*
+     Beryl fractal
+
+*Eric Courteau (ecourteau@cplus.fr)*
+     francais.cat (translation of tutorials)
+
+*Jean-Pierre Demailly (Jean-Pierre.Demailly@ujf-grenoble.fr)*
+     Updates for French translation
+
+*Radek Doulik (rodo@atrey.karlin.mff.cuni.cz)*
+     TK interface, windowid patches
+
+*Martin Dozsa (madsoft@centrum.cz)*
+     cs.po (Czech translation of menus)
+
+*Arpad Fekete (Fekete.Arpad.2@stud.u-szeged.hu)*
+     Some new fractals, and the 'More formulae' menu
+
+*Zelia Maria Horta Garcia (zeliagarcia@seed.pr.gov.br)*
+     Brazilian/Portuguese translation
+
+*Tim Goodwin (tgoodwin@cygnus.co.uk)*
+     english.cat corrections
+
+*Ben Hines*
+     autoconf suggestions, Mac OS X port
+
+*Jan Hubicka (jh@ucw.cz)*
+     Zooming routines, ugly interface, palettes, drivers, autopilot,
+     filters, documentation, tutorials etc.
+
+*Jens Kilian (jjk@acm.org)*
+     BeOS driver, deutsch.cat
+
+*Thomas A. K. Kjaer (takjaer@imv.aau.dk)*
+     OS/2 ports (320x200 graphics and AA-lib)
+
+*Zoltan Kovacs (kovzol@math.u-szeged.hu)*
+     Internationalization, Hungarian translations, finalizing version
+     3.1, bug fixes, web design, current maintainer
+
+*Zsigmond Kovacs (kovzsi@gmail.com)*
+     Fractal examples
+
+*J.B. Langston III (jb-langston@austin.rr.com)*
+     Native Mac OS X port (from version 3.2.2); web redesign;
+     co-maintainer
+
+*Andreas Madritsch (amadritsch@datacomm.ch)*
+     New fractal types, bailout, many fixes
+
+*Mateusz Malczak (xaos@malczak.info)*
+     User formula evaluation library
+
+*Giorgio Marazzi (gmarazzi@vtr.net)*
+     Improvements and fixes for espanhol.cat
+
+*Thomas Marsh (thomas.marsh2@gmail.com)*
+     First zoomer, formulae, planes, X11 driver, inversions, many ideas
+
+*Dominic Mazzoni (dmazzoni@cs.cmu.edu)*
+     Macintosh port (version 2.0)
+
+*David Meleedy*
+     Grammatical and spelling fixed version of `xaos.6'
+
+*Paul Nasca (zynaddsubfx@yahoo.com)*
+     Ministatus improvement
+
+*Nix (nix@esperi.demon.co.uk)*
+     Grammatical and spelling fixed version of `xaos.hlp' and other
+     files
+
+*Terje Pedersen (terjepe@login.eunet.no)*
+     Amiga port
+
+*Cesar Perez (oroz@users.sourceforge.net)*
+     Spanish translations
+
+*Fabrice Premel (premelfa@etu.utc.fr)*
+     Periodicity checking
+
+*Jan Olderdissen (jan@olderdissen.com)*
+     Win32 port
+
+*Ilinca Sitaru (ilinca.sitaru@gmail.com)*
+     Romanian translation
+
+*Daniel Skarda*
+     Fractal examples
+
+*Andrew Stone (Stone Design - www.stone.com)*
+     Videator Support, Cocoa improvements, performance mode, bug fixes
+
+*Marton Torok (marton.torok@gmail.com)*
+     Small fixes for pipes
+
+*Pavel Tzekov (paveltz@csoft.bg)*
+     Win32 support
+
+*Charles Vidal*
+     Tcl/Tk interface
+
+*Tapio K. Vocaldo (taps@rmx.com)*
+     Macintosh port
+
+*Tormod Volden*
+     Fixes for X11 driver to improve compatability with Xorg,
+     XScreenSaver, Beryl and Compiz
+
+*Philippe Wautelet (p.wautelet@fractalzone.be)*
+     Bug fixes for version 3.1.1, French translation, gcc 4.0 fixes
+
+*Sergio Zanchetta*
+     Italian translation
+
+C.0.1 Included Software
+-----------------------
+
+XaoS uses the following libraries. These libraries may be included with
+some binary distributions of XaoS.
+
+   _gettext 0.17_ Website: `http://www.gnu.org/software/gettext/'
+Copyright (C) 1995-1997, 2000-2007 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later
+(http://gnu.org/licenses/gpl.html) This is free software: you are free
+to change and redistribute it.  There is NO WARRANTY, to the extent
+permitted by law.
+
+   _GNU Scientific Library 1.11_ Website:
+`http://www.gnu.org/software/gsl/' Copyright (C) 1996, 1997, 1998,
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 The GSL Team.
+License GPLv3+: GNU GPL version 3 or later
+(http://gnu.org/licenses/gpl.html) This is free software: you are free
+to change and redistribute it.  There is NO WARRANTY, to the extent
+permitted by law.
+
+   _libpng 1.2.25_ Website: `http://www.libpng.org/pub/png/libpng.html'
+Copyright (c) 1998-2008 Glenn Randers-Pehrson Copyright (c) 1996-1997
+Andreas Dilger Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
+
+
+File: xaos.info,  Node: support,  Next: index,  Prev: about,  Up: Top
+
+Függelék: D Getting Support
+*****************************
+
+XaoS is a community-supported free software project. There are many ways
+to get help, all of which are explained below.
+
+Függelék: E Home Page
+***********************
+
+The XaoS homepage is `http://xaos.sf.net'. Check here for the latest
+news and information about XaoS and to download the latest versions.
+
+E.0.1 Discussion Forums
+-----------------------
+
+XaoS has two discussion forums hosted on SourceForge. You can read them
+freely, but in order to post, you must to register for a free
+SourceForge account.
+
+*Help*
+     Provides a place for you to ask for help using XaoS. Other XaoS
+     users and/or the XaoS developers will answer your questions.
+
+     `http://sourceforge.net/forum/forum.php?forum_id=17768'
+
+*Open Discussion*
+     Provides a place to discuss anything related to XaoS or fractals.
+     You can share tips, your own fractal creations, or any other
+     fractal-related ideas with other XaoS users.
+
+     `http://sourceforge.net/forum/forum.php?forum_id=17767'
+
+   We welcome you to join these forums and become involved in the XaoS
+community.
+
+E.0.2 Mailing Lists
+-------------------
+
+XaoS currently has three mailing lists hosted on SourceForge.
+Unfortunately, there is currently very little traffic on any of them.
+Hopefully in the future, we can get more XaoS users and developers
+involved in the mailing lists.  The lists are as follows:
+
+*xaos-announce@lists.sourceforge.net*
+     Low volume list that is used only to announce new releases.
+
+     Subscribe:
+     `http://lists.sourceforge.net/mailman/listinfo/xaos-announce'
+     Archive:
+     `http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-announce'
+
+*xaos-devel@lists.sourceforge.net*
+     Developer mailing list, where the developers coordinate and
+     discuss XaoS development.
+
+     Subscribe:
+     `http://lists.sourceforge.net/mailman/listinfo/xaos-devel'
+     Archive:
+     `http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-devel'
+
+*xaos-discuss@lists.sourceforge.net*
+     General discussion list is for XaoS users to share tips and ideas
+     about XaoS.
+
+     Subscribe:
+     `http://lists.sourceforge.net/mailman/listinfo/xaos-discuss'
+     Archive:
+     `http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-discuss'
+
+   Please feel free to join any or all of these mailing lists and share
+your ideas with the developers and other XaoS users.
+
+E.0.3 Bug Reports
+-----------------
+
+If you think you have found a bug in XaoS, please report it. The
+developers will do their best to resolve the bug in a timely manner.
+
+   Bug Tracker:
+`http://sourceforge.net/tracker/?atid=105771&group_id=5771'
+
+   Please don't submit duplicate bugs. Browse the existing ones first
+to make sure nobody has already reported it. You may add additional
+information about a bug by entering a comment on an existing bug.
+
+   If you are not sure if something is a bug, please open a support
+request. The developers will try to answer your question and can
+convert your support request to a bug if necessary.
+
+   Support Requests:
+`http://sourceforge.net/tracker/?atid=205771&group_id=5771'
+
+E.0.4 Feature Requests
+----------------------
+
+If you have an idea for a great new feature you'd like to see added to
+XaoS, please let us know about it.  You can submit a feature request
+via SourceForge, and the XaoS developers will do their best to
+implement your request in a future version.
+
+   Feature Requests:
+`http://sourceforge.net/tracker/?atid=355771&group_id=5771'
+
+   Please don't submit duplicate feature requests. Browse the existing
+ones first to make sure nobody has already requested the feature your
+want. You may add your vote for a feature by adding a comment to the
+existing request.
+
+
+File: xaos.info,  Node: index,  Prev: support,  Up: Top
+
+Index of functions
+******************
+
+
+* Menu:
+
+* angle:                                 uiview.               (line 43)
+* animateview:                           animateview.          (line  7)
+* autopilot:                             autopilot.            (line  7)
+* autorotate:                            rotate.               (line 28)
+* bailout:                               bailout.              (line 26)
+* clearline:                             linemenu.             (line 73)
+* clearlines:                            linemenu.             (line 79)
+* clearscreen:                           clearscreen.          (line  7)
+* color:                                 color.                (line  7)
+* cycling:                               cycling.              (line  7)
+* cyclingspeed:                          cycling.              (line 25)
+* defaultpalette:                        defpalette.           (line  7)
+* display:                               display.              (line  7)
+* fastjulia:                             fastjulia.            (line  7)
+* fastmode:                              dynamic.              (line  7)
+* fastrotate:                            rotate.               (line 20)
+* filter:                                filter.               (line  7)
+* formula:                               formula.              (line  7)
+* incoloring:                            incoloring.           (line  7)
+* initstate:                             initstate.            (line  7)
+* intcoloring:                           tcolor.               (line  7)
+* interrupt:                             interrupt.            (line  7)
+* julia:                                 uimandelbrot.         (line 31)
+* juliaseed:                             uimandelbrot.         (line 38)
+* letterspersec:                         letterspersec.        (line  7)
+* line:                                  linemenu.             (line 40)
+* linekey:                               linemenu.             (line 67)
+* load:                                  load.                 (line  7)
+* loadexample:                           loadexample.          (line  7)
+* maxiter:                               maxiter.              (line  7)
+* maxstep:                               speed.                (line 17)
+* message:                               message.              (line  7)
+* ministatus:                            ministatus.           (line  7)
+* morphangle:                            morphangle.           (line  7)
+* morphjulia:                            morphjulia.           (line  7)
+* morphlastline:                         linemenu.             (line 58)
+* morphline:                             linemenu.             (line 48)
+* morphview <1>:                         morphview.            (line  7)
+* morphview:                             smoothmorph.          (line  7)
+* moveview:                              moveview.             (line  7)
+* nogui:                                 nogui.                (line  7)
+* outcoloring:                           outcoloring.          (line  7)
+* outtcoloring:                          tcolor.               (line  9)
+* palette:                               palette.              (line  7)
+* periodicity:                           periodicity.          (line  7)
+* perturbation:                          uiperturbation.       (line 26)
+* plane:                                 plane.                (line  7)
+* quit:                                  quit.                 (line  7)
+* randompalette:                         randompalette.        (line  7)
+* range:                                 range.                (line  7)
+* recalculate:                           recalculate.          (line  7)
+* record:                                record.               (line  7)
+* rotationspeed:                         rotate.               (line 34)
+* savecfg:                               savecfg.              (line  7)
+* saveimg:                               saveimg.              (line  7)
+* savepos:                               savepos.              (line  7)
+* shiftpalette:                          shiftpalette.         (line  7)
+* speed:                                 speed.                (line  7)
+* speedup:                               speed.                (line 26)
+* status:                                status.               (line  7)
+* stop:                                  zoom.                 (line 29)
+* text:                                  text.                 (line  7)
+* textposition:                          textposition.         (line  7)
+* textsleep:                             textsleep.            (line  7)
+* unzoom:                                zoom.                 (line 23)
+* usleep:                                usleep.               (line  7)
+* view:                                  uiview.               (line 31)
+* wait:                                  wait.                 (line  7)
+* zoom:                                  zoom.                 (line 17)
+* zoomcenter:                            zoom.                 (line 11)
+
+
+
+Tag Table:
+Node: Top440
+Node: Overview1491
+Node: Why?1688
+Node: What?3850
+Node: tutorial4423
+Node: controls14259
+Node: video16315
+Node: format20282
+Node: writehelp25754
+Node: xshl26241
+Node: drivers27386
+Node: aa28084
+Node: BeOS30601
+Node: DGA33457
+Node: dos34077
+Node: dX-fullscreen36510
+Node: dX-window37637
+Node: ggi37722
+Node: plan938273
+Node: SVGAlib39374
+Node: win3240754
+Node: X1142660
+Node: menus43657
+Node: root44527
+Node: animroot44588
+Node: stopreplay44871
+Node: plc45020
+Node: load45377
+Node: linemenu45710
+Node: animf48485
+Node: animateview49195
+Node: smoothmorph49730
+Node: morphview50314
+Node: morphjulia51377
+Node: moveview52005
+Node: morphangle52236
+Node: zoom52905
+Node: time53743
+Node: usleep54217
+Node: textsleep54618
+Node: wait55175
+Node: file55760
+Node: loadpos56031
+Node: savepos56293
+Node: record56739
+Node: play57242
+Node: saveimg57454
+Node: loadexample58090
+Node: savecfg58446
+Node: quit58833
+Node: edit59010
+Node: undo59200
+Node: redo59473
+Node: copy59648
+Node: paste59940
+Node: fractal60224
+Node: formula60787
+Node: uimandelbrot61519
+Node: uiperturbation63041
+Node: bailout64230
+Node: uiview65327
+Node: initstate67336
+Node: plane67829
+Node: incoloring68996
+Node: outcoloring70522
+Node: tcolor72247
+Node: calc73867
+Node: range74331
+Node: periodicity74958
+Node: maxiter77134
+Node: fastjulia78377
+Node: dynamic79136
+Node: rotate79975
+Node: mfilter81407
+Node: filter82063
+Node: edge82712
+Node: edge283251
+Node: starfield83795
+Node: stereogram84154
+Node: interlace88540
+Node: blur88956
+Node: emboss89371
+Node: palettef89706
+Node: anti90274
+Node: truecolor90981
+Node: ui91592
+Node: speed92053
+Node: letterspersec93116
+Node: autopilot93511
+Node: recalculate94348
+Node: interrupt94723
+Node: nogui94958
+Node: status95432
+Node: ministatus95835
+Node: misc96140
+Node: command96541
+Node: renderanim96927
+Node: clearscreen97180
+Node: display97525
+Node: text97831
+Node: color98571
+Node: textposition98855
+Node: message99325
+Node: helpmenu99732
+Node: xtextpos99871
+Node: ytextpos100144
+Node: mformula100424
+Node: mandel100775
+Node: mandel3101054
+Node: octal101531
+Node: newton101870
+Node: barnsley102414
+Node: phoenix102694
+Node: magnet102930
+Node: palettemenu103272
+Node: defpalette103608
+Node: randompalette104104
+Node: palette104609
+Node: cycling105473
+Node: shiftpalette106452
+Node: about107164
+Node: support111546
+Node: index115382
+
+End Tag Table
diff --git a/doc/xaos.texinfo b/doc/xaos.texinfo
new file mode 100644
index 0000000..fbcc70c
--- /dev/null
+++ b/doc/xaos.texinfo
@@ -0,0 +1,3468 @@
+\input texinfo   @c -*-texinfo-*-
+
+@c The original files are xaos.geninfo and xaos.hlp. xaos.texinfo is
+@c automatically generated. So make all changes in the orignal files please.
+@c To regenerate xaos.texinfo, please run "mktexinfo".
+
+@c Use A4 paper - If you don't like that, remove the following 3 lines.
+@iftex
+@afourpaper
+@end iftex
+
+@setfilename xaos.info
+@settitle An fast realtime interactive fractal zoomer --- user's manual
+@dircategory Graphics
+@direntry 
+* XaoS: (xaos).               A fast real-time interactive fractal zoomer
+@end direntry
+
+
+@ifinfo
+@copyright{} 1996-2008 Jan Hubicka and the XaoS Development Team
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+@end ifinfo
+
+@c %**end of header
+
+@set VERSION    3.4
+@set DATE       April 17, 2008
+
+@titlepage
+
+@title{XaoS @value{VERSION}}
+@subtitle{A fast real-time interactive fractal zoomer --- User's manual}
+
+@author{Jan Hubi@v cka}
+@tex
+Dukelsk\'ych bojovn\'\i ku 1944 
+@end tex
+@*
+390 03 T@'abor @*
+Czech Republic
+
+Email: @code{jh@@ucw.cz}
+
+@value{DATE}
+
+@page
+@vskip 0pt plus 1filll
+@vskip 0pt plus 1filll
+
+@copyright{} 1996-2008 @tex Jan Hubi\v cka and the XaoS Development Team
+@end tex
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+@end titlepage
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node   Top,    Overview,       (dir),  (dir)
+
+@ifinfo
+@top XaoS @value{VERSION}
+@flushright 1.0
+A real-time interactive fractal zoomer
+User's manual
+@value{DATE}
+@end flushright
+
+This manual contains user documentation about XaoS --- a fast real-time fractal
+zoomer. XaoS uses a development model, so sources are freely available. The
+file @code{xaosdev.texinfo} in the source documentation contains a hacker's
+manual (design overview, algorithm description etc.).
+@end ifinfo
+
+@menu
+* Overview::		What does this software do then?
+* tutorial::		XaoS tutorial
+* controls::		Basic controls
+* video::		How to encode video files
+* format::		XaoS's file format description
+* writehelp::		How to write XaoS help files
+* xshl::		XaoS simple hypertext language
+* drivers::		Driver specific documentation
+* menus::		Functions, menu items and command line parameters
+* about::		Credits
+* support::		Getting Support
+* index::		Function index
+@end menu
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node Overview, tutorial, Top, Top
+
+@chapter Overview
+@menu
+* Why?::		Why yet another fractal generator?
+* What?::		What does this software do then?
+@end menu
+
+@node Why?, What?, Overview, Overview
+@section Why yet another fractal generator?
+
+
+We decided to make XaoS, because all fractal browsers we know of take a
+long time to calculate each image. You may browse nice images
+generated by them but real impressions of fractals --- the self
+similarity and infinite zooming into the nice parts of fractals ---
+can be seen only in animations. There are many programs available that
+make nice animations, but they take a long time to calculate and lots
+of space on disk. Most such animations are quite ugly because their
+authors can't see them without many hours of calculations.
+
+A natural question is: is it possible to generate such animations in
+real-time? The answer was negative for many years, since the Mandelbrot set is
+very computationally expensive. Things are changing. Today's computers
+are fast enough to calculate approx. 10.000 of pixels per frame,
+which is enough 
+for a very low resolution animation (100x100). Several programs doing that
+are available. But 100x100 animation still looks quite ugly. To make
+animation nice you need at least 320x200 pixels. And that is 6 times more!
+One possibility is to wait until computers will be fast enough, but
+it will take many years, and then 320x200 animations will be obsolete
+and everyone will want 1024x768 resolution instead or more.
+
+We found a special algorithm that saves up to 99.98% of calculations during
+zooming by reusing pixels already calculated in previous frames. There were
+some programs doing similiar tricks before but we don't know about any able
+to do zooming interactively with a speed similar to XaoS. Many other tricks
+were later implemented XaoS to achieve yet higher framerates. Now XaoS does
+up to 120 frames per second on a 120Mhz pentium in a fullscreen 320x200
+animation, and calculates an average of 160 (0.24%) pixels per frame. This makes
+XaoS fast enough to achieve its primary goal, realtime animation, but there
+are still many areas that could improve, since more complex fractals,
+higher resolutions, or slower computers still bring many problems.
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node What?, , Why?, Overview
+@comment  node-name,  next,      previous,  up
+@section What does this software do then?
+
+XaoS is a realtime interactive fractal zoomer. This means that it lets you
+zoom smoothly into any place in the fractal you choose without the many hours
+of calculation required by most other fractal generators. It now has many
+other features too, like 13 different fractal types, autopilot, special coloring
+modes, support for various bit depths (8bpp, truecolor, hicolor and realcolor),
+random palette generation, color cycling etc...
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node tutorial, controls, Overview, Top
+
+@chapter XaoS tutorial
+
+This is a brief introduction to the basic XaoS features.
+
+@section How to zoom
+The main advantage of XaoS is that after a few seconds' delay to calculate
+the first image, you may choose any point with the mouse and press the @emph{left} button.
+The image will start to zoom smoothly into the point you choose. You may move
+the mouse and zoom smoothly into interesting areas. By pressing the @emph{middle
+button} (or @emph{left+right} buttons) you may also
+@emph{move the image} using ``drag & drop'' if you missed an interesting
+place. @emph{Unzooming} is also possible by using the @emph{right button},
+but it is much slower because optimizations are not so effective as for zooming.
+
+In case you think that the default @emph{speed} is boring (it is quite slow, to
+make XaoS smooth on a slow computer) you may change it by pressing @emph{arrow
+up/down}. But faster zooming is more expensive, so if the speed is too high
+you will see little but funny colorful blinking rectangles.
+
+@section Autopilot
+
+To make XaoS yet more impressive we made a special autopilot that
+automatically drives into interesting boundaries of the set. So you can
+press @code{A}, play your favorite music, drink coffee and relax. I never
+tried this but it should be really relaxing! Many pictures in the XaoS
+gallery were discovered using the autopilot.
+
+The autopilot also has some additional features. It turns back when the
+zoomed picture stops being interesting, and is able to spot when it's zoomed
+into a really boring part (or has reached the limit of floating point
+numbers) and restart zooming from the top.
+
+@section Various fractal formulae
+
+XaoS also supports formulae other than the Mandelbrot set. You may change
+@emph{formula} using the @emph{number keys}
+or @emph{SHIFT+letters}.
+
+
+
+On keys @code{1} to @code{5} are @emph{Mandelbrot sets of various power}. The ``normal''
+Mandelbrot set is on key @code{1}.
+
+On key @code{6} is a fractal called @emph{Newton}. It is Newton's famous formula for finding roots.
+
+On key @code{7} is the @emph{fourth ordered Newton} fractal.
+
+On key @code{8} is a fractal called @emph{Barnsley}.
+
+On key @code{9} is @emph{Barnsley's second} fractal.
+
+On key @code{0} is @emph{Barnsley's third} fractal.
+
+With keys @code{SHIFT-A} you can display a fractal called @emph{octo}. It is a fractal that Thomas
+discovered in fractint.
+
+With keys @code{SHIFT-B} you can display a fractal called @emph{Phoenix}. It is a very nice and quite famous fractal.
+
+With keys @code{SHIFT-C} you can display a fractal called @emph{Magnet}. This fractal has quite a complex formula so it is
+a bit slow.
+
+With keys @code{SHIFT-D} you can display the @emph{Magnet2} fractal.
+
+The rest of the built-in fractals are accessible through an other menu, but
+you can still use the hotkeys.
+
+On @code{SHIFT-E} is a fractal called @emph{Triceratops} found by Arpad.
+
+On @code{SHIFT-F} is a fractal called @emph{Catseye} found by Arpad.
+This is more interesting if you change the bailout value.
+
+On @code{SHIFT-G} is a fractal called @emph{Mandelbar}. It was in
+Gnofract4d, and they found it at:
+http://mathworld.wolfram.com/MandelbarSet.html
+
+On @code{SHIFT-H} is the @emph{Lambda} fractal.
+
+On @code{SHIFT-I} and @code{SHIFT-J} are the @emph{Manowar}
+and @emph{Spider} fractals, they were found by users of fractint.
+(Scott Taylor or Lee Skinner)
+It was on http://spanky.triumf.ca/www/fractint/
+taylor_skinner_type.html
+
+The next 3 fractals are famous classic fractals.
+
+On @code{SHIFT-K} is the @emph{Sierpinski} Gasket.
+You can change its shape by selecting another Julia seed.
+(This is for technical reasons.)
+
+On @code{SHIFT-L} is the @emph{Sierpinski Carpet.}
+It's shape can also be changed by selecting another Julia seed.
+
+On @code{SHIFT-M} is the @emph{Koch Snowflake.}
+
+
+
+@section Out-coloring modes
+
+To make fractals yet more interesting, more coloring modes for points
+outside the set are provided. ``Classical coloring mode'' uses the number of
+iterations that the orbit required to escape to (nearly) infinity. You can change this
+mode from the @emph{Fractal menu} or by pressing key @code{C}
+To see more about coloring modes, try the tutorial on Incoloring modes from the XaoS features overview.
+
+Those cryptic names for coloring modes are mathematical formulae, where @emph{iter} means number
+of iterations, @emph{real} means real coordinate of last orbit, and @emph{imag} means imaginary
+coordinate of last orbit.
+
+@section In-coloring mode
+
+In-coloring mode is similar to out-coloring, except that it changes how
+things inside the set are displayed. This can also be changed from the @emph{fractal
+menu} or by pressing @code{F}.
+
+You might also want to see the tutorial on
+Out-coloring modes from the XaoS features overview.
+
+@section Planes
+
+All fractals displayed by XaoS are functions with a complex parameter. It
+can be displayed in the normal complex plane, where x is the real part of
+the number, and y is the imaginary part; but it can also be displayed in
+a number of other planes. You can select the plane to use from the
+@emph{Fractal menu}, or by pressing @code{I}.
+
+Like the coloring modes, planes have cryptic names. You guessed it, they're
+mathematical formulae. Here @code{mu} means coordinates in the normal
+complex plane. If you have coordinates in @code{1/mu} plane, and you need
+coordinates in the a complex plane (to calculate the Mandelbrot set) you
+simply use the coordinates as mu. Lambda is another plane that can be
+converted to mu using a similar formula.
+
+@table @strong
+@item mu
+normal mode.
+
+@item 1/mu
+Inversion: infinity goes to 0 and 0 goes to infinity.
+
+@item 1/(mu+0.25)
+Similar to inversion, but moves the center outside of the
+Mandelbrot set so that it looks parabolic.
+
+@item lambda
+Lambda plane.
+
+@item 1/lambda
+Inversion of lambda plane.
+
+@item 1/lambda-1
+Inversion with moved center.
+
+@item 1/(mu-1.40115)
+A very interesting mode for the Mandelbrot set. It makes small things
+big, so you can browse the set's details easily.
+@end table
+
+
+@section Mandelbrot/Julia switching
+
+Most of the fractals displayed by XaoS (currently all of them) have two
+forms: Mandelbrot and Julia. Every point in a Mandelbrot set has its
+own Julia set. To see more about this correspondence, try the tutorial on
+Julia set from the Introduction to fractals.
+
+In the Mandelbrot mode, you can get a corresponding Julia by moving the mouse
+to an interesting point and pressing @code{M}. To get back press @code{M}
+again. Some fractals (Barnsley and phoenix) are already in their Julia
+versions, because the Mandelbrot ones are boring. But by pressing @code{M}
+in such fractal you should get the Mandelbrot version, and by choosing another
+point as the base point and pressing @code{M} again you should get a
+completely different fractal. The most interesting points for Julia sets
+are at the boundaries of the Mandelbrot set. Most of the Julias inside or
+outside the set are boring.
+
+
+@section Fast Julia preview mode
+
+Fast Julia mode is a quick way to find a point to use as a base for the Julia
+set.. Just press @code{J} and a small Julia set will be displayed in the top
+left corner. Then move the mouse around with button 1 depressed, and the Julia
+for the point the mouse is over will be automatically generated.
+
+@section Palette
+
+If you think that the default XaoS colors are ugly or you are just
+bored by them you can change it by pressing @code{P}. XaoS will
+automatically generate random palettes. Many of them look ugly, so
+press @code{P} again to get another one until you find one you like.
+
+@section Filters
+
+Many interesting effects are done by post-calculation filters. @xref{filter}.
+XaoS has filters that do everything from embossing, through motion-blurring,
+right through to turning the fractal into a stereogram. To enable them use
+the @code{filter menu} or press @code{E}.
+
+@section Palette cycling
+
+This is a very old trick that makes the Mandelbrot set a little flashier. You
+may enable or disable it using @code{Y}. In the truecolor modes you need
+to enable the palette emulator filter first. This is done
+via the @code{E} key, or from the filter menu.
+
+@section Changing number of iterations
+
+To calculate fractals perfectly, you need an infinite number of
+iterations. XaoS does just the first few of them, so after lots of zooming
+you may get into a place that looks quite boring, and the boundaries of the
+set are rounded, without any interesting details. This can be changed by
+changing the number of iterations:
+
+Press and hold @code{arrow right} and wait until iterations are high enough.
+This may slow down calculation much. To reduce number of iterations
+press @code{arrow left}.
+
+@section Changing resolution
+
+XaoS usually starts in a low resolution (320x200 or thereabouts) to make
+calculations faster. If you have a fast computer or you need to
+save bigger @code{.gif} images, you may change the resolution. This
+can be done by pressing @code{=} in the full screen drivers, or simply
+by resizing the XaoS window.
+
+@section Changing driver
+
+XaoS usually has more than one driver available. You may change it on
+the fly in case you want a different one. For example, XaoS started in X11
+can be switched at runtime to use the AA driver. This can be done from the
+UI menu.
+
+This action is bit dangerous, because XaoS can crash during initialization
+if there is some problem with initialization; XaoS tries to initialize a new
+driver, and if it fails it attempts to return back to the original. Sometimes
+this is impossible, and all XaoS can do is terminate..
+
+@section Other features
+XaoS has many other features, but they don't fit into this tutorial. Most of
+them are available from the menu, so you can experiment with them. You might
+also want to see the @emph{animated tutorials} from the @emph{help menu},
+to have an idea what XaoS can do.
+
+
+@c ## chapter tutorial ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node controls, video, tutorial ,Top
+
+@chapter Basic controls
+By default the mouse buttons work in the following way:
+
+@table @strong
+@item left
+zoom in
+@item right
+zoom out
+@item middle
+move fractal in a drag-and-drop fashion
+@end table
+
+@emph{Note:} Since most Macs only have one button mice, these controls
+are emulated on Mac OS X using modifier keys. See the help section on
+Mac OS X for details.
+
+This behavior can change. If you enable rotation, the first button is used for rotating
+fractals. Also, in fast Julia mode, the first button is used to change the seed.
+
+If you don't have a middle button, press both buttons to enable
+emulation.
+
+After few minutes of zooming you will probably exceed the precision and the
+fractals will get boring. If you are getting strange big rectangles on the screen,
+you probably reached the numeric limit: there is no way to avoid this except
+un-zoom back and choose a different area. It doesn't hurt so much, since you have
+zoomed approximately 64 051 194 700 380 384 times, so there are quite a lot of areas to
+explore. Algorithms with unlimited precision exist, but they are still too
+slow for real-time zooming.
+
+The other possibility is that you have reached the iteration limit. The fractal is
+calculated approximately, and in this case you need to increase number of
+iterations used for approximation (and decrease the speed in the process).
+This is done from the menu or using the arrow keys @emph{Left} and @emph{Right}.
+
+An @emph{Up} and @emph{Down} keys should be used to change zooming
+speed. Note that higher speed costs more and image will be blocky.
+
+This behavior can also change. With palette cycling enabled, @emph{Left}
+and @emph{Right} keys change cycling speed; in continuous
+rotation they change rotation speed.
+
+All other functions are available from the menu, which (in the default
+configuration) are displayed when you move the mouse to the top of the
+screen/window. It is useful to learn the shortcut keys, which are
+shown in gray next to the menu items they trigger.
+
+
+@c ## chapter controls ##
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node video, format, controls ,Top
+
+
+@chapter How to encode video files from XaoS
+
+To create a video, make and @code{xaf} file first (the easiest way to do this is
+to use the @emph{record} function in the file menu). Then you need to render
+the animation. XaoS can output sequences of ordinary @code{PNG} images, that
+can later be used by a video encoder.
+
+@section Generating image sequences for video
+
+To generate an image sequence, choose @emph{Render Animation} from the @emph{Misc}
+menu. You can also use the following command on the command line:
+
+
+@example
+xaos -render [filename] -size 352x240 -antialiasing
+-renderframerate 24 -basename [basename]
+@end example
+
+
+@emph{File to render} (@code{[filename]}) is the name of the @code{xaf} file,
+@emph{Basename} (@code{[basename]}) is the name used as the base filename for rendered images. This should also include the path where you want to save the images.
+XaoS adds a four digit sequence number and @code{.png} extension to this name automatically.
+
+You might also want to change the resolution. Make sure that the resolution
+you choose is supported by the video codec you wish to use.
+
+The framerate can also be altered. Make sure you choose a framerate that is supported by
+the video codec you wish to use.
+
+@emph{Antialiasing} (@code{-antialiasing}) is used to produce anti-aliased images.
+It takes a much longer
+time and much more memory to calculate them, but resulting images are better
+for video compression and they result in a much smaller video file.
+(the same is true of @emph{JPEG images})
+
+On the other hand, the other XaoS rendering option @emph{Always Recalculate} (@code{-alwaysrecalc}) (which disables
+XaoS's zooming optimizations) is @emph{not recommended}. If that's used, the
+sequence of animation then contains quite a lot of extra information, which
+increases size of video file, but because of the codec's lossy compression it is hard
+to see any difference, so it's not worth it.
+@section Rendered files
+Once you start it, XaoS will generate thousands of frames. They take quite
+a long time to calculate and save, and consume plenty of disk space.
+(e.g. to render part 1 of the tutorial you need about 60MB and half an hour of time).
+
+All images are named @code{[basename]framenum.png}. For example @code{intro0001.png} is
+the first frame of the animation intro. If consecutive frames are the same, XaoS
+doesn't save them, so some frames may be missing. If your encoder can't handle
+that, you will need to write a simple script which will fill in the gaps by means
+of @code{mv} or symbolic linking.
+
+A list of all filenames is saved into the file @code{[basename].par}, where each line is
+the name of one frame. The names repeat here if necessary, so you can use this
+file to supply filenames to the encoder.
+@section Encoding videos
+Once XaoS has generated the png files for each frame of the animation, you
+can use a third-party video encoder to convert the sequence of images into
+a video file. We currently recommend the following encoders, which support
+a wide variety of video codecs and file formats:
+@table @strong
+@item ffmpeg
+Available from: @code{http://ffmpeg.mplayerhq.hu/}
+Instructions: @code{http://ffmpeg.mplayerhq.hu/faq.html#SEC12}
+@item mencoder
+Part of mplayer, available from: http://www.mplayerhq.hu/
+Instructions: @code{http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-enc-images.html}
+@end table
+These are both command line tools. If you prefer a graphical tool, you may
+prefer Quicktime Pro from Apple (http://www.apple.com/quicktime/pro/). However,
+this software costs approximately US$30, and the authors of XaoS have no
+experience with it. Although QuickTime may be easier to use, the two free
+encoders above are just as capable once you learn how to use them.
+
+
+Note: we used to recommend Berkeley parallel MPEG encoder to
+encode the generated png files into MPEG videos. We have kept
+the instructions mainly for historic purposes.
+
+
+@c ## chapter video ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node format, writehelp,video ,Top
+@chapter XaoS's file format
+This section describes the format used by XaoS for animations, configuration
+files and saved positions. All these files have a common format, designed
+to be easily readable, to allow manual editing of files and easy conversion by
+other programs.
+
+I also taken care to make it easily extensible for future versions of XaoS
+so I hope there will not be many incompatibilities between various XaoS
+versions.
+
+The format is a simple set of commands executed sequentially. XaoS does not provide
+any variables/cycles as usual scripting languages do, but future extension to
+full-blown Scheme should be easy since the format uses Scheme-like syntax.
+The syntax of every command is:
+
+@code{(command_name }@emph{[param1] [param2]}@code{)}
+
+where parameters are optional and separated by whitespace (an arbitrary number
+of spaces, tabs and newlines). The parameters can have the following types:
+
+@table @strong
+@item integer
+number w/o decimal point (@code{123})
+@item float
+floating point number in decimal notation with optional exponent (@code{1.23E2})
+@item keyword
+text started by quote @code{'}. It is used to pass various string constants
+like formula name (@code{'mandel}) Quote is required for scheme compatibility
+@item string
+Text inside double quotes. The only parameter that should contain whitespace
+@item boolean
+@code{#t} for true or @code{#f} for false
+@end table
+
+There is a complete description of all XaoS functions (with some examples) and an
+index of functions in the XaoS registry. @xref{menus}. You may particularly want
+to read about the animation functions. @xref{animf}. Also, the following functions
+are significant:
+
+@table @strong
+@item load
+
+This function loads and interprets a file. It works similarly to @code{#include}
+in C.
+@item initstate
+
+Available in version 3.0 and above, this function resets XaoS's state to default
+values. This command should be at the beginning of each animation file,
+since otherwise some stuff previously enabled by user could cause unexpected
+effects. State is not reset by default before playing animations since it would
+make it impossible to write macros. Current versions don't really need macros, but
+in future versions, when the Scheme programming language will be available, this
+should be a much more interesting subject.
+@item usleep
+
+This function waits for a selected amount of time(in usec) before processing the
+next command. The screen is recalculated and displayed at the beginning of
+the sleep if necessary. The remaining time is spent by waiting, calculating if
+necessary, or performing any animation you entered via animation commands.
+@item wait
+
+Waits until the animation or image rendering is complete. Do not call this
+function when zoom, or continuous rotation is active otherwise deadlock happens. It is
+a good idea to call it immediately before text subtitles are displayed, since it looks
+ugly when they are displayed over a blocky unfinished fractal. Because the
+degree of blockiness at a given instant is a function of your machine speed,
+it may look nice for you but ugly for others with slower machines. Also
+you should call this after an animation is performed, before the switch to another
+fractal happens; since the switch involves calculation, the screen is stopped
+for a while and an unfinished fractal there looks ugly.
+You should also call it, when you want to do something as soon as possible.
+@end table
+
+Example:
+
+
+@example
+;configure everything for the first frame
+(inistate)
+(palette 1 1163254293 0) ;custom palette
+(cycling #t) ;enable cycling
+(cyclingspeed 7)
+(maxiter 276) ;higher number of iterations
+(range 3) ;default range for solid guessing
+(usleep 1000000) ;second frame starts here
+(moveview -1.8101154154614007889 -8.2687205907162041209E-05)
+;just move the image
+(usleep 1000000) ;third frame
+(morphview -1.8101154154614007889 -8.2687205907162041209E-05
+6.277210971069452361E-10 6.2772109785334669875E-10)
+;10 seconds of zooming into selected
+rectangle
+(usleep 100000000)
+@end example
+
+
+The best way to learn XaoS command language is probably to read position files
+and modify them. For example, to create zooming animation from the original
+file:
+
+
+@example
+(initstate)
+(defaultpalette 0)
+(formula 'mandel)
+(view -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+9.69332308834E-08)
+@end example
+
+
+Just change the @code{view} command to @code{morphview}, and add @code{usleep}:
+
+
+
+@example
+(initstate)
+(defaultpalette 0)
+(formula 'mandel)
+(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+9.69332308834E-08)
+(usleep 10000000)
+@end example
+
+
+The following code produces Julia morphing in the real axis:
+
+
+@example
+(initstate)
+(fastjulia #t)
+(juliaseed -2 0)
+(morphjulia 2 0)
+(usleep 2000000)
+@end example
+
+
+
+And following is the ``rotozooming'' animation:
+
+
+
+@example
+(initstate)
+(fastrotate #t)
+(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+9.69332308834E-08)
+(morphangle 300)
+(usleep 10000000)
+(wait)
+(fastrotate #f)
+@end example
+
+
+
+@chapter XaoS gallery
+
+I plan to make a gallery of animations and position files on the XaoS home-page,
+so please send any nice animations and images you created using XaoS
+to the mailing list or upload them to our website.
+@c ## chapter format ##
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node writehelp, xshl,format ,Top
+@chapter How to write XaoS help files
+XaoS help is stored in the file @code{help/xaos.hlp}. It is divided into parts,
+each part being started by a @emph{keyword}. In the help file keywords are
+written as @code{%keyword}
+
+If you are writing documentation about some command in the XaoS function
+registry, use the same keyword as the name of the command in order to make
+context sensitive help work.
+
+
+@c ## chapter writehelp ##
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node xshl, drivers,writehelp ,Top
+@section xshl
+@emph{Xshl} stands for @emph{XaoS simple hypertext language}. It
+uses similar tags to HTML. It is simpler and more restrictive in order to
+make it easy to parse using various scripts. In C code you can use the
+library present in @code{src/util/xshl.c} to parse it.
+
+The following tags are supported:
+
+@table @strong
+@item head
+make headings (should be at the beginning of the page, at least)
+@item emph
+emphasize
+@item tt
+Use non proportional font
+@item br
+Break line
+@item p
+Next paragraph
+@item dl
+Definition list
+@item dt
+Definition tag (should be used only inside a definition list)
+@item dd
+Definition description (should be used only inside a definition list)
+@item center
+align to center
+@item right
+align to right
+@item red
+change color to red (should not be used in help files)
+@item black
+change color to black (should not be used in help files)
+@item white
+change color to white (should not be used in help files)
+@item a name
+link to other help page
+@item tutor name
+activate tutorial
+@item notex
+Ignore this in texinfo manuals
+@end table
+
+
+
+@c ## section xshl ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node drivers, menus,xshl ,Top
+
+@chapter Platform-specific documentation
+XaoS is portable and works on many different platforms. Since not all platforms are
+exactly the same, there are some differences between the behavior of XaoS on
+different platforms. Here is documentation about each specific port.
+
+@c ## chapter drivers ##
+
+@menu
+* aa::			AA-lib --- high quality ascii art driver
+* BeOS::		BeOS drivers
+* DGA:: 		DGA driver
+* dos::			DOS driver
+* dX-fullscreen::	directX fullscreen driver
+* dX-window::		directX windowed driver
+* ggi::			GGI driver
+* plan9::		plan9 driver
+* SVGAlib::		SVGAlib driver
+* win32::		Win32 driver
+* X11:: 		X11 driver
+@end menu
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node aa, BeOS , ,drivers
+
+@section AA-lib driver
+
+The AA driver is currently the most advanced and portable driver for XaoS.
+It is based on AAlib---a high quality ASCII-art library developed by the AA-project.
+(see @code{http://aa-project.sf.net})
+
+It is a fully featured XaoS driver for text mode displays. It supports 256 colors
+and the mouse where possible.
+
+It also has some extended features available from the UI menu:
+
+@table @strong
+@item Attributes
+AA-lib may use character attributes to improve image quality.
+By default it uses normal, dim and bold characters where possible,
+but you can also enable different attributes like reversed or bold font
+characters. You may also enable usage of non ansii/reversed characters if
+your device supports it.
+@item Font
+AA-lib uses a bitmap image of the font to prepare the approximation table
+used for ASCII art rendering. This bitmap is expected to be same as the one used
+by your device. AAlib performs detection where possible however some devices
+(like UNIX text terminals or MDA) do not support this. AAlib has few font
+images compiled in, so in this case you should try to use one of them to
+achieve best results.
+@item Inversion
+Some devices use inverse video: use this to get correct results on such devices.
+@item Dithering mode
+Dithering is an way to get more exact color in approximations, by combining
+more characters; but this method can produce ugly looking noise on certain images.
+Use this menu to disable or tune it.
+@item Palette options
+By default AA driver uses the XaoS palette to render images, but it quite often
+looks ugly on text displays. Here you can choose a special text palette instead. Note that with
+filters enabled, the results may be rather ugly. This function is available from
+the @emph{palette menu}.
+@item Save text screen
+The normal save function will generate a PNG image instead of nice
+ASCII-art. To save ASCII art use this function instead. It supports many
+text file formats like HTML, ANSI, more, etc... It will also ask you for
+font and attributes(see above). It is available from the @emph{file
+menu}.
+@end table
+
+The AA-lib driver also provides the full set of standard AA-lib's command line
+options. You may use them to tune parameters like gamma correction, and so on.
+See @code{xaos -help} or the AA-lib documentation for details.
+
+The AA driver was written by Jan Hubicka, 1997.
+
+@c ## section aa ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node BeOS, DGA , aa ,drivers
+
+@section BeOS support
+
+XaoS has pretty advanced support for BeOS R4. It works on both PowerPC and
+Intel platforms, supports multithreading, the clipboard, file dragging,
+has native look and feel and can work as an image translator from XaoS files
+to images.
+
+The first version of the BeOS driver was written by Jens Kilian and later
+extended by Jan Hubicka.
+
+@subsection Installation
+
+You can start the installation script to do everything for you. If you want
+something special, read this section.
+
+In order for XaoS to work you need to keep the executable together with
+its data files (@code{help}, @code{examples}, @code{catalogs} and the @code{tutorials} directory)
+
+When first started, XaoS registers two new mime types called
+@code{image/x-xaos-position} for XaoS Position Files and
+@code{video/x-xaos-animation} for XaoS Animation Files,
+registers icons for them and sets itself as default application.
+
+@subsection Available display drivers
+
+XaoS supports following drivers:
+
+@table @strong
+@item BeOS
+Standard windowed driver using application server
+@item DirectWindow
+Driver done using Game Kit's direct window class
+@item WindowScreen
+Fullscreen driver.
+@end table
+
+By default, XaoS starts in windowed mode and uses the application server for output.
+You could change the driver to DirectWindow to use direct access to video RAM.
+Note that this mode is slower in most cases, and not supported by some videocards.
+
+The BeOS driver by default chooses the most similar bitmap supported by XaoS
+to achieve best and fastest results.
+In the UI menu you can change this default choice to another one if you wish.
+Also you can ask the BeOS and DirectWindow to resize to fullscreen mode.
+
+XaoS also supports real fullscreen mode using the BWindowScreen API. To switch
+XaoS to this driver, use the UI menu. If you want to use this mode by default,
+use the @code{-driver WindowScreen} command line option.
+
+This driver differs a lot from windowed ones. It use direct access to the video
+card, allowing you to change video mode. Also, the 256 color mode
+can access the palette, so it is not dithered like the windowed mode.
+Because BeOS can't do GUI in fullscreen mode, XaoS uses its own toolkit.
+I hope you will feel confortable in it.
+
+@subsection XaoS as translator
+
+You should be able to open XaoS files in graphics applications
+such as ShowImage or ArtPaing. In Preferences you can find the DataTranslations
+program, that can be used to set the size, type and DPI of the resulting image.
+Also antialiasing can be enabled.
+
+Note that @emph{translation can take a while}. So be patient and
+wait for the result.
+
+If the translator doesn't work, ensure that you have a link to the XaoS executable
+in @code{/boot/beos/system/add-ons/Translators/}.
+
+@c ## section BeOS ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node DGA, dos , BeOS ,drivers
+
+@section DGA driver
+This is the driver for DGA (Direct Graphics Architecture) extension used by
+XFree86 X servers. It is pretty new so it could be buggy.
+
+Bugs/limitations:
+
+@table @strong
+@item In 8bpp mode, XaoS has problems with the palette with certain window managers
+I don't know why this happens. Just let me know what's wrong, or use another
+window manager.
+@item Banked modes are not supported.
+I don't have any card to test this with, so it doesn't work in the current version.
+@end table
+
+DGA driver was written by Jan Hubicka, 1999.
+
+
+@c ## section DGA ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node dos, dX-fullscreen , DGA ,drivers
+
+@section DOS driver
+This is a fully featured driver for DJGPP and allegro.
+It supports many VGA modes, VESA 1.0---3.0, VBE/AF, S3 and some other cards.
+
+The following problems may occur:
+
+@table @strong
+@item Some DPMI servers may cause problems
+Some DPMI servers like the one from Novell/Dr/Open DOS are buggy. Use clean DOS
+instead and XaoS will automatically start @code{cwsdpmi}.
+Under Open Dr DOS use @code{dpmi off} at command line to disable it.
+@item Higher resolutions don't work
+If your videocard has enough memory for the selected resolution,
+you most probably have an unsupported videocard.
+Please use a VESA BIOS extension on this videocard. (See the note about VESA
+at the end of this section.)
+@item XaoS needs a coprocessor
+I don't distribute a coprocessor library linked into XaoS because it is too slow for
+a real-time zoomer. Coprocessor emulation will not help, because xaos works in protected mode.
+@item XaoS needs mouse driver to be usable
+@item XaoS works slowly in higher resolution
+This could also be caused by Allegro's slow driver or your videocard's VESA BIOS.
+You could try some other VESA BIOS extension instead.
+Look at the @code{http://www.talula.demon.co.uk} for the FreeBE
+project or Scitech Display Doctor package.
+(See the note about VESA at the end of this section.)
+@end table
+@subsection VESA
+VESA is a standard for using higher resolutions in DOS. Many videocards have
+VESA support in the BIOS so you don't need any additional software, while others
+need support from a special program. Also some VESA BIOS implementations are
+buggy or suboptimal; there are 3 different versions, version 1.0 is many times
+slower than 2.0, which has support for protected mode and linear framebuffers.
+So if you have problems with higher resolutions, or some graphics modes are
+not available (like 320x200 truecolor), you might try some software package
+which emulates VESA.
+
+The most famous VESA emulating program is Scitech Display Doctor. It has support
+for many videocards and is quite reliable. It's disadvantage is that it is
+shareware and works for only 30 days. You might also look on
+@code{ftp.simtel.net}, where there are many VESA emulation packages such as
+@code{s3vbe} or the new FreeBe project at
+@code{http://www.talula.demon.co.uk}
+
+DOS driver was written by Jan Hubicka, 1997.
+
+@c ## section dos ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node dX-fullscreen, dX-window , dos ,drivers
+
+@section DirectX fullscreen driver
+This is da river for Windows 9x and NT. It is new since version 3.1 and
+because of some oddities of Windows API and kludges in DirectX
+it may be rather unstable. Please report all bugs. In case
+of problems you could use the DOS version of XaoS instead.
+
+This driver allows the Windows port of XaoS to run in full screen mode.
+The driver supports 256, 65536 and 16777216 color modes (24bpp and 32bpp)
+in all resolutions supported by DirectX.
+You can change graphics mode by pressing the @code{=} key
+(or by using the UI/Resize menu). If the selected mode is not supported,
+the driver will restore the previous setting.
+
+Use the @code{-mode WIDTHxHEIGHTxDEPTH} (like @code{-mode 640x480x16})
+command line option to change graphics mode.
+
+If you want to start XaoS in DirectX, use the @code{-driver dX-fullscreen}
+option.
+
+See the Win32 driver documentation for some more Windows
+releated information.
+
+DirectX driver was written by Jan Hubicka, Jan Olderdissen
+and Pavel Tzekov, 1999.
+
+@c ## section dX-fullscreen ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node dX-window, ggi , dX-fullscreen ,drivers
+@c ## section DX-window ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node ggi, plan9, dX-window ,drivers
+
+@section GGI driver
+
+GGI stands for General Graphics Interface. Part of this project is to develop
+libggi, a portable graphics library, and XaoS's GGI driver uses that.
+It is experimental, since the API of libggi is not stabilized yet.
+There are some problems with keyboard handling---the shift key doesn't work
+yet.
+
+Everything else might work well, but there are no guarantees. It is alpha quality
+software.
+
+GGI driver was written by Jan Hubicka, 1998.
+
+@c ## section ggi ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node plan9, SVGAlib, ggi ,drivers
+
+@section Plan9 driver
+
+Plan9 is a very nice small operating system by the authors of Unix at Bell Labs.
+It is very incompatible with other operating systems; even the C compiler and
+header files are different, but XaoS should work well there (even on the
+limited free demo installation without any POSIX compatibility stuff)
+
+There are a few limitations: the file selector and image saving don't work.
+You can save position files and then later render them on the other OS, or save
+screenshots.
+
+Plan9 terminals also don't provide any way to catch the arrow keys, so you
+can't use them. Use the mouse to navigate in the menus. Also, getting the screen
+resolution is impossible, so use @code{-pixelwidth} and @code{-pixelheight}
+instead of @code{-screenwidth} and @code{-screenheight}.
+
+By default XaoS changes the colormap. This will collide with other colorful
+programs like Mortha. You can disable this behavior using
+@code{-nopalette} switch, but this will slow down XaoS.
+
+Plan9 driver was written by Jan Hubicka, 1997.
+
+@c ## section plan9 ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node SVGAlib, win32, plan9 ,drivers
+
+@section SVGAlib driver
+
+This is a driver for Linux SVGAlib. I really like this driver, because
+I much prefer full screen zooming instead of a small 320x320 window in X11.
+It was one of the first drivers for XaoS and is fully featured.
+The following problems can occur:
+
+@table @strong
+@item XaoS doesn't initialize graphics mode
+when started under users other than root SVGAlib requires root privileges
+to directly access the hardware. When you really want to start XaoS as a
+normal user, enable the suid bit (@code{chmod +s}) at XaoS executable.
+note that I take care to disable all security holes caused by this
+bit so I believe it is safe.
+@item Mouse doesn't work
+@item Screen is blank at higher resolutions
+Both this problems are probably caused by misconfiguration of
+SVGAlib. Please configure it in @code{etc/vga/libvga.cong} or
+@code{/usr/local/lib/libvga.conf}
+GPM can also cause problems. Try to kill it before starting XaoS.
+@item When I switch console I can't switch back
+This is another typical SVGAlib bug. Try to hold @code{F} key longer than @code{alt}.
+It helps on my computer. On older SVGAlib there was a famous ``enter bug'' that caused
+a crash after pressing enter. Try to update to a newer release.
+@end table
+
+SVGAlib driver was written by Jan Hubicka, 1997.
+
+@c ## section SVGAlib ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node win32, X11, SVGAlib ,drivers
+
+@section Win32 driver
+
+This is a driver for Windows 9x and NT. It is new since version 3.1 and
+because of some oddities of Windows API it may be rather unstable.
+Please report all bugs. In case of problems you could use the DOS version
+of XaoS instead.
+
+The driver should work in all bit depths, but 16 color mode is not natively
+supported by the XaoS engine. XaoS internally works in 32k colors and
+the result is converted to 16 colors by Windows. Because Windows
+conversion routines are slow and ugly, the result is slow and ugly.
+Please configure your display to another bit depth to ``solve''
+this problem.
+
+Use @code{-size WIDTHxHEIGHT} command line option to change the default
+window size.
+
+This driver also maps to native Windows look and feel. There is a small
+problem with combo boxes in dialogs. They are expected to give you a choice
+between a few strings. The keyboard controls (changing choice by arrow keys)
+work, but mouse selection is broken. If you know how to solve this bug,
+please let me know.
+
+XaoS is a UNIX application and has many command line options.
+Some features are not available from the GUI.
+Because Windows applications can't have normal output,
+most of the critical messages are displayed in message boxes, but
+some longer messages are omitted. The most significant omission is the help
+about command line options that you can find in @code{doc/cmdopts.txt}.
+
+One thing that might be confusing is that animation rendering mode doesn't
+display anything, but only renders images. Start the rendering,
+and a message box will inform you that XaoS is entering the calculation
+loop. Relax and wait for the message box signaling the end of the loop.
+
+Note that XaoS also supports the DirectX API.
+
+Win32 driver was written by Jan Hubicka, Jan Olderdissen and Pavel Tzekov, 1999.
+
+
+@c ## section win32 ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node X11, , win32 ,drivers
+
+@section X11 driver
+This was the first driver done for XaoS. It supports many visuals, shared
+colormaps and MitSHM extension.
+
+Bugs/limitations:
+
+@table @strong
+@item XaoS makes some X servers too busy
+Sometimes XaoS generates images faster than X can display them.
+In this case XaoS responds poorly to the mouse, and other applications slow
+down too. This happens especially often on old R4 servers. Use @code{-sync}
+to avoid this problem. Note that @code{-sync} does @code{not} make all
+communication with X asynchronous; it just adds one additional XSync call.
+So the slowdown is not as large as you might expect.
+@item Does not work on all visuals
+This driver supports only 8bpp pseudocolor/grayscales, 15,16,24 and 32bpp truecolor, 1bpp and 8bpp staticolor visuals.
+@item Palette rotating does not work for 8bpp pseudocolor w/o private palette
+@end table
+
+X11 driver was written by Jan Hubicka and Thomas Marsh, 1997.
+
+@c ## section X11 ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node menus, about,  drivers,Top
+
+@appendix Menus, functions and command line parameters
+All XaoS functions are referenced by a central function registry. The
+scripting language, menus, dialogs and command line options are built
+from this database. This section contains information about all functions
+available in this registry.
+@menu 
+* root::	Root menu
+* animroot::	Animation root menu
+* plc::	Replay only commands
+
+* linemenu::	Line drawing functions
+* animf::	Animation functions
+* time::	Timing functions
+* file::	File
+* edit::	Edit
+* fractal::	Fractal
+* calc::	Calculation
+* mfilter::	Filters
+* ui::	UI
+* misc::	Misc
+* helpmenu::	Help
+* xtextpos::	Horizontal text position
+* ytextpos::	Vertical text position
+* mformula::	Formulae
+* palettemenu::	Palette
+@end menu 
+@node root,  animroot,  ,  menus
+
+
+
+@node animroot,  plc,  root,  menus
+
+
+
+@appendixsec Animation root menu
+This menu is displayed at the top of the screen when animation replay is active.
+@menu 
+* file::	File
+* stopreplay::	Stop replay
+* helpmenu::	Help
+* ui::	UI
+@end menu 
+@node stopreplay,  ,  ,  animroot
+
+
+@appendixsubsec Stop replay
+Terminate animation replay.
+
+@emph{Available as}: menu item
+
+
+
+@node plc,  linemenu,  animroot,  menus
+
+
+@appendixsec Replay only commands
+Some commands, such as timing primitives or animation functions, are available
+only in animation files.
+@menu 
+* linemenu::	Line drawing functions
+* animf::	Animation functions
+* time::	Timing functions
+* load::	Include file
+@end menu 
+@node load,  ,  ,  plc
+
+
+
+
+@appendixsubsec Include file
+@defun load file 
+@end defun
+
+This function lets you include another file in your script. It works similarly
+to @code{#include} in C or @code{load} in Scheme.
+The file is searched for in the same directory as the current source file.
+
+@emph{Available as}: command
+
+@node linemenu,  animf,  plc,  menus
+
+
+
+@appendixsec Line drawing functions
+XaoS has support for drawing lines. These functions are available only in
+animations and could be used to show some parts of fractals or draw simple
+diagrams. See the tutorial ``Introduction to fractals''
+for examples of this feature.
+
+Lines can be drawn in @emph{screen} coordinates, where 0,0
+is the top left corner and 1,1 is bottom right, @emph{scaled}
+coordinates, which are similar, but scaled to keep 0,0---1,1 rectangular,
+or @emph{Fractal} coordinates, to draw a line at an exact position
+on the screen.
+
+The color of the line should be specified by the @code{color} command.
+You might draw an arbitrary number of lines and, later, morph them. Each line is
+identified by a unique numeric key; the current key can be set using @code{linekey}.
+Commands for changing lines operate on the line with the current key.
+(Lines drawn in sequence have consecutive numbers.)
+
+For example:
+
+
+@example
+(color 'red)
+(line 'scaled 0.3 0.5 0.7 0.5)
+(line 'scaled 0.3 0.5 0.7 0.5)
+(line 'scaled 0.3 0.5 0.3 0.5)
+(line 'scaled 0.7 0.5 0.7 0.5)
+(linekey 0)
+(morphline 'scaled 0.3 0.3 0.7 0.3)
+(morphline 'scaled 0.3 0.7 0.7 0.7)
+(morphline 'scaled 0.3 0.3 0.3 0.7)
+(morphline 'scaled 0.7 0.3 0.7 0.7)
+(usleep 1000000)
+@end example
+
+
+Creates line morphing to rectangle.
+
+
+
+
+@defun line keyword complex complex 
+@end defun
+
+Draw line between two points.
+@code{keyword} specifies type of coordinates and should be one of the
+following: @code{`fractal}, @code{`screen} or @code{`scaled}.
+This function also increases the line key.
+
+@emph{Available as}: command
+
+
+
+
+
+@defun morphline keyword complex complex 
+@end defun
+
+Morph current line to given coordinates.
+@code{keyword} specifies type of coordinates and should be one of the
+following: @code{`fractal}, @code{`screen} or @code{`scaled}.
+The line will start moving at the next timing command, and reach the
+final position before the end of it.
+This function also increases the line key.
+
+@emph{Available as}: command
+
+
+
+
+
+@defun morphlastline keyword complex complex 
+@end defun
+
+This function has the same functionality as morphline, but it doesn't
+increase the line key, and touches the line with the previous key. This is useful when
+you want to move a just-drawn line---you don't need to set linekey back.
+
+@emph{Available as}: command
+
+
+
+@defun linekey integer 
+@end defun
+
+Set current line key.
+
+@emph{Available as}: command
+
+
+
+@defun clearline 
+@end defun
+
+Clear current line. This function also increases the line key.
+
+@emph{Available as}: command
+
+@defun clearlines 
+@end defun
+
+Clear all displayed lines. Lines can also be cleared using the
+@code{clearscreen} or @code{display} commands available from the Misc menu. @xref{misc}.
+
+@emph{Available as}: command
+
+@node animf,  time,  linemenu,  menus
+
+
+
+@appendixsec Animation functions
+These functions are used to animate fractal state---to zoom, unzoom and morph
+various parameters. They should be used only in animation files.
+Animations are usually performed for a time selected by an immediately following
+timing function. @xref{time}.
+For example:
+
+
+@example
+(view 0 0 1 1)
+(morphview 0 0 2 2)
+(usleep 5000000)
+@end example
+
+
+Will do a 5 second long unzooming animation.
+@menu 
+* animateview::	Animate view
+* smoothmorph::	Smooth morphing
+* morphview::	Morph view
+* morphjulia::	Morph julia
+* moveview::	Move view
+* morphangle::	Morph angle
+* zoom::	Zooming functions
+@end menu 
+@node animateview,  smoothmorph,  ,  animf
+
+
+@appendixsubsec Animate view
+@defun animateview float float float float 
+@end defun
+
+This function is almost identical to function @code{view}. @xref{uiview}.
+It expects that the view will be changed only slightly, so recalculation is done
+with @code{ANIMATE} priority. This means that dynamic resolution is used by
+default.
+
+Viewport is selected by the center and two radiuses (real and imaginary). See
+@code{view} for more information.
+
+@emph{Available as}: command
+
+@node smoothmorph,  morphview,  animateview,  animf
+
+
+@appendixsubsec Smooth Morphing
+@defun morphview keystring starttime endtime 
+@end defun
+This function lets you smoothly start and stop morphing. Specify
+starttime and stoptime as nonzero, and morphing will speed up and slow down for
+that number of usecs.
+
+The keystring is used to select what morphing you want to control. It is one of
+the following:
+@table @strong
+@item 'view
+control morphview
+@item 'angle
+control morphangle
+@item 'julia
+control morphjulia
+@item 'line
+control morphline
+@end table
+@node morphview,  morphjulia,  smoothmorph,  animf
+
+
+@appendixsubsec Morph view
+@defun morphview float float float float 
+@end defun
+For the time selected by the next @code{usleep} or other timing function, the viewpoint is smoothly morphed from
+the current one to that selected by @code{morphview}.
+
+Viewport is selected by the center and two radiuses (real and imaginary). See
+@code{view} for more information.
+
+This function can easily be used for creating zooming/unzooming animations using position files.
+This is an example position file generated by XaoS:
+
+
+@example
+(initstate)
+(defaultpalette 0)
+(formula 'mandel)
+(view -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+9.69332308834E-08)
+@end example
+
+
+By replacing the @code{view} command with @code{morphview} and
+adding @code{usleep} you can create a zooming animation:
+
+
+@example
+(initstate)
+(defaultpalette 0)
+(formula 'mandel)
+(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+9.69332308834E-08)
+(usleep 10000000)
+@end example
+
+
+
+
+@emph{Available as}: command
+
+@node morphjulia,  moveview,  morphview,  animf
+
+
+@appendixsubsec Morph Julia
+@defun morphjulia complex 
+@end defun
+For the time selected by the next @code{usleep} or other timing function, the Julia seed
+is smoothly interpolated from the current one to that selected by @code{morphjulia}. By default this will
+cause recalculation of the whole screen.
+To avoid this, use fast Julia mode. @xref{fastjulia}.
+
+A simple animation morphing Julia seed in the X axis:
+
+
+@example
+(initstate)
+(fastjulia #t)
+(juliaseed -2 0)
+(morphjulia 2 0)
+(usleep 2000000)
+@end example
+
+
+
+@emph{Available as}: command
+
+@node moveview,  morphangle,  morphjulia,  animf
+
+
+@appendixsubsec Move view
+@defun moveview complex 
+@end defun
+Smoothly move the image center to another position.
+
+@emph{Available as}: command
+
+@node morphangle,  zoom,  moveview,  animf
+
+
+@appendixsubsec Morph angle
+@defun morphangle float 
+@end defun
+Smoothly rotate the image to another angle. By default rotation causes
+recalculation of the whole screen. To avoid this you need to enable
+fast rotate mode. @xref{rotate}. Don't forget to disable it later, since
+it slows down other animations.
+
+
+A simple ``rotozooming'' animation:
+
+
+@example
+(initstate)
+(fastrotate #t)
+(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08
+9.69332308834E-08)
+(morphangle 300)
+(usleep 10000000)
+(wait)
+(fastrotate #f)
+@end example
+
+
+@emph{Available as}: command
+
+@node zoom,  ,  morphangle,  animf
+
+
+@appendixsubsec Zooming functions
+
+The functions for zooming/unzooming were created mainly for recording
+animations. In manually created animation files, it is easier to use
+@code{morphview}. @xref{morphview}.
+
+@defun zoomcenter complex 
+@end defun
+This function sets the center to zoom in on. The center is given as a position
+in fractal coordinates.
+
+@emph{Available as}: command
+@defun zoom 
+@end defun
+Start zooming to the area specified by @code{zoomcenter}.
+
+The speed of zooming should be controlled by the function @code{speed}
+or in a more exact way by @code{maxstep} and @code{speedup}.
+
+@defun unzoom 
+@end defun
+
+Start unzooming from the area specified by @code{zoomcenter}.
+
+@emph{Available as}: command
+@defun stop 
+@end defun
+Stop zooming or unzooming.
+
+@emph{Available as}: command
+
+@node time,  file,  animf,  menus
+
+
+
+@appendixsec Timing functions
+Timing functions are used to control the animation replay daemon. It can wait
+for a given time, or wait until calculation is complete. The animation functions
+are controlled by such waiting; animations that are running while delays start
+keep running through the delay.
+@menu 
+* usleep::	Usleep
+* textsleep::	Wait for text
+* wait::	Wait for complete image
+@end menu 
+@node usleep,  textsleep,  ,  time
+
+
+@appendixsubsec Usleep
+@defun usleep integer 
+@end defun
+
+This function waits for a given amount of time (in usec) before processing
+the next command. The screen is recalculated and displayed at the beginning of
+usleep if necessary necessary. The remaining time is spent in waiting or
+performing animation.
+
+@emph{Available as}: command
+
+@node textsleep,  wait,  usleep,  time
+
+
+@appendixsubsec Wait for text
+@defun textsleep 
+@end defun
+
+
+This function's behavior is very similar to @code{usleep},
+but the time is calculated from the number of letters currently displayed
+onscreen. If you want to wait just long enough for the user to read the subtitle,
+use this function. The user can alter the replay speed as desired using
+@code{letterspersec}. @xref{letterspersec}. This value can be changed during
+replay with the arrow keys.
+
+@emph{Available as}: command
+
+@node wait,  ,  textsleep,  time
+
+
+@appendixsubsec Wait for complete image
+@defun wait 
+@end defun
+
+Wait until the image is complete. You should always use this function after
+zooming or unzooming when dynamic resolution is in use. This ensures that
+the image calculation will be complete so the user can see the result before
+the animation continues. It may also be useful in combination with filters like
+motion blur. @xref{blur}.
+
+This function deadlocks if used with animation functions; don't
+do that.
+
+@emph{Available as}: command
+
+@node file,  edit,  time,  menus
+
+
+
+@appendixsec File
+@menu 
+* loadpos::	Load
+* savepos::	Save
+* record::	Record
+* play::	Replay
+* saveimg::	Save image
+* loadexample::	Load random example
+* savecfg::	Save configuration
+* quit::	Quit
+@end menu 
+@node loadpos,  savepos,  ,  file
+
+
+@appendixsubsec Load XaoS position file
+
+Load a XaoS position file (@code{*.xpf}).
+See the format description for more information.
+
+@emph{Available as}: menu item, command line option
+
+@node savepos,  record,  loadpos,  file
+
+
+@appendixsubsec Save XaoS position file
+@defun savepos file 
+@end defun
+
+Save current state to a XaoS position file (@code{*.xpf}). This file is
+human-readable, and can easily be improved by hand after saving, or used as
+a base for animations.
+See the format description for more information.
+
+@emph{Available as}: menu item, command line option, command
+
+@node record,  play,  savepos,  file
+
+
+@appendixsubsec Record animation
+@defun record bool [ file ] 
+@end defun
+
+
+e
+Toggle recording to a XaoS animation file (@code{*.xaf}). This file is
+human-readable, and can easily be improved by hand after recording.
+See the format description for more information.
+
+From the scripting language, @code{(record #t)} enables recording, and
+@code{(record #f)} disables it.
+
+@emph{Available as}: menu item, command line option, command
+
+@node play,  saveimg,  record,  file
+
+
+@appendixsubsec Replay animation
+
+Replay a XaoS animation file (@code{.xaf}).
+
+@emph{Available as}: menu item, command line option
+
+@node saveimg,  loadexample,  play,  file
+
+
+@appendixsubsec Save image
+@defun saveimg file 
+@end defun
+
+Save current state to an image file. This file is in @code{.png} (portable
+network graphics) format, which can be read by many applications varying from
+graphics programs all the way to Web browsers.
+
+This function needs an external library called @code{libpng}. If the library
+wasn't available during compilation, this function is unavailable too.
+Please see @code{INSTALL} for more information about obtaining libpng
+and recompiling XaoS.
+
+@emph{Available as}: menu item, command line option, command
+
+@node loadexample,  savecfg,  saveimg,  file
+
+
+@appendixsubsec Load random example
+@defun loadexample 
+@end defun
+
+Choose random @code{.xpf} file from the @code{examples} directory and
+load it.
+You might use it as the starting point for next exploration.
+
+@emph{Available as}: menu item, command line option, command
+
+@node savecfg,  quit,  loadexample,  file
+
+
+@appendixsubsec Save configuration
+@defun savecfg 
+@end defun
+
+Save current configuration to @code{~/.xaosrc} (under Unix) or @code{xaos.cfg}
+(under DOS and Windows). XaoS automatically reloads the configuration from this
+file when it starts.
+
+@emph{Available as}: menu item, command line option, command
+
+@node quit,  ,  savecfg, file
+
+
+@appendixsubsec Quit
+@defun quit 
+@end defun
+
+Quit XaoS.
+
+@emph{Available as}: menu item, command line option, command
+
+@node edit,  fractal,  file,  menus
+
+
+@appendixsec Edit
+A fairly ordinary Edit menu.
+@menu 
+* undo::	Undo
+* redo::	Redo
+* copy::	Copy
+* paste::	Paste
+@end menu 
+@node undo,  redo,  ,  edit
+
+
+@appendixsubsec Undo
+Undo last operation. `Last operation' is quite hard to define in
+XaoS (where changes are continuous), so it might be surprising.
+I hope it will do what you want.
+
+@emph{Available as}: menu item
+@node redo,  copy,  undo,  edit
+
+
+@appendixsubsec Redo
+Redo last undone operation. See undo. @xref{undo}.
+
+@emph{Available as}: menu item
+@node copy,  paste,  redo,  edit
+
+
+@appendixsubsec Copy
+Copy fractal to clipboard. This is a platform-dependent operation that may
+not have an analogue on your platform (e.g. there is no concept of a clipboard
+under aalib).
+
+@emph{Available as}: menu item
+@node paste,  ,  copy,  edit
+
+
+@appendixsubsec Paste
+Paste fractal from clipboard. This is a platform-dependent operation that may
+not have an analogue on your platform (e.g. there is no concept of a clipboard
+under aalib).
+
+@emph{Available as}: menu item
+
+@node fractal,  calc,  edit,  menus
+
+
+@appendixsec Fractal
+This menu contains all functions related to fractal parameters and display;
+you can change things like the formula used, coloring modes, seeds and much
+else.
+
+@menu 
+* formula::	Formula
+* mformula::	formulae
+* incoloring::	Incoloring mode
+* outcoloring::	Outcoloring mode
+* plane::	Plane
+* palettemenu::	Palette
+* uimandelbrot::	Mandelbrot mode
+* uiperturbation::	Perturbation
+* uiview::	View
+* initstate::	Reset to defaults
+* tcolor::	True-color coloring modes
+@end menu 
+@node formula,  uimandelbrot,  ,  fractal
+
+
+@appendixsubsec Formula
+@defun formula keyword 
+@end defun
+
+Set the current fractal formula. @code{keyword} should be one of the
+following:
+@table @strong
+@item 'mandel
+Standard Mandelbrot set. @xref{mandel}.
+@item 'mandel3
+Mandelbrot set, power 3. @xref{mandel3}.
+@item 'mandel4
+Mandelbrot set, power 4.
+@item 'mandel5
+Mandelbrot set, power 5.
+@item 'mandel6
+Mandelbrot set, power 6.
+@item 'newton
+Newton's approximation method. @xref{newton}.
+@item 'barnsley
+First Barnsley's formula. @xref{barnsley}.
+@item 'octo
+Fractint's octo. @xref{octal}.
+@item 'phoenix
+Phoenix. @xref{phoenix}.
+@item 'magnet
+Magnet. @xref{magnet}.
+@end table
+
+@emph{Available as}: command
+
+@node uimandelbrot,  uiperturbation,  formula,  fractal
+
+
+@appendixsubsec Mandelbrot/Julia mode
+
+Most fractals rendered by XaoS can be represented as Mandelbrot sets or Julias.
+Each point in the Mandelbrot set has its own Julia set. To learn more about
+this correspondence, see the tutorial on the Julia set.
+
+This function switches between Mandelbrot and Julia representations. When
+switching to Julia, you need to set the seed---a point selected from the
+Mandelbrot set.
+
+If you run this function from the menu, you are prompted for the Julia seed
+as a number. Often, this can be clumsy, and it would be easier to specify a
+point with the mouse pointer. If you hit the @code{M} key instead of
+using the menu, the current mouse position is used.
+
+Good seedpoints lie at the boundaries of the Mandelbrot set; other seeds
+usually generate quite a boring fractal. You can also explore various seeds
+at high speed using the Fast Julia mode. @xref{fastjulia}.
+
+Not all fractals have Julias, but XaoS can generate fake Julia sets for
+those that do not, which use some Julia-like modification of the formula;
+so this function is currently usable for all fractal types.
+
+@emph{Available as}: menu item
+@defun julia bool 
+@end defun
+
+This function is used to enable/disable julia mode in animation files.
+
+@emph{Available as}: command line option, command
+@defun juliaseed complex 
+@end defun
+
+Select the current julia seed.
+
+@emph{Available as}: command line option, command
+
+@node uiperturbation,  uiview,  uimandelbrot,  fractal
+
+
+@appendixsubsec Perturbation
+
+Perturbation is a simple trick which changes the point at which orbits start.
+Traditionally zero is used, but other values can generate interesting
+results too.
+
+On enabling this function from the menu, you will be asked for a complex
+number specifying the perturbation. It is a toggle; selecting it again
+resets the perturbation to zero without prompting.
+
+It can be used to specify a complex number representing a point on the screen.
+If you hit the @code{B} key instead of using the menu, the current mouse
+position is used. This too is a toggle, so @code{B} again will disable
+perturbation by setting it to zero.
+
+This function only has an effect for certain formulae (like the
+Mandelbrot set</a>) and only then in <a uimandelbrot>Mandelbrot mode. @xref{mandel}.
+
+@emph{Available as}: menu item
+@defun perturbation complex 
+@end defun
+
+This is the scripting-language variation of the perturbation function. Instead
+of toggling, you always specify the perturbation to use. Use 0 0 to disable
+perturbation.
+
+@emph{Available as}: command line option, command
+
+@node bailout,  fastjulia,  maxiter,  calc
+
+
+@appendixsubsec Bailout
+
+Bailout is the value which is checked for each point of
+the orbit if the point is far enough
+from the complex zero point in the current iteration.
+If the point is far enough, then the iteration immediately
+stops and the starting point on the screen will be
+painted with a given colour, depending on the fractal
+type and many other settings.
+
+For the Mandelbrot set
+this value is 4. Other fractal types usually
+have the same bailout value. For most fractals many bailout values
+give more or less similar output. E.g., for the second order
+Mandelbrot set one can prove that the sequence |z| (z:=z^2+c) tends to
+infinity if and only if |z|>2 for some element z of this sequence.
+In XaoS program, Bailout value is the square of this 2, i.e. you can change this
+to any value greater than 2 for similar results.
+
+Other fractal types may use other bailout values. The default
+is 4 for each types.
+
+@emph{Available as}: menu item, command line option, command
+@defun bailout float 
+@end defun
+
+
+@node uiview,  initstate,  uiperturbation,  fractal
+
+
+@appendixsubsec View
+
+Set your current viewpoint in the fractal. This function is useful when you have
+found some interesting coordinates somewhere (on a web page, perhaps) and you
+want to see that position in XaoS.
+
+In the dialog you will be asked for the @emph{center}, @emph{radius}
+and @emph{angle} of the image.
+
+The center specifies the point which is displayed at the center of the screen.
+The radius is the radius of a circle around this point; XaoS will size the image
+so that this circle only just fits on the screen. The angle gives the rotation of
+the image in degrees.
+
+People specify fractal coordinates in many ways. Some people use the coordinates
+of the upper-left and lower-right visible points, specifying the coordinates as four
+numbers @math{x1}, @math{y1}, @math{x2}, @math{y2}.
+To set the same viewpoint in XaoS, set the real portion of the center to
+@math{(x1+x2)/2}, the imaginary part of center to @math{(y1+y2)/2}, and
+the radius to the greater of @math{x2-x1} and @math{y2-y1}.
+
+Other programs use a zoom factor instead of a radius. For these, you can set the
+radius to @math{2/zoom}.
+
+@emph{Available as}: menu item
+@defun view float float float float 
+@end defun
+
+This function is used to set the visible area of fractal in animation files.
+It doesn't let let you specify the angle, (for that, see the separate function
+@code{angle}), but lets you specify an ellipse instead of a circle. You can
+specify both a real and an imaginary radius, so you have better control over the
+area that will be visible. XaoS will size the image so that the ellipse only just
+fits on the screen.
+
+@emph{Available as}: command line option, command
+@defun angle float 
+@end defun
+
+Set the rotation angle in degrees. By default this causes recalculation of the
+screen. You can enable the fast rotation mode, which lets you
+rotate the screen without recalculation; but it slows down other things, so
+don't forget to disable it later.
+
+@emph{Available as}: command line option, command
+
+@node initstate,  plane,  uiview,  fractal
+
+
+@appendixsubsec Reset to defaults
+@defun initstate 
+@end defun
+
+This function resets most of XaoS's values to their defaults. It is useful when
+you get lost and want to start from the beginning. It should also be used
+as the first command of every animation file, to ensure that the file is always
+played with the same settings in effect.
+
+@emph{Available as}: menu item, command line option, command
+
+@node plane,  incoloring,  initstate,  fractal
+
+
+@appendixsubsec Plane
+@defun plane integer 
+@end defun
+
+All fractals displayed by XaoS are functions with a complex parameter.
+They can be be displayed in the normal complex plane where the @code{x}
+coordinate is the real part of the number and the @code{y} is imaginary;
+but they can also be displayed differently:
+@table @strong
+@item @math{mu}
+Normal complex plane (default)
+@item @math{1/mu}
+Inversion---infinity is at 0 and
+0 is at infinity.
+@item @math{1/(mu+0.25)}
+Similar to inversion, but moves
+the center outside the Mandelbrot set,
+so it looks parabolic.
+@item @math{lambda plane}, @math{1/lambda}, @math{1/lambda-1}
+Lambda plane and its inversion, and with a different center.
+@item @math{1/(mu-1.40115)}
+A very interesting mode for the
+Mandelbrot set, this makes small
+things large, for easier browsing
+of the set's details.
+@end table
+The tutorial about planes has some examples.
+
+
+
+In the scripting language, the planes are numbered as follows:
+
+@table @strong
+@item 0
+@math{mu}
+@item 1
+@math{1/mu}
+@item 2
+@math{1/(mu+0.25)}
+@item 3
+@math{lambda}
+@item 4
+@math{1/lambda}
+@item 5
+@math{1/(lambda-1)}
+@item 6
+@math{1/(mu-1.40115)}
+@end table
+
+@emph{Available as}: command line option, command
+
+@node incoloring,  outcoloring,  plane,  fractal
+
+
+@appendixsubsec Inside coloring mode
+@defun incoloring integer 
+@end defun
+
+Areas inside the set are usually filled in black, but this is only a convention;
+you could color them in differently to make the fractal look more interesting.
+The only method available to make areas inside the set visible is to display
+the value of the latest orbit as the value of each pixel.
+
+The tutorial on incoloring has more information and
+examples.
+
+XaoS has many different ways to show that value. The cryptic names of the modes
+are mathematical formulae, where @emph{real} means the real part of the
+latest orbit, and @emph{imag} means the imaginary part. @emph{zmag}
+uses the magnitude of the value. The @emph{Decomposition-like} method uses
+the angle of the orbit. Also, truecolor incoloring modes are available, that
+display one value in each of the red, blue and green color planes (or, for some
+modes, in each of the hue, saturation and value planes).
+
+In the scripting language, the incoloring mode is specified by one of the
+following integers:
+
+@table @strong
+@item 0
+@math{0} (default)
+@item 1
+@math{zmag}
+@item 2
+Decomposition-like
+@item 3
+@math{real/imag}
+@item 4
+@math{abs(abs(c)-abs(r))}
+@item 5
+@math{cos(mag)}
+@item 6
+@math{mag*cos(real^2)}
+@item 7
+@math{sin(real^2-imag^2)}
+@item 8
+@math{atan(real*imag*creal*cimag)}
+@item 9
+squares
+@item 10
+Truecolor. To set exact parameters for truecolor coloring use the
+@code{tcolor} command.
+@end table
+
+@emph{Available as}: command line option, command
+
+@node outcoloring,  tcolor,  incoloring,  fractal
+
+
+@appendixsubsec Outside coloring mode
+@defun outcoloring integer 
+@end defun
+
+Outcoloring modes are similar to incoloring modes, but indicate
+how to display the areas outside the set instead. As with incoloring modes, the
+value of the latest orbit can be used to determine the color of each pixel, but the
+default is to use the number of iterations needed for the value at that point to become
+recognisably divergent as the color.
+
+The tutorial on outcoloring has more information and
+examples.
+
+The cryptic names of the modes are mathematical formulae, where @emph{iter}
+means the number of iterations required for the value to become recognisably divergent,
+@emph{real} means the real part of the latest orbit, and @emph{imag}
+means the imaginary part. @emph{binary decomposition} uses a different color
+when the imaginary part of the orbit is lower than zero, and @emph{smooth}
+attempts to remove stripes and discontinuities. Also, truecolor outcoloring
+modes are available, that display one value in each of the red, blue and green color planes
+(or, for some modes, in each of the hue, saturation and value planes).
+
+In the scripting language, the outcoloring mode is specified by one of the following
+integers:
+
+@table @strong
+@item 0
+@math{iter} (default)
+@item 1
+@math{iter+real}
+@item 2
+@math{iter+imag}
+@item 3
+@math{iter+real/imag}
+@item 4
+@math{iter+real+imag+real/imag}
+@item 5
+binary decomposition
+@item 6
+biomorphs
+@item 7
+potential
+@item 8
+color decomposition
+@item 9
+smooth
+@item 10
+True-color outcoloring mode. To set exact parameters for truecolor coloring use @code{outtcoloring}. @xref{tcolor}.
+@end table
+
+@emph{Available as}: command line option, command
+
+@node tcolor,  ,  outcoloring,  fractal
+
+
+@appendixsubsec Truecolor coloring mode
+@defun intcoloring integer 
+@end defun
+@defun outtcoloring integer 
+@end defun
+
+Truecolor coloring modes are similar to incolor and
+outcolor coloring modes; but instead of using a palette,
+they directly calculate the red, green and blue components of the color.
+This lets you display more parameters at once, and produces interesting
+and often attractive results. On 8bpp displays you need to enable the
+palette emulator filter first to see anything, amd the quality
+won't be so good, as far fewer colors are available per parameter.
+
+The tutorial on truecolor coloring modes has more
+information and examples.
+
+The cryptic names of the modes are always three mathematical formulae (one for
+each color component), where @emph{real} means the real part of the latest
+orbit, and @emph{imag} means the imaginary part.
+
+To enable inside/outside truecolor coloring mode in the scripting language,
+set @code{incoloring}/@code{outcoloring} value to 10 (truecolor coloring
+mode) before (or after) calling @code{intcoloring} or @code{outtcoloring}.
+
+In the scripting language, the coloring mode is specified by one of the following
+integers:
+
+@table @strong
+@item 0
+black
+@item 1
+@math{re*im} @math{sin(re^2)} angle
+@item 2
+@math{sin(re)} @math{sin(im)} @math{sin(square)}
+@item 3
+hsv
+@item 4
+hsv2
+@item 5
+@math{cos(re^c)} @math{cos(im^2)} @math{cos(square)}
+@item 6
+@math{abs(re^2)} @math{abs(im^2)} @math{abs(square)}
+@item 7
+@math{re*im} @math{re*re} @math{im*im}
+@item 8
+@math{abs(im*cim)} @math{abs(re*cre)} @math{abs(re*cim)}
+@item 9
+@math{abs(re*im-csqr)} @math{abs(re^2-csqr)} @math{abs(im^2-csqr)}
+@end table
+
+@emph{Available as}: command line option, command
+
+@node calc,  mfilter,  fractal,  menus
+
+
+
+@appendixsec Calculation
+This menu contains functions that control calculation parameters such as
+the maximum iteration count and periodicity checking.
+@menu 
+* range::	Solid guessing
+* dynamic::	Dynamic resolution
+* periodicity::	Periodicity checking
+* maxiter::	Iterations
+* bailout::	Bailout
+* fastjulia::	Fast Julia mode
+* dynamic::	Dynamic resolution
+* rotate::	Rotation
+@end menu 
+@node range,  periodicity,  ,  calc
+
+
+@appendixsubsec Solid guessing range
+@defun range integer 
+@end defun
+
+XaoS has a solid guessing optimization: if all corners of a rectangle have
+the same color, it assumes that the whole rectangle is a solid colored block,
+and doesn't calculate points inside the rectangle. This optimization saves
+lots of calculation, but sometimes introduces errors. This value alters the
+maximum size of the rectangle that can be guessed at one time. The default
+value is 3; use 0 to disable the optimization.
+
+@emph{Available as}: command line option, command
+
+@node periodicity,  maxiter,  range,  calc
+
+
+@appendixsubsec Periodicity checking
+@defun periodicity bool 
+@end defun
+
+Periodicity checking is one way to speed up the calculation. Areas inside the
+set always need @code{maxiter} iterations to determine that
+the point is probably inside the set (while it is rare for areas outside to
+need anywhere near that much). Often the orbital trajectory falls into a
+periodic, repeating cycle; if that can be detected, the calculation can be
+stopped early, as there's no way that the orbit can ever leave the cycle
+again (hence it cannot diverge, hence the point must be inside the set).
+
+Implementating this method efficiently is quite problematic. It slows down
+the cases where cycles are not found, because cycle-checking is quite hard work
+and has to take place for all points, even those that don't become cyclic.
+Because of the inexactness of floating-point calculations, the cycles are
+never exact, so you need to use an error value. Higher error values mean that
+cycles will be detected sooner, while lower error values increase the
+exactness of the calculation. Higher values can introduce serious errors,
+especially at the front of the Mandelbrot set. XaoS detects this automatically
+and corrects for it in most cases, but sometimes it might be wrong. Also,
+other optimizations in XaoS (such as boundary tracing) don't give this method
+much of a chance to run, since areas inside the set are usually not
+calculated at all.
+
+That's why the advantages of this optimization are questionable. You should
+probably experiment with enabling and disabling it. Sometimes XaoS is faster
+with this enabled, sometimes when disabled. Also, this method works only
+when incoloring methods are disabled, and only for some
+fractal types (some fractal types, e.g. newton, don't have any concept of
+an area `inside the set' at all.)
+
+The tutorial chapter ``Escape time fractals'' has
+more information on fractal calculation in XaoS, and there is a lengthy
+section in the hacker's manual (@code{xaosdev.texinfo}) devoted to the
+subject.
+
+@emph{Available as}: menu item, command line option, command
+
+@node maxiter,  bailout,  periodicity,  calc
+
+
+@appendixsubsec Iterations
+@defun maxiter integer 
+@end defun
+
+When the fractal set is calculated, a orbital trajectory is examined for each
+point. If the orbit diverges to infinity, the point is outside the set.
+Otherwise, the point is inside the set. For exact calculations, you need to
+know the entire orbital trajectory, which is infinitely long for areas inside
+the set, so fractals cannot be calculated exactly. By default, XaoS calculates
+at most 170 positions (iterations) and then gives up; if the point is still
+inside the bail-out value, it guesses that the point is inside the set.
+
+When zoomed into a detailed area, especially one close to the set boundary,
+this value could become too low, and the fractal will become boring.
+You might try increasing this value if you want to get the image interesting
+again; but this necessarily slows down the calculation at the same time.
+
+The tutorial chapter ``Escape time fractals'' has
+more information on fractal calculation in XaoS, and there is a lengthy
+section in the hacker's manual (@code{xaosdev.texinfo}) devoted to the
+subject.
+
+@emph{Available as}: menu item, command line option, command
+
+@node fastjulia,  dynamic,  bailout,  calc
+
+
+@appendixsubsec Fast Julia mode
+@defun fastjulia bool 
+@end defun
+
+By default, changing the seed for the Julia set requires recalculation of the
+image (which is quite slow). It's a nice effect to change the seed smoothly and
+show the Julia set morphing as the seed changes. XaoS has a special algorithm
+which can calculate such morphings in realtime. It is very inexact, but it is
+good enough for a fast preview.
+
+If you want to select a good seedpoint, enable fast Julia mode and find a
+nice place by dragging with the first mouse button depressed; then change to
+the Julia mode to see the exact image.
+
+@emph{Available as}: menu item, command line option, command
+
+@node dynamic,  rotate,  fastjulia,  calc
+
+
+
+@appendixsec Dynamic resolution
+@defun fastmode keyword 
+@end defun
+
+XaoS performs many optimizations, but fairly often this is not enough. In order
+to keep a high framerate, XaoS automatically lowers the resolution of the image,
+increasing it when there is time for more calculation. This feature is enabled by
+default when animating, but you might also like to enable it for new images
+(which makes the image `come into focus' when it is recalculated from scratch for
+whatever reason), or disable it completely if you don't like it.
+
+In the scripting languge, the keyword should be one of the following:
+@table @strong
+@item @code{'never}
+Disable dynamic resolution
+@item @code{'animate}
+Use only for animations (default)
+@item @code{'new}
+Use also for new images
+@end table
+@node rotate,  ,  dynamic,  calc
+
+
+
+@appendixsec Image rotation
+
+XaoS has support for rotation of the image to any angle. By default, changing
+the angle requires recalculation of the whole screen, but when
+@emph{fast rotation mode} is enabled, the angle can be changed smoothly.
+In this mode XaoS calculates a larger non-rotated image and rotates it when
+needed, so it increases memory requirements and slows XaoS down; hence, it
+should be disabled when rotation is not being used.
+
+The user interface provides two rotation modes---@emph{rotate by
+mouse} which allows the angle to be changed by dragging with the first
+mouse button depressed, and @emph{continuous rotation mode}, where the image
+is rotated clockwise continuously, and the arrow keys can be used to change
+the rotiation speed.
+@defun fastrotate bool 
+@end defun
+
+This function is used to enable and disable fast rotation mode.
+@emph{Available as}: command line option, command
+@appendixsubsec Automatic rotation
+@defun autorotate bool 
+@end defun
+
+Use this function to enable continuous rotation. In the scripting language you
+can also use @code{morphangle} to get an outwardly similar
+but more controllable effect.
+@defun rotationspeed float 
+@end defun
+
+Specify the speed of continuous rotation, in degrees per second.
+Negative values are allowed and rotate anticlockwise.
+
+@emph{Available as}: menu item, command line option, command
+
+
+
+@node mfilter,  ui,  calc,  menus
+
+
+
+@appendixsec Filters
+Filters are a post-calculation effect applied to the resulting image. They
+can do things like motion blurring, edge detection, emulation of palettes
+or truecolor on displays that can't handle them, and such things. There is
+a tutorial chapter about them.
+
+@menu 
+* filter::	Filter command
+* edge::	Edge detection
+* edge2::	Edge detection2
+* starfield::	Starfield
+* stereogram::	Random dot stereogram
+* interlace::	Interlace filter
+* blur::	Motion blur
+* emboss::	Emboss
+* palettef::	Palette emulator
+* anti::	Antialiasing
+* truecolor::	Truecolor emulator
+@end menu 
+@node filter,  edge,  ,  mfilter
+
+
+@appendixsubsec Filter command
+@defun filter keyword bool 
+@end defun
+
+This command is used to enable or disable filters. @xref{mfilter}.
+The @emph{keyword} specifies the filter to change, and should be one of
+the following:
+
+@table @strong
+@item @code{'edge}
+Edge detection
+@item @code{'edge2}
+Edge detection2
+@item @code{'starfield}
+Starfield
+@item @code{'stereogram}
+Random dot stereogram
+@item @code{'interlace}
+Interlace filter
+@item @code{'blur}
+Motion blur
+@item @code{'emboss}
+Emboss
+@item @code{'palette}
+Palette emulator
+@item @code{'anti}
+Antialiasing
+@item @code{'truecolor}
+Truecolor
+@end table
+
+@emph{Available as}: command
+@node edge,  edge2,  filter,  mfilter
+
+
+@appendixsubsec Edge detection
+
+This filter is a standard edge detection algorithm; solid areas are filled
+in black. Some fractals look very interesting with this filter (and some
+areas of some fractals just look like noise). This version of the filter produces
+relatively wide lines, so is useful at higher resolutions. The filter
+edge detection2 makes thinner lines, for the low resolution modes.
+
+@emph{Available as}: menu item, command line option
+
+@node edge2,  starfield,  edge,  mfilter
+
+
+@appendixsubsec Edge detection2
+
+This filter is a standard edge detection algorithm; solid areas are filled
+in black. Some fractals look very interesting with this filter (and some
+areas of some fractals just look like noise). This version of the filter produces
+relatively tight lines, so is useful at lower resolutions. The filter
+edge detection makes thinner lines, for the high resolution modes.
+
+@emph{Available as}: menu item, command line option
+
+@node starfield,  stereogram,  edge2,  mfilter
+
+
+@appendixsubsec Starfield
+
+The starfield filter generates random stars whose density depends on the
+iteration count. Choose your favorite spiral fractal and enable this filter
+to get a Grand Design spiral galaxy :)
+
+@emph{Available as}: menu item, command line option
+
+@node stereogram,  interlace,  starfield,  mfilter
+
+
+@appendixsubsec Random dot stereogram
+
+Fractal images are good as a base for random dot stereograms. In
+case you don't know what these are, please point your browser to
+Google or another search engine and find some articles about such
+images, because learning to read such images takes some effort. They
+make it possible to generate three dimensional images on a normal monitor
+without any additional hardware, by exploiting bugs in the human brain
+(although you need two working eyes, and some people never learn to
+see them; they can simply ignore this feature).
+
+XaoS is able to generate these images in animations, so you may use
+all normal XaoS functions (except palette changing and palette rotation,
+which makes no sense applied to a stereogram). To make the animation yet
+more exciting, XaoS emulates ``falling'' into the set; while you zoom in,
+your distance from the set drops and drops---but you never hit it; when the
+set reaches the level of your monitor, the distance is changed again so
+you are far away.
+
+To make this work right, XaoS needs to know the @emph{exact size of your
+monitor}. Because most platforms have no way to determine this, you need to
+use @emph{command line options} to tune it. If it's not set or is wrong,
+the stereograms will probably be impossible to see (if your monitor is too
+big or resolution too low), or the images will seem to be shallow (if your
+monitor is too small or resolution too high).
+
+By default XaoS expects my 15" monitor (29.0cm x 21.5 cm). Another
+cause of problems is the virtual screen supported by some windowed
+environments (like some X servers) that makes a program think that the
+resolution is higher than it actually is, and you see only part of
+this extra-large screen.
+
+The worst thing you could possibly do is to run full-screen XaoS in some
+graphical windowing system (OS/2 on top of Windows or Wine on top of Linux,
+perhaps) where XaoS can't tell the real size of its window at all. In such
+cases, it's normally better (not to mention faster) to run XaoS natively,
+rather than under such an emulation layer.
+
+The following command line options are provided to specify sizes:
+
+@table @strong
+@item @code{-screenwidth}, @code{-screenheight}
+Lets you specify the size of your screen in centimeters. Note that
+you need to specify the size of the visible image on the monitor, not
+the size with edge borders, or the size of the tube. The simplistic
+`my monitor is 17", just turn 17" into centimeters' doesn't work;
+that 17" is a marketing figure and has only a vague connection to
+reality. Get out a ruler and measure it.
+
+@item @code{-pixelwidth}, @code{-pixelheight}
+Lets you specify the exact size of a single pixel, if XaoS cannot
+determine this for itself from your screen size.
+@end table
+
+These options are used by some other parts of XaoS as well, so you should
+use them even when you don't want to see stereograms. You should probably
+write a small starting script (or alias, or shortcut; whatever your environment
+uses) that passes the correct parameters to XaoS.
+
+If the window is @emph{smaller than 8cm in any direction}, you will probably be
+unable to see anything; make the window bigger.
+
+The correct way to see XaoS stereograms is:
+@table @strong
+@item 1
+Start XaoS with options specifying the exact size of your screen or one pixel on it
+@item 2
+Sit 60cm away from monitor
+@item 3
+If you use a windowed environment, resize XaoS's window to make it wider than, say, 15 cm.
+@item 4
+Enable the filter (by pressing @code{E})
+@item 5
+focus on a point far away from the monitor (try to use your
+own reflection, if your monitor's not antireflective); the random blurring should
+eventually fall into the pattern of a Mandelbrot set.
+@item 6
+Carefully use your mouse to zoom into interesting areas
+(it is easy to lose concentration when you are not trained; but you can use
+the autopilot...)
+@item 7
+Enjoy animation :)
+@end table
+
+If you still can't see the stereograms, it could be that the fractal, or your eye,
+is deformed. A deformed fractal can be caused by your specifying your monitor size
+wrongly. Visual problems that damage depth perception, as well as problems like
+astigmatism, can make it impossible to see stereograms at all.
+
+
+@emph{Available as}: menu item, command line option
+
+@node interlace,  blur,  stereogram,  mfilter
+
+
+@appendixsubsec Interlace filter
+
+The interlace filter halves the horizontal resolution, and in each frame alternates
+between drawing only the even and only the odd lines. This speeds up the
+calculation, and in higher resolutions produces a motion-blur-like effect.
+
+@emph{Available as}: menu item, command line option
+
+@node blur,  emboss,  interlace,  mfilter
+
+
+@appendixsubsec Motion blur
+
+Motion blur mixes the current frame with previous ones to produce a
+motion-blur effect. It might be rather slow in 16bpp truecolor modes. The best
+results can probably be seen in 8bpp modes, so you might want to enable the
+palette filter first.
+
+@emph{Available as}: menu item, command line option
+
+@node emboss,  palettef,  blur,  mfilter
+
+
+@appendixsubsec Emboss
+
+This is a standard emboss filter, as seen in programs such as the GIMP or
+Photoshop. It produces especially nice results with the smooth
+outcoloring mode. @xref{outcoloring}.
+
+@emph{Available as}: menu item, command line option
+
+@node palettef,  anti,  emboss,  mfilter
+
+
+@appendixsubsec Palette emulator
+
+XaoS can work in either palette or truecolor mode. Both modes
+have advantages and disadvantages. Palette mode allows effects such as palette
+rotation, while truecolor mode allows smoother incoloring
+and outcoloring modes and the
+truecolor coloring modes. If your display is truecolor, you
+can enable this filter to get palette emulation (albeit not as cheaply as in
+a real paletted mode).
+
+@emph{Available as}: menu item, command line option
+
+@node anti,  truecolor,  palettef,  mfilter
+
+
+@appendixsubsec Antialiasing
+
+Antialiasing is a technique to increase image quality by eliminating jagged
+edges. XaoS calculates four values for each pixel (on the subpixel boundaries)
+and uses the average of them for the pixel value.
+
+This filter slows XaoS down a @emph{lot} and greatly increases memory
+requirements. It is useful mainly when you want to save images and want to make
+them look as nice as possible. Antialiasing also helps a lot when you want to
+encode JPEG or MPEG files; they are much shorter if antialiased (MPEG and JPEG
+hate jagged edges).
+
+@emph{Available as}: menu item, command line option
+
+@node truecolor,  ,  anti,  mfilter
+
+
+@appendixsubsec Truecolor emulator
+
+XaoS can work in either palette or truecolor mode. Both modes
+have advantages and disadvantages. Palette mode allows effects such as palette
+rotation, while truecolor mode allows smoother incoloring
+and outcoloring modes and the
+truecolor coloring modes. If your display is 8bpp, you can enable
+this filter to get truecolor emulation (but, obviously, not with as many colors
+as a real truecolor display).
+
+More information about filters
+
+@emph{Available as}: menu item, command line option
+
+@node ui,  misc,  mfilter,  menus
+
+
+
+@appendixsec UI
+
+This menu contains functions to control the user interface layer of XaoS:
+zooming speed, the autopilot, realtime status information, and so on.
+
+@menu 
+* speed::	Zooming speed
+* letterspersec::	Letters per second
+* autopilot::	Autopilot
+* recalculate::	Recalculate
+* interrupt::	Interrupt
+* nogui::	Disable XaoS's builtin GUI
+* status::	Status
+* ministatus::	Ministatus
+@end menu 
+@node speed,  letterspersec,  ,  ui
+
+
+@appendixsubsec Zooming speed
+@defun speed float 
+@end defun
+
+Change zooming speed, where 1 is the default, 2 means twice as fast, and so on.
+
+@emph{Available as}: menu item, command line option, command
+
+In the scripting language you can use the following functions for better
+control:
+@defun maxstep float 
+@end defun
+
+Selects the zooming/unzooming speed. The parameter specifies how much of the
+range will be removed each twentieth of a second; 0 means nothing, 1 means
+everything (the parameter obviously has to be less than 1).
+Higher values mean faster zooming.
+
+@emph{Available as}: command
+@defun speedup float 
+@end defun
+When zooming/unzooming, every twentieth of a second the @code{speedup}
+value is added to the current step until @code{maxstep} is reached.
+So this value selects the rate at which zooming stops and starts.
+Both these functions are more for internal use of XaoS then for manually
+written scripts, but they could come in useful nonetheless.
+
+@emph{Available as}: command
+
+@node letterspersec,  autopilot,  speed,  ui
+
+
+@appendixsubsec Letters per second
+@defun letterspersec integer 
+@end defun
+
+Speed of subtitles for the @code{textsleep} function.
+The user can set this value to suit; it can also be changed with the left and
+right arrow keys during animation replay.
+
+@emph{Available as}: command line option, command
+
+@node autopilot,  recalculate,  letterspersec,  ui
+
+
+@appendixsubsec Autopilot
+@defun autopilot bool 
+@end defun
+
+To make XaoS yet more impressive, we made a special autopilot mode that
+automatically drives into interesting boundaries of the set; you should
+press @code{A}, play your favorite music, drink coffee and relax. I never
+tried this but it should be really relaxing! Many pictures in the XaoS
+gallery were discovered using the autopilot.
+
+The autopilot also has some additional features. It backtracks if the
+zoomed picture is not interesting anymore, and can detect when it's zoomed
+into really a boring part of the fractal or reached the limit of floating
+point arithmetic on the platform, and restart zooming from the top.
+
+@emph{Available as}: menu item, command line option, command
+
+@node recalculate,  interrupt,  autopilot,  ui
+
+
+@appendixsubsec Recalculate
+@defun recalculate 
+@end defun
+
+Recalculate current fractal. This should be used when the fractal on the
+screen is strange because of error propagation caused by
+solid guessing. @xref{range}.
+
+@emph{Available as}: menu item, command line option, command
+
+@node interrupt,  nogui,  recalculate,  ui
+
+
+@appendixsubsec Interrupt
+@defun interrupt 
+@end defun
+
+Interrupt current calculation.
+
+@emph{Available as}: menu item, command line option, command
+
+
+@node nogui,  status,  interrupt,  ui
+
+
+@appendixsubsec Disable XaoS's builtin GUI
+@defun nogui bool 
+@end defun
+
+Disable XaoS menus and dialogs. This function should be used by external GUI
+programs; these manipulate XaoS via a pipe, so the internal GUI should be
+disabled at the same time. See the hacker's manual (@code{xaosdev.texinfo})
+for more details.
+
+@emph{Available as}: menu item, command line option, command
+
+@node status,  ministatus,  nogui,  ui
+
+
+@appendixsubsec Status
+@defun status bool 
+@end defun
+
+Enable/disable status information. This displays some useful information
+about the current fractal, such as viewpoint etc. (In low-resolution modes it
+also almost completely obscures the current fractal...)
+
+@emph{Available as}: menu item, command line option, command
+
+@node ministatus,  ,  status,  ui
+
+
+@appendixsubsec Ministatus
+@defun ministatus bool 
+@end defun
+
+Enable/disable status line. This contains basic information such as how
+much you are zoomed and the framerate.
+
+@emph{Available as}: menu item, command line option, command
+
+@node misc,  helpmenu,  ui,  menus
+
+
+
+@appendixsec Misc
+Miscellaneous functions.
+@menu 
+* command::	Command
+* renderanim::	Render animation
+* clearscreen::	Clear screen
+* display::	Display fractal
+* text::	Display text
+* color::	Color
+* xtextpos::	Horizontal text position
+* ytextpos::	Vertical text position
+* textposition::	Text position
+* message::	Message
+@end menu 
+@node command,  renderanim,  ,  misc
+
+
+@appendixsubsec Command
+
+You can invoke all XaoS functions using a simple command language reminiscent
+of Scheme. This option lets you run a single command. If you want to run more
+than one, you might want to use an XaoS animation file instead;
+they are written in the same language.
+
+@emph{Available as}: menu item
+
+@node renderanim,  clearscreen,  command,  misc
+
+
+@appendixsubsec Render animation
+
+Render an animation to image files. See How to encode MPEG files
+for more information.
+
+@emph{Available as}: menu item,
+@node clearscreen,  display,  renderanim,  misc
+
+
+@appendixsubsec Clear screen
+@defun clearscreen 
+@end defun
+
+Clear the screen. To display the fractal again, use @code{display}. @xref{display}.
+This function is mainly useful in tutorials and similar animations.
+
+@emph{Available as}: menu item, command
+
+@node display,  text,  clearscreen,  misc
+
+
+@appendixsubsec Display fractal
+@defun display 
+@end defun
+
+Display fractal. This functions reverses the effect of the @code{clearscreen},
+line drawing and text output functions.
+
+@emph{Available as}: menu item, command
+
+@node text,  color,  display,  misc
+
+
+@appendixsubsec Display text
+@defun text string 
+@end defun
+
+Display the given text on the screen. This function is mainly useful in tutorials.
+Text should be cleared by printing lots of spaces, or using the
+@code{clearscreen}</a> or <a display>@code{display}
+functions. You might also want to use the @code{textposition}
+function to select the part of the screen to display the text on.
+
+To wait for the user to read the text, you can use the @code{textsleep}
+function.
+
+Example:
+
+
+@example
+(clearscreen)
+(textposition 'center 'middle)
+(text "Welcome into my animation")
+(textsleep)
+(display)
+@end example
+
+
+@emph{Available as}: menu item, command line option, command
+
+@node color,  textposition,  text,  misc
+
+
+@appendixsubsec Color
+@defun color keyword 
+@end defun
+
+Change text and line color. @emph{keyword} should be one of @code{'white},
+@code{'black} and @code{'red}.
+
+@emph{Available as}: menu item, command line option, command
+
+@node textposition,  message,  color,  misc
+
+
+@appendixsubsec Text position
+@defun textposition keyword keyword 
+@end defun
+
+Select text position. The first keyword specifies the horizontal
+position, the second the vertical position. The horizontal position should be
+one of @code{'left}, @code{'center}, and @code{'right}.
+The vertical should be one of @code{'top}, @code{'middle}, and @code{'bottom}.
+
+@emph{Available as}: command line option, command
+
+@node message,  ,  textposition,  misc
+
+
+@appendixsubsec Message
+@defun message string 
+@end defun
+
+This function is almost identical to the @code{text} function,
+except that it uses message catalogs in the @code{catalog} directory to
+translate messages into other languages. It should be used only in the multi-lingual
+XaoS tutorials.
+
+@emph{Available as}: command line option, command
+
+@node helpmenu,  xtextpos,  misc,  menus
+
+
+
+@appendixsec Help
+This menu contains help and tutorials.
+
+@node xtextpos,  ytextpos,  helpmenu,  menus
+
+
+
+@appendixsec Horizontal text position
+Select the horizontal position used to display text. @xref{text}.
+It can be placed at the left, in the center or at the right.
+
+@node ytextpos,  mformula,  xtextpos,  menus
+
+
+
+@appendixsec Vertical text position
+Select the vertical position used to display text. @xref{text}. It can be
+placed at the top, in the middle or at the bottom of the screen.
+
+@node mformula,  palettemenu,  ytextpos,  menus
+
+
+
+@appendixsec formulae
+
+Each escape time fractal has its own formula. XaoS supports the following
+formulae:
+
+@menu 
+* mandel::	Mandelbrot
+* mandel3::	Mandelbrot^3
+* octal::	Octal
+* newton::	Newton
+* barnsley::	Barnsley1
+* phoenix::	Phoenix
+* magnet::	Magnet
+@end menu 
+@node mandel,  mandel3,  ,  mformula
+
+
+@appendixsubsec Mandelbrot
+
+The Mandelbrot set is the most famous escape time fractal ever. It has the
+simple formula @math{z=z^2+c}. See the tutorial chapter.
+
+@emph{Available as}: menu item, command line option
+
+@node mandel3,  octal,  mandel,  mformula
+
+
+@appendixsubsec Mandelbrot^3---Mandelbrot^6 and Mandelbrot^9
+
+The Mandelbrot^3 fractal is a simple modification of the standard
+Mandelbrot set formula, using @math{z=z^3+c} instead of
+@math{z=z^2+c}.
+
+Other derivations of the Mandelbrot set (Mandelbrot^4 and so on) use even
+higher powers. See the tutorial chapter.
+
+@emph{Available as}: menu item, command line option
+@node octal,  newton,  mandel3,  mformula
+
+
+@appendixsubsec Octal
+
+This is a less well-known fractal that Thomas discovered in Fractint.
+It has an interesting shape when displayed in the alternative
+planes. @xref{plane}. See the tutorial chapter.
+
+@emph{Available as}: menu item, command line option
+
+@node newton,  barnsley,  octal,  mformula
+
+
+@appendixsubsec Newton
+
+This is Newton's approximation method for finding the roots of a polynomial. It
+uses the polynomial @math{x^3=1} and counts the number of iterations needed
+to reach the approximate value of the root. See the tutorial chapter.
+
+This fractal doesn't have Julia sets, but XaoS is able to generate Julia-like
+sets which are also very interesting (they are sometimes called ``Nova
+formulae'').
+
+@emph{Available as}: menu item, command line option
+
+@node barnsley,  phoenix,  newton,  mformula
+
+
+@appendixsubsec Barnsley1
+
+This is a formula by Michael Barnsley. It produces very nice crystalline Julia
+sets. See the tutorial chapter.
+
+@emph{Available as}: menu item, command line option
+
+@node phoenix,  magnet,  barnsley,  mformula
+
+
+@appendixsubsec Phoenix
+
+This formula produces very nice Julia sets.
+See the tutorial chapter.
+
+@emph{Available as}: menu item, command line option
+
+@node magnet,  ,  phoenix,  mformula
+
+
+@appendixsubsec Magnet
+
+This is a formula that comes from theoretical physics.
+It is derived from the study of theoretical lattices in the context of magnetic
+renormalization transformations.
+See the tutorial chapter.
+
+@emph{Available as}: menu item, command line option
+
+@node palettemenu,  ,  mformula,  menus
+
+
+
+@appendixsec Palette
+This menu contains functions to change the palette the fractal is displayed with.
+@menu 
+* defpalette::	Default palette
+* randompalette::	Random palette
+* palette::	Custom palette
+* cycling::	Color cycling
+* shiftpalette::	Shift palette
+@end menu 
+@node defpalette,  randompalette,  ,  palettemenu
+
+
+@appendixsubsec Default palette
+@defun defaultpalette number 
+@end defun
+
+Create a default palette. In the scripting language, @code{number} specifies
+how much the palette is shifted by.
+
+Note that changing the palette in truecolor modes forces recalculation of
+the whole screen. To avoid this, you can enable the
+palette emulation filter first.
+
+@emph{Available as}: menu item, command line option, command
+
+@node randompalette,  palette,  defpalette,  palettemenu
+
+
+@appendixsubsec Random palette
+@defun randompalette 
+@end defun
+
+Create a random palette. XaoS will automatically pick one of its
+palette-generation algorithms and create one.
+
+Note that changing the palette in truecolor modes forces recalculation of
+the whole screen. To avoid this, you can enable the
+palette emulation filter first.
+
+@emph{Available as}: menu item, command line option, command
+
+@node palette,  cycling,  randompalette,  palettemenu
+
+
+@appendixsubsec Custom palette
+@defun palette integer integer integer 
+@end defun
+
+A custom palette lets you re-create some of the random palettes. The first value
+specifies the algorithm, which should currently be one of the following:
+@table @strong
+@item 0
+Default palette
+@item 1
+Black to color gradient
+@item 2
+Black to color to white gradient
+@item 3
+Cubistic-like algorithm.
+@end table
+The seed specifies a random seed for the palette; different seeds generate
+different palettes. The last value is the amount by which the palette is shifted.
+
+Note that changing the palette in the truecolor modes forces recalculation of
+the whole screen. To avoid this, you can enable the
+palette emulation filter first.
+
+@emph{Available as}: menu item, command line option, command
+
+@node cycling,  shiftpalette,  palette,  palettemenu
+
+
+@appendixsubsec Color cycling
+@defun cycling bool 
+@end defun
+
+Color cycling is an old and simple effect to animate fractals. The Mandelbrot
+set looks particularly nice when color-cycled. On truecolor displays, color
+cycling fails to initialize (since those displays don't have a palette).
+You can enable palette emulation filter to make it possible.
+
+@emph{Available as}: menu item, command line option, command
+
+In the user interface, colors can also be cycled in the opposite direction
+with the ``@emph{Reversed color cycling}'' function.
+
+To control the cycling speed, you coan use arrow keys or the
+``@emph{Color cycling speed}'' function.
+
+@emph{Available as}: menu item
+@defun cyclingspeed integer 
+@end defun
+
+The parameter specifies the number of skips per second. It can be negative to
+cycle in the opposite direction.
+
+@emph{Available as}: menu item, command line option, command
+
+@node shiftpalette,  ,  cycling,  palettemenu
+
+
+@appendixsubsec Shift palette
+@defun shiftpalette integer 
+@end defun
+
+Shift palette by the specified number of cells. This can be used to tune the
+palette's position on the fractal. You can also use the
+@emph{Shift one forward} and @emph{Shift one backward} functions
+for fine-tuning. Note that shifted and rotated palettes could look different on
+different displays (because they may have different palette sizes).
+
+Shifting the palette on truecolor displays causes a recalculation of the screen.
+To avoid this, you could use palette emulation filter. @xref{palettef}.
+
+@emph{Available as}: menu item, command line option, command
+
+
+@c ## menus controls ##
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+@comment  node-name,  next,      previous,  up
+@node about, support,menus ,Top
+@appendix About XaoS
+@appendix Credits
+(alphabetically)
+@table @strong
+@item Lucio Henrique de Araujo (lucio.matema@@gmail.com)
+Brazilian/Portuguese translation
+@item Samuel Bizien (samuel@@bizien.info)
+Beryl fractal
+@item Eric Courteau (ecourteau@@cplus.fr)
+francais.cat (translation of tutorials)
+@item Jean-Pierre Demailly (Jean-Pierre.Demailly@@ujf-grenoble.fr)
+Updates for French translation
+@item Radek Doulik (rodo@@atrey.karlin.mff.cuni.cz)
+TK interface, windowid patches
+@item Martin Dozsa (madsoft@@centrum.cz)
+cs.po (Czech translation of menus)
+@item Arpad Fekete (Fekete.Arpad.2@@stud.u-szeged.hu)
+Some new fractals, and the 'More formulae' menu
+@item Zelia Maria Horta Garcia (zeliagarcia@@seed.pr.gov.br)
+Brazilian/Portuguese translation
+@item Tim Goodwin (tgoodwin@@cygnus.co.uk)
+english.cat corrections
+@item Ben Hines
+autoconf suggestions, Mac OS X port
+@item Jan Hubicka (jh@@ucw.cz)
+Zooming routines, ugly interface, palettes, drivers, autopilot, filters, documentation, tutorials etc.
+@item Jens Kilian (jjk@@acm.org)
+BeOS driver, deutsch.cat
+@item Thomas A. K. Kjaer (takjaer@@imv.aau.dk)
+OS/2 ports (320x200 graphics and AA-lib)
+@item Zoltan Kovacs (kovzol@@math.u-szeged.hu)
+Internationalization, Hungarian translations, finalizing version 3.1, bug fixes, web design, current maintainer
+@item Zsigmond Kovacs (kovzsi@@gmail.com)
+Fractal examples
+@item J.B. Langston III (jb-langston@@austin.rr.com)
+Native Mac OS X port (from version 3.2.2); web redesign; co-maintainer
+@item Andreas Madritsch (amadritsch@@datacomm.ch)
+New fractal types, bailout, many fixes
+@item Mateusz Malczak (xaos@@malczak.info)
+User formula evaluation library
+@item Giorgio Marazzi (gmarazzi@@vtr.net)
+Improvements and fixes for espanhol.cat
+@item Thomas Marsh (thomas.marsh2@@gmail.com)
+First zoomer, formulae, planes, X11 driver, inversions, many ideas
+@item Dominic Mazzoni (dmazzoni@@cs.cmu.edu)
+Macintosh port (version 2.0)
+@item David Meleedy
+Grammatical and spelling fixed version of @code{xaos.6}
+@item Paul Nasca (zynaddsubfx@@yahoo.com)
+Ministatus improvement
+@item Nix (nix@@esperi.demon.co.uk)
+Grammatical and spelling fixed version of @code{xaos.hlp} and other files
+@item Terje Pedersen (terjepe@@login.eunet.no)
+Amiga port
+@item Cesar Perez (oroz@@users.sourceforge.net)
+Spanish translations
+@item Fabrice Premel (premelfa@@etu.utc.fr)
+Periodicity checking
+@item Jan Olderdissen (jan@@olderdissen.com)
+Win32 port
+@item Ilinca Sitaru (ilinca.sitaru@@gmail.com)
+Romanian translation
+@item Daniel Skarda
+Fractal examples
+@item Andrew Stone (Stone Design - www.stone.com)
+Videator Support, Cocoa improvements, performance mode, bug fixes
+@item Marton Torok (marton.torok@@gmail.com)
+Small fixes for pipes
+@item Pavel Tzekov (paveltz@@csoft.bg)
+Win32 support
+@item Charles Vidal
+Tcl/Tk interface
+@item Tapio K. Vocaldo (taps@@rmx.com)
+Macintosh port
+@item Tormod Volden
+Fixes for X11 driver to improve compatability with Xorg, XScreenSaver, Beryl and Compiz
+@item Philippe Wautelet (p.wautelet@@fractalzone.be)
+Bug fixes for version 3.1.1, French translation, gcc 4.0 fixes
+@item Sergio Zanchetta
+Italian translation
+@end table
+@subsection Included Software
+XaoS uses the following libraries. These libraries may be included
+with some binary distributions of XaoS.
+
+@emph{gettext 0.17}
+Website: @code{http://www.gnu.org/software/gettext/}
+Copyright (C) 1995-1997, 2000-2007 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later (http://gnu.org/licenses/gpl.html)
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+@emph{GNU Scientific Library 1.11}
+Website: @code{http://www.gnu.org/software/gsl/}
+Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 The GSL Team.
+License GPLv3+: GNU GPL version 3 or later (http://gnu.org/licenses/gpl.html)
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+@emph{libpng 1.2.25}
+Website: @code{http://www.libpng.org/pub/png/libpng.html}
+Copyright (c) 1998-2008 Glenn Randers-Pehrson
+Copyright (c) 1996-1997 Andreas Dilger
+Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
+
+@c ## appendix about ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node support, index ,about ,Top
+@appendix Getting Support
+XaoS is a community-supported free software project. There are many ways
+to get help, all of which are explained below.
+
+@appendix Home Page
+The XaoS homepage is @code{http://xaos.sf.net}. Check here for the
+latest news and information about XaoS and to download the latest versions.
+
+
+@subsection Discussion Forums
+XaoS has two discussion forums hosted on SourceForge. You can read them
+freely, but in order to post, you must to register for a free SourceForge
+account.
+
+@table @strong
+@item Help
+Provides a place for you to ask for help using XaoS. Other XaoS users
+and/or the XaoS developers will answer your questions.
+
+
+@code{http://sourceforge.net/forum/forum.php?forum_id=17768}
+@item Open Discussion
+Provides a place to discuss anything related to XaoS or fractals.
+You can share tips, your own fractal creations, or any other fractal-related
+ideas with other XaoS users.
+
+
+@code{http://sourceforge.net/forum/forum.php?forum_id=17767}
+@end table
+
+
+We welcome you to join these forums and become involved in the XaoS community.
+
+@subsection Mailing Lists
+
+XaoS currently has three mailing lists hosted on SourceForge. Unfortunately,
+there is currently very little traffic on any of them. Hopefully in the future,
+we can get more XaoS users and developers involved in the mailing lists.
+The lists are as follows:
+
+@table @strong
+@item xaos-announce@@lists.sourceforge.net
+Low volume list that is used only to announce new releases.
+
+
+Subscribe: @code{http://lists.sourceforge.net/mailman/listinfo/xaos-announce}
+Archive: @code{http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-announce}
+
+@item xaos-devel@@lists.sourceforge.net
+Developer mailing list, where the developers coordinate and discuss XaoS development.
+
+
+Subscribe: @code{http://lists.sourceforge.net/mailman/listinfo/xaos-devel}
+Archive: @code{http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-devel}
+
+@item xaos-discuss@@lists.sourceforge.net
+General discussion list is for XaoS users to share tips and ideas about XaoS.
+
+
+Subscribe: @code{http://lists.sourceforge.net/mailman/listinfo/xaos-discuss}
+Archive: @code{http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-discuss}
+@end table
+
+
+Please feel free to join any or all of these mailing lists and share your ideas with the
+developers and other XaoS users.
+
+@subsection Bug Reports
+If you think you have found a bug in XaoS, please report it. The developers will do their
+best to resolve the bug in a timely manner.
+
+
+Bug Tracker: @code{http://sourceforge.net/tracker/?atid=105771&group_id=5771}
+
+
+Please don't submit duplicate bugs. Browse the existing ones first to make
+sure nobody has already reported it. You may add additional information about a bug by
+entering a comment on an existing bug.
+
+
+If you are not sure if something is a bug, please open a support request. The developers
+will try to answer your question and can convert your support request to a bug if necessary.
+
+
+Support Requests: @code{http://sourceforge.net/tracker/?atid=205771&group_id=5771}
+
+@subsection Feature Requests
+If you have an idea for a great new feature you'd like to see added to XaoS, please let us know about it.
+You can submit a feature request via SourceForge, and the XaoS developers will do their best to
+implement your request in a future version.
+
+
+Feature Requests: @code{http://sourceforge.net/tracker/?atid=355771&group_id=5771}
+
+
+Please don't submit duplicate feature requests. Browse the existing ones
+first to make sure nobody has already requested the feature your want. You may add your
+vote for a feature by adding a comment to the existing request.
+
+@c ## appendix support ##
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@comment  node-name,  next,      previous,  up
+@node index,  ,support ,Top
+@unnumbered Index of functions
+
+@printindex fn
+
+
+@contents
+@bye
diff --git a/doc/xaosdev.info b/doc/xaosdev.info
new file mode 100644
index 0000000..57b5d82
--- /dev/null
+++ b/doc/xaosdev.info
@@ -0,0 +1,2862 @@
+This is Info file xaosdev.info, produced by Makeinfo version 1.68 from
+the input file xaosdev.texinfo.
+
+INFO-DIR-SECTION Graphics
+START-INFO-DIR-ENTRY
+* XaoS: (xaosdev).               The fast real-time interactive fractal zoomer
+                                  (developers documentation
+END-INFO-DIR-ENTRY
+
+   (C) 1997 Jan Hubicka
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+
+File: xaosdev.info,  Node: Top,  Prev: (dir),  Up: (dir)
+
+XaoS 3.1
+********
+
+                                An real-time interactive fractal zoomer
+                                                         Hacker's guide
+                                                           May 14, 1998
+
+   This manual contains documentation for those who are interested in
+studying and improving XaoS sources or using them in other programs.
+It includes description of algorithm and documentation of those parts
+of XaoS I think they should be useful for someone.
+
+* Menu:
+
+* design::		Overview of the XaoS design
+* driver::		Driver API description
+* gui-driver::		Writing user interface driver
+* eui::			Writing an external user interface
+* ui-helper::		UI helper library
+* xthreads::		XaoS thread library
+* filters::		Filters
+* algorithm::		Algorithm description
+* timerlib::		The timer library
+* registry::		XaoS function registry
+* index::		Function command and variable index
+
+
+File: xaosdev.info,  Node: design,  Next: driver,  Prev: Top,  Up: Top
+
+Overview of the XaoS design
+***************************
+
+   Whole sources of XaoS are designed into several "libraries" (some of
+them are not really libraries, but added into other's, but should be
+separated easily).
+
+   Understanding to the main philosophy should help you to navigate in
+the sources.  I also expect that many of the lower level stuff should
+be useful in the other projects, since it is designed to be fairly
+generic.
+
+   So here is an overview from the lowest level stuff to the highest.
+
+Palette and image library
+=========================
+
+   Sources are in directory `src/filter'. The aim of palette library is
+to provide relatively abstract interface to the various visuals and
+hide differences in the hardware and driver implementation. Fixedcolor,
+pseudocolor, grayscale and truecolor visuals should be handled in the
+almost same way.
+
+   It provides the structure `palette', which contains actual palette.
+You might allocate new colors here (you give RGB value and
+corresponding pixel is returned), interpolate colors where possible,
+cycle colors and so on.  Every palette also consist from the two
+parts--the preallocated color cells and the actual palette. This lets
+for example to GUI possibility to allocate statically colors for its
+texts and dialogs, while rest of palette is under control of different
+parts of XaoS.
+
+   This library also contain set of functions to allocate different
+palettes used by other parts. I expected that different parts of XaoS
+should use same palette. Nothing similar happened yet, but functions
+are kept here.
+
+   The image library is built at the top of palette library. It extends
+functionality for handling actual image data. Each image is represented
+by one or two frame-buffers (it is useful for double-buffering). One
+frame-buffer is called current and other old. They should be flipped by
+special function.  Program can draw into both of them.
+
+   Frame-buffers are hold as the set of pointers to the scan-lines.
+This brings better flexibility, because tricks like sub-windows, or
+flipped bitmaps are possible. Also speeds up, since you should avoid
+one multiplication.
+
+   The last significant information image structure hold is of course
+bpp depth.  It is counted in bytes, and should be 0-4. Where 0 is used
+for 1bit bitmaps.
+
+Filter library
+==============
+
+   Source are available in `src/filter'. This library controls the
+process of creation of the image. It handles an queue of the filters,
+where each filter should modify the image. There are two special filter
+at the beginning and end of queue. The first filter is usually the
+actual fractal engine which creates image, while the terminal filter is
+usually user interface helper library.
+
+Xthread library
+===============
+
+   This library provides interface to various multi-threading libraries
+(currently the BeOS, plan9 and POSIX implementations are available). It
+allows to run various function paraelly and some synchronization
+primitives (semaphores). It is simple, but has all the functionality
+required for the XaoS engine.
+
+Fractal library
+===============
+
+   Source are available in `src/engine/', headers in `fractal.h'.  This
+library contains the actual fractal calculation routines. It operates
+with fractal context, which contains informations like current formula,
+seed for julia, palette etc.
+
+   Functions for calculating the various fractal types and various
+coloring modes are available here.
+
+Zooming engine and other filters.
+=================================
+
+   Source are available in `src/engine/'.  This is the actual zooming
+engine filter. It is done in fairly independent way at fractal library,
+so it should be possibly used for zooming other stuff.  (it was already
+used for zooming large scale images containing maps of Hungary).
+
+   All other filter has their special file, where is implementation and
+structure containing all functions exported from the filter to user
+interface. They are registered in the file `ui_helper'.  One other
+terminal filter is implemented--Julia morpher. Other filters adds
+special effects (such as motion blur), or does conversions (such as
+rotation, dithering etc.)
+
+Timer library
+=============
+
+   This library provides many of very useful timing primitives. Such as
+timers, etc. Currently it is used by some other programs too.
+
+xio library
+===========
+
+   This library aims to provide united interface to file-system. Some
+strange systems (such as MacOS) has file-system API done in much
+different way than in UNIX. They don't have names in string, and uses
+special structures etc.
+
+xshl library
+============
+
+   Xshl stands for XaoS simple hypertext library. It contains fairly
+universal engine parsing an xshl language. It is similar to HTML with
+some additions and many restrictions. It should render this texts for
+the proportional/non-proportional fonts and various sizes.
+
+help library
+============
+
+   it is built at the top of xshl and xio libraries. It should read
+help files, wick contains an chapters. Parse chapter with given keyword
+etc.
+
+xmenu library
+=============
+
+   This is the XaoS function registry. All functions from UI-Helper
+library are registered in the registry. From this registry the menus,
+dialogs, command line options and scripting language are built.
+
+Catalog library
+===============
+
+   This is library for handling an message catalogs. It should read
+catalog and convert the keyword into actual message.
+
+PNG library
+===========
+
+   This library provides the function for saving an image from Image
+library to the file (in PNG format). Other formats should be added as
+well if required.
+
+UI-helper library
+=================
+
+   This library controls all the low-level stuff and provides an high
+level interface to it. It has functions for playing animations,
+zooming/UN-zooming and such. It heavily uses all the described
+libraries. It don't implement functions for handling menus and such,
+but makes great help for such implementations, because of the function
+registry database.
+
+Ugly interface
+==============
+
+   This is currently the only real user interface for XaoS (there is
+also an second, wich is used for rendering animations, but it is not
+user interface, how users expect it). It is built at the top of
+UI-helper library and provides functions for drawing menus, dialogs and
+such.  It has drivers for many platforms, and it should be easily
+ported to the others.
+
+   In the future, it should be quite easily to extended to let drivers
+specify their own menu/dialog handling code, so it should be possible
+to give it an "native" look of given platform.
+
+   It has also an function, where an GUI drawing routines are disabled.
+Function registry database is transfered trough pipe to external
+program, wick should build the menus and act as external user
+interface. It then back sends an commands in the scripting language
+representing things, that user done.  So it is an another way, how to
+give native look to ugly interface.
+
+   Ugly interface has also one serious limitation--for the historical
+reasons it is coded to handle just one window (rest of XaoS probably
+can do multiple windows--untested). So in windowed environments it is
+impossible to open multiple menus with fractals. At the other hand,
+this limitation is not so important, once external GUI enter the role.
+They should just start multiple XaoS engines. This will bring extra
+robustness, multitasking and some other advantages, so it is the
+proffered way. Thats why I don't plan to remove this limitation yet.
+
+
+File: xaosdev.info,  Node: driver,  Next: gui-driver,  Prev: design,  Up: Top
+
+Driver API description
+**********************
+
+   To port successfully XaoS to some platform you need:
+
+   * ANSI C compatible optimizing compiler. Note that optimizing
+     compiler is really required, since XaoS is coded to be good target
+     for optimizations and don't have any routines coded in assembly,
+     so if you will use some bad compiler, you should receive more than
+     ten times slower result. Also note that some compilers has serious
+     problems with compiling XaoS--like most of DOS compilers (Watcom
+     C, Borland C, Microsoft C etc...), has serious problems.  They
+     generate incorrect code or crash during compilation. I highly
+     recommend to use GNU C compiler. Even some versions of GNU C has
+     problems. Please read `compilers.txt' for more information.
+
+   * Fast way to avoid division by zero/overflow and other floating
+     point exception. XaoS is carefully coded to not to crash in this
+     case, but don't have any tests to avoid such situation and expect
+     random result in such case.  Many platforms provide way to switch
+     coprocessor into mode, where 1/0 is evaluated into Inf etc. If
+     there is no such way, try to use some kind of signal handler that
+     will ignore such exceptions.
+
+     The "normal" solution--add ifs to avoid division by zero is almost
+     impossible. The division is quite easy to check. But other
+     cases--overflows are much worse. So I don't think it is possible
+     to avoid all crashes just by adding ifs.
+
+     XaoS don't depend at IEEE arithmetic. Result in such cases should
+     me mostly undefined. XaoS usually works well with compiler's
+     switches for inexact math enabled (such as `-ffast-math' in GNU).
+     But no guarantees. For example at Alphas this is not true--since
+     they usually generates exceptions then.  Also `-mno-ieee-fp' at
+     Intel don't work. This is due to gcc bug. Gcc in some cases reverse
+     the condition when this switch is enabled. I've made patch to fix this
+     problem and hope that it will get to egcs or gcc soon.
+
+   * Text or graphics output device. If you have only text output
+     device, you may use AA driver, which renders fractals into high
+     quality ASCII art. In this case you might skip this chapter,
+     download AA-lib (http://www.ta.jcu.cz/aa) and read porting chapter
+     of AAlib manual. Graphics device must one of:
+
+        * 8bits per pixel with user definable palette `C256', static
+          palette `FIXEDCOLOR', or static grayscale `GRAYSCALE'
+
+        * 16bits per pixel with arbitrary bits per each color
+          `TRUECOLOR'
+
+        * 24bits per pixel with 8 bits per each color, arbitrary order
+          `TRUECOLOR24'
+
+        * 32bits per pixel with arbitrary order of colors, where each
+          colors fit to exactly one byte `TRUECOLOR'
+
+        * 1bits per pixel bitmap with both orders (Least or Most
+          significant bit first)
+
+     Please contact me if you have different kind of device. Some modes
+     (like miss-ordered truecolor modes) should be added really easily
+     if required.  Note that mono/4/16 colors devices will be probably
+     never supported internally by XaoS, since I expect they will be
+     slower than 8bpp, so XaoS will internally work in 8bpp and then
+     image should be converted. Contact me if you want to write such
+     converter. (For bitmap there already exists--see `dither.c'.
+
+   * Some way to save images. By default XaoS uses `pnglib', which is
+     ported to many platforms, but there is still many others. If your
+     system has some standard image format, which is easier to handle
+     than `.png', contact me and I will show you, how to add such
+     support to XaoS (see `png.c').
+
+   * Stdio compatible library (this is problem at Mac or BeOS). XaoS
+     has the abstract layer at the top of stdio, so it should use other
+     input/output libraries too. You might write just another
+     implementation if it's library called `xio'. See `xio.h'.
+
+   Ugly interface is designed to make writing of new drivers as easy as
+possible.  You need to write just few functions to fill following table:
+(use file `ui_template' for starting of writing new driver from scrath)
+     struct ui_driver {
+       char *name;
+       int (*init)(void);            /*initializing function. returns 0 if fail*/
+       void (*getsize)(int *,int *);	/*get current size..in full-screen versions
+                                       i.e svga and dos asks user for it*/
+       void (*processevents)(int,int *,int *,int *,int *);
+                                     /*processevents..calls ui_resize,ui_key
+                                       also returns positions of mouse..
+                                       waits for event if first parameter is
+                                       1*/
+       void (*getmouse)(int *,int *,int *);
+                                     /*returns current mouse positions*/
+       void (*uninit)();             /*called before exit*/
+       int (*set_color)(int,int,int,int);
+                                     /*alloc palette color and returns number*/
+       int (*set_range)(ui_palette *palette,int start,int end)
+                                     /*Set palette range*/
+       void (*print)(int,int,char *);/*prints text*/
+       void (*display)();            /*displays bitmap*/
+       int (*alloc_buffers)(char **buffer1,char **buffer2);/*makes buffers*/
+       void (*free_buffers)(char *buffer1,char *buffer2);/*frees buffers*/
+       void (*flip_buffers)(void);   /*prints text*/
+       void (*mousetype) (int type); /*Change mouse cursor*/
+       void (*flush) (void);         /*Flush current state to screen*/
+       int textwidth;                /*width of text*/
+       int textheight;		/*height of text*/
+       struct params *params;        /*command line parameters*/
+       int flags;
+       float width,height;
+       int maxwidth,maxheight;
+       int imagetype;
+       int palettestart,paletteend,maxentries;
+       int rmask, gmask, bmask;
+       struct gui_driver gui_driver;
+     };
+
+Functions
+=========
+
+   Ui uses following functions to communicate with driver:
+
+ - Function: init
+     function that initializes driver and returns 1 if success and 0 if
+     fail
+
+ - Function: getsize (INT *WIDTH, INT *HEIGHT)
+     returns size of screen(window) x and y
+
+ - Function: processevents (INT WAIT, INT *X,INT *Y, INT *BUTTONMASK,
+          INT &KEYS)
+     gets new keyboard/mouse events. parameters:
+    WAIT
+          if 1 function can wait for next event otherwise just lookup if
+                    something came. This is useful on multi-tasked os
+          where xaos 	   does not eats unnecesaru CPU.
+
+    *X,*Y
+          here returns current positions of mouse
+
+    *B
+          returns mask of `BUTTON1',`BUTTON2',`BUTTON3' for mouse
+          buttons
+
+    *K
+          returns mask for cursor keys
+         `1'
+               left
+
+         `2'
+               right
+
+         `4'
+               up
+
+         `8'
+               down             function also calls `ui_key' (ASCII
+     character) and ui_resize if required.      For special keys use
+     `UIKEY_UP', `UIKEY_DOWN', etc. See     `ui.h' for complete lists
+     of this constants.
+
+     note in case of problems freeing/allocating inside processevents
+     you may     call `ui_call_resize' that calls resize later outside
+     this function
+
+ - Function: uninit
+     Unitialises driver--called before exit.
+
+ - Function: set_range (UI_PALETTE *PALETTE, INT START, INT END)
+     This is an preffered way to set palette (second way is `set_color')
+     when `imagetype' is `UI_C256' (256 color with palette) one of this
+     two functions is required. In truecolor modes they are unused. In
+     case direct access to palette is possible at your platform, define
+     this one. Function is expected to set all color cells between
+     START to END to colors defined in PALETTE. `Ui_palette' is array
+     of UI_RGB. `Palette[0]' is color for entry number START. `Ui_rgb'
+     is an array of `char'.  `Palette[0][0]' is red field of entry
+     number START, `Palette[0][1]' is green and `Palette[0][2]' is
+     blue. `0' means black and `255' means full intensity. Use `NULL'
+     if your driver don't support this call.
+
+ - Function: set_color (INT R, INT G, INT B, INT INIT)
+     This is an secondary way, that should be used at platforms w/o
+     direct   palette access (like X11 or static color schemes). It
+     receives RGB value   of color, and returns index of color cell
+     with this color or -1 if no more   color cells available. An INIT
+     parameter is set to 1, when first entry   of palette is allocated,
+     `set_color' is expected to free all color   entries previously
+     allocated. Use `NULL' if your driver don't support   this call
+
+ - Function: print (INT `x',INT `y', CHAR *`text')
+     prints text to screen at position x/y. This function is a bit
+     archaistic   (XaoS now uses in the most cases its own functions
+     drawing directly to the   buffer), but in some
+     cases--initialization messages or calculation,   functions are
+     unusable, so we still need this primitive. In the `C256'   mode
+     you might rely, that first allocated color is always black and
+     second   is white.
+
+ - Function: display (VOID)
+     displays current buffer to screen
+
+ - Function: alloc_buffers (CHAR **BUFFER1,CHAR **BUFFER2)
+     allocs two buffers that can hold screen size bitmap.    Also sets
+     current buffer to BUFFER1. Since version 2.1 returns scan-line
+     size in bytes(usually width) and 0 if fail. This is useful on
+     systems, that   allocated bitmap bigger than
+     window/screen(dividable by 4 or so)
+
+ - Function: free_buffers (CHAR *BUFFER1, CHAR *BUFFER2)
+     frees allocated buffers
+
+ - Function: flip_buffer (VOID)
+     flips buffers--set current buffer to other one
+
+ - Function: flush (VOID)
+     This function should be used by drivers with buffered output to
+     flush   output buffers. Other driver should set it to NULL.
+
+ - Function: mousetype (INT TYPE)
+     This function is used to change mouse cursor. It receives
+     following values:
+    `NORMALMOUSE'
+          This mouse is usually displayed at screen, when UI waits for
+          user      commands
+
+    `WAITMOUSE'
+          This mouse is displayed when UI is busy(should be famous wait
+          clocks)      or you may use mouse defined in
+          ui_dos--mandelbrot set
+
+    `REPLAYMOUSE'
+          This mouse is displayed during replay. Should be none at
+          fullscreen      drivers, since blinking mouse cursor during
+          replay looks ugly. At      windowed system disabling mouse
+          looks ugly, so it should be some funny      cursor.
+     You should use NULL if your driver don't support this.
+
+Other information
+=================
+
+   Also some additional variables are used to inform ui about driver.
+All this values can be changed by init functions in case they are
+unknown before.
+
+TEXTHEIGHT, TEXTWIDTH
+     width and height of your font
+
+PALETTESTART, PALETTEEND
+     First and last palette entry, that should be changed. This you
+     should use   to avoid changing of entries reserved for window
+     system, text, mouse etc.
+
+RMASK, GMASK, BMASK
+     This fields are used in truecolor modes to specify, where each
+     color is   defined
+
+MAXENTRIES;
+     Number of allocatable entries. Normally should be
+     PALETTESTART-PALETTEEND
+
+IMAGETYPE
+     defines type of image. Should be one of following values:
+    `UI_C256'
+          classical 256 color with palette scheme used by most older
+          graphics     adapters. You should use it also for
+          static-color schemes but they are     not supported well in
+          current version.
+
+    `UI_TRUECOLOR'
+          32bpp truecolor mode
+
+    `UI_TRUECOLOR24'
+          24bpp truecolor mode.
+
+    `UI_TRUECOLOR16'
+          16bpp truecolor mode
+
+   FOLLOWING PART IS NOT REQUIRED TO MAKE FIRST VERSION OF DRIVER
+WORKING.  so you may skip to REGISTERING DRIVER for first read and
+return here later.
+
+PARAMS
+     Using this you may define command line options for you driver.
+
+     They are defined using params structure like:
+            static struct params params[]={
+              {"-mode",P_NUMBER,&defmode,
+                "Select graphics mode(same number as in interactive menu)"},
+              {NULL,0,NULL,NULL}  /*this is MUST be last option field*/
+            };
+
+     every line is one parameters. List ends with `{NULL,0,NULL,NULL}'.
+      First filed is option name.    Second field is type of parameter:
+    `P_SWITCH'
+          no parameter--variable is just set to 1 if option
+
+    `P_NUMBER'
+          integer number
+
+    `P_STRING'
+          string
+
+    `P_FLOAT'
+          floating point number (variable is float)     Third is
+     pointer to variable that is changed if option is set.    It is for
+     example `int*' for `P_NUMBER' or `P_SWITCH' and so on..    Last
+     one is help text. Displayed by `ui -h'
+
+WIDTH,HEIGHT
+     see FLAGS. May be set to `0.0, 0.0' for the beginning
+
+MAXWIDTH,MAXHEIGHT
+     see FLAGS. May be set to 0,0 for the beginning
+
+FLAGS
+     This variable says more about your driver. You may start with
+     value 0.    But for final version it is recommended to read
+     following chapter carefully.
+
+     Flags are uppercase constants and should be set by following way:
+
+     `ASYNC_PALETTE | RANDOM_PALETTE_SIZE'
+
+     following switches are supported:
+
+    `RANDOM_PALETTE_SIZE'
+          random size of palette. This is used in X where palette is
+          shared between     programs. By default xaos allocates all
+          available colors up to 256. This     is not very nice to
+          other applications in X. So randomsize causes that     just
+          some random number of colors(between 8-256) are allocated.
+
+          Also when this variable is off XaoS expects that allays same
+          number of     colors is available.
+
+    `UPDATE_AFTER_RESIZE'
+          recalculate and redraw screen even if its size is not changed.
+             In case that resize procedure destroys data in buffers
+
+    `RESIZE_COMMAND'
+          Some drivers (mainly the fullscreen ones) may in the function
+          `get_size'     ask user for the size and color depth. It
+          should be nice to let user change this parameter     at
+          runtime. I.E force XaoS to reinitialize his images. This is
+          done by     `ui_resize' call. This call in windowed drivers
+          is called by the     external event. But in fullscreen
+          drivers you need key/menu item for this.      You might add
+          this function directly into XaoS's function registry (see
+          for example the GGI driver)--it is usefull mainly when you
+          want to make     some size selection dialog in the standard
+          way, or let XaoS add his default     one. And this is done by
+          this flag. See for example SVGAlib or DOG driver.
+     Screen/window size informations:
+
+     Xaos needs to know exact size of displayed images. This is required
+        for random dot stereo-grams and also for keeping fractals in
+     their shape     (do not make them wide on 640x200 resolution etc.)
+        So minimally one of the following values should be defined.
+      (they are sorted in order I prefer them)
+    `SCREENSIZE'
+          values width/height specifies exact size of screen/window in
+          centimeters
+
+    `PIXELSIZE'
+          values width/height specifies exact size of one pixel in
+          centimeters      This is better for windowed environments
+          where window size is often changed
+
+    `FULLSCREEN'
+          driver runs fullscreen. XaoS automatically uses default
+          screen size      (29.0cm x 21.5cm)
+
+    `RESOLUTION'
+          driver does not know exact screen size. But knows resolution
+          used.       (it is in variables width/height) XaoS
+          automatically calculates      pixel width
+          using:29.0cm/maxwidth      and height: 21.5/maxheight
+     Of course default width and height can be changed by command line
+     options.     You may also use combinations like:
+
+    `SCREENSIZE | FULLSCREEN'
+          the best for fullscreen drivers
+
+    `PIXELSIZE | RESOLUTION'
+          the best for windowed drivers
+
+    `FULLSCREEN'
+          for fullscreen drivers than have no idea about screen size...
+                do not forget to set WIDTH, HEIGHT, MAXWIDTH,
+     MAXHEIGHT fields if required.
+
+GUI_DRIVER
+     See next section for description.
+
+Registering driver
+==================
+
+   Than just register driver to `driver.c' and you may compile :) You
+may use `ui_template.c' as driver template..
+
+   You may also look at xthreads library description if you are porting
+XaoS to some SMP platform.
+
+   Please let me know if you want to start code some driver.
+
+
+File: xaosdev.info,  Node: gui-driver,  Next: eui,  Prev: driver,  Up: Top
+
+Writting GUI driver
+*******************
+
+   XaoS have builtin GUI. Many operating systems have native gui
+toolkits and XaoS default GUI might look strange there. To avoid this
+problem, you might write external gui program (see eui section) or
+write mappings of XaoS GUI functions. The advantage of external gui
+process in multitasking.  XaoS is not thread safe and GUI must be
+synchronous with calculation.  Also ugly interface code currently don't
+support multiple windows (this should be solved in future).  This
+solution is suitable mainly for those systems, where cooperation of two
+programs sharing one window should be problem (like on Windows).
+
+   To write gui driver you need to fill following structure:
+     struct gui_driver
+     {
+        void (*setrootmenu)(struct uih_context *c, char *name);
+        void (*enabledisable)(struct uih_context *c, char *name);
+        void (*menu)(struct uih_context *c, char *name);
+        void (*dialog)(struct uih_context *c, char *name);
+        void (*help)(struct uih_context *c, char *name);
+     };
+
+   All function have `uih_context' parameter. You don't need to worry
+about it's contents. Just pass it to the called functions that require
+it. This parameter is for multiple window support, that is not
+implemented yet.
+
+   The `setrootmenu' function expected to draw root menu according to
+the menu called `name'. To get menu fields you might use following
+piece of code:
+     #include <ui.h>
+     #include <xmenu.h>
+     
+     ....
+     
+     int i;
+     menuitem *item;
+     for (i = 0; (item = menu_item (name, i)) != NULL; i++)
+        {
+           if (item->type == MENU_SUBMENU) {
+     	      /* This field is submenu. You might call here
+     	         function to construct submenu. item->shortname contains
+     		 name for submenu */
+           }
+           /* add menu field here.
+     
+              You might check flags here:
+              item->flags&MENUFLAG_CHECKBOX
+     	   field have beckbox
+              item->flags&MENUFLAG_RADIO
+     	   field is part of radio button group. In current implementation
+     	   there is one radio button group per menu.
+     
+     	 in both cases you might call: menu_enabled(uih, item) to see
+     	 if item is checked or not.
+     
+              item->name contains field's text
+     
+     	 item->key contains hotkey (one letter string in current
+     	 implementation)
+        }
+   Once field is selected, call function `ui_menuactivate(item, NULL)'
+where `item' is pointer to `menuitem' record of selected field.
+
+   Function `enabledisable' is called when checkbox or radiobutton
+state is changed. The `name' parameter match to `item->shortname' of
+changed field.  So you need to browse all created menus, compare
+`item->shortname' and in case it match, call `menu_enabled' to obtain
+new state. For radiobuttons only enable events are noticed. Your code
+is expected to automatically disable all other radiobuttons in the same
+submenu.
+
+   function `menu' works in similar way to `setrootmenu' but displays
+popup menu.
+
+   Function `dialog' is called for dialogs. The function should look
+like:
+     menuitem *item = menu_findcommand(name);
+     menudialog *dialog = menu_getdialog(uih, item);
+     int i;
+     for(i=0; dialog[i].question; i++)
+     {
+        /* Construct dialog, where left side contains labels with
+         dialog[i].question. Right side contains input entities based on the
+         dialog[i].type. Dialog[i].type is one of the following:
+     
+         DIALOG_INT: integer value input. The default value is: dialog[i].defint
+         DIALOG_FLOAT: floating point input value (long double, where availble
+         exact). Default value is dialog: dialog[i].deffloat
+         DIALOG_COORD: complex value floating point input (two floats), default
+         values are dialog[i].deffloat and dialog[i].deffloat2
+         DIALOG_STRING: string input. default value is dialog[i].defstr
+         DIALOG_IFILE: input file
+         DIALOG_OFILE: output file
+              default mask is dialog[i].defstr
+         DIALOG_CHOICE: choice between various strings.
+              retype dialog[i].defstr to char ** to get pointer to NULL terminated
+     	 array of the choices.
+     }
+   Once dialog is filled by user, gui_driver is expected to allocate
+array of union `dialogparam' `dialogparam':
+     dialogparam *p = calloc (sizeof (*p), nitems);
+   fill selected values. `p[i].dint' is used to pass integer value, or
+number of DIALOG_CHOICE selection, `p[i].number' is used for floating
+point number, `p[i].dstring' for strings and filenames,
+`p[i].dcoord[0]' and `p[i].dcoord[1]' for complex values.
+
+   The string values are expected to be in separate malloced chunks.
+Once array is filled, call `ui_menuactivate(item, p)'.
+
+   The function `help' is used to display help about given topic.  To
+implement it you might eighter convert XaoS help file to some native
+format, or use xshl library to render help page for you. To render xshl
+page use:
+     #include <xshl.h>
+     xshl_line *lines;
+     int getwidth (void *data, int flags, char *text)
+     {
+     	return width of text with given flags
+     	flags is mask of the following:
+              XSHL_BIG - large text
+              XSHL_EMPH - emphatized text
+              XSHL_MONOSPACE - monospaced text (typewriter)
+              XSHL_LINK - line (should be underlined or so)
+              XSHL_WHITE
+              XSHL_RED
+              XSHL_BLACK - color of text (not very meaningfull here)
+              XSHL_RIGHTALIGN
+              XSHL_CENTERALIGN - alignment of the text
+     
+     }
+     lines = help_make (name, getwidth, textheight, largetextheight);
+     if (lines == NULL)
+       lines = help_make ("main", getwidth, textheight, largetextheight);
+   Now you might use `lines' to draw the help. It is pointer to the
+arraw of structures:
+     struct xshl_line {
+       int y;
+       struct xshl_item *first;
+     };
+   `y' is possition of the line from beggining of text and first is
+pointer to the blocks of texts on the line. Last line contains NULL
+pointer in the first section.
+
+   `first' is linked list of the structures:
+     struct xshl_item {
+       struct xshl_context c;
+       char *text;
+       int x;
+       int width;
+       struct xshl_item *next;
+     };
+
+   you might draw text `text' on the possition `x' (and `y' from the
+line record) using style described by `xshl_context':
+     struct xshl_context {
+     	  int flags;
+     	  char *linktext;
+     };
+   `flags' have same meaning as in `getwidth' section. `linktext' is
+name of the next help page in case field have XSHL_LINK atribute.
+
+   As an example of `gui_driver' see win32 driver code.
+
+
+File: xaosdev.info,  Node: eui,  Next: ui-helper,  Prev: gui-driver,  Up: Top
+
+Writting an external user interface
+***********************************
+
+   This part describes, how to make an external user interface--it is
+the separate program, which makes an window with all menus and dialogs.
+It uses XaoS engine for calculating the fractal as separate process.
+This design brings many advantages--the external GUI implementation
+should have an "native look" for given platform and should contain many
+extensions, such as multiple windows etc. Also all calculation are done
+in the multitasking and user interface is usable even when engine is
+busy.
+
+   The X window provides a way, when program draws into other's
+window--"master" program creates window and sub-window, where he wants
+to have fractal, then calls engine with `-windowid' NUMBER_OF_WINDOW
+parameters. It instead of creating new window uses specified window.
+Most famous example of such cooperation is probably
+ghostscript/ghostview.
+
+   Other windowed environments probably provides similar way for
+cooperation. At others it should be implemented using shared memory, so
+it should work at most platforms, I expect.
+
+   Of course, you might also design UI as separate button box in
+another window, like most of animation players, or Imagemagick have. In
+fact external GUI should be very similar to Imagemagick style.
+
+basic concept
+=============
+
+   The UI implementation has function to disable it's GUI functions.
+Because of the function registry, all it's menus and dialogs are
+described in the fairly simple database. This database is mapped also
+to the scripting language similar to scheme. So the external UI
+implementation just translate the actions into this scripting language
+and sends it trough pipe.
+
+   This commands should be created automatically from the database, as
+well as menus and dialogs, so UI don't need to have special code for
+various XaoS features. At the beginning it should use XaoS' command
+`(print_menus)' to force him to send information about database, then
+build menus using this information.
+
+   For this you need just some equivalent to UNIX pipes, so again I
+expect it is doable at most platforms.
+
+starting XaoS as slave process
+==============================
+
+   One of the first thinks, engine needs to do is to initialize XaoS in
+right mode to work as slave process. For this you need to do several
+thinks:
+
+   * Open the pipe
+
+   * Disable builtin GUI
+
+   * Read menu hierarchy (this is optional--GUI can also have all menus
+     coded into it. But it is not recommended, since it will make
+     problems with future adding new features)
+
+   Opening pipe is done via `-pipe' option. It takes one parameter,
+which is name of FIFO you want use. If you specify "`-'", XaoS will
+read input from stdin.
+
+   To disable XaoS GUI use option `-nogui'. This will disable all menus,
+dialogs and help text.
+
+   To read menu hiearchy just add `-print_menus' parameter and then
+parse XaoS's output. This will print the whole hierarchy. In case you
+are building menus at the time, they are selected, you might prefer
+usage of the command `print_menu'. It prints just one menu without it's
+sub-menus, so it's output should be directly used for building it. It
+takes one string parameter, which is name of menu you want to print. To
+print root menu use `"root"'.  Option should look like this:
+`-print_menu root'.
+
+   Under X Window you need also specify the `-windowid'. Also the
+`-shared' is quite recommended. Otherwise in pseudocolor visuals XaoS
+will create it's own colormap, wich will most probably collide with
+UI's colormap and XaoS or UI will have false colors. If you have any
+idea, how to avoid this, let me know.
+
+   You might also let user to specify some extra parameters from the
+command line. You should simple add the to the end of command line. The
+`-nogui' and `-print_menus' commands must be first for the simple
+reason: XaoS parses it's command line in the early initialization
+stages. Some commands (like `-print_menus') should be processed at this
+time, while others (like `-loadpos' needs to have working engine. This
+commands are queued and processed later, once engine is  initialized.
+In case some such command is before `-print_menus' XaoS will decide to
+keep same order of commands, so it will queue `-print_menus' too. This
+will case, that menus will be printed much later and startup will be
+slower.
+
+   So the proper calling sequence for the user interface under X should
+look like:
+
+     xaos -nogui -print_menus -windowid <id> -share -pipe - [OTHER OPTIONS]
+
+Parsing the menu structure
+==========================
+
+   The structure is printed menu by menu. Each menu contains an header,
+some entries and `endmenu'. Whole listing from `print_menus' is
+terminated by `endmenus'.
+
+   The header starts with `menu' and then contains an identifier of menu
+and full name. Such as:
+
+     menu "fractal" "Fractal"
+
+   Then each entry has its own line. It starts by type, which should be
+`submenu' or `menuentry'.
+
+   `submenu' has similar format to header--fullname of menu and
+identifier.
+
+   `menuentry' adds next few fields. It has an type of entry, which
+should be `normal', `radio' or `checkbox'. `radio' and `checkbox' are
+followed by `on' or `off' specifying whether it is enabled or disabled.
+The radio-buttons don't have explicit information about groups they
+belongs to. For now I just expect, that each menu contains just one
+such group, so it is clear.
+
+   Then set of flags should follow. Currently two flags are defined.
+`dialog', wich specifies, that function has dialog, and
+`dialogatdisable'. By default, dialog for check-boxed functions are
+displayed just in case they are enabled. The second flag reverses this
+behaviour. It is now used for `mandlebrot' function, which behaves in
+this style. When you disable it, user is prompted for the Julia seed.
+
+   So specification should look like this:
+
+     menu fractal "Fractal"
+     submenu "formulae" "mformula"
+     submenu "Incoloring mode" "mincoloring"
+     submenu "Outcoloring mode" "moutcoloring"
+     submenu "Plane" "mplane"
+     submenu "Palette" "palette"
+     menuentry "Mandelbrot mode" "uimandelbrot" checkbox off dialogatdisable dialog
+     menuentry "Perturbation" "uiperturbation" checkbox off dialog
+     menuentry "View" "uiview" normal dialog
+     menuentry "Reset to defaults" "initstate" normal
+     endmenu
+
+Activating functions and dialogs
+================================
+
+   Once the menu structure is built and user selects some item, it
+should be activated. It is done by simple command: `(NAME)'. Once "`)'"
+is sent, command is executed by XaoS.
+
+   Check-boxed functions has one extra parameter--`#t' to enable them
+and `#f' to disable. So if you want enable item `autopilot' send:
+`autopilot #t'
+
+   Radio-buttons don't have any such special parameter--because
+disabling radio-button is nonsense.
+
+   In case, item has flag dialog enabled, engine expects that UI will
+make dialog first, ask user of values and then call function with
+parameters.  UI needs first to know, what parameters function expect.
+It is done by sending command `(print_dialog "NAME")'.  XaoS replies
+with dialog specification very similar to menu specification.
+
+   It has header `dialog' followed by the name of function. Then one
+dialog entry per line is sent. it is started by `dialogentry' followed
+by question UI should display. The is type, which should be one of the
+following:
+`integer'
+     Integer number such as `123'
+
+`float'
+     Floating point number such as `123.123'
+
+`string'
+     String such as `"ahoj"'
+
+`keyword'
+     String such as `'ahoj'. The keywords are mostly similar to string,
+     except they can not contain space. They are used for example for
+     specifying formula type. Strings are used for printing texts etc.
+
+`inputfile'
+
+`outputfile'
+     Here UI should display file selection dialogs. With `outputfile'
+     it is also good idea to check, whether file exist and in this case
+     make some overwriting dialog too.
+
+`onoff'
+     Boolean value (`#f', or `#t')
+
+`complex'
+     Complex value--two floating point numbers such as `123.123 123.123'
+
+`choice'
+     Choice between some keywords. Those keywords are send after
+     `choice' in enclosed the `{' `}'.  Last information at the line is
+the default value in the same format as examples above. For files, the
+default value is in format `"[PREFIX]*[EXTENSION]"'.
+
+   Some examples:
+
+     customdialog "uiview"
+     dialogentry "center:" complex 0.000000 0.000000
+     dialogentry "Radius:" float 0.000000
+     dialogentry "Angle:" float 0.000000
+     enddialog
+     
+     dialog "load"
+     dialogentry "Filename:" inputfile "fract*.xpf"
+     enddialog
+     
+     customdialog "color"
+     dialogentry "Color" choice {white black red }white
+     enddialog
+
+   To activate function, send command which contain function name,
+possible `#t'/`#f' in check-boxes and parameters in the same order as
+in dialog, same format as in examples, separated by the space. Such as:
+
+     (uiview 0 0 0.5 0)
+     (load "text.xpf")
+     (color 'white)
+
+Synchronization
+===============
+
+   In some cases, XaoS can change radio-box and check-box values. (like
+when user pressed a key, or loaded some file). So all changes are sent
+to GUI, wich should inform about this. They are sent to standard output
+in following format:
+
+     checkbox "name" on/off
+     radio "name" on/off
+
+   So your GUI should parse this and change it's menus when necessary.
+
+   Also XaoS's menus can contain more distinct trees. In some cases
+(like when animation replay is active) root of menu structure should
+change. The XaoS sends command:
+
+     root "name"
+
+   Also user can press keys, which normally displayed menus, dialogs or
+help. Then XaoS sends commands:
+
+     menu "name"
+     dialog "name"
+     help "topic"
+
+   All this commands should be taken into account by GUI, or should be
+ignored.
+
+help
+====
+
+   XaoS's help is in the simple hypertext language. In order to
+simplify it's parsing I've made an xshl and help libraries. So making
+of help window should be quite easy. Just call help function:
+
+ - Function: struct xshl_line *help_make (char *COMMAND, int GETWIDTH
+          (void *, int FLAGS, char *TEXT), int WIDTH, int SMALLHEIGHT,
+          int BIGHEIGHT);
+   and you will receive of listings of text with positions, where to
+print into window.
+
+   `command' parameter is topic of help. `getwidth' function is
+function, wich returns width of given text. `width' is width of window,
+`smallheight' is height of small font and `bigheight' is height of big
+font.
+
+   Please ask me for more details if necessary.
+
+   And thats all. Good luck with coding.
+
+
+File: xaosdev.info,  Node: ui-helper,  Next: xthreads,  Prev: eui,  Up: Top
+
+UI-helper library
+*****************
+
+   UI helper library takes care to all XaoS' engine functions and
+features and gives the higher level API, which is quite easy to
+understand. If you want to write completely new user interface
+(replacement for the ugly interface--not just new bindings for native
+menus or external user interfaces) or you want to use XaoS engine in
+your program as an library, you will probably want to use this library.
+
+   It's API has many calls and features. This section gives just brief
+overview of it's calls. Please ask me about details.
+
+initialization
+==============
+
+   To initialize ui helper library, you need to prepare an palette and
+image.  Palette is created using palette library calls `createpalette'.
+Creating truecolor palette should look like this:
+
+       struct palette *pal = createpalette (0, 0, TRUECOLOR, 0, 0, NULL,
+                                            NULL, NULL, NULL);
+
+   For details about creating palettes see `ui.c' or ask me.
+
+   To create image call:
+
+       struct *image img = create_image_mem (width, height, 2, pal,
+                                             pixelwidth, pixelheight);
+
+   This creates image in the memory. If you want to create it in your
+own buffers, you might use `create_image_cont' or `create_image' calls.
+Again see `ui.c'.
+
+   Then it is time to fire up main library:
+
+       struct uih_context *uih = uih_mkcontext (0, img, passfunc,
+                                                NULL, NULL);
+
+   The `passfunc' is called when engine is calculating. It might process
+events and display process information. It should look like this:
+
+     static int
+     ui_passfunc (struct uih_context *c, int display, char *text, float percent)
+     {
+       /*process events */
+       if (uih->display)
+         {
+           uih_drawwindows (uih);
+           /*display */
+         }
+       if (display)
+         {
+           if (percent)
+     	sprintf (str, "%s %3.2f%%        ", text, (double) percent);
+           else
+     	sprintf (str, "%s          ", text);
+           /*display it */
+         }
+     }
+   It might set `uih->interrupt', if it wants to interrupt current
+calculation.
+
+   You also might load the catalog file in order to make tutorials
+working:
+
+       uih_loadcatalog (uih, "english");
+
+   Since this ui_helper library is fully functional and you might enter
+the main loop.
+
+main loop
+=========
+
+   UI helper library does an timing primitives. So it expect an
+standard form of the main loop. It asks the program to display changed
+image when necessary.  Library also use timerlib for it's timing. So
+read section about this library, since you might use it for your
+purposes too.
+
+   Main loop should look like this:
+
+     while (1)
+       {
+         if (uih->display)
+           {
+     	uih_prepare_image (uih);
+     	uih_drawwindows(uih);
+     	/*display current image buffer*/
+           }
+         uih_update (uih, mousex, mousey, buttons);
+         if ((time = tl_process_group (syncgroup, NULL)) != -1 &&
+     	    !uih->inanimation) {
+     	    /*relax given time in usec - wait of events etc..*/
+         }
+         /*and repeat*/
+       }
+
+calling functions
+=================
+
+   UI helper library has many functions declared in `ui_helper.h' for
+various actions. There is too much of them to describe, but their names
+are quite informative, so I hope you will not have problems.
+
+   You might also use XaoS function registry, which does all this stuff
+for you.  You will just draw menus and dialogs based at this registry
+and automatically all features will be available. So if you are writing
+an ordinary user interface, this is the preffered way.
+
+   Note that `ui_helper' library is not reentrant, so you can't call
+most of this function from the `passfunc'. If you are using registry,
+activating function handles this automatically and queues functions
+when necessary.  To process them you need to flush queue in the main
+loop as follows:
+
+     static void
+     processbuffer (void)
+     {
+       menuitem *item;
+       dialogparam *d;
+       if (uih->incalculation)
+         return;
+       while ((item = menu_delqueue (&d)) != NULL)
+         {
+           menu_menuactivate (item, d);
+         }
+     }
+
+closing library
+===============
+
+   This is done using:
+
+       uih_freecontext (uih);
+
+   One implementation of user interface at the top is ugly interface.
+See dirrectory `src/ui'. Another, much simpler is `render.c', which does
+animation rendering.
+
+
+File: xaosdev.info,  Node: xthreads,  Next: filters,  Prev: ui-helper,  Up: Top
+
+XaoS thread library
+*******************
+
+   This description should be useful for those, who want to port XaoS
+into multiprocessor platforms and those, who want to implement some
+filter or other relatively computational expensive code. Note that
+thread library should be mapped into nothread calls, in case host does
+not allows multi-threading or it is not SMP architecture (since this
+library is used only to distribute calculation into other CPUs)
+
+   XaoS thread library is simple map of few functions required by XaoS
+to system library for threads.
+
+   It has following variables:
+
+ - Variable: ethreads
+     This is set to 1 in case that threads are enabled
+
+ - Variable: nthreads
+     Number of threads
+
+   It and following calls:
+
+ - Function: void xth_init (int THREADS)
+     This function initializes threading library (starts threads, sets
+     ETHREAD to 1 and NTHREADS to n. THREADS parameter should be set to
+     0--auto-detection or number of threads users wants. In case threads
+     is set to 1, threading library is disabled and following functions
+     are mapped into those nothread_ equivalents defined in `xthread.h'.
+
+     Note that threads are not identical--there is main thread (one
+     that called xth_init) that communicates with drivers, controls
+     calculation etc. and other tasks that are waiting to orders from
+     main task. They also can't use functions from xthread library.
+
+ - Function: void xth_uninit (void)
+     This function UN-initialize thread library--kills child threads,
+     sets ETHREAD to 0 and NTHREADS to 1.
+
+ - Function: void xth_function (xfunction *FUNCTION, void *data, int
+          RANGE)
+     This function is used in case, engine wants to perform some
+     operation at image in parael. It is expected to wait until all
+     threads are ready and start FUNCTION at all threads including
+     control one with following parameters: DATA--this parameter is
+     same as DATA passed to xth_function, TASKINFO--pointer to structure
+     taskinfo, that is platform depended (defined in `xthread.h') but
+     must have at least field `n', that holds number of thread (control
+     thread has 0 and other numbers in range 1 - NTHREADS). Next two
+     parameters is range of image, function is expected to do action.
+     Xth_function is expected to divided RANGE into NTHREADS equal
+     pieces and pass always start of piece and start of next piece
+     (RANGE in case of last one). Function does not wait for other
+     threads at the end and returns immediately to main thread after
+     FUNCTION returns.
+
+     This function is called approx. 5-10 times per frame
+
+ - Function: void xth_sync (void)
+     This functions waits until all threads are ready for next order
+     from main task.
+
+     This function is called approx 5-10 times per frame
+
+ - Function: void xth_bgjob (xfunction *FUNCTION, void *DATA)
+     This function is expected to behave as follows: look if there is
+     any thread waiting for orders, if so, ask him to call FUNCTION
+     with similar conventions as in xth_function except that range
+     parameters are set to 0.  Otherwise it starts function in normally
+     (at foreground).
+
+     This function is called once per frame.
+
+ - Function: void xth_nthread (struct taskinfo *S)
+     This function should be used to determine number of current
+     thread. Do not use `taskinfo->n' instead since in case threads are
+     disabled, it should be defined to 0 and that allows optimizer to
+     perform better optimizations.  This function should be called by
+     all threads.
+
+ - Function: void xth_lock (int N)
+
+ - Function: void xth_unlock (int N)
+     Lock/unlock lock number N. At least `MAXSEMAPHORS' locks must be
+     available.
+
+     Note that locks are used always for very short fragments of code
+     so they needs to be fast. So spin-locks are maybe better than
+     Dijskra semaphores.  Untested. They are called once per calculated
+     line/row during zoom and once per approx 10 pixels during
+     calculation of new image.
+
+ - Function: void xth_sleep (int N, int L)
+     It is expected to atomically unlock lock L and sleep in queue N.
+     At least `MAXCONDS' queues must be available.  After it is waked
+     up, lock L again. This mechanism is used by calculation of new
+     image algorithm, but it is designed to minimize its calls, so I
+     expect they should be called once or twice.
+
+ - Function: void xth_wakeup (int N)
+     Wake up some thread from queue N. Lock used by sleep calls is
+     locked in this cases. Function should also wake up all threads if
+     such operation is not supported by host API. With luck, this
+     function should not be called at all. It should be called by new
+     image calculation routines in case queue is empty. This happens in
+     case of 50 threads but happens rarely at two or eight threads
+     according to my tests.
+
+ - Function: void xth_wakeall (int N)
+     Similar to wakeup but wake up all threads.
+
+
+File: xaosdev.info,  Node: filters,  Next: algorithm,  Prev: xthreads,  Up: Top
+
+Filters
+*******
+
+   This is a brief description of filter system used internally by XaoS.
+Filters in XaoS provides an object oriented interface to every part of
+XaoS engine. Main filters are: User interface implemented in ui_helper.c
+and zooming engine implemented in zoom.c. Filters are connected into an
+queue--at the beginning there is just two filters here(zoom and ui) but
+later additional filters should be inserted into the middle of queue
+like an stereo-gram generation etc. The queue supports operations like
+remove filter, add filter and initialize.
+
+   In the calculation every filter should use data calculated by filter
+lower in the queue. Data are stored into image. So for example
+stereo-gram filter should use fractal generated by zooming engine and
+create an stereo-gram.
+
+   This makes XaoS's code more flexible and makes easy future
+enhancements like different zooming engine, image rotation, other
+special effects, plug-ins and some other funny stuff since interface of
+each such part is well defined and each filter has quite good control
+over his child.  So stereo-gram filter should change palette, force
+zooming engine to change depth, width and height of calculated image to
+fit his needs and so on.
+
+   This document describes mainly creating of filter like stereo-gram
+generator i.e. filter placed into middle of queue since I don't expect
+there will be many people creating "terminal" filters (zooming
+engines/user interface layer) note that different user interface is
+possible since user interface layer is not the real user interface just
+set of high level functions that should be called by main application
+like set_view. So in case you want to use XaoS as an calculation engine
+in your program this document is probably not for you.
+
+   Each filter is defined by filter_action structures as follows:
+     struct filteraction {
+       char *name;
+       char *shortname;
+       int flags;
+       struct filter *(*getinstance)(struct filteraction *a);
+       void (*destroyinstance)(struct filter *f);
+       int (*doit)(struct filter *f,int flags,int time);
+       int (*requirement)(struct filter *f,struct requirements *r);
+       int (*initialize)(struct filter *f,struct initdata *i);
+       void (*convertup)(struct filter *f,int *x,int *y);
+       void (*convertdown)(struct filter *f,int *x,int *y);
+       void (*removefilter)(struct filter *f);
+     };
+   This structure describes static filter's parameters (like its name)
+and basic set of methods required for communication with resto of XaoS.
+The name field describes filter's name like "An random dot stereo-gram
+generator". Name is displayed by ugly interface in filter's menu. So it
+is expected to be descriptive and shorter than 30 characters. The short
+name is one word long name for filter like "stereogram". This name is
+used by save files, possibly by command line parameters. Simply
+everywhere where user should need to write it and writing long
+descriptive name should be just wasting of time and disk space.
+
+   Flags field is kept for future enhancements and is expected to be 0
+for now.
+
+Creating / destroying of instance
+=================================
+
+   Functions getinstance and destroyinstance are equivalents to
+constructor and destructor in OOP. Getinstance is expected to create
+and fill following structure:
+
+     struct filter {
+       struct filter *next,*previous;
+       struct queue *queue;
+       struct filteraction *action;
+       struct image *image,*childimage;
+       struct requirements req;
+       struct fractal_context *fractalc;
+       void *data;
+       char *name;
+       int flags;
+       void (*wait_function) (struct filter *f);
+       /*stuff for wait_function*/
+       int pos,max,incalculation,readyforinterrupt,interrupt;
+       char *pass;
+     };
+   Altrought this structure seems to be long and complex, most of
+fields are unused at this time and rest of them are filled
+automatically by function:
+
+ - Function: struct filter * createfilter (struct filteraction *FA);
+     That should be used to create instance. Only possibly interesting
+     field is data. It's pointer reserved for filter's internal use. So
+     it should be pointer to filter's internal variables if required.
+     Following is example implementation of get-instance with
+     allocating of such additional structure. In case nothing similar
+     is required you should use directly createfilter at getinstance's
+     place.
+
+     static struct filter *getinstance(struct filteraction *a)
+     {
+           struct filter *f = createfilter(a);    /*create filter structure*/
+           struct stereogramdata *i=calloc(sizeof(*i),1);
+                                                  /*allocate internal variables*/
+           /*initialize your variables here*/
+           f->data=i;                             /*add pointer to internal data*/
+           return (f);
+     }
+
+   The destroyinstance is expected to free memory used by filter
+structure and all internal data of filter. To free filter structure use
+normal free(filter); So implementation of such function should look
+like:
+     static void destroyinstance(struct filter *f)
+     {
+          destroyinheredimage(f);
+          free(f->data);
+          free(f);
+     }
+   The meaning of destroyinheredimage will be described later.
+
+Initialization
+==============
+
+   During initialization phaste each filter says to his parent what kind
+of images it supports (this should depend on images supported by his
+child), parent chooses best supported image format for his purposes and
+gives it to the child. Initialization is done in two pases.
+
+   First pass start by lowest filter in the queue and each filter
+passes to his parents requirement structure.
+
+   Second pass starts by the highest filter and each filter passes to
+child an image and some other stuff. Then calculation should begin.
+
+   Queue needs to be reinitialized after creating, resizing,
+adding/removing of filter and similar operations.
+
+   First pass is implemented using require function. This function is
+expected to take care at child's requirements it received as parameter,
+fill requirements structure and call require function of his parent
+filter.
+     struct requirements {
+       int nimages;
+       int supportedmask;
+       int flags;
+     };
+   The nimages field should be set to 1 or 2. In case it is 2, parent
+filter must pass image with two buffers. Note that in case it is 1,
+parent should pass image with two buffers too.
+
+   Supported mask is mask of supported image types by filter. Image
+types are following:
+`C256'
+     An normal 8bpp image with palette
+
+`TRUECOLOR24'
+     An 24bpp truecolor image with 8bits for each color.
+
+`TRUECOLOR16'
+     An 16bpp truecolor image
+
+`TRUECOLOR'
+     An 32bpp truecolor image with 8bits for each color.
+
+`LARGEITER'
+     An 16bpp image but w/o colors. It is expected to hold number of
+     iterations   it should be also tought as 16bpp grayscale image
+
+`SMALLITER'
+     Similar to `LARGEITER' but 8bpp
+
+   In case you don't worry about palettes, allocations of colors and
+you do just some operation with bitmap, so you worry just about depth
+of image you should use mask of following: `MASK1BPP' for 8 bit images,
+`MASK2BPP' for 16bit and so on.
+
+   The latest field of requirements structure is flags. It mask from
+following constants:
+
+`IMAGEDATA'
+     in case your filter requires data from previous frame untouched.
+     In case   this is not set, filters should reuse your image and
+     change it. But some   filters like and motion blur or zooming
+     engine requires data from previous   frame to construct new, so
+     this flag should be set there is no more flags supported at the
+moment. Function require should also save child's require structure
+into filter->req for later use by initialize pass. So you should look
+like:
+     static int requirement(struct filter *f,struct requirements *r)
+     {
+       f->req=*r;    /*Save an child's requirements*/
+       r->nimages=1; /*Just one image is required*/
+       r->flags&=~IMAGEDATA;/*unset the imagedata field*/
+       r->supportedmask=C256|TRUECOLOR|HICOLOR|REALCOLOR;
+                     /*mask of all supported image types*/
+       return (f->next->action->requirement(f->next, r));
+                     /*call parent*/
+     }
+   Next pass is main initialization. It goes in opposite order(from
+parent to child) and child's infers some stuff from parent like images
+etc...  The initialize structure receives an initdata structure:
+     struct initdata {
+       void (*wait_function) (struct filter *f);
+       struct image *image;
+       struct fractal_context *fractalc;
+       int flags;
+     };
+   an wait_function is function called by filter during calculation that
+lets the parent filters(usually user interface layer) to inform user
+how calculation continues. Image is an image expected to be filled by
+image in calculation phaste. Fractalc is pointer to structure that will
+contain information about fractal during calculation(like formula type
+etc...) Flags is mask of following constants:
+`DATALOST'
+     this is set in case, that data in image was lost(image was cleared
+     or  resized or freshly allocated). Filters that uses data from
+     previous frames  should take care to this flag. Zooming engine for
+     example recalculates  whole image since pixels from previous frame
+     was lost.   Note that data should be lost also in case, filter
+     receives different  image that in previous initialization since
+     some filter behind was  removed.  An inhering process is done
+using function:
+
+ - Function: void inhermisc (struct filter *F,struct initdata *I);
+     This function sets fields in filter structure like as fractalc or
+     wait_func.  Inhering of image is quite complex, since new image
+     needs to be prepared for child. In order to save memory it is
+     highly recommended to use same image or at least same memory for
+     data when passing to child. But this is not allays possible.
+     Following function implements heuristic to do this:
+
+ - Function: int inherimage (struct filter *F,struct initdata *DATA,
+          int FLAGS, int WIDTH, int HEIGHT, struct palette *PALETTE,
+          float PIXELWIDTH, float PIXELHEIGHT)
+     You should call this function in your initialize pass. It fills
+     image and childimage in filter structure, prepares initdata for
+     child and creates image for child. Note that it should fail in
+     some cases and return 0. In this case filter is expected to
+     interrupt initialization and return 0 too.
+
+     An FLAGS parameter is mask of following constants:
+    `IMAGEDATA'
+          in case your filter requires data from previous frame
+
+    `TOUCHDATA'
+          In case your filter touches data in output image. This is
+          very usual but   there is some filters (like interlace or
+          subwindow that don't)
+
+    `NEWIMAGE'
+          Set in case your filter can not deal with shared images
+          (images that have   input data in same memory are as output)
+     WIDTH and HEIGHT should be set to 0 in case you want same
+     width/height as in parent image or width and height of image you
+     want to pass to child.  PALETTE is palette of image you want to
+     pass. Set to `NULL' if palette should be inhered from parent's
+     image (usual).  PIXELWIDTH and PIXELHEIGHT specifies physical size
+     of pixel in centimeters.  If set to 0 they are inhered from
+     parent's image.
+
+   In case you use inherimage mechanism you also must call
+destroyinheredimage in destroyinstance function and updateinheredimage
+at the beginning of calculate function.
+
+   Example implementation:
+     static int initialize(struct filter *f,struct initdata *i)
+     {struct stereogramdata *s=f->data;
+       inhermisc(f,i);
+       if(!inherimage(f,i,TOUCHIMAGE,0,0,NULL,0,0) return 0;
+       /*initialize here*/
+       return(f->previous->action->initialize(f->previous,i));
+     }
+   Also note that fractal context hold pointer to fractal palette. In
+case You don't change image palette everything is OK. But in case
+child's image differs from parents image, there should be two
+behaviors--fractal's palette is child one (this should be common for
+example in conversion filters ( 8bpp to truecolor etc)) or fractal's
+palette is parent's one (like in edge detection filter). By default
+fractal's palette is kept to parent's one.  This should be changed by
+setfractalpalette call. It has two parameters--filter structure and
+palette. When you pass as palette child's palette, fractal's palette
+will be changed to child. In case you pass NULL. Changing of palette
+will be disabled (like in motion blur filter in 8bpp mode).  Note that
+this is changed just in case you still have access to fractal palette.
+Some parent should redirect palette before. Than this function does
+nothing.
+
+Caluclation
+===========
+
+   Main calculation is done using doit function. It is expected to call
+child's calculation function when required and apply filter at output.
+It receives flags. Only flag in `INTERRUPTIBLE' for now. It is mainly
+for zooming engine so I do not describe it here. But filter is expected
+to pass this flag to child. Next parameter is time in milliseconds that
+expired since last doit call. It should be used to calculate speed of
+animation.
+
+   Calculation loops returns flags. Flags is mask from following
+constants:
+`ANIMATION'
+     in case filter performs some animation and expect that calculation
+     will be  called again soon
+
+`CHANGED'
+     in case something changed in output image (usual)
+
+`INEXACT'
+     This is enabled by zooming engine in `INTERRUPTIBLE' mode in case
+     that time  exceeded.
+
+   An doit function changes image. Image structure contains following
+fields significant for you:
+`bytesperpixel'
+     number of bytes per pixel (image depth)
+
+`palette'
+     palette of image.
+
+`currlines'
+     array of pointers to beginnings of every scanline of image
+
+`oldlines'
+     array of pointers like currlines but for previous image in case
+     doublebuffering is enabled
+
+`nimages'
+     set to 2 in case doublebuffering is active
+
+`flipimage'
+     pointer to function that flips oldlines and currlines.
+
+   palette structure contains following significant fields:
+
+`type'
+     type of palette/image (`C256', `TRUECOLOR' etc...)
+
+`size'
+     number of allocated entries
+
+`pixels'
+     array of allocated entries. Conversion table from number of
+     iteration  to pixel value.
+
+`rgb'
+     Rgb values for pixels (`NULL' for `TRUECOLOR', `HICOLOR' and
+     similiar types)
+
+   To make easier writing calculation loops for different depths
+`pixel8_t', `pixel16_t' and `pixel32_t' are predefined. You also can
+use include system as in edge detection filter, that lets you write
+calculation loops just once and use cpixel_t and it will be compiled
+for every bitmap depth.  See edge detection filter (engine/edge.c and
+engine/edged.c) for implementation details.
+
+Conversion
+==========
+
+   Convertup and convertdown functions are used for converting screen
+coordinates to position in fractal and back. Convertup is function that
+receives coordinates in child's image and is expected to convert them
+into coordinates in parents image and call parent's convertup function.
+
+   Convertdown is reversed(from parent to child).
+
+   In case coordinates respond 1:1 you should use convertupgeneric and
+convertdowngeneric. In other case implementation should look like:
+
+     static void convertup(struct filter *f,int *x,int *y)
+     {
+         *y*=2;
+         *x*=2;
+         if(f->next!=NULL) f->next->action->convertup(f->next,x,y);
+     }
+     static void convertdown(struct filter *f,int *x,int *y)
+     {
+         *y/=2;
+         *x/=2;
+         if(f->previous!=NULL) f->previous->action->convertdown(f->previous,x,y);
+     }
+
+Removing of filter
+==================
+
+   Before filter is removed from queue, removefilter function is called.
+It is expected to clean up thinks filter changed. Should be NULL in
+most cases.
+
+Registering of filter
+=====================
+
+   Once filteraction structure is filled, filter is done and you should
+try to enable it. To enable it in user interface you need to edit
+ui/ui_helper.c, add filter into uih_filters structure and increase
+uih_nfilters.  Note that order of filters in uih_filter is significant,
+since same order is kept in filter queue, so you should specify if you
+want to be called before/after filter xy.
+
+   Then it is high time to start experimenting.
+
+   Good luck!
+
+
+File: xaosdev.info,  Node: algorithm,  Next: timerlib,  Prev: filters,  Up: Top
+
+Algorithm description
+*********************
+
+   The main idea behind XaoS is that it is not required to calculate the
+whole image every frame. Most pixels are already calculated in the
+previous frames. You usually don't have exactly the pixels you want,
+but all within a range lower than a step between pixels are acceptable.
+That is why the image flicker a bit and why points do not blink
+randomly as in recalculated animations.
+
+   This document describes some of the most important algorithms in XaoS
+   * Saving Previous Pixels
+
+   * Approximation Algorithm
+
+   * Moving Pixels to New Positions
+
+   * Calculating New Pixels
+
+   * Symmetry
+
+   * Calculation of Mandelbrot Set
+
+   * Dynamic Resolution
+
+   * Autopilot
+
+Saving Previous Pixels
+======================
+
+   Ideally, all recalculated points should be saved and used for
+building successive frames. I could not figure out a practical way to
+implement this. To save all frames for half an hour would require 24 Mb
+of memory, and searching the saved frames would be more computationally
+expensive than recalculating an entirely new frame.
+
+   One way was later used by program Frang. It remembers all pixels as
+x,y and value fields and when it builds new image, it draws all pixels
+to it and then browses image and fills it by new pixels. Possibly some
+rle cache should be used for calculated pixels. Frang actually uses
+algorithm, that takes away pixels out of screen, so it behaves exactly
+in same way as algorihm described here. At the other hand, this method
+seems to require much more memory than XaoS algorithm and drawing
+pixels/browsing image cost quite a lot, so algorithm described here
+seems to be faster. Since it never requires examining of whole image
+and new image is constructed using block move operations.
+
+   For this reason only the last generated frame is used as reference.
+This way the memory requirements are proportional to xsize * ysize. It
+can be shown that this method is only about 2-5% slower during zooming.
+Of course unzooming back to once browsed areas is much slower.
+
+   Because only the previous frame is used, another optimization can be
+performed: Imaginary and real parts of the calculated image are not
+precise since they are the result of successive iterations of same
+algorithm. In order to prevent errors from being distributed to the
+following frames their exact coordinates need to be known.
+Fortunately, it isn't necessary to save their values since it is known
+that all real components in a row and all imaginary components in a
+column are equal. Thus, the only things that must be saved are the real
+components for every row and the imaginary components for every column.
+
+   This allows for a substantial speed-up in approximation because the
+calculation requires less data. Of course, some rows and columns fall
+out of the threshold and new ones need to be calculate to fill in the
+gaps in the frame.
+
+   Obviously, much less work is done. There are only xsize + ysize
+calculations instead of xsize * ysize. So the main loop in XaoS looks
+like this:
+   * Make approximations for rows
+
+   * Make approximations for columns
+
+   * Move old pixels to their new positions
+
+   * Calculate pixels for which there is no good approximation for
+      their row
+
+   * Calculate pixels for which there is not good approximation for
+       their column but there is one for their row
+
+Approximation Algorithm
+=======================
+
+Introduction to problem
+-----------------------
+
+   You can see that the approximation algorithm is central to the
+implementation of XaoS. If the guess is incorrect the image will look
+strange, boundaries will not be smooth and the zoom will flicker. On
+the other hand, if it adds more new rows or columns than required,
+zooming will become much slower. Also, in the instance of doubling
+(i.e., using an old row or column more than once) the resolution will
+lower. It is important to keep the increasing imaginary and real
+components in the correct order. If a row and column of complex
+coordinates follows one with higher coordinate values an improved
+approximation can be attained by swapping their values.
+
+   The algorithm needs to be relatively fast. It is only used for xsize
++ ysize values but if its speed is proportional to O(n^2), it can be
+slower than a whole recalculation of the image. Speeds of O(n) or O(n *
+log(n)) are acceptable.
+
+Some simple algorithms to solve it
+----------------------------------
+
+   Initially, a very simple algorithm was used:
+
+   Find the old row/column nearest the row/column that needs to be
+regenerated. If the difference between them is less than one step
+(step = (end - beginning) / resolution) then use it. Otherwise,
+recalculate a new one.
+
+   Finding the nearest row/column pair is very simple since it is always
+greater or equal to the pair needing to be generated.
+
+   Surprisingly, this simple algorithm has almost all the problems
+described above. Doubling was fixed by lowering the limit to step / 2.
+This cause a considerable slowdown so the limit was returned to step.
+Instead, the algorithm was changed to search for only row/column pairs
+that are greater than the previous frame's row/column pairs. This is
+the algorithm that was used in version 1.0
+
+   This algorithm still added to many new rows and columns and did not
+generate smooth boundaries. For version 1.1 a heuristic was added that
+preferred approximating rows/columns with lower values. This way it did
+not occupy possible rows/columns for the next approximation. The result
+was a speedup by a magnitude of four. In versions 1.1 to 2.0 many
+improvements were made to the heuristic to give it added performance.
+The following example tries to explain how complicated the problem is
+(O is the old coordinates and X is the values to be approximated):
+             X1        X2        X3        X4        X5        X6        X7
+     O1 O2                    O3 O4 O5                   O6 O7 O8
+
+   The normal algorithm will aproximate X1 by O2, X3 by O4 but nothing
+more. For the algorithm with threshold step instead of step / 2:
+
+       O2 to X1
+       O3 to X2
+       O4 to X3
+       O5 to X4
+       O6 to X5
+       O8 to X6
+
+   But this will fail with X7. The second algorithm which relies on
+lower values will do the following:
+
+       O1 to X1
+       O3 to X2
+       O4 to X3
+       O5 to X4
+       O6 to X5
+       O7 to X6
+       O8 to X7
+
+   O1 to X1 is wrong. And there is many and many other situations that
+may occur. But you may see that the normal algorithm will calculate 4
+new rows/columns but the heuristic saves all of these calculations.
+
+Current algorithms used
+-----------------------
+
+   In version 2.1 work on this heuristic was disabled after I discovered
+a surprisingly simple algorithm that solves all these problems. First I
+decided to define exactly what is best approximation. This should be
+done by defining a price for every approximation and choose the
+approximation with the lowest price. Prices are defined as such:
+
+   Approximating row/column x by y costs dist(x, y) ^ 2.
+
+   This prefers two smaller approximation errors before a single larger
+error and describes my goal quite well.
+
+   The cost for adding a new row/column specifies when it is better to
+do a bad approximation and when to add a new row/column. I use (4 *
+step) * (4 * step). This means that the approximation is acceptable when
+dist(x, y) < 4 * step. Otherwise, adding a new row/column costs less.
+Now the best approximation is known. All that is required is a fast
+algorithm to do this. Surprisingly, this is possible in linear time
+using a relatively simple dynamic algorithm. It uses approximations of
+length < n to make a guess at the length of n. It can start by
+approximating one row/column and then again for two, three up to
+xsize/ysize rows/columns.
+
+   The algorithm starts by calculating prices for all possible new
+positions for old row/column 1. Because of the pricing there are
+maximally 8 new positions. (Other ones must cost more than adding new
+row/column). Of course it is possible that there are no new positions.
+
+   For calculating the price of approximations for row/column 2 I may
+use previous one: Try new position n. Calculate the price and add the
+best approximation for the previous (row/column 1) one that uses a new
+position lower than n(prohibits doubling or swapping). This should be
+one of 8 positions or eventually adding of new one and not using
+row/column 1 at all.
+
+   The same method can be used for the rest of the rows/columns. At the
+end the best price may be found for the last row/column and return by
+the way it was calculated. (For this I need the saved "calculated
+using" values.) At this step the best approximation has been determined.
+
+   To fill the table, 9 * n steps are required and n steps to backtrack
+best approximation. The only problem is that this algorithm is still a
+little slow (chiefly because of slow memory access on Intel
+architectures). -But with some optimizing it works well.
+
+   This algorithm is almost perfect except that it occasionally adds new
+rows/columns to the wrong locations. It does not prefer to add new
+rows/columns into holes. But it does not seem that this is the real
+problem. The last optimization made was based upon the face that added
+rows/columns do not have the exact real and imaginary components
+calculated by (beginning + x * step) but lies at the average of left
+and right neighbors. This makes the boundaries smooth and distributes
+coordinates better. It also has the added benefit of making the input
+better for future approximations.
+
+   Another danger during implementation if this algorithm is that
+adding new rows/columns into their ideal positions should cause
+miss-ordered results, since some rows/columns should be off more that
+is distance between them.  To avoid this, I use algorithm that always
+examine start and end of block of new rows/columns and linearly
+interpolates value between them. Special care needs to be at the blocks
+that start at the beginning or overs at the end.
+
+   Implementation should be much faster using custom fixedpoint
+routines--first recalculate values that 0 means start of image and
+65536 means end.  Than calculation is much cleaner. Values <0 and
+>65536 are of screen, calculation is independent at scale and many
+thinks should be recalculated--like tables for calculating price from
+distance.  Also dividing main loops into many specialized parts and
+avoiding filing unnecessary parts of table helps. So current algorithm
+in XaoS is about 5 or 6 times faster than first naive implementation.
+
+Moving Pixels to New Positions
+==============================
+
+   Since XaoS is using the approximation algorithm the following table
+is filled for every row/column:
+   * calculate
+
+   * oldpoint
+
+   * position     calculate is 1 if the current row/column is new and
+needs to be calculated or 0 if no old pixels need to be moved. oldpoint
+is a pointer to the old row/column that corresponds to the new one. This
+pixel needs to be copied to the new location. position is the real and
+imaginary components of the coordinates used for future approximations.
+Because almost all points will be moved, the solution seems to be
+simple: for every new point look at the row and column table; copy it
+if required.
+
+   There is the problem that this minimally needs three memory reads for
+every pixel (read calculate, oldpoint and index of old point). This is
+too slow, so a small optimization is performed. Instead rewriting the
+piece of code in assembly, normal memcpy is used to move blocks of
+pixels to their new locations. This minimizes the internal loop and
+access can be done more quickly since memcpy is usually optimized for
+each architecture.
+
+   Using the row table, a list of blocks to move for every row is
+created. With this new table all the pixels can be moved quickly. This
+increased the speed of XaoS about four times and made this function so
+fast that it is no longer a problem. (In fact, it takes much less
+processing than all other parts of XaoS.)
+
+Calculating New Pixels
+======================
+
+   The above optimizations make XaoS very fast, but another 30% increase
+in speed is acquired by using a clever method for calculating the new
+pixels. Many methods are known for saving calculations during the
+generation of fractal images. The most powerful is boundary detection.
+It relies on the fact that the Mandelbrot Set is connected with lakes.
+You need only one pixel at the boundary, then traverse the whole set
+and then fill the solid area inside. This method saves many
+calculations but is too complex for adding just one line. Many claim
+that it does not introduce any errors, but this is not true. It is
+possible for a connected part of the lake to be so small that it is not
+visible in smaller resolutions. In this case, boundary detection misses
+the whole area. This algorithm is actually used just for calculating of
+new images (i.e. at the startup).
+
+   XaoS uses modification of method known as solid guessing. The pixels
+at the boundaries of a rectangle are calculated. If they are all the
+same you may assume that this rectangle does not does not contain
+anything and fill it.
+
+   This algorithm is further modified to operate on added lines. For
+this it is at least as good as boundary detection and produces more
+tangible errors. When adding a single line, the upper and lower line
+may be examined for the nearest three pixels. If they are all the same
+then it is assumed that 9x9 pixels are the same. This disables all
+calculations inside solid areas and calculates as many points as
+boundary detection. The only possibility of creating a larger error
+with this method as opposed to boundary detection is in the instance
+that the shape of the set is so sharp that it does not set any of the
+tested points but comes from the right (i.e., uncalculated) location.
+This situation is not very common.
+
+   Later, rules were added for new rows and columns that crossed each
+other. In this instance you can test only four pixels. This situation
+is very rare. It is hoped that it does not introduce many errors.
+
+   If multiple blocks of new lines need to be calculated there are not
+reference pixels to use for solid guessing. Interlacing does the trick.
+By calculating the odd lines without any guessing, the guessing
+algorithm is now possible for the remaining uncalculated lines. This
+simple trick saves about 30% of the calculation of the main Mandelbrot
+image.
+
+   A similar approximation can also be done for the X coordinate. This
+makes it possible to improve solid guessing at even pixels because all
+surrounding pixels are available, further reducing errors.
+
+Symmetry
+========
+
+   Many fractals are horizontally or vertically symmetrical. This is
+implemented in the approximation code. When there is no good
+approximation available, try to mirror the opposite side if the line is
+available.
+
+   This method primarily speeds up the initial image.
+
+Calculation of the Mandelbrot Set
+=================================
+
+   Internal Mandelbrot calculation loop is unrolled--it calculates
+first 8 iterations using normal method and then it expects that number
+of iterations will be probably large so it switches into mode, where it
+calculates iterations in block of 8 with one bailout test at the end.
+When bailout is received, saved values from previous iterations is
+restored and last 8 iterations are recalculated slowly to get exact
+values. This helps a lot especially at Pentium, where conditionals in
+floating point code is slow.
+
+   Another stuff is periodicity checking. XaoS has both version of
+loops--with an without periodicity checks. In most cases it uses
+nonperiodicity checking version. Periodicity check version is used just
+in case, some inside set pixel has been found during solid guessing
+paste around. This is done mainly because periodicity checking version
+of loop is significantly slower.
+
+Dynamic Resolution
+==================
+
+   The above optimizations often do not help enough and image
+calculation is still too slow. One option was to reduce the framerate,
+but a framerate lower than 5 frames per second is unbearable. Another
+option is simply to calculate only the details that can be determined
+within a time interval.
+
+   Rows/columns not calculated are simple approximated by referencing
+the nearest other row/column. The result is an image with larger pixels.
+One problem is the fact that the order of calculating the rows/columns
+is significant. Previous versions of XaoS simply calculated all rows
+from top to bottom and then columns from left to right. Using the
+dynamic resolution code with this algorithm would result in distorted
+images. This was solved by adding priority to every row/column and
+calculating the high priority row/column first. The algorithm for
+adding these priorities is as follows:
+   * Find middle row/column of uncalculated block. Priority is the size
+        of the block (in floating point coordinates)
+
+   * Start function for left block and right block
+
+   This function produces quite good results. It tends to make same size
+rectangles on the whole image and does not depend on resolution.
+
+   Another interesting optimization is that during the zoom it is more
+advantageous to calculate rows/columns in the center of the zoom
+instead of the borders since these will be in the viewport longer and
+the user is usually focusing on center of the zoom anyhow.
+
+   This is done by simply adding to the calculated priority
+normal_priority / (abs(newposition - oldposition) / step + 1). This
+prefers rows/columns that do not move a great deal. Of course,
+unzooming uses the formula reversed.
+
+   The last variable to consider is the time interval for one frame.
+Setting it too low makes the calculation slow. Setting it too high
+makes the framerate too low. So the amount of time spent in other parts
+of the program is calculated and multiplied by 5 to determine the
+interval. If time is then lower than 15FPS, 15FPS is used instead,
+since slower animations are unacceptable. At the other hand if it is
+higher than 35FPS, it is set to 35FPS, since higher framerate is just
+wasting of computer resources. When image is not animating, this values
+is changed, so framerate is choose between 5FPS and 15FPS. This caused
+that images are calculated quickly after zooms stops.
+
+Autopilot
+=========
+
+   Another interesting algorithm controls the autopilot. It is actually
+quite simple. Interesting parts are found at the boundaries of the set.
+It randomly looks around and zooms to the first area containing both
+outside and inside set points. Some fractals (such as the Newton) do
+not have points inside the set at all. In this case it selects a point
+where many (more than 2) different colors are around. (i.e., It zooms
+into noisy areas.)
+
+   In the instance that there are no such areas, the autopilot will
+unzoom. Also detects oscillating.
+
+   Current implementation also does detection of out of range numbers
+and randomly choosed points are choosed near the old one, to avoid too
+often changes of direction.
+
+SMP support
+===========
+
+   Since version 3.0 XaoS supports SMP. This is done using threads.
+Most of XaoS routines should be threaded easily--for example
+moveoldpoints just divides image into n equal part and each part is
+proceeded by one processor.  Only unthreaded part is realloc table
+calculation routines. I don't see any way to paraelize it except it
+calculates both--x and y approximation at one time (using two
+processors).  Another interesting algorithm to paraelize is boundary
+trace. See comments `btrace.c' for discussion about current
+implementation.  Only problem of current implementation I see is
+possibility, that calculation is divided into too many parts (realloc
+tables, move points, calculate, symmetries, dynamic resolution) and
+tasks needs to synchronize between each part. So this should be too
+slow at real SMP box.
+
+
+File: xaosdev.info,  Node: timerlib,  Next: registry,  Prev: algorithm,  Up: Top
+
+The timer library
+*****************
+
+   Timer library is library I did for timing in XaoS. But I found it
+useful in many other programs (like demonstrations, games, animation
+players and all other stuff that needs to be timed). So you should read
+this description and possibly use it in your application and save some
+coding time.
+
+   There is many ways how to design of such timed application (game)
+
+  1. read user input, move badies, display and again this way has one
+     disadvantage. Speed of game depends on speed of computer.  This
+     was acceptable in old times where only processor was Z80 :) but now
+     with wide variety of various hardwares such internal loop is
+     unacceptable
+
+  2. read user input, measure time since last loop and calculate step
+     for badies, move badies for set step, display and again.  This way
+     fixes problem with speed. But moving badies just for calculated
+     step, that should differ a much is quite complex, usually
+     introduces complex calculation, floating/fixedpoint math and other
+     unnecesarry stuff that makes program long and introduces many bugs.
+
+  3. Set the fixed framerate that is high enough to make game smooth
+     but low enough to do whole internal loop in time. So internal loop
+     should look like: read user input, move badies, display, measure
+     time spent in loop an sleep rest of time until next frame.  This
+     is quite popular scheme but has another disadvantage--game can not
+     be designed to use whole CPU power since on slower computers
+     internal loop should take longer time that is reserved for one
+     frame. Game will run slowly again.
+
+  4. To take away disadvantage of previous method, many games times just
+     moving of badies and user input. Other stuff like displaying
+     should be done in rest of time. In DOS games moving and user input
+     is often at asynchronous interrupt and drawing runs as main loop.
+     This solves problem in case that drawing of game takes
+     significantly longer time than moving of badies. This is quite
+     usual so this scheme works well.
+
+  5. previous scheme still has one problem--since timer interrupt works
+     asynchronously, there should happend many race condition, in case
+     moving takes longer time than time reserved from frame, computer
+     can crash. So this scheme should be enhanced into synchronous one
+     with exactly same result but avoiding problem with race condition:
+
+     read user input, measure time spent by loop and calculate how many
+     simulated frame interrupts activated since last activation, if
+     zero sleep until simulated interrupt, move badies as many times as
+     required, display
+
+     this is an combination of 4 and 3 and seems to be most comfortable
+     way for writing games but since main loop is now quite complex
+     many games don't do that.
+
+  6. there is still one small problem. Method 5 expect that moving takes
+     significantly lower time that displaying. This may not be truth.
+     Simple work around is to write moving routine, that should move
+     for x moves by faster way that calling move x times. This is often
+     possible and makes easy extension to scheme 5. This scheme allows
+     you to use very large maximal framerate (say 100FPS) and to have
+     same results as method 2 (that is maximally exact method)
+
+   As you can see, designing of main loop isn't so easy. This is just
+very simple example. More advanced application for example should want
+to move one set of badies at one framerate and other at different
+framerate. This requires two such timings. Another complication is that
+there is many different ways to measure time exactly at different
+platforms. Under Linux you can measure using gettimeofday but under DOS
+this is exact just to 1/18 of second and thats too low for smooth
+animation and so on.
+
+   Thats why I decided to design portable easy to use timer library,
+that makes easy to implement all described method, combining of them
+and much more.  During design I taken care at the following thinks:
+quality of timing, how easy to use it is, speed, portability and to
+minimalize inexpected situations (like race conditions in asynchronous
+interrupts and so on)
+
+The name of game
+================
+
+   Timer library operates with "timers". They should be created, you
+should measure time since last reset, pause them or set "handler" and
+"interval".  But handler is not activated at given interval yet. Since
+timer library is not asynchronous, you must activate them.
+
+   For activating is used "groups". You should process group at some
+place in your program. Then all timers in group are checked and their
+handlers activated if required. When time spent since last activation
+is higher than interval, handler is activated more times. Also interval
+to next invocation is calculated to keep frequency.  Simple scheduling
+is performed at handler--handler is activated just once and then all
+other timers are checked before it is activated again. You should also
+define an multihandler--handler that is activated just once and
+receives argument how many intervals has left.
+
+   There is two special groups--`asyncgroup'. Timers in this group are
+activated asynchronously like from interrupt. It is not recommended to
+use it, since it brings many problems and usually isn't required. Also
+it does not work at many platforms. `Syncgroup' is the default group.
+Program is expected to process is quite often. In case you don't need
+to use more groups, you should use this one.
+
+   Time in timerlib is bit strange, since it does not flow continuously
+but jumps. It is updated every time you call `tl_updatetime'. I used
+this way in order to minimize context switches but later I found this
+scheme very useful, since you should lookup timer, do something and
+then reset it and don't wory about time spend between lookup and reset
+since it is 0 in case you did not called tl_updatetime. This helps to
+keep frequency of timers exact w/o any errors caused by such
+situations. At the other hand you need to call tl_updatetime at least
+once in your main loop.
+
+   Maybe you don't know why to create more groups, but I found it quite
+useful.  For example an autopilot in XaoS has such special group--I
+need to call it approx. every 1/20 of second but just at one place in
+program. Invoking of autopilot when calculation is active should
+produce incorrect results, so I have special group for autopilot and
+process just at one place where I am sure it is safe.
+
+   Timers should be also emulated. You should stop them and then
+control flow of time for given timer. This should be quite useful for
+example when you want precalculate animation at given framerate.
+
+   To control group of timers, you might create "emulators". It is just
+another time controlled by you. It is useful in cases you want to
+emulate fixed framerate (for animation rendering) or such.
+
+Time functions
+==============
+
+ - Function: void tl_update_time (void)
+     Update time used by timerlib. This must be called at least once in
+     main loop otherwise time will not flow. See above.
+
+ - Function: void tl_sleep (int TIME)
+     Sleep given time. Similar to usleep at POSIX.
+
+Group functions
+===============
+
+ - Function: tl_group* tl_create_group (void)
+     Allocate and initialize group header. Returns NULL when malloc
+     fails.
+
+ - Function: void tl_free_group (tl_group *GROUP)
+     Free memory storage used by group structure
+
+ - Function: int tl_process_group (tl_group *GROUP, int *ACTIVATED)
+     Process timers in group and activates their handlers. Returns time
+     until next invocation. Main loop should sleep returned time then.
+     An ACTIVATED parameter sould be `NULL'. If it is non `NULL',
+     variable is set to number of activated handlers.
+
+Timer functions
+===============
+
+ - Function: tl_timer* tl_create_timer (void)
+     Create timer structure.
+
+ - Function: void tl_free_timer (tl_timer *TIMER)
+     Free memory storage used by timer structure
+
+ - Function: void tl_reset_timer (tl_timer *TIMER);
+     Reset timer to current time. (time of last actication of
+     `tl_update_time')
+
+ - Function: int tl_lookup_timer (tl_timer *TIMER);
+     Return time since last call of tl_reset_timer or last activation
+     of handler.
+
+ - Function: void tl_set_interval (tl_timer *TIMER, int INTERVAL);
+
+ - Function: void tl_set_handler (tl_timer *TIMER, void (*HANDLER)
+          (void *),void *userdata);
+
+ - Function: void tl_set_multihandler (tl_timer *TIMER, void (*HANDLER)
+          (void *,int),void *userdata);
+     Handler, multihandler and interval control functions
+
+ - Function: void tl_add_timer (tl_group *GROUP, tl_timer *TIMER)
+     Add timer to given group. Timer should be added into just one
+     group.
+
+ - Function: void tl_stop_timer (tl_timer *TIMER)
+
+ - Function: void tl_resume_timer (tl_timer *TIMER)
+     Stop and resume timer.
+
+ - Function: void tl_slowdown_timer (tl_timer *TIMER,int TIME)
+     Time in timer is moved back for given time.
+
+Emulator functions
+==================
+
+ - Function: struct timeemulator *tl_create_emulator (void);
+     This function creates new emulator--you need to create one first
+     before emulating.
+
+ - Function: void tl_free_emulator (struct timeemulator *T);
+     Destroy emulator's data
+
+ - Function: void tl_elpased (struct timeemulator *T, int ELPASED);
+     Move emulated time.
+
+ - Function: void tl_emulate_timer (struct timer *T, struct
+          timeemulator *E);
+     Set timer to the emulated mode. Since now all time is controled by
+     emulator E. All other behavior of timer keeps unchanged.
+
+ - Function: void tl_unemulate_timer (struct timer *T);
+     Disable emulated mode for the timer.
+
+Example main loop
+=================
+
+     while(1)
+     {
+       time=tl_process_group(syncgroup,activated); /*Call game control functions*/
+       update_keys();
+       if(activated) /*something changed*/
+         display();
+       else tl_sleep(time);
+     }
+
+
+File: xaosdev.info,  Node: registry,  Next: index,  Prev: timerlib,  Up: Top
+
+XaoS function registry
+**********************
+
+   XaoS has an ui helper library, which provides functionality provided
+by user interface. All it's useful functions are registered into
+central registry.  This registry is used to generate menus and dialogs
+as well as command line options or scripting language. So it is very
+significant think in XaoS design.
+
+   Not only those who want hack XaoS ui-helper layer needs to know
+this, but also authors of drivers should use this to add new driver
+depended functions into XaoS's menu. Also external user interface is
+based at this.  Main idea behind external user interfaces (currently
+one for TCL/Tk and Gtk is under development) is following: XaoS
+transfers it's registry to interface (using simple description
+language). User interface starts XaoS in it's window and builds menus
+and dialogs based at this registry. Then once user select some
+function, it creates an command for scripting language and sends it back
+to XaoS' engine.
+
+   So knowledge of this part is essential for many developers. Please
+take care for this part.
+
+   The implementation of registry is in file `xmenu.c', header is
+`xmenu.h'. Mainly for historical reasons it speaks about menus and
+dialogs. (It was designed for the GUI at the beginning) I am keeping
+this terminology, since it is quite clean and easy to understand
+instead of talking in some cryptic abstract term.
+
+Function description
+====================
+
+   To add function into database, you need write it's description into
+menuitem structure. It has following prototype:
+
+     typedef struct menuitem
+       {
+         char *menuname;
+         char *key;
+         char *name;
+         char *shortname;
+         int type;
+         int flags;
+         void (*function) ();
+         int iparam;
+         void *pparam;
+         int (*control) (struct uih_context *);
+         menudialog *(*dialog) (struct uih_context *);
+       }
+     menuitem;
+
+ - Variable: menuname
+     Name of menu (or category) function belongs in. The root of all
+     categories is called `"root"'. XaoS alternativly uses an
+     `"animroot"' when animation replay is active. If you are adding an
+     function, it is better to add it into some subcategory like as
+     `"ui"' (it will be placed into UI menu then) or create an new
+     category for your functions if needed. It will appear as submenu
+     in main menu in the UI.
+
+ - Variable: key
+     Ascii code of hotkey to activate this function. Use `NULL' if none.
+
+ - Variable: name
+     Longer name of functions used in the menu entry, or `xaos --help'
+     listing
+
+ - Variable: shortname
+     One-word name of function used in command language and references
+     to function.
+
+ - Variable: type
+     type of function--this is not return type. Type should be one of
+     following constants:
+    `MENU_SUBMENU'
+          An submenu. This is not real function, but name for submenu.
+          You might fill    the KEY, NAME, SHORTNAME functions. An name
+          of this new    submenu is placed in the field PPARAM.
+
+    `MENU_NOPARAM'
+          An normal function without any parameters. When actived,
+          function    FUNCTION with just an pointer to `uih_context'
+          will be called.
+
+    `MENU_INT'
+          This should be used to simplify entering of more similar
+          functions (handled    by just one universal function in the c
+          code). This function is handled in    same way as
+          `MENU_NOPARAM', but also in one integer parameters taken
+          from `iparam' is passed.
+
+    `MENU_STRING'
+          Similar to `MENU_INT' but uses string instead of integer.
+
+    `MENU_DIALOG'
+          If you function needs some paramters, use dialog structure to
+          describe    them. In scripting language your function will
+          have parameters then, in    user interface dialog will be
+          displayed. PPARAM must then point to    array of dialog
+          entries. Witting them will be described later.     If your
+          function has just one parameter described in dialog
+          structure, it    will be called in normal c way--if you want
+          string parameter, one    pointer pointing to string (in
+          addition to `uih_context') will be    passed to the functions.
+
+          In case of multiple parameters are requested, it is
+          impossible to call    function in c way without special
+          wrapper for each such case. So it will    receive pointer to
+          array of `dialogparam' unions, wich contains    one entry for
+          each parameter. `dialogparam' is declared as follows:
+               typedef union
+                 {
+                   char *dstring;
+                   int dint;
+                   number_t number;
+                   number_t dcoord[2];
+                   xio_path dpath;
+                   void *dummy;
+                 }
+               dialogparam;
+
+    `MENU_CDIALOG'
+          In some cases, it is useful to add some context specific
+          default values    to the dialog structure. In this case you
+          might use this type instead. In    this case function DIALOG
+          is called first, and it is expected to    return pointer to
+          correct dialog structure. Dialog structure must lie in
+          static storage (since it is not freed) and always must have
+          the same    fields, just differ in the default values.
+          Also this function must work correctly even in the case
+          pointer to    `uih_context' is `NULL', since it is often
+          called in the    initialization stages (parameter parsing
+          etc.)
+
+ - Variable: flags
+     Flags are used to set additional information about function:
+    `MENUFLAG_CHECKBOX'
+          Some features act like check-box--i.e. by one calling of
+          function they are enabled, second call disables this. In menu
+          it is useful to add an check-box for this function indicating
+          whether feature is on or off.
+
+          And thats exactly what this flag does :). You need also
+          define the function CONTROL wich return's `1' when enabled
+          and `0' when disabled.  In order to let external GUI's work
+          correctly you need also call `uih_updatemenus("name")' every
+          time state of this function changes.
+
+          In the scripting language this adds an first parameter, wich
+          if `#t' or `#f'.  Engine then calls function just when it is
+          necessary. For `#t' dialog is requested, with `#f' function
+          is called just as `NOPARAM'. I.e.  dialog is displayed just
+          when enabling feature.
+
+    `MENUFLAG_DIALOGATDISABLE'
+          In checkbox display dialog when this feature is disabled
+          instead when enabled.
+
+    `MENUFLAG_RADIO'
+          Other features act like radio-button. Control function in
+          this case receives same parameter as defined for `MENU_INT'
+          or `MENU_STRING' types and is expected to return `1' when
+          enabled. You also need to call `uih_updatemenus' when
+          changed. No special parameter is added in the scripting
+          language.
+
+    `MENUFLAG_INTERRUPT'
+          Interrupt current calculation when this function called (it
+          is used by functions with causes recalculation of screen)
+
+    `MENUFLAG_INCALC'
+          By default XaoS queues functions and calls later when they
+          are activated in caluclation. This flag disables this feature.
+
+    `MENUFLAG_ATSTARTUP'
+          By default XaoS queues functions and calls later when they
+          are activated as command line parameters (in time engine is
+          not fully initialized yet).  This flag disables this feature.
+
+    `MENUFLAG_NOMENU'
+          Function will not be visible in the menu
+
+    `MENUFLAG_NOPLAY'
+          Function will not be available as command in scripts
+
+    `MENUFLAG_NOOPTION'
+          Function will not be available as command line option
+
+Initializing menuitem structure as static variable
+==================================================
+
+   In most case menuitems should be wrote as static variables. Because
+contents of this structure should change in future, please use one of
+macros defined in `xmenu.h'. They provides cleaner and easier to extend
+way to define this entries.
+
+   For example to define `MENU_NOPARAM' function use following macro:
+
+ - Function: MENUNOP (MENUNAME, KEY, NAME, SHORTNAME, FLAGS, FUNCTION)
+   Similar macros exist for the other types too. They ends for `CB' or
+`RB' for check-boxed or radio-boxes functions. See `menu.c' for large
+example of definitions. They should look like this:
+
+     static menuitem menuitems[] =   /*XaoS menu specifications */
+     {
+       SUBMENU ("", NULL, "Root menu", "root"),
+       SUBMENU ("", NULL, "Replay only commands", "plc"),
+       MENUNOP ("comm", NULL, "print menus specifications of all menus",
+                "print_menus", MENUFLAG_NOMENU|MENUFLAG_NOPLAY|MENUFLAG_ATSTARTUP,
+                uih_printallmenus),
+                ...
+
+Dialog description
+==================
+
+   Dialog description is similar to menuitem. It is array of following
+structures:
+     typedef struct dialog
+       {
+         char *question;
+         int type;
+         int defint;
+         char *defstr;
+         number_t deffloat;
+         number_t deffloat2;
+       }
+     menudialog;
+   It is terminated by QUESTION pointer set to `NULL'.
+
+   The QUESTION contains string ui should display when is asking for
+this field.
+
+   TYPE should be one of following values: `DIALOG_INT',
+`DIALOG_FLOAT', `DIALOG_STRING', `DIALOG_KEYSTRING' (the difference
+between string and keystring is, that in scripting language string is
+passed as `"hello"', but keystring is passed as scheme keyword as
+`'hello'), `DIALOG_IFILE' (input file), `DIALOG_OFILE', `DIALOG_CHOICE'
+(choice between different keystrings), `DIALOG_ONOFF' (boolean
+parameter), `DIALOG_COORD' (two floats--complex number)
+
+   Set to corresponding DEF* field for default value. In case of files
+use string in the format `"[PREFIX]*[EXTENSION]"'. For type
+`DIALOG_CHOICE' set DEFSTR to pointer to array of strings terminated by
+`NULL' entry.
+
+   To write dialog structures again use macros defined in `xmenu.h'
+like:
+     DIALOGSTR(question,default)
+   The definition should look like:
+
+     static menudialog uih_viewdialog[] =
+     {
+       DIALOGCOORD ("center:", 0, 0),
+       DIALOGFLOAT ("Radius:", 1),
+       DIALOGFLOAT ("Angle:", 0),
+       {NULL}
+     };
+
+Modifying registry
+==================
+
+ - Function: void menu_add (menuitem *ITEM, int N);
+     Add array of N items to the database.
+
+ - Function: void menu_delete (menuitem *ITEMS, int N);
+     Remove array of N items from database.
+
+Querying registry
+=================
+
+ - Function: menuitem* menu_findkey (char *KEY, char *ROOT);
+     Find item for given key. ROOT is menu where to start (submenus are
+     searched recursively)
+
+ - Function: menuitem* menu_findcommand (char *NAME);
+     Find item for given short name
+
+ - Function: char* menu_fullname (char *MENU);
+     Long name for the short name of menu
+
+ - Function: menuitem* menu_item (char *MENU, int N);
+     Nth entry of the MENU. Return `NULL' if no more entries available.
+
+ - Function: int menu_enabled (menuitem *ITEM, struct uih_context *C);
+     Check whether given item is activated (for check-boxed and
+     radio-boxed functions)
+
+ - Function: int menu_havedialog (menuitem *ITEM, struct uih_context
+          *C);
+     Does this function have dialog?
+
+ - Function: menu_getdialog (CONTEXT, M)
+     Macro returns pointer to dialog structure. (function must have it,
+     otherwise garbage is returned).
+
+ - Function: int menu_available (menuitem *ITEM, char *ROOT);
+     Check whether item is available as one of entries of ROOT (or it's
+     submenus)
+
+
+File: xaosdev.info,  Node: index,  Prev: registry,  Up: Top
+
+Index of functions, variables, types and constants
+**************************************************
+
+* Menu:
+
+* alloc_buffers:                         driver.
+* ANIMATION:                             filters.
+* C256 <1>:                              filters.
+* C256:                                  driver.
+* CHANGED:                               filters.
+* createfilter:                          filters.
+* display:                               driver.
+* ethreads:                              xthreads.
+* filter:                                filters.
+* filteraction:                          filters.
+* FIXEDCOLOR <1>:                        filters.
+* FIXEDCOLOR:                            driver.
+* flip_buffer:                           driver.
+* flush:                                 driver.
+* free_buffers:                          driver.
+* FULLSCREEN:                            driver.
+* getinstance:                           filters.
+* getsize:                               driver.
+* GRAYSCALE <1>:                         filters.
+* GRAYSCALE:                             driver.
+* image <1>:                             filters.
+* image:                                 design.
+* INEXACT:                               filters.
+* inherimage:                            filters.
+* inhermisc:                             filters.
+* init:                                  driver.
+* initdata:                              filters.
+* MASK1BPP:                              filters.
+* MAXCONDS:                              xthreads.
+* MAXSEMAPHORS:                          xthreads.
+* menu_add:                              registry.
+* menu_available:                        registry.
+* MENU_CDIALOG:                          registry.
+* menu_delete:                           registry.
+* MENU_DIALOG:                           registry.
+* menu_enabled:                          registry.
+* menu_findcommand:                      registry.
+* menu_findkey:                          registry.
+* menu_fullname:                         registry.
+* menu_getdialog:                        registry.
+* menu_havedialog:                       registry.
+* MENU_INT:                              registry.
+* menu_item:                             registry.
+* MENU_NOPARAM:                          registry.
+* MENU_STRING:                           registry.
+* MENU_SUBMENU:                          registry.
+* menudialog:                            registry.
+* MENUFLAG_ATSTARTUP:                    registry.
+* MENUFLAG_CHECKBOX:                     registry.
+* MENUFLAG_DIALOGATDISABLE:              registry.
+* MENUFLAG_INCALC:                       registry.
+* MENUFLAG_INTERRUPT:                    registry.
+* MENUFLAG_NOMENU:                       registry.
+* MENUFLAG_NOOPTION:                     registry.
+* MENUFLAG_NOPLAY:                       registry.
+* MENUFLAG_RADIO:                        registry.
+* menuitem:                              registry.
+* MENUNOP:                               registry.
+* mousetype:                             driver.
+* nthreads:                              xthreads.
+* P_FLOAT:                               driver.
+* P_NUMBER:                              driver.
+* P_STRING:                              driver.
+* P_SWITCH:                              driver.
+* palette:                               design.
+* params:                                driver.
+* PIXELSIZE:                             driver.
+* print:                                 driver.
+* processevents:                         driver.
+* RANDOM_PALETTE_SIZE:                   driver.
+* requirements:                          filters.
+* RESIZE_COMMAND:                        driver.
+* RESOLUTION:                            driver.
+* SCREENSIZE:                            driver.
+* set_color:                             driver.
+* set_range:                             driver.
+* timeemulator:                          timerlib.
+* tl_add_timer:                          timerlib.
+* tl_create_group:                       timerlib.
+* tl_create_timer:                       timerlib.
+* tl_elpased:                            timerlib.
+* tl_emulate_timer:                      timerlib.
+* tl_free_emulator:                      timerlib.
+* tl_free_group:                         timerlib.
+* tl_free_timer:                         timerlib.
+* tl_lookup_timer:                       timerlib.
+* tl_process_group:                      timerlib.
+* tl_reset_timer:                        timerlib.
+* tl_resume_timer:                       timerlib.
+* tl_set_handler:                        timerlib.
+* tl_set_interval:                       timerlib.
+* tl_set_multihandler:                   timerlib.
+* tl_sleep:                              timerlib.
+* tl_slowdown_timer:                     timerlib.
+* tl_stop_timer:                         timerlib.
+* tl_unemulate_timer:                    timerlib.
+* tl_update_time:                        timerlib.
+* TRUECOLOR <1>:                         filters.
+* TRUECOLOR:                             driver.
+* TRUECOLOR24 <1>:                       filters.
+* TRUECOLOR24:                           driver.
+* TRUECOLOR32 <1>:                       filters.
+* TRUECOLOR32:                           driver.
+* UI_C256:                               driver.
+* ui_driver:                             driver.
+* UI_FIXEDCOLOR:                         driver.
+* UI_GRAYSCALE:                          driver.
+* UI_TRUECOLOR:                          driver.
+* UI_TRUECOLOR24:                        driver.
+* UI_TRUECOLOR32:                        driver.
+* uninit:                                driver.
+* UPDATE_AFTER_RESIZE:                   driver.
+* xshl_line:                             eui.
+* xth_bgjob:                             xthreads.
+* xth_function:                          xthreads.
+* xth_init:                              xthreads.
+* xth_lock:                              xthreads.
+* xth_nthread:                           xthreads.
+* xth_sleep:                             xthreads.
+* xth_sync:                              xthreads.
+* xth_uninit:                            xthreads.
+* xth_unlock:                            xthreads.
+* xth_wakeall:                           xthreads.
+* xth_wakeup:                            xthreads.
+
+
+
+Tag Table:
+Node: Top501
+Node: design1475
+Node: driver9067
+Node: gui-driver25868
+Node: eui32613
+Node: ui-helper43320
+Node: xthreads47876
+Node: filters52923
+Node: algorithm69506
+Node: timerlib89511
+Node: registry99566
+Node: index111446
+
+End Tag Table
diff --git a/doc/xaosdev.texinfo b/doc/xaosdev.texinfo
new file mode 100644
index 0000000..49203d8
--- /dev/null
+++ b/doc/xaosdev.texinfo
@@ -0,0 +1,2842 @@
+\input texinfo   @c -*-texinfo-*-
+
+@c Use A4 paper - If you don't like that, remove the following 3 lines.
+@iftex
+@afourpaper
+@end iftex
+
+@setfilename xaosdev.info
+@settitle A fast real-time interactive fractal zoomer --- hacker's guide
+@dircategory Graphics
+@direntry 
+* XaoS: (xaosdev).               The fast real-time interactive fractal zoomer
+                                 (developers documentation)
+@end direntry
+
+
+@ifinfo
+@copyright{} 1997 Jan Hubicka
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+@end ifinfo
+
+@c %**end of header
+
+@set VERSION    3.1.1
+@set DATE       Feb 5, 2005
+
+@titlepage
+
+@title XaoS @value{VERSION}
+@subtitle A fast real-time fractal zoomer --- hacker's guide
+
+@author Jan Hubi@v cka
+@tex
+Dukelsk\'ych bojovn\'\i ku 1944 
+@end tex
+@*
+390 03 T@'abor @*
+Czech Republic
+
+Email: @code{jh@@ucw.cz}
+
+@value{DATE}
+
+@page
+@vskip 0pt plus 1filll
+@vskip 0pt plus 1filll
+
+@copyright{} 1997 @tex Jan Hubi\v cka 
+@end tex
+
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
+@end titlepage
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node   Top, , (dir), (dir)
+
+@ifinfo
+@top XaoS @value{VERSION}
+@flushright 1.0
+A real-time interactive fractal zoomer
+Hacker's guide
+@value{DATE}
+@end flushright
+
+This manual contains documentation for those who are interested in
+studying and improving the XaoS sources or using them in other programs. 
+It includes a description of the algorithm and documentation of those parts
+of XaoS that I think might be useful for others.
+@end ifinfo
+
+@menu
+* design::		Overview of the XaoS design
+* driver::		Driver API description
+* gui-driver::		Writing user interface driver
+* eui::			Writing an external user interface
+* ui-helper::		UI helper library
+* xthreads::		XaoS thread library
+* filters::		Filters
+* algorithm::		Algorithm description
+* timerlib::		The timer library
+* registry::		XaoS function registry
+* index::		Function command and variable index
+@end menu
+
+@node design, driver ,Top ,Top
+@chapter Overview of the XaoS design
+
+XaoS is divided into several ``libraries'' (some of them have been merged
+together; nonetheless the conceptual divisions are there and they can be
+separated easily).
+
+Understanding the design philosophy should help you to navigate in the sources.
+I also expect that much of the lower level stuff may be useful in other
+projects, since it is designed to be fairly generic.
+
+So here is an overview, from the lowest level stuff to the highest.
+
+@section Palette and image library
+
+@findex image
+@findex palette
+The sources for this are in the directory @code{src/filter}.
+The aim of the palette library is to provide a relatively abstract interface to
+the various visuals, and hide differences in the hardware and driver
+implementations. Fixed color, pseudocolor, grayscale and truecolor visuals
+should be handled in almost the same way.
+
+It provides the @code{palette} structure, containing a palette. You might
+allocate new colors here (you give an RGB value and the corresponding pixel
+is returned), interpolate colors where possible, cycle colors and so on.
+
+Every palette contains two parts --- the preallocated color cells and the actual
+palette. For instance, this could be used to allow the GUI the possibility to
+allocate static, unchanging colors for its texts and dialogs, while the rest of
+the palette is under the control of different parts of XaoS.
+
+This library also contains a set of functions to allocate different palettes
+used by other parts of XaOS. I expected that different parts of XaoS could share
+the same palette. This hasn't happened yet, but the functions are kept here just
+in case.
+
+The image library is built on top of the palette library, providing
+functionality for handling actual image data. Each image is represented by one
+or two frame-buffers (useful for double-buffering). One frame-buffer is
+called `current' and the other `old'. They are flipped by a special function.
+The program can draw into either of them.
+
+Frame-buffers are held as a set of pointers to scan-lines. This provides more
+flexibility than more obvious representations, because tricks like sub-windows
+and flipped bitmaps are possible. It's also fast, since you should avoid one
+multiplication.
+
+The last significant information the image structure holds is of course the bpp
+depth.  It is counted in bytes, and ranges from 0--4 (where 0 is used for 1bit
+bitmaps).
+
+@section Filter library
+Sources are available in @code{src/filter}.
+This library controls the process of image creation. It handles a queue of
+filters, where each filter modifies the image in some way. The filters at the
+beginning and end of the queue are special; the first filter is usually the
+actual fractal engine which creates the image, and the last filter is usually
+the user interface helper library.
+
+@section Xthread library
+This library provides an interface to various multi-threading libraries;
+currently the BeOS, plan9 and POSIX implementations are available. It allows the
+running of various functions in parallel, and provides some synchronization
+primitives (semaphores). It is simple, but has all the functionality required
+for the XaoS engine.
+
+@section Fractal library
+Sources are available in @code{src/engine/}, headers in @code{fractal.h}.
+This library contains the actual fractal calculation routines. It is governed by
+a fractal context, which contains information like the current formula, the seed
+(for julia sets), the palette, and so on.
+
+Functions for calculating the various fractal types and various coloring modes
+are also available here.
+
+@section Zooming engine and other filters.
+Sources are available in @code{src/engine/}.
+This is the actual zooming engine filter. It is fairly independent of the
+fractal library, so it could possibly be used for zooming other stuff. (It has
+already been used for zooming large scale images containing maps of Hungary).
+
+The file @code{ui_helper} contains the implementation of all filters not already
+mentioned, and a structure containing all functions exported from the filter to
+the user interface. One other terminal filter is implemented --- the Julia
+morpher. Other filters add special effects (such as motion blur), or do
+conversions (such as rotation or dithering).
+
+@section Timer library
+This library provides many useful timing primitives (such as timers).
+It is used by some other programs too.
+
+@section xio library
+This library aims to provide a unified, portable interface to the file
+system. Some strange systems (such as MacOS) have a very different filesystem
+API to UNIX; perhaps they don't represent filenames as a string, use special
+structures, or something; this library abstracts away from all that.
+
+@section xshl library
+Xshl stands for XaoS simple hypertext library. It contains a fairly universal
+engine parsing an `xshl' language, similar to HTML, with some additions and many
+restrictions. It can render text for both proportional and monospaced fonts, in
+various sizes.
+
+@section help library
+This is built on top of the xshl and xio libraries. It can read help files
+containing help chapters, can parse keywords in chapters, and so on.
+
+@section xmenu library
+This is the XaoS function registry. All functions from UI-Helper library are
+registered in the registry. From this registry the menus, dialogs, command
+line options and scripting language are built.
+
+@section Catalog library
+This is a library for handling message catalogs. It should read catalogs and
+convert keywords into an actual message.
+
+@section PNG library
+This library provides a function for saving an image from the Image library to a
+file, in PNG format. Other formats could be added as well if required.
+
+@section UI-helper library
+This library controls all the low-level stuff and provides a high-level
+interface to it. It has functions for playing animations, zooming/un-zooming
+and suchlike. It all the other libraries heavily. It doesn't implement
+functions for handling menus and such, but could be helpful for such
+implementations, because of the function registry database.
+
+@section Ugly interface
+This is currently the only real user interface for XaoS (there is another, wich
+is used for rendering animations, but it is not a user interface as users
+understand the term). It is built above the UI-helper library and provides
+functions for drawing menus, dialogs and so on.  It has drivers for many
+platforms, and can be easily ported to others.
+
+In the future, it should be quite easily extended to let drivers specify their
+own menu/dialog handling code; so it should be possible to give it a ``native''
+look on each platform.
+
+It can also operate in a mode where the GUI drawing routines are disabled; the
+function registry database is transferred through a pipe to an external program,
+which should build the menus and act as an external user interface, sending back
+commands in the scripting language (presumably representing things that the user
+has done). This provides another way to give a native look to the ugly interface,
+and could also be used to interface other scripting languages to XaoS.
+
+The ugly interface has one serious limitation --- for historical reasons, it is
+coded to handle just one window (the rest of XaoS can probably do multiple
+windows, but this is untested), so in windowed environments it is impossible to
+open multiple menus with fractals. On the other hand, this limitation is not so
+important once external GUIs enter the picture, as they could just start
+multiple XaoS engines. This is also preferred because it brings extra
+robustness, multitasking and some other advantages. That's why I don't plan to
+remove this limitation yet.
+
+@node driver, gui-driver ,design ,Top
+@chapter Driver API description
+
+To port XaoS successfully to some platform you need:
+
+@itemize @bullet
+@item
+An ISO C compatible optimizing compiler. Note that an optimizing compiler is
+really required, since XaoS is coded to be a good target for optimizations and
+doesn't have many routines coded in assembly; so if you will use a bad compiler,
+you will notice drastic slowdowns (a slowdown of 10x or more). Some compilers
+have serious problems compiling XaoS; this applies to most DOS compilers (Watcom
+C, Borland C, Microsoft C) for instance.  They generate incorrect code or crash
+during compilation. I highly recommend using the GNU C compiler, but even some
+versions of GNU C have difficulty. Please read @code{compilers.txt} for more
+information.
+@item
+A fast way to avoid division by zero/overflow and other floating point
+exceptions. XaoS is carefully coded to not crash in this case, but doesn't have
+any tests to avoid such situations; expect random results in such cases.  Many
+platforms provide a means to switch coprocessor into a mode where 1/0 produces
+Inf and so on. If there is no such means, try to use some kind of signal handler
+that will ignore such exceptions.
+
+The ``normal'' solution --- add @code{if}s to avoid division by zero --- is
+almost impossible. Division is quite easy to check for, but other cases (such as
+overflows) are much harder. I don't think it is possible to avoid all crashes
+just by adding @code{if}s.
+
+XaoS doesn't depend on IEEE arithmetic. The result in the sort of edge cases
+where IEEE makes a difference is mostly undefined. XaoS usually works well with
+compiler switches for inexact math enabled (such as @code{-ffast-math} in GCC),
+but, of course, there are no guarantees. For example on Alphas this is not true,
+since they usually generate exceptions in that case.
+@item
+A text or graphics output device. If you only have a text output device you may
+use the AA driver, which renders fractals into high quality ASCII art. In this
+case you might want to skip this chapter, download AA-lib
+(http://www.ta.jcu.cz/aa) and read the porting chapter of AAlib manual. A
+graphics device must be one of:
+
+@findex C256
+@findex FIXEDCOLOR
+@findex GRAYSCALE
+@findex TRUECOLOR
+@findex TRUECOLOR24
+@findex TRUECOLOR32
+@itemize @bullet
+@item 8 bits per pixel with user definable palette @code{C256}, static palette @code{FIXEDCOLOR}, or static grayscale @code{GRAYSCALE}
+@item 16 bits per pixel with arbitrary bits per color @code{TRUECOLOR}
+@item 24 bits per pixel with 8 bits per color, arbitrary order @code{TRUECOLOR24}
+@item 32 bits per pixel with arbitrary order of colors, where each color fits in exactly one byte @code{TRUECOLOR}
+@item 1 bit per pixel bitmap, either least or most significant bit first
+@end itemize
+
+Please contact me if you have a different kind of device. Some modes (like
+mis-ordered truecolor modes) could be added really easily if required.  Note
+that mono/4/16 colors devices will probably never be supported internally by
+XaoS, since I expect they will be slower than 8bpp, so XaoS will internally work
+in 8bpp and then convert to 1/2/4bpp. Contact me if you want to write such a
+converter. (For bitmap one already exists --- see @code{dither.c}.)
+@item
+Some way to save images. By default XaoS uses @code{libpng}, which is ported to
+many platforms, but there are many platforms where it isn't ported yet. If your
+system has some standard image format which is easier to handle than
+@code{.png}, contact me and I will show you how to add such support to XaoS (see
+@code{png.c}).
+@item
+Stdio compatible library (this is a problem on the Mac and BeOS). XaoS has an
+abstract layer above stdio, so it can use other input/output libraries too. You
+could write another implementation of this layer, called @code{xio}. See
+@code{xio.h}, @code{xstdio.c}, and @code{xstdio_mac.h} for an example.
+@end itemize
+
+The ugly interface is designed to make writing new drivers as easy as possible.
+Use the file @code{ui_template} when starting to write a new driver from
+scratch. You need to write only a few functions, filling out the following
+table:
+@findex ui_driver
+@example
+struct ui_driver @{
+  char *name;
+  int (*init)(void);            /*initializing function. returns 0 if fail*/
+  void (*getsize)(int *,int *);	/*get current size..in full-screen versions
+                                  i.e svga and dos asks user for it*/
+  void (*processevents)(int,int *,int *,int *,int *);
+                                /*processevents..calls ui_resize,ui_key
+                                  also returns positions of mouse..
+                                  waits for event if first parameter is
+                                  1*/
+  void (*getmouse)(int *,int *,int *);
+                                /*returns current mouse positions*/
+  void (*uninit)();             /*called before exit*/
+  int (*set_color)(int,int,int,int);
+                                /*alloc palette color and returns number*/
+  int (*set_range)(ui_palette *palette,int start,int end)
+                                /*Set palette range*/
+  void (*print)(int,int,char *);/*prints text*/
+  void (*display)();            /*displays bitmap*/
+  int (*alloc_buffers)(char **buffer1,char **buffer2);/*makes buffers*/
+  void (*free_buffers)(char *buffer1,char *buffer2);/*frees buffers*/
+  void (*flip_buffers)(void);   /*prints text*/
+  void (*mousetype) (int type); /*Change mouse cursor*/
+  void (*flush) (void);         /*Flush current state to screen*/
+  int textwidth;                /*width of text*/
+  int textheight;		/*height of text*/
+  struct params *params;        /*command line parameters*/
+  int flags;
+  float width,height;
+  int maxwidth,maxheight;
+  int imagetype;
+  int palettestart,paletteend,maxentries;
+  int rmask, gmask, bmask;
+  struct gui_driver gui_driver;
+@};
+@end example
+
+@section Functions
+
+@code{ui} uses the following functions to communicate with a driver:
+
+@defun init
+  Initializes the driver and returns 1 on success and 0 on failure.
+@end defun
+@defun getsize (int *@var{width}, int *@var{height})
+  Returns the size of screen (or window) in x and y dimensions.
+@end defun
+@defun processevents (int @var{wait}, int *@var{x},int *@var{y}, int *@var{buttonmask}, int &@var{keys})
+  Gets new keyboard/mouse events. Parameters are:
+  @table @var
+  @item wait
+     If 1, the function can block, waiting indefinitely for the next event,
+     otherwise it just determines if something's already arrived. This is
+     useful on multi-tasked OSes, where eating unnecessary CPU time on
+     busy-waiting is discouraged.
+  @item *x,*y
+    Returns the current mouse coordinates.
+  @item *b 
+    Returns a mouse button bitmask of @code{BUTTON1}, @code{BUTTON2}, and @code{BUTTON3}.
+  @item *k 
+    Returns a cursor key bitmask:
+    @table @code
+    @item 1 
+    @key{left}
+    @item 2 
+    @key{right}
+    @item 4 
+    @key{up}
+    @item 8 
+    @key{down}
+    @end table
+    @end table
+    The function calls @code{ui_key} (ASCII character) and @code{ui_resize}
+    if required. For special keys use @code{UIKEY_UP}, @code{UIKEY_DOWN}, etc.
+    See @code{ui.h} for a complete list of these constants.
+
+    In case of problems freeing/allocating inside @code{processevents} you may 
+    call @code{ui_call_resize}, which calls resize later outside this function.
+@end defun
+
+@defun uninit
+ Uninitialises driver---called before exit.
+@end defun
+
+@defun set_range (ui_palette *@var{palette}, int @var{start}, int @var{end})
+This is the preferred way to set the palette (the other way is with
+@code{set_color}). When @var{imagetype} is @code{UI_C256} (256 color with
+palette) one of these two functions @emph{must} be used. In truecolor modes they
+are unused. If direct palette access is possible on your platform, define this
+function. The function is expected to set all color cells between @var{start}
+and @var{end} to colors defined in @var{palette}. @var{ui_palette} is array of
+@var{ui_rgb} elements. @var{palette[0]} is the color of entry number
+@var{start}. @var{ui_rgb} is an array of @code{char}.  @var{palette[0][0]} is
+the red field of entry number @var{start}, @var{palette[0][1]} is the green and
+@var{palette[0][2]} is the blue. @code{0} means black and @code{255} means full
+intensity. Use @code{NULL} if your driver doesn't support this call.
+@end defun
+
+@defun set_color (int @var{r}, int @var{g}, int @var{b}, int @var{init})
+  This is a secondary way to set the palette, that should be used at platforms
+  w/o direct palette access (like X11 or static color schemes). It receives the
+  RGB value of the color, and returns the index of the color cell with this
+  color, or -1 if no more color cells are available. The @var{init} parameter is
+  set to 1 when this function is called for the first time on a given
+  palette; @code{set_color} is then expected to free all color entries
+  previously allocated. Use @code{NULL} if your driver doesn't support
+  this call.
+@end defun
+
+@defun print (int @var{x},int @var{y}, char *@var{text})
+  Prints text to screen at position x/y. This function is a bit archaic
+  (XaoS now uses its own functions drawing directly to the buffer in most
+  cases), but in some cases --- initialization messages or calculation ---
+  the functions are unusable, so we still need this primitive. In the
+  @code{C256} mode you can rely on the first allocated color always being
+  black and the second being white.
+@end defun
+
+@defun display (void)
+  Displays current buffer on screen
+@end defun
+
+@defun alloc_buffers (char **@var{buffer1},char **@var{buffer2})
+  Allocates two buffers that can hold a bitmap the size of the screen.
+  Also sets the current buffer to @var{buffer1}. Since version 2.1, this
+  returns the scan-line size in bytes (usually the screen width) or 0
+  on failure. This is useful on systems that allocate a bitmap bigger
+  than the window/screen (divisible by 4 or thereabouts).
+@end defun
+
+@defun free_buffers (char *@var{buffer1}, char *@var{buffer2})
+  Frees allocated buffers.
+@end defun
+
+@defun flip_buffer (void)
+  Flips buffers --- sets the current buffer to the other one.
+@end defun
+
+@defun flush (void)
+  This function should be used by drivers with buffered output to flush
+  those buffers. Other drivers should set it to @code{NULL}.
+@end defun
+
+@defun mousetype (int type)
+   This function is used to change the mouse cursor. @var{type} has the
+   following values:
+   @table @code
+   @item NORMALMOUSE
+     This pointer is that usually displayed, while the UI waits for user
+     input.
+   @item WAITMOUSE
+     This pointer is displayed when the UI is busy (perhaps the famous
+     hourglass) or you may use that defined in ui_dos --- a Mandelbrot
+     set.
+   @item REPLAYMOUSE
+     This pointer is displayed during replay. There should be none in
+     fullscreen drivers, since a blinking mouse cursor during replay
+     looks ugly. On windowed systems, disabling the mouse looks ugly,
+     so it should be some funny cursor.
+   @end table
+   You should use @code{NULL} if your driver doesn't support this.
+@end defun
+
+@section Other information
+Some additional variables are also used to inform the ui library about the
+driver. All these values can be changed by init functions in case they were
+unknown beforehand.
+
+@table @var
+@item textheight, textwidth
+  Width and height of your font
+@item palettestart, paletteend
+  First and last palette entry that can be changed. You should use this
+  to avoid changing entries reserved for the window system, UI objects,
+  mouse, etc.
+@item rmask, gmask, bmask
+  These fields are used in truecolor modes to specify where each color is
+  defined.
+@item maxentries;
+  Number of allocatable entries. Normally should be
+  @var{palettestart}-@var{paletteend}
+@item imagetype
+  Defines the type of image. Should be one of the following values:
+@findex UI_C256
+@findex UI_FIXEDCOLOR
+@findex UI_GRAYSCALE
+@findex UI_TRUECOLOR
+@findex UI_TRUECOLOR24
+@findex UI_TRUECOLOR32
+  @table @code
+  @item UI_C256
+    The classical 256 color with palette scheme used by most older graphics
+    adapters. You should also use it for static-color schemes, but they are
+    not well supported in current versions of XaoS.
+  @item UI_TRUECOLOR
+    32bpp truecolor mode
+  @item UI_TRUECOLOR24
+    24bpp truecolor mode
+  @item UI_TRUECOLOR16
+    16bpp truecolor mode
+  @end table
+@end table
+
+What follows is @emph{not required} to get the driver working at first,
+so you may skip to @emph{registering driver} on the first read and return
+here later.
+
+@table @var
+
+@item params
+  You may define command line options for your driver.
+
+  They are defined using a @var{params} structure like:
+@findex params
+  @example
+  static struct params params[]=@{
+    @{"-mode",P_NUMBER,&defmode,
+      "Select graphics mode(same number as in interactive menu)"@},
+    @{NULL,0,NULL,NULL@}  /*this MUST be last option field*/
+  @};
+  @end example
+
+  where every line is one parameter. The list ends with @code{@{NULL,0,NULL,NULL@}}.
+  The first field is the option name.
+  The second field is the parameter type:
+@findex P_SWITCH
+@findex P_NUMBER
+@findex P_STRING
+@findex P_FLOAT
+  @table @code
+    @item P_SWITCH 
+    No parameter --- variable is just set to 1 if the option is supplied.
+    @item P_NUMBER 
+    Integer number
+    @item P_STRING 
+    String
+    @item P_FLOAT 
+    Floating point number (variable is float)
+  @end table
+  The third element is a pointer to a variable that is changed if the option is
+  supplied. (For instance, it is @code{int*} for @code{P_NUMBER} or
+  @code{P_SWITCH}.)
+  The last element is help text displayed by @code{ui -h}.
+
+
+@item width,height
+  See @var{flags}. May be set to @code{0.0, 0.0} at the start.
+
+@item maxwidth,maxheight
+  See @var{flags}. May be set to 0,0 at the start.
+
+@item @var{flags}
+  This variable says more about your driver. A good starting value is 0.
+  But for the final version it is recommended to read the following carefully.
+
+  Flags are uppercase constants and should be set as follows:
+
+  @code{ASYNC_PALETTE | RANDOM_PALETTE_SIZE}
+
+  The following flag constants are supported:
+
+  @table @code
+@findex RANDOM_PALETTE_SIZE
+@findex UPDATE_AFTER_RESIZE
+@findex RESIZE_COMMAND
+  @item RANDOM_PALETTE_SIZE
+    States that the palette is randomly sized. This is used in X where the
+    palette is shared between many programs. By default XaoS allocates all
+    available colors up to 256. This is not very nice to other applications in
+    X, so this flag states that that a random number of colors (in the range
+    8--256) are allocated.
+  
+    When this variable is off XaoS expects that the same number of colors is
+    always available.
+  @item UPDATE_AFTER_RESIZE
+    Causes the screen to be recalculated and redrawn upon a resize, even if
+    its size has not changed, in case the resize procedure destroys data in
+    XaoS' buffers.
+  @item RESIZE_COMMAND
+    Some drivers (mainly the fullscreen ones) may ask the user for the size
+    and color depth to use, in the function @code{get_size}. It would be nice
+    to let the user change this parameter at runtime and force XaoS to
+    reinitialize all its images. This is done with the @code{ui_resize}
+    call
+
+    In windowed drivers, this is called by external window-system events, but in
+    fullscreen drivers you'll need a key or menu item for this. You could add
+    this function directly into XaoS's function registry (see for example the
+    GGI driver) --- it is useful mainly when you want to use a size selection
+    dialog that is standard for your environment, or let XaoS use its default
+    one. For example, see the SVGAlib or DOS driver.
+  @end table
+
+  Screen/window size information:
+
+    Xaos needs to know the exact physical size of displayed images. This is
+    required for random dot stereograms and also for keeping the aspect ratio
+    of fractals correct (do not make them wide in 640x200 resolution etc.)
+    At least one of the following values should be defined (given in the order I
+    prefer)
+@findex SCREENSIZE
+@findex PIXELSIZE
+@findex FULLSCREEN
+@findex RESOLUTION
+  @table @code
+    @item SCREENSIZE
+     The @var{width}/@var{height} values specify the exact size of the
+     screen/window in centimeters
+    @item PIXELSIZE
+     The @var{width}/@var{height} values specify the exact size of one pixel in
+     centimeters. This is better for windowed environments, where the window
+     size is often changed.
+    @item FULLSCREEN
+     The driver runs fullscreen. XaoS automatically uses the default screen size
+     (29.0cm x 21.5cm)
+    @item RESOLUTION
+     The driver does not know the exact screen size, but knows the resolution
+     used (in the @var{width}/@var{height} variables); XaoS automatically
+     calculates pixel width using width = 29.0cm/maxwidth and height =
+     21.5/maxheight.
+   @end table
+   Of course the default width and height can be changed by command line
+   options. You may also use combinations like:
+   
+   @table @code
+   @item SCREENSIZE | FULLSCREEN 
+   The best for fullscreen drivers
+   @item PIXELSIZE | RESOLUTION 
+   The best for windowed drivers
+   @item FULLSCREEN 
+   For fullscreen drivers that have no idea about screen size...  
+   @end table
+
+   Do not forget to set the @var{width}, @var{height}, @var{maxwidth},
+   @var{maxheight} fields if required.
+
+@item gui_driver
+   See the next section for description.
+@end table
+
+
+@section Registering the driver
+
+Once you've done the above, you just register the driver in @code{drivers.c} and
+you may compile :) You can use @code{ui_template.c} as a driver template.
+
+You may also look at the xthreads library description if you are porting XaoS to
+some SMP platform.
+
+Please let me know if you want to start to code a driver.
+
+@node gui-driver, eui ,driver ,Top
+@chapter Writing a GUI driver
+
+XaoS has a builtin GUI. Many operating systems have native GUI toolkits and XaoS
+default GUI might look strange there. To avoid this problem, you might write an
+external GUI program (see eui section) or write mappings from the XaoS GUI
+functions to the native ones. The advantage of an external GUI process is
+multitasking; XaoS is not thread safe and the GUI must be synchronous with
+calculation.  Also, the ugly interface code currently doesn't support multiple
+windows (although this should be solved in the future).  This solution is
+suitable mainly for those systems where two cooperating programs sharing one
+window is a problem (like Windows).
+
+To write a GUI driver you need to fill out the following structure:
+@example
+struct gui_driver
+@{
+   void (*setrootmenu)(struct uih_context *c, char *name);
+   void (*enabledisable)(struct uih_context *c, char *name);
+   void (*menu)(struct uih_context *c, char *name);
+   void (*dialog)(struct uih_context *c, char *name);
+   void (*help)(struct uih_context *c, char *name);
+@};
+@end example
+
+All functions have a @code{uih_context} parameter. You don't need to worry about
+its contents; just pass it to the functions that require it. This parameter is
+for multiple window support, which is not implemented yet.
+
+The @code{setrootmenu} function draws the root menu according to the menu called
+@code{name}. To get the menu fields you might use the following piece of code:
+@example
+#include <ui.h>
+#include <xmenu.h>
+
+....
+
+int i;
+menuitem *item;
+for (i = 0; (item = menu_item (name, i)) != NULL; i++)
+   @{
+      if (item->type == MENU_SUBMENU) @{
+	      /* This field is a submenu. You might call a function to
+	         construct the submenu here. item->shortname contains
+		 the name for the submenu.  */
+      @}
+      /* Add menu field here.
+
+         You might check flags here:
+         item->flags&MENUFLAG_CHECKBOX
+	   field has a checkbox
+         item->flags&MENUFLAG_RADIO
+	   field is part of a radio button group. In the current
+           implementation, there is one radio button group per menu.
+
+	 in both cases you can call menu_enabled(uih, item) to see
+	 if the item is checked or not.
+
+         item->name contains the field's text
+
+	 item->key contains a hotkey (a one letter string in the
+         current implementation)
+   @}
+@end example
+Once the field is selected, call the function @code{ui_menuactivate(item, NULL)}
+where @code{item} is a pointer to the @code{menuitem} record of the selected
+field.
+
+The @code{enabledisable} function is called when the checkbox or radiobutton
+state is changed. The @code{name} parameter is the same as the
+@code{item->shortname} of the changed field, so you need to search all the
+menus, compare @code{name} to @code{item->shortname}, and if it matches, call
+@code{menu_enabled} to get the new state. For radiobuttons, only enable events
+are noticed. Your code is expected to automatically disable all other
+radiobuttons in the same submenu.
+
+The @code{menu} function works similarly to @code{setrootmenu}, but displays a
+popup menu.
+
+The @code{dialog} function is called for dialogs. The function should look like:
+@example
+menuitem *item = menu_findcommand(name);
+menudialog *dialog = menu_getdialog(uih, item);
+int i;
+for(i=0; dialog[i].question; i++)
+@{
+   /* Construct dialog, where the left side contains labels with
+    dialog[i].question, and the right side contains input entities based on the
+    dialog[i].type. Dialog[i].type is one of the following:
+
+    DIALOG_INT: integer value input. The default value is: dialog[i].defint
+    DIALOG_FLOAT: floating point input value (long double, where available).
+    Default value is dialog: dialog[i].deffloat
+    DIALOG_COORD: complex value floating point input (two floats), default
+    values are dialog[i].deffloat and dialog[i].deffloat2
+    DIALOG_STRING: string input. Default value is dialog[i].defstr
+    DIALOG_IFILE: input file
+    DIALOG_OFILE: output file
+         default mask is dialog[i].defstr
+    DIALOG_CHOICE: choice between various strings.
+         cast dialog[i].defstr to char ** to get a pointer to a NULL
+         terminated array of choices.
+@}
+@end example
+Once the dialog is filled by the user, @code{gui_driver} is expected to allocate
+an array of union @code{dialogparam}:
+@example
+dialogparam *p = calloc (sizeof (*p), nitems);
+@end example
+and fill in the selected values. @code{p[i].dint} is used to pass an integer
+value, or the number of a DIALOG_CHOICE selection, @code{p[i].number} is used
+for floating point numbers, @code{p[i].dstring} for strings and filenames,
+@code{p[i].dcoord[0]} and @code{p[i].dcoord[1]} for complex values.
+
+The string values are expected to be in separately @code{malloc}ed chunks. Once
+the array is filled, call @code{ui_menuactivate(item, p)}.
+
+The function @code{help} is used to display help about a given topic. To
+implement it you could either convert XaoS help file to some native format, or
+use the xshl library to render the help page for you. To render an xshl page
+use:
+@example
+#include <xshl.h>
+xshl_line *lines;
+int getwidth (void *data, int flags, char *text)
+@{
+	return width of text with given flags
+	flags is mask of the following:
+         XSHL_BIG - large text
+         XSHL_EMPH - emphasized text
+         XSHL_MONOSPACE - monospaced text (typewriter)
+         XSHL_LINK - line (should be underlined or suchlike)
+         XSHL_WHITE 
+         XSHL_RED 
+         XSHL_BLACK - color of text (not very meaningful here)
+         XSHL_RIGHTALIGN 
+         XSHL_CENTERALIGN - alignment of text
+
+@}
+lines = help_make (name, getwidth, textheight, largetextheight);
+if (lines == NULL)
+  lines = help_make ("main", getwidth, textheight, largetextheight);
+
+@end example
+Now you might use @code{lines} to draw the help. It is a pointer to the array of
+structures:
+@example
+struct xshl_line @{
+  int y;
+  struct xshl_item *first;
+@};
+@end example
+@var{y} is the position of the line from the beginning of the text, and
+@var{first} is a pointer to the blocks of text on the line. The last line
+contains a @code{NULL} pointer in the first section.
+
+@code{first} is a linked list of @code{xshl_item} structures:
+@example
+struct xshl_item @{
+  struct xshl_context c;
+  char *text;
+  int x;
+  int width;
+  struct xshl_item *next;
+@};
+@end example
+
+You can draw @code{text} at position @code{x} (and @code{y} from the line
+record) using the text style described by @code{xshl_context}:
+@example
+struct xshl_context @{
+	  int flags;
+	  char *linktext;
+@};
+@end example
+@code{flags} has the same meaning as in the @code{getwidth}
+section. @code{linktext} is the name of the next help page when the field has
+the @code{XSHL_LINK} atribute.
+
+For an example of @code{gui_driver}, see the win32 driver code.
+
+
+
+
+@node eui, ui-helper ,gui-driver ,Top
+@chapter Writing an external user interface
+
+This part describes how to make an external user interface --- that is, a
+separate program which constructs a window with all menus and dialogs. It uses
+the XaoS engine to calculate the fractal as a separate process. This design
+brings many advantages --- the external GUI implementation could have a ``native
+look'' for given platform and could contain many extensions (perhaps multiple
+windows). Also all calculation is done while multitasking, so the user interface
+is usable even when the engine is busy.
+
+The X Window System provides a way for programs to draw into others' windows ---
+the ``master'' program creates window the sub-window where it wants to put the
+fractal, then calls the engine with @code{-windowid} @var{number_of_window}
+parameters. Instead of creating a new window, the engine uses uses the specified
+window. The most famous example of such cooperation is probably
+ghostscript/ghostview.
+
+Other windowed environments probably provide similar means for for
+cooperation. In most others it will probably be implemented using shared memory,
+so it should work on most platforms, I expect.
+
+Of course, you might also design the UI as a separate button box in another
+window, like most animation players, or ImageMagick do. In fact, the external
+GUI could be very similar in style to ImageMagick...
+
+@section Basic concept
+
+The UI implementation has a function to disable its GUI functions.  Because of
+the function registry, all its menus and dialogs are described in a fairly
+simple database, which is also mapped to the Scheme-like scripting language.
+The external UI implementation can just translate the user's actions into this
+scripting language and send that through the pipe.
+
+The commands, menus, and dialogs should be created automatically from the
+database, so the UI doesn't need to have special code for each XaoS feature. At
+the beginning it should use XaoS' @code{(print_menus)} command to force it to
+send information about the database, then build menus using this information.
+
+For this you only need some equivalent to UNIX pipes, so again I expect it is
+doable on most platforms.
+
+@section Starting XaoS as a slave process
+
+One of the first things the engine needs to do is to initialize XaoS in the
+right mode to work as a slave process. For this you need to do several things:
+
+
+@itemize @bullet
+@item Open the pipe
+@item Disable the builtin GUI
+@item Read the menu hierarchy (this is optional --- GUI can also have all menus
+coded into it. But it is not recommended, since it will cause problems with
+adding new features in future)
+@end itemize
+
+Opening pipe is done via the @code{-pipe} option. It takes one parameter, the
+name of the FIFO you want to use. If you specify ``@code{-}'', XaoS will read
+input from stdin.
+
+To disable the XaoS GUI use @code{-nogui}. This will disable all menus, dialogs
+and help text.
+
+To read the menu hierarchy, just add @code{-print_menus} parameter and then
+parse XaoS's output. This will print the whole menu hierarchy. If you are
+building menus at the time they are selected, you might prefer to use the
+@code{print_menu} command, which prints just one menu without its submenus; its
+output could be immediately used for building a menu. The command takes one
+string parameter, the name the menu you want to print; i.e., to print the root
+menu use @code{-print_menu root}.
+
+Under the X Window System you also need to specify the @code{-windowid}; also
+the @code{-shared} option is quite recommended. Otherwise in pseudocolor visuals
+XaoS will create its own colormap, wich will likely collide with the UI's
+colormap, and either XaoS or the UI will have wrong colors. If you have any
+idea how to avoid this, let me know.
+
+You might also let the user specify some extra parameters from the command line,
+by simply adding those options to the end of the command line. The @code{-nogui}
+and @code{-print_menus} commands must be first for a simple reason: XaoS parses
+its command line early in initialization. Some commands (like
+@code{-print_menus}) should be processed at this time, while others (like
+@code{-loadpos} need a working engine. Such commands are queued and processed
+later, once the engine is initialized. XaoS never reorders commands; if an
+option that requires queuing is located before @code{-print_menus} on the
+command line, it will queue @code{-print_menus} too. This will cause the menus
+to be printed much later, slowing startup.
+
+So the proper calling sequence for the user interface under X should look like:
+
+
+@example
+xaos -nogui -print_menus -windowid <id> -share -pipe - @var{[other options]}
+@end example
+
+@section Parsing the menu structure
+
+The structure is printed menu by menu. Each menu contains a header, some
+entries, then @code{endmenu}. The listing from @code{print_menus} is terminated
+by @code{endmenus}.
+
+The header starts with @code{menu} and then contains a menu identifier, and the
+menu's full name, e.g.
+
+@example
+menu "fractal" "Fractal"
+@end example
+
+Each entry which follows has its own line. It starts with a menu type, which
+should be @code{submenu} or @code{menuentry}.
+
+@code{submenu} has a similar format to the header --- the full menu name, and an
+identifier.
+
+The next few fields are @code{menuentry}-related. It has an entry type, which
+could be @code{normal}, @code{radio} or @code{checkbox}. @code{radio} and
+@code{checkbox} are followed by @code{on} or @code{off} specifying whether it is
+enabled or disabled by default. (The radio-buttons don't have explicit
+information about which group they belong to. For now I expect that each menu
+contains just one such group, so it is clear in any case.)
+
+A set of flags should follow. Currently two flags are defined: @code{dialog},
+wich specifies that the function has a dialog box, and
+@code{dialogatdisable}. By default, dialogs for check-boxed functions are
+displayed only when the checkboxes are enabled. The second flag reverses this
+behaviour. It is currently used for the @code{mandelbrot} function, which
+behaves in this way; when you disable it, the user is prompted for the Julia
+seed.
+
+So a specification should look something like this:
+
+@example
+menu fractal "Fractal"
+submenu "formulae" "mformula"
+submenu "Incoloring mode" "mincoloring"
+submenu "Outcoloring mode" "moutcoloring"
+submenu "Plane" "mplane"
+submenu "Palette" "palette"
+menuentry "Mandelbrot mode" "uimandelbrot" checkbox off dialogatdisable dialog
+menuentry "Perturbation" "uiperturbation" checkbox off dialog
+menuentry "View" "uiview" normal dialog
+menuentry "Reset to defaults" "initstate" normal
+endmenu
+@end example
+
+@section Activating functions and dialogs
+
+Once the menu structure is built and the user selects some item, it should be
+activated. This is done by a simple command: @code{(@var{name})}. Once
+``@code{)}'' is sent, the command is executed by XaoS.
+
+Check-boxed functions has one extra parameter --- @code{#t} to enable them and
+@code{#f} to disable. So if you want to enable the @code{autopilot} item, send:
+@code{autopilot #t}
+
+Radio-buttons don't have any such parameter, because disabling radio-buttons
+makes no sense.
+
+If the item has a dialog enabled, the engine expects that the UI will make the
+dialog first, ask the user for values and then pass back a function with
+parameters. But first, the UI needs to know what parameters the function
+expects.  This is done by sending the command @code{(print_dialog
+"@var{name}")}.  XaoS replies with a dialog specification very similar to the
+menu specification.
+
+This has the header @code{dialog} followed by the name of the function being
+described. Then one dialog entry per line is sent, started by
+@code{dialogentry}, followed by the question the UI should display. Next is a
+type, which should be one of the following:
+@table @code
+@item integer
+Integer number such as @code{123}
+@item float
+Floating point number such as @code{123.123}
+@item string
+String such as @code{"ahoj"}
+@item keyword
+String such as @code{'ahoj}. Keywords are mostly similar to strings, except that
+they can not contain spaces. They are used, for example, for specifying types of
+formulae. Strings are used for printing text and so on.
+@item inputfile
+@item outputfile
+Here the UI should display a file selection dialogs. With @code{outputfile} it
+is also a good idea to check whether the file exists and ask the user if he
+wants to overwrite it.
+@item onoff
+Boolean value (@code{#f}, or @code{#t})
+@item complex
+Complex value --- two floating point numbers such as @code{123.123 123.123}
+@item choice
+Choice between some keywords. The keywords are sent after @code{choice},
+enclosed in @code{@{} @code{@}}.
+@end table
+The last information on the line is the default value, in the same format as the
+examples above. For files, the default value is in the format
+@code{"@var{[prefix]}*@var{[extension]}"}.
+
+Some examples:
+
+@example
+customdialog "uiview"
+dialogentry "center:" complex 0.000000 0.000000
+dialogentry "Radius:" float 0.000000
+dialogentry "Angle:" float 0.000000
+enddialog
+
+dialog "load"
+dialogentry "Filename:" inputfile "fract*.xpf"
+enddialog
+
+customdialog "color"
+dialogentry "Color" choice @{white black red @}white
+enddialog
+
+@end example
+
+To activate a function, send a command consisting of the function name followed
+by a sequence of parameters, mapped one-to-one to dialog box fields, in the same
+order as those fields. The parameters have the same format as in the above
+examples; checkbox fields return @code{#t} and @code{#f}. For instance:
+
+@example
+(uiview 0 0 0.5 0)
+(load "text.xpf")
+(color 'white)
+@end example
+
+@section Synchronization
+
+In some cases, XaoS can change radio-box and check-box values itself (when user
+presses a key, or loads some file, for instance). All such changes are sent to
+the GUI so that it can update what the user sees correspondingly. They are sent
+to standard output in the following format:
+
+@example
+checkbox "name" on/off
+radio "name" on/off
+@end example
+
+Your GUI code should parse this and change its menus when necessary.
+
+XaoS's menus can contain multiple distinct trees. In some cases (like when
+animation replay is active) the root of the menu structure should change. To
+indicate this to the GUI, XaoS sends a command:
+
+@example
+root "name"
+@end example
+
+Also, the user can press keys which normally display menus, dialogs or
+help. If XaoS has the keyboard focus, it will receive these instead of the
+GUI. XaoS sends commands to indicate this:
+
+@example
+menu "name"
+dialog "name"
+help "topic"
+@end example
+
+All these commands should be taken into account by the GUI, or could be ignored
+(not recommended!)
+
+@section help
+
+XaoS's help is in a simple hypertext language. In order to simplify its parsing,
+I've made xshl and help libraries. Making a help window with these libraries
+should be quite easy; just call the help function:
+@deftypefn Function struct xshl_line *help_make (char *@var{command}, int @var{getwidth} (void *, int @var{flags}, char *@var{text}), int @var{width}, int @var{smallheight}, int @var{bigheight});
+@end deftypefn
+and you will receive a stream of text with coordinates describing where to
+display the text into the shared window.
+
+The @code{command} parameter is the help topic. The @code{getwidth} function
+returns the width of a given piece of text. @code{width} is the width of the
+window, @code{smallheight} is the height of the small font, and @code{bigheight}
+is the height of the big font.
+
+Please ask me for more details if necessary.
+
+And thats all. Good luck with coding.
+
+@node ui-helper, xthreads ,eui ,Top
+@chapter UI-helper library
+
+UI helper library takes care of all of XaoS' engine functions and features and
+provides a higher level API which is quite easy to understand. If you want to
+write a completely new user interface (a replacement for the ugly interface ---
+not just new bindings for native menus or external user interfaces) or you want
+to use the XaoS engine in your program, you will probably want to use this
+library.
+
+Its API has many calls and features. This section gives a brief overview of its
+calls. Please ask me for details.
+
+@section initialization
+
+To initialize the UI helper library, you need to prepare a palette and image.
+The palette is created using the palette library call
+@code{createpalette}. Creating a truecolor palette should look like this:
+
+@example
+  struct palette *pal = createpalette (0, 0, TRUECOLOR, 0, 0, NULL,
+                                       NULL, NULL, NULL);
+@end example
+
+For details about creating palettes see @code{ui.c} or ask me.
+
+To create an image, call:
+
+@example
+  struct *image img = create_image_mem (width, height, 2, pal,
+                                        pixelwidth, pixelheight);
+@end example
+
+This creates an image in memory. If you want to create it in your own buffers,
+you might use @code{create_image_cont} or @code{create_image} calls.  Again see
+@code{ui.c}.
+
+Then it is time to fire up the main library:
+
+@example
+  struct uih_context *uih = uih_mkcontext (0, img, passfunc,
+                                           NULL, NULL);
+@end example
+
+The @code{passfunc} is called when the engine is calculating. It might process
+external events and display progress information. It should look like this:
+
+@example
+static int
+ui_passfunc (struct uih_context *c, int display, char *text, float percent)
+@{
+  /*process events */
+  if (uih->display)
+    @{
+      uih_drawwindows (uih);
+      /*display */
+    @}
+  if (display)
+    @{
+      if (percent)
+	sprintf (str, "%s %3.2f%%        ", text, (double) percent);
+      else
+	sprintf (str, "%s          ", text);
+      /*display it */
+    @}
+@}
+@end example
+It can set @code{uih->interrupt} if it wants to interrupt the current
+calculation (whereupon the main calculation loop will return to its caller).
+
+You can also load the catalog file in order to make tutorials work:
+
+@example
+  uih_loadcatalog (uih, "english");
+@end example
+
+Once this is done, the ui_helper library is fully functional and you can enter
+the main loop.
+
+@section main loop
+The UI helper library does not have any timing primitives; so it expects a
+standard form of main loop. It asks it caller to redisplay a changed image when
+necessary.  The library also uses the generic timerlib library for its timing,
+for which see elsewhere in this document.
+
+The main loop should look like this:
+
+@example
+while (1)
+  @{
+    if (uih->display)
+      @{
+	uih_prepare_image (uih);
+	uih_drawwindows(uih);
+	/*display current image buffer*/
+      @}
+    uih_update (uih, mousex, mousey, buttons);
+    if ((time = tl_process_group (syncgroup, NULL)) != -1 &&
+	    !uih->inanimation) @{
+	    /*relax for the given time in usec - wait for events etc..*/
+    @}
+    /*and repeat*/
+  @}
+@end example
+
+@section Calling functions
+
+The UI helper library has many functions declared in @code{ui_helper.h} for
+various actions. There are too many of them to describe here, but their names
+are quite informative, so I hope you will not have problems.
+
+(You could also use the XaoS function registry, which does all this stuff for
+you; you will just draw menus and dialogs based on this registry and all
+features will be automatically made available. If you are writing an ordinary
+user interface, this is the preferred way.)
+
+Note that the @code{ui_helper} library is not reentrant, so you can't call most
+of these functions from the @code{passfunc}. If you are using the registry, the
+activating function handles this automatically and queues functions when
+necessary.  To process them you need to flush the queue in the main loop as
+follows:
+
+@example
+static void
+processbuffer (void)
+@{
+  menuitem *item;
+  dialogparam *d;
+  if (uih->incalculation)
+    return;
+  while ((item = menu_delqueue (&d)) != NULL)
+    @{
+      menu_menuactivate (item, d);
+    @}
+@}
+@end example
+
+@section closing library
+
+This is done using: 
+
+@example
+  uih_freecontext (uih);
+@end example
+
+One user of this library is the ugly interface code in XaoS; see the
+@code{src/ui} directory. Another, much simpler user is
+@code{src/ui-hlp/render.c}, which does animation rendering.
+
+@node xthreads, filters ,ui-helper ,Top
+@chapter XaoS thread library
+
+This description should be useful for those who want to port XaoS to
+multiprocessor platforms, and those who want to implement a filter or other
+relatively computationally expensive code. Note that the thread library uses
+nothread calls as a degenerate case when only one thread is used, when the host
+does not allow multi-threading or it is not an SMP architecture (since this
+library is used only to distribute calculation into other CPUs).
+
+XaoS thread library is a simple map of a few functions required by XaoS to the
+system's library for threads.
+
+It has the following variables:
+
+@deffn Variable ethreads
+This is set to 1 in the case that threads are enabled
+@end deffn
+
+@deffn Variable nthreads
+Number of threads
+@end deffn
+
+It provides the following functions:
+
+@deftypefn Function {void} xth_init (int @var{threads})
+This function initializes the threading library (starts threads, sets
+@var{ethread} to @code{1} and @var{nthreads} to @var{n}. @var{threads} parameter
+should be set to 0 for auto-detection, or to the number of threads the user
+wants. If threads is set to 1, the threading library is disabled and the
+following functions are mapped to the @code{nothread_} equivalents defined in
+@code{xthread.h}.
+
+Note that all threads are not interchangeable --- there is a main thread (the
+one that called @code{xth_init}) that communicates with drivers, controls
+calculation, and so on, and there are child threads that are waiting for orders
+from the main thread. The latter threads can't use any functions from the
+xthread library.
+@end deftypefn
+
+@deftypefn Function {void} xth_uninit (void)
+This function un-initializes the thread library --- kills child threads and sets
+@var{ethread} to 0 and @var{nthreads} to 1.
+@end deftypefn
+
+@deftypefn Function {void} xth_function (xfunction *@var{function}, void *data, int @var{range})
+This function is used when the engine wants to perform some operation on the
+image in parallel. It is expected to wait until all threads are ready, then
+start @var{function} on all threads, including the control one, with the
+following parameters: @var{data} --- the same as @var{data} passed to
+@code{xth_function}, @var{taskinfo} --- pointer to a platform-dependent
+@code{taskinfo} structure (defined in @code{xthread.h}), but must have at least
+a field @code{n}, that holds the thread number (where the control thread is
+numbered 0 and other threads are numbered in the range 1 -- @var{nthreads}).
+The next two parameters are the range of images across which the function is
+expected to work. @code{xth_function} is expected to divide @var{range} into
+@var{nthreads} equal pieces and pass to each thread the start of a piece and the
+start of the next piece (@var{range} for the last one). The function does not
+wait for other threads to finish at the end, but returns immediately to main
+thread after @var{function} returns.
+
+This function is called approx. 5--10 times per frame.
+@end deftypefn
+
+@deftypefn Function {void} xth_sync (void)
+This function waits until all threads are ready for the next order from the main
+task.
+
+This function is called approx 5--10 times per frame.
+@end deftypefn
+
+@deftypefn Function {void} xth_bgjob (xfunction *@var{function}, void *@var{data})
+This function is expected to behave as follows: if there are any threads waiting
+for orders, ask one of them to call @var{function} with similar conventions as
+in @code{xth_function} except that the @var{range} parameters are set to 0.
+Otherwise it starts function in the foreground, as usual.
+
+This function is called once per frame.
+@end deftypefn
+
+@deftypefn Function {void} xth_nthread (struct taskinfo *@var{s})
+This function should be used to determine the current thread number. Do not use
+@code{taskinfo->n} instead, since if threads are disabled this will be defined
+to 0 to allow the optimizer to perform better optimizations.  This function can
+be called by all threads.
+@end deftypefn
+
+@deftypefn Function {void} xth_lock (int @var{n})
+@end deftypefn
+@deftypefn Function {void} xth_unlock (int @var{n})
+Lock/unlock lock number @var{n}. At least @code{MAXSEMAPHORS} locks must be
+available.
+@findex MAXSEMAPHORS
+
+Note that locks are used for very short fragments of code, so they need to be
+fast; so spinlocks may be better than classical Dijkstra semaphores (although
+this is untested). They are called once per calculated line/row during zoom and
+once per approx 10 pixels during calculation of a new image.
+@end deftypefn
+
+@findex MAXCONDS
+@deftypefn Function {void} xth_sleep (int @var{n}, int @var{l})
+Expected to atomically unlock lock @var{l} and sleep in queue @var{n}.  At least
+@code{MAXCONDS} queues must be available.  After the function is woken up, lock
+@var{l} again. This mechanism is used by the new image calculation algorithm,
+but it is designed to minimize its calls, so I expect it should be called once
+or twice.
+@end deftypefn
+
+@deftypefn Function {void} xth_wakeup (int @var{n})
+Wake up some thread from queue @var{n}. The lock used by sleep calls is locked
+in this case. The function should wake up all threads if a single-thread awaken
+is not supported by the host API.
+
+With luck, this function will not be called at all; it will be called by the new
+image calculation routines when the queue is empty. This happens when there are
+50 threads or thereabouts, but happens rarely at two or eight threads in my
+tests.
+@end deftypefn
+
+@deftypefn Function {void} xth_wakeall (int @var{n})
+Similar to wakeup but wake up all threads.
+@end deftypefn
+
+
+@node filters, algorithm ,xthreads ,Top
+@chapter Filters
+
+This is a brief description of the filter system used internally by XaoS.
+Filters in XaoS provide an object oriented interface to every part of the XaoS
+engine. The main filters are the user interface implemented in ui_helper.c and
+the zooming engine implemented in zoom.c. Active filters are kept in a queue ---
+in the beginnning there are just two filters here (zoom and ui), but at any
+later time additional filters (stereogram generation, and so on) can be inserted
+into the middle of the queue.
+
+When calculating, every filter should use data calculated by the filter
+immediately before it in the queue, which that filter placed into the image it
+passes to its child.  For example, the stereogram filter should take the fractal
+generated by the zooming engine and create a stereogram from it (assuming that
+the zooming engine is immediately after the zooming engine in the filter queue).
+
+This makes XaoS's code more flexible and makes future enhancements easy (perhaps
+a different zooming engine, or image rotation, other special effects, plug-ins
+or some other funny stuff) since the enhancements are forced to be decoupled by
+the filter library, and since each filter has a degree of control over filters
+that follow it in the queue.  For instance, the stereogram filter should change
+the palette, force the zooming engine to change the depth, width and height of
+the calculated image to fit its needs, and so on.
+
+This document mainly describes the creation of a filter like the stereogram
+generator --- i.e. a filter placed into the middle of the queue --- since I
+don't expect there will be many people creating ``terminal'' filters (zooming
+engines/user interface layers). Note that different user interfaces are
+possible, since the user interface layer is not the real user interface, just a
+set of high level functions that should be called by the main application, like
+@code{set_view}. So if you want to use XaoS as a calculation engine in your
+program this document is probably not for you.
+
+Each filter is defined by a @var{filteraction} structure, as follows::
+@findex filteraction
+@example
+struct filteraction @{
+  char *name;
+  char *shortname;
+  int flags;
+  struct filter *(*getinstance)(struct filteraction *a);
+  void (*destroyinstance)(struct filter *f);
+  int (*doit)(struct filter *f,int flags,int time);
+  int (*requirement)(struct filter *f,struct requirements *r);
+  int (*initialize)(struct filter *f,struct initdata *i);
+  void (*convertup)(struct filter *f,int *x,int *y);
+  void (*convertdown)(struct filter *f,int *x,int *y);
+  void (*removefilter)(struct filter *f);
+@};
+@end example
+This structure describes unchanging parameters to the filter (like its name) and
+a basic set of methods required for communication with the rest of XaoS.  The
+@var{name} field is a comparatively long description of the filter's name, such
+as ``A random dot stereogram generator''. @var{name} is displayed by the ugly
+interface in the Filters menu, so it is expected to be descriptive (but shorter
+than 30 characters). The short name is a one word long name for the filter, like
+``stereogram''. This name is used in save files and command line parameters;
+everywhere that the user might need to write it, so writing a long descriptive
+name would just be wasteful of time and disk space.
+
+The flags field is reserved for future enhancements and is expected to be 0 for
+now.
+
+@section Instance creation / destruction
+
+Functions @code{getinstance} and @code{destroyinstance} are equivalent to the
+constructor and destructor in object-oriented languages. @code{getinstance} is
+expected to create and fill out the following structure:
+
+@findex filter
+@example
+struct filter @{
+  struct filter *next,*previous;
+  struct queue *queue;
+  struct filteraction *action;
+  struct image *image,*childimage;
+  struct requirements req;
+  struct fractal_context *fractalc;
+  void *data;
+  char *name;
+  int flags;
+  void (*wait_function) (struct filter *f);
+  /*stuff for wait_function*/
+  int pos,max,incalculation,readyforinterrupt,interrupt;
+  char *pass;
+@};
+@end example
+Although this structure seems to be long and complex, most of the fields are
+currently unused, and the rest of them are filled out automatically by a helper
+function:
+
+@deftypefn Function {struct filter *} createfilter (struct filteraction *@var{fa});
+
+This function should be used to do the dirty work of instance creation and fill
+out the @var{filter} structure. The only possibly interesting field is
+@var{data}, a pointer reserved for the filter's internal use; it can be a
+pointer to the filter's internal variables if required. This is what a
+@code{getinstance} implementation that allocates such an additional structure
+might look like:
+
+@findex getinstance
+@example
+static struct filter *getinstance(struct filteraction *a)
+@{
+      struct filter *f = createfilter(a);    /*create filter structure*/
+      struct stereogramdata *i=calloc(sizeof(*i),1);
+                                             /*allocate internal variables*/
+      /*initialize your variables here*/
+      f->data=i;                             /*add pointer to internal data*/
+      return (f);
+@}
+@end example
+
+If nothing similar is required you can simply put @code{creatfilter} into the
+@var{getinstance} field.
+
+@end deftypefn
+
+@code{destroyinstance} is expected to free the memory used by the filter
+structure and all the filter's internal data. To free the filter structure use
+the normal @code{free} call. An implementation of such function should look
+something like
+:
+@example
+static void destroyinstance(struct filter *f)
+@{
+     destroyinheredimage(f);
+     free(f->data);
+     free(f);
+@}
+@end example
+The meaning of @code{destroyinheredimage} will be described later.
+
+
+@section Initialization
+
+During the initialization phase, each filter says to its parent what kind of
+images it supports (which should depend on the images that it's child has said
+it supported), the parent chooses the best supported image format for its
+purpose and gives that to the child (while passing that information on up the
+queue of filters). Initialization is done in two passes:
+
+The first pass starts at the lowest filter in the queue (zoom, by default); each
+filter passes a @var{requirements} structure to its parent.
+
+The second pass starts at the highest filter (the ui filter), and each filter
+passes to its child an image and some other stuff. Then calculation should
+begin.
+
+The queue needs to be reinitialized after creating, resizing, adding or removing
+a filter, and similar operations.
+
+The first pass is implemented using the @code{require} function. This function
+is expected to look at the child's requirements it received as a parameter, fill
+out its own @var{requirements} structure, and call the @code{require} function
+of its parent filter.
+@findex requirements
+@example
+struct requirements @{
+  int nimages;
+  int supportedmask;
+  int flags;
+@};
+@end example
+The @var{nimages} field should be set to 1 or 2. When it is 2, the parent filter
+@emph{must} pass the image in two buffers (double-buffered). Note that if it is
+1, the parent @emph{should} pass the image in two buffers, but is not required
+to.
+
+@var{supportedmask} is a mask giving the image types supported by the
+filter. Valid image types are:
+@findex C256
+@findex FIXEDCOLOR
+@findex GRAYSCALE
+@findex TRUECOLOR
+@findex TRUECOLOR24
+@findex TRUECOLOR32
+@table @code
+@item C256
+  A normal 8bpp image with palette
+@item TRUECOLOR24
+  A 24bpp truecolor image with 8 bits for each color.
+@item TRUECOLOR16
+  A 16bpp truecolor image
+@item TRUECOLOR
+  A 32bpp truecolor image with 8 bits for each color.
+@item LARGEITER
+  A 16bpp image, but without colors. The pixels are expected to hold an
+  iteration count; it could also be thought of as a 16bpp grayscale image.
+@item SMALLITER
+  Similar to @code{LARGEITER}, but 8bpp.
+@end table
+
+@findex MASK1BPP
+If you don't want to worry about palettes, color allocations and so on, but just
+want to do some non-display operation with a bitmap, you probably only care
+about the image depth and not the precise meaning of the pixels; in that case,
+you can use one of the bitmasks @code{MASK1BPP} for 8 bit images,
+@code{MASK2BPP} for 16 bit and so on.
+
+The final field in the @var{requirements} structure is @var{flags}. It's a mask
+composed from the following constants:
+
+@table @code
+@item IMAGEDATA
+  Set this if your filter requires the data from previous frame untouched. When
+  this is not set, filters can reuse your image and change it. But some
+  filters, like motion blur or the zooming engine, require data from the
+  previous frame to construct the new one; for such filters, this flag should be
+  set.
+@end table
+There are no more flags supported at the moment. The @code{require} function
+should also save the child's @code{requirements} structure into
+@var{filter->req} for later use by the initialize pass. The code for a
+@code{requirement} function might look like
+@example
+static int requirement(struct filter *f,struct requirements *r)
+@{
+  f->req=*r;    /*Save an child's requirements*/
+  r->nimages=1; /*Just one image is required*/
+  r->flags&=~IMAGEDATA;/*unset the imagedata field*/
+  r->supportedmask=C256|TRUECOLOR|HICOLOR|REALCOLOR;
+                /*mask of all supported image types*/
+  return (f->next->action->requirement(f->next, r));
+                /*call parent*/
+@}
+@end example
+The next pass is the main initialization pass. It goes in the opposite order
+(from parent to child, from the top of the queue to the bottom, in the same
+direction as image flow), and the child receives some stuff from the parent
+(such as images). The @code{initialize} function receives an @var{initdata}
+structure:
+@findex initdata
+@example
+struct initdata @{
+  void (*wait_function) (struct filter *f);
+  struct image *image;
+  struct fractal_context *fractalc;
+  int flags;
+@};
+@end example
+@var{wait_function} points to a function called by the filter during calculation
+that lets the parent filter (usually the user interface layer) inform the user
+of calculation progress. @var{image} is an image expected to be filled with an
+image in the calculation phase. @var{fractalc} is a pointer to a structure that
+will contain information about the fractal itself during calculation (formula
+type and so on). @var{flags} is a mask of the following constants:
+@table @code
+@item DATALOST
+ This is set if the data in the previous image was lost (if the image was
+ cleared or resized or freshly allocated). Filters that use data from previous
+ frames should pay attention to this flag. The zooming engine, for example,
+ recalculates the whole image if this flag is set, since all pixels from
+ the previous frame were lost.
+ Note that data will also be lost if the filter receives a different
+ @var{image} than in the previous initialization (since some filter before it in
+ the queue was removed).
+@end table
+Inheritance is carried out using these functions:
+
+@deftypefn Function void inhermisc (struct filter *@var{f},struct initdata *@var{i});
+
+This function sets fields in the filter structure like @var{fractalc} or
+@var{wait_func}.  Inheritance of images is quite complex, since the new image
+needs to be prepared for the child filter. In order to save memory it is highly
+recommended to use the same image --- or at least the same memory --- for data
+when passing to the child, but this is not allays possible. The following
+function implements a heuristic to reuse the image where possible:
+@end deftypefn
+@deftypefn Function int inherimage (struct filter *@var{f},struct initdata *@var{data}, int @var{flags}, int @var{width}, int @var{height}, struct palette *@var{palette}, float @var{pixelwidth}, float @var{pixelheight}) 
+You should call this function in your @code{initialize} pass. It fills out
+@var{image} and @var{childimage} in the @var{filter} structure, and prepares
+@var{initdata} and @var{image} for the child. Note that in some cases it may
+fail and return 0. In this case the filter is expected to interrupt
+initialization and return 0 too.
+
+The @var{flags} parameter is a mask of the following constants:
+@table @code
+@item IMAGEDATA
+  Set if your filter requires data from the previous frame.
+@item TOUCHDATA
+  Set if your filter touches data in the output image. This is the usual case,
+  but some filters, like interlace or subwindow, don't touch the image data at
+  all.
+@item NEWIMAGE
+  Set if your filter cannot use the same image for output as it uses for input
+  (that is, if the two images must be distinct blocks of memory).
+@end table
+@var{width} and @var{height} are the width and height of the image you want to
+pass to the child; it should be set to 0 if you want the same width/height as in
+the parent image. @var{palette} is the palette of the image you want to pass;
+set to @code{NULL} if the palette should be inherited from the parent's image
+(as is usual).  @var{pixelwidth} and @var{pixelheight} give the physical size of
+a pixel in centimeters; if set to 0 they are inherit from the parent's image.
+@end deftypefn
+
+If you use the @code{inherimage} mechanism, you must also call
+@code{destroyinheredimage} in the @code{destroyinstance} function and
+@code{updateinheredimage} at the beginning of the @code{calculate} function.
+
+Example implementation:
+@example
+static int initialize(struct filter *f,struct initdata *i)
+@{struct stereogramdata *s=f->data;
+  inhermisc(f,i);
+  if(!inherimage(f,i,TOUCHIMAGE,0,0,NULL,0,0) return 0;
+  /*initialize here*/
+  return(f->previous->action->initialize(f->previous,i));
+@}
+@end example
+Also note that the fractal context holds a pointer to the fractal's palette. If
+you don't change the image's palette everything is OK; but if the child's image
+differs from the parent's, there should be two behaviors --- the fractal's
+palette is the child's one (this is common in color conversion filters, going
+from 8bpp to TrueColor and suchlike), or the fractal's palette is the parent's
+one (like in the edge detection filter). By default the fractal's palette is set
+to the parent's one, because this is most likely to be generally useful;
+anything else requires explicit work from the parent to set up the child's new
+palette.
+
+This can be changed by the @code{setfractalpalette} call, which has two
+parameters --- the @var{filter} structure, and the new palette. When you pass
+the child's palette as @var{palette}, the fractal's palette will be changed to
+the child's. If you pass @code{NULL}, changing the palette will be disabled (as
+in the motion blur filter in 8bpp mode).  This is only changeable if you still
+have access to the fractal's palette; some parent might have already redirected
+the palette beforehand, in which case this function does nothing.
+
+
+@section Calculation
+
+The calculation is done using the @code{doit} function:
+
+@deftypefn Function int (*doit)(struct filter *f,int flags,int time)
+
+This function is expected to call the child's calculation function when
+required, and apply its filter to the child's output.
+
+The @var{flags} are mostly undefined; only @code{INTERRUPTIBLE} is defined for
+now, and @emph{that} is mainly for the zooming engine so I do not describe it
+here. Nonetheless, the filter is expected to pass the @var{flags} to its
+child. Finally, @var{time} is the time in milliseconds that expired since the
+last @code{doit} call. It can be used to calculate the animation speed, perhaps
+in an attempt to keep the speed constant.
+
+@end deftypefn
+
+Calculation loops return a bitmask composed of the following flags:
+@findex ANIMATION
+@findex CHANGED
+@findex INEXACT
+@table @code
+@item ANIMATION
+ Set if the filter performs some animation, and expects that its calculation
+ function will be called again soon.
+@item CHANGED
+ Set if something changed in the output image (the usual case).
+@item INEXACT
+ This is enabled by the zooming engine in @code{INTERRUPTIBLE} mode in case the
+ @var{time} was exceeded.
+@end table
+
+Most @code{doit} functions change the image. The @var{image} structure contains
+following fields that might be significant to filters:
+@findex image
+@table @code
+@item bytesperpixel
+  Number of bytes per pixel (image depth).
+@item palette
+  Palette of image.
+@item currlines
+  Array of pointers to the beginning of each scanline in the image.
+@item oldlines
+  Like @var{currlines}, but for the previous image, when double-buffering is
+  enabled.
+@item nimages
+  Set to 2 when double-buffering is active.
+@item flipimage
+  Pointer to a function that flips @var{oldlines} and @var{currlines}.
+@end table
+
+The @var{palette} structure contains the following significant fields:
+
+@table @code
+@item type
+ Type of palette/image (@code{C256}, @code{TRUECOLOR} etc...)
+@item size
+ The number of allocated entries in the palette.
+@item pixels
+ The array of allocated entries; a conversion table mapping from the iteration
+ number to a pixel value.
+@item rgb
+ @sc{RGB} values for pixels (@code{NULL} for @code{TRUECOLOR}, @code{HICOLOR}
+ and similar paletteless types)
+@end table
+
+To make writing calculation loops for different bit-depths easier,
+@code{pixel8_t}, @code{pixel16_t} and @code{pixel32_t} are predefined. You also
+can use preprocessor magic as the edge detection filter does; this lets you
+write calculation loops just once, using @code{cpixel_t}, and the code will be
+compiled for every bitmap depth.  See the edge detection filter
+(@code{src/engine/edge.c} and @code{src/engine/edged.c}) for implementation
+details.
+
+
+@section Coordinate conversion
+
+The @code{convertup} and @code{convertdown} functions are used for converting
+screen coordinates to a position in the fractal and back. @code{convertup}
+receives coordinates in the child's image, and is expected to convert them into
+coordinates in the parent's image and call the parent's @code{convertup}
+function.
+
+@code{convertdown} is the reverse of @code{convertup} (going from parent to
+child).
+
+If coordinates correspond 1:1 you should use @code{convertupgeneric} and
+@code{convertdowngeneric}; otherwise, the implementation should look something
+like this:
+
+@example
+static void convertup(struct filter *f,int *x,int *y)
+@{
+    *y*=2;
+    *x*=2;
+    if(f->next!=NULL) f->next->action->convertup(f->next,x,y);
+@}
+static void convertdown(struct filter *f,int *x,int *y)
+@{
+    *y/=2;
+    *x/=2;
+    if(f->previous!=NULL) f->previous->action->convertdown(f->previous,x,y);
+@}
+@end example
+
+@section Filter removal
+
+Before the filter is removed from the queue, the @code{removefilter} function is
+called.  It is expected to clean up anything that the filter changed.
+
+In most cases, it should be left at @code{NULL}.
+
+@section Filter registration
+
+Once the @var{filteraction} structure is filled, the filter is ready, and you
+should try to enable it. To enable it in the user interface you need to edit
+@code{src/ui-hlp/ui_helper.c}, add the filter to the @var{uih_filters}
+structure, and increase @var{uih_nfilters}. Note that the order of filters in
+@var{uih_filter} defines the order of the filters in the filter queue.
+
+Then it is high time to start experimenting.
+
+Good luck!
+@node algorithm, timerlib, filters ,Top
+@chapter Algorithm description
+The main idea behind XaoS is that it is not necessary to calculate the whole
+image in every frame; most pixels were already calculated by the previous
+frames. You usually don't have exactly the pixels you want, but all within a
+range lower than a step between pixels are acceptable. That is why the image
+flickers a bit and why points do not blink randomly as in recalculated
+animations.
+
+   This document describes some of the most important algorithms in XaoS:
+   @itemize @bullet
+     @item Saving Previous Pixels
+     @item Approximation Algorithm
+     @item Moving Pixels to New Positions
+     @item Calculating New Pixels
+     @item Symmetry
+     @item Calculation of Mandelbrot Set
+     @item Dynamic Resolution
+     @item Autopilot
+    @end itemize   
+
+@section Saving Previous Pixels
+
+Ideally, all recalculated points should be saved and used for
+building successive frames. I could not figure out a practical way to
+implement this. To save all frames for half an hour would require 24
+Mb of memory, and searching the saved frames would be more
+computationally expensive than recalculating an entirely new frame.
+
+One way was later used by the program Frang. It remembers all pixels as
+triplets of (x,y,value), and when it builds a new image, it draws all
+the pixels that it remembers to that image and then browses the image
+and fills it with new pixels. (Possibly an @sc{rle} encoding should be
+used for calculated pixels to conserve memory.) Frang actually uses an
+algorithm that takes away pixels from the screen, so it behaves in
+exactly the same way as the algorithm described here. On the other hand,
+this method seems to require much more memory than XaoS' algorithm, and
+drawing pixels/browsing the image costs quite a lot, so the algorithm
+described here seems to be faster, since it never requires examining the
+whole image, and the new image is constructed using block move
+operations.
+
+For this reason, only the last generated frame is used as a reference.
+This way the memory requirements are proportional to @math{xsize *
+ysize}. It can be shown that this method is only about 2--5% slower
+during zooming. (Of course unzooming back to once browsed areas is much
+slower.)
+
+Because only the previous frame is used, another optimization can be
+performed: The imaginary and real parts of the calculated image are not
+precise, since they are the result of successive iterations of the
+algorithm. In order to prevent errors from being propagated to the
+following frames, their exact coordinates need to be known.
+Fortunately, it isn't necessary to save their values since it is known
+that all real components in a row and all imaginary components in a
+column are equal. Thus, the only things that must be saved are the real
+components for every row and the imaginary components for every column.
+
+This allows for a substantial speed-up in approximation because the
+calculation requires less data. Of course, some rows and columns fall
+out of the threshold and new ones need to be calculated to fill in the
+gaps in the frame.
+
+Obviously, much less work is done than in a brute-force calculation:
+there are only @math{xsize + ysize} calculations instead of
+@math{xsize * ysize}. So the main loop in XaoS looks like this:
+   @itemize @bullet
+     @item Make approximations for rows
+     @item Make approximations for columns
+     @item Move old pixels to their new positions
+     @item Calculate pixels for which there is no good approximation for
+       their row
+     @item Calculate pixels for which there is no good approximation for
+       their column, but there is one for their row
+    @end itemize
+
+@section Approximation Algorithm
+
+  @unnumberedsubsec Introduction to problem
+
+You can see that the approximation algorithm is central to the
+implementation of XaoS. If a guess is incorrect the image will look
+strange, boundaries will not be smooth and the zoom will flicker. On the
+other hand, if it adds more new rows or columns than required, zooming
+will become much slower. Also, if doubling should happen (i.e., using an
+old row or column more than once) the resolution will lower and the
+image will look jagged. It is important to keep the increasing imaginary
+and real components in the correct order. If a row and column of complex
+coordinates follows one with higher coordinate values, an improved
+approximation can be attained by swapping their values.
+
+The algorithm needs to be relatively fast. It is only used for @math{xsize + ysize}
+values, but if its speed is proportional to @math{O(n^2)}, it can be
+slower than a whole recalculation of the image. Speeds of @math{O(n)} or @math{O(n * log(n))} are acceptable.
+
+  @unnumberedsubsec Some simple algorithms to solve it
+
+Initially, a very simple algorithm was used:
+
+  Find the old row/column nearest the row/column that needs to be
+  regenerated. If the difference between them is less than one step
+  (@math{step = (end - beginning) / resolution}) then use it. Otherwise,
+  recalculate a new one.
+
+Finding the nearest row/column pair is very simple since it is always
+greater than or equal to the pair needing to be generated.
+
+Surprisingly, this simple algorithm has almost all the problems
+described above. Doubling was fixed by lowering the limit to @math{step / 2.}
+This caused a considerable slowdown so the limit was returned to @math{step}.
+Instead, the algorithm was changed to search for only row/column pairs
+that are greater than the previous frame's row/column pairs. This is
+the algorithm that was used in version 1.0.
+
+This algorithm still added too many new rows and columns, and did not
+generate smooth boundaries. For version 1.1 a heuristic was added that
+preferred approximating rows/columns with lower values. This way it
+did not occupy possible rows/columns for the next approximation. The
+result was a speedup by a magnitude of four. In versions 1.1 to 2.0
+many improvements were made to the heuristic to give it added
+performance. The following example tries to explain how complicated
+the problem is (O is the old coordinates and X is the values to be
+approximated):
+@example
+        X1        X2        X3        X4        X5        X6        X7
+O1 O2                    O3 O4 O5                   O6 O7 O8
+@end example
+
+The normal algorithm will aproximate X1 by O2, X3 by O4 but nothing
+more. For the algorithm with threshold step instead of @math{step / 2}:
+
+@example
+  O2 to X1
+  O3 to X2
+  O4 to X3
+  O5 to X4
+  O6 to X5
+  O8 to X6
+@end example
+
+But this will fail with X7. The second algorithm which relies on lower
+values will do the following:
+
+@example
+  O1 to X1
+  O3 to X2
+  O4 to X3
+  O5 to X4
+  O6 to X5
+  O7 to X6
+  O8 to X7
+@end example
+
+O1 to X1 is wrong. And there is many and many other situations that
+may occur. But you may see that the normal algorithm will calculate 4
+new rows/columns but the heuristic saves all of these calculations.
+
+  @unnumberedsubsec Current algorithms used
+
+In version 2.1 work on this heuristic was disabled after I discovered a
+surprisingly simple algorithm that solves all these problems. First I
+decided to exactly define the ``best approximation''. This should be
+done by defining a price for every approximation and choose the
+approximation with the lowest price. Prices are defined as such:
+
+  Approximating row/column x by y costs @math{dist(x, y) ^ 2}.
+
+This prefers two smaller approximation errors before a single larger
+error and describes my goal quite well.
+
+The cost for adding a new row/column specifies when it is better to do
+a bad approximation and when to add a new row/column. I use @math{(4 * step)
+* (4 * step)}. This means that the approximation is acceptable when
+@math{dist(x, y) < 4 * step}. Otherwise, adding a new row/column costs less.
+Now the best approximation is known. All that is required is a fast
+algorithm to do this. Surprisingly, this is possible in linear time
+using a relatively simple dynamic algorithm. It uses approximations of
+@math{length < n} to make a guess at the length of @math{n}. It can start by
+approximating one row/column and then again for two, three up to
+xsize/ysize rows/columns.
+
+The algorithm starts by calculating prices for all possible new
+positions for old row/column 1. Because of the pricing there are
+maximally 8 new positions. (Other ones must cost more than adding new
+row/column). Of course it is possible that there are no new positions.
+
+
+For calculating the price of approximations for row/column 2 I may use
+the previous column: Try new position n. Calculate the price and add the
+best approximation for the previous (row/column 1) that uses a new
+position lower than n (thus prohibiting doubling or swapping). This
+should be one of 8 positions or (eventually) adding a new one and not
+using row/column 1 at all.
+
+The same method can be used for the rest of the rows/columns. At the
+end the best price may be found for the last row/column and return by
+the way it was calculated. (For this I need the saved ``calculated
+using'' values.) At this step the best approximation has been
+determined.
+
+To fill the table, @math{9 * n} steps are required and n steps to
+backtrack to the best approximation. The only problem is that this
+algorithm is still a little slow (chiefly because of slow memory access
+on the Intel architectures). But, with some optimizing, it works well.
+
+This algorithm is almost perfect except that it occasionally adds new
+rows/columns to the wrong locations --- it does not prefer to add new
+rows/columns into holes --- but it does not seem that this is a real
+problem. The last optimization made was based upon the fact that added
+rows/columns do not have the exact real and imaginary components
+calculated by (@math{beginning + x * step}) but lie at the average of
+their left and right neighbors. This makes the boundaries smooth and
+distributes coordinates better. It also has the added benefit of making
+the input better for future approximations.
+
+Another danger during implementation of this algorithm is that adding new
+rows/columns into their ideal positions could cause misordered results,
+since some rows/columns could be off more than the distance between
+them. To avoid this, I use an algorithm that always examines the start
+and end of a block of new rows/columns and linearly interpolates the
+value between them. Special care needs to be taken with the blocks that
+start at the beginning or finish at the end.
+
+Implementation should be much faster using custom fixed-point
+routines --- first recalculate values such that 0 means start of image
+and 65536 means end. Than calculation is much cleaner. Values <0 and
+>65536 are off screen, calculation is independent of scale, and many
+things should be recalculated --- like tables for calculating price from
+distance.  Also dividing the main loops into many specialized parts and
+avoiding filling unnecessary parts of tables helps. So current algorithm
+in XaoS is about 5 or 6 times faster than first naive implementation.
+
+@section Moving Pixels to New Positions
+
+Since XaoS is using the approximation algorithm the following table is
+filled for every row/column:
+   @itemize @bullet
+     @item calculate
+     @item oldpoint
+     @item position
+   @end itemize
+
+calculate is 1 if the current row/column is new and needs to be
+calculated or 0 if no old pixels need to be moved. oldpoint is a
+pointer to the old row/column that corresponds to the new one. This
+pixel needs to be copied to the new location. position is the real and
+imaginary components of the coordinates used for future
+approximations. Because almost all points will be moved, the solution
+seems to be simple: for every new point look at the row and column
+table; copy it if required.
+
+There is the problem that this minimally needs three memory reads for
+every pixel (read calculate, oldpoint and index of old point). This is
+too slow, so a small optimization is performed. Instead of rewriting the
+piece of code in assembly, normal memcpy is used to move blocks of pixels
+to their new locations. This minimizes the internal loop and access can
+be done more quickly since memcpy is usually optimized for each
+architecture.
+
+Using the row table, a list of blocks to move for every row is
+created. With this new table all the pixels can be moved quickly. This
+increased the speed of XaoS by about four times and made this function
+so fast that it is no longer a problem. (In fact, it takes much less
+time than all other parts of XaoS.)
+
+@section Calculating New Pixels
+
+The above optimizations make XaoS very fast, but another 30% increase in
+speed is acquired by using a clever method for calculating the new
+pixels. Many methods are known for saving calculations during the
+generation of fractal images. The most powerful is boundary detection.
+It relies on the fact that the Mandelbrot Set is connected with lakes.
+You need only one pixel at the boundary, then can traverse the whole set
+and fill the solid area inside. This method saves many calculations but
+is too complex for adding just one line. Many claim that it does not
+introduce any errors, but this is not true. It is possible for a
+connected part of the lake to be so small that it is not visible in
+smaller resolutions. In this case, boundary detection misses the whole
+area. This algorithm is actually used just for calculating of new images
+(i.e. at the startup).
+
+XaoS uses modification of method known as solid guessing. The pixels
+at the boundaries of a rectangle are calculated. If they are all the
+same you may assume that this rectangle does not does not contain
+anything and fill it.
+
+This algorithm is further modified to operate on added lines. For this
+it is at least as good as boundary detection and produces more
+tangible errors. When adding a single line, the upper and lower line
+may be examined for the nearest three pixels. If they are all the same
+then it is assumed that 9x9 pixels are the same. This disables all
+calculations inside solid areas and calculates as many points as
+boundary detection. The only possibility of creating a larger error
+with this method as opposed to boundary detection is in the instance
+that the shape of the set is so sharp that it does not set any of the
+tested points but comes from the right (i.e., uncalculated) location.
+This situation is not very common.
+
+Later, rules were added for new rows and columns that crossed each
+other. In this instance you can test only four pixels. This situation
+is very rare. It is hoped that it does not introduce many errors.
+
+If multiple blocks of new lines need to be calculated there are no
+reference pixels to use for solid guessing. Interlacing does the
+trick. By calculating the odd lines without any guessing, the guessing
+algorithm is now possible for the remaining uncalculated lines. This
+simple trick saves about 30% of the calculation of the main Mandelbrot
+image.
+
+A similar approximation can also be done for the X coordinate. This
+makes it possible to improve solid guessing at even pixels because all
+surrounding pixels are available, further reducing errors.
+
+@section Symmetry
+
+Many fractals are horizontally or vertically symmetrical. This is
+implemented in the approximation code. When there is no good
+approximation available, try to mirror the opposite side if the line
+is available.
+
+This method primarily speeds up the initial image.
+
+@section Calculation of the Mandelbrot Set
+
+The internal Mandelbrot calculation loop is unrolled --- it calculates
+the first 8 iterations using the normal method, and then it expects that
+number of iterations will probably be large, so it switches into a mode
+where it calculates iterations in blocks of 8 with one bailout test at
+the end. When the bailout is attained, saved values from previous
+iterations are restored and the last 8 iterations are recalculated slowly
+to get exact values. This especially helps on the Pentium, where
+conditionals in floating point code are slow.
+
+Another stuff is periodicity checking. XaoS has loops with and without
+periodicity checks. In most cases it uses the no-periodicity-checking
+version. The periodicity check version is used just in the case where
+some inside-set pixel has been found during the solid guessing
+phase. This is done mainly because the periodicity checking version of
+the loop is significantly slower.
+   
+@section Dynamic Resolution
+
+The above optimizations often do not help enough and image calculation
+is still too slow. One option was to reduce the framerate, but a
+framerate lower than 5 frames per second is unbearable. Another option
+is simply to calculate only the details that can be determined within
+a time interval.
+
+Rows/columns not calculated are simply approximated by referencing the
+nearest row/column. The result is an image with larger pixels.  One
+problem is the fact that the order of calculating the rows/columns is
+significant. Previous versions of XaoS simply calculated all rows from
+top to bottom and then columns from left to right. Using the dynamic
+resolution code with this algorithm would result in distorted
+images. This was solved by adding a priority to every row/column and
+calculating the high priority row/column first. The algorithm for adding
+these priorities is as follows:
+@itemize @bullet
+  @item Find middle row/column of uncalculated block. Priority is the size
+    of the block (in floating point coordinates)
+  @item Start function for left block and right block
+@end itemize
+
+This function produces quite good results. It tends to make same-sized
+rectangles on the whole image and does not depend on resolution.
+
+Another interesting optimization is that during the zoom it is more
+advantageous to calculate rows/columns in the center of the zoom
+instead of the borders since these will be in the viewport longer and
+the user is usually focusing on the center of the zoom anyhow.
+
+This is done by simply adding to the calculated priority
+@math{normal_priority / (abs(newposition - oldposition) / step + 1)}. This
+prefers rows/columns that do not move a great deal. (Of course,
+unzooming uses the reverse of this formula.)
+
+The last variable to consider is the time interval for one frame.
+Setting it too low makes the calculation slow. Setting it too high makes
+the framerate too low. So the amount of time spent in other parts of the
+program is calculated and multiplied by 5 to determine the interval. If
+this indicates a framerate lower than 15FPS, 15FPS is used instead, since
+slower animations are unacceptable. On the other hand, if it is higher
+than 35FPS, it is set to 35FPS, since a higher framerate than that is
+just wasting computer resources. When the image is not animating, this
+value is changed, so a framerate between 5FPS and 15FPS is selected. This
+ensures that images are calculated quickly after zooming stops.
+
+@section Autopilot
+
+Another interesting algorithm controls the autopilot. It is actually
+quite simple. Interesting parts are found at the boundaries of the
+set. It randomly looks around and zooms to the first area containing
+both outside and inside set points. Some fractals (such as the Newton)
+do not have points inside the set at all. In this case it selects a
+point where many (more than 2) different colors are around. (i.e., It
+zooms into noisy areas.)
+
+In the instance that there are no such areas, the autopilot will
+unzoom. It also detects oscillations / vacillations and breaks them.
+
+The current implementation also does detection of out of range numbers;
+randomly chosen points are chosen near the old one, to avoid frequent
+changes of direction.
+
+@section SMP support
+Since version 3.0 XaoS supports SMP. This is done using threads. Most of
+XaoS routines should be threaded easily --- for example
+@code{moveoldpoints} just divides image into @math{n} equal parts and
+each part is computed by one processor. The only unthreaded part is the
+realloc table calculation routines. I don't see any way to paralellize it
+except for calculating both @math{x} and @math{y} approximations
+simultaneously (using two processors). Another interesting algorithm to
+parallelize is boundary trace; see the comments in
+@code{src/engine/btrace.c} for discussion of the current implementation.
+The only problem I see in the current implementation is the possibility
+that calculation is divided into too many parts (realloc tables, move
+points, calculate, symmetries, dynamic resolution) causing too much
+synchronization between each part. So this may be too slow on a real SMP
+box.
+
+@node timerlib, registry,algorithm ,Top
+@chapter The timer library
+
+Timer library is a library originally written for timing in XaoS; but I
+found it useful in many other programs (like demonstrations, games,
+animation players and other stuff that needs to be timed). So you should
+read this description and possibly use it in your application and save
+some coding time.
+
+There are many ways to design a timed application (such as a game)
+
+@enumerate
+@item
+Read user input, move baddies, display and loop again.
+
+This way has one disadvantage; the speed of game depends on the speed of
+the computer.  This was acceptable in olden times where the only
+processor was the Z80 :) but now with a wide variety of hardware with
+widely differing speeds such a loop is unacceptable.
+
+@item
+Read user input, measure time since last loop and calculate step for
+baddies, move baddies for set step, display and loop again.
+
+This way fixes the problem with speed. But moving baddies just for
+calculated step, that should differ a much is quite complex, usually
+introduces complex calculation, floating/fixedpoint math and other
+unnecessary stuff that makes program long and introduces many bugs.
+
+@item
+Set a fixed framerate that is high enough to make the game smooth but low
+enough to do the whole internal loop in time. The internal loop then
+looks like this: read user input, move baddies, display, measure time
+spent in loop, sleep until next frame.
+
+This is quite a popular scheme but has another disadvantage --- game can
+not be designed to use the whole CPU power, since on slower computers
+internal loop would longer than is available for one frame, so the game
+will run slowly again.
+
+@item
+To take away disadvantage of previous method, many games time just the
+moving of baddies and user input. Other stuff like displaying should be
+done in the `untimed' rest of the time. In DOS games moving and user
+input is often done in an asynchronous interrupt and drawing runs as the
+main loop. This solves the case where the drawing of the game takes a
+significantly longer time than the moving of baddies. This is quite
+common so this scheme works well.
+
+@item
+The previous scheme still has one problem --- since the timer interrupt
+works asynchronously, there could be many race conditions: if moving
+takes a longer time than the time reserved for it, the computer can
+crash. So this scheme should be enhanced into a synchronous one with
+exactly the same result but avoiding the problem with race conditions:
+
+Read user input, measure the time spent by the loop and calculate how
+many simulated frame interrupts were activated since last activation: if
+zero, sleep until simulated interrupt, move baddies as many times as
+required, display, and loop again.
+
+This is a combination of 4 and 3 and seems to be the most comfortable way
+for writing games, but since the main loop is now quite complex many
+games don't do that.
+
+@item
+there is still one small problem. Method 5 expects that moving takes a
+significantly smaller time than displaying. This may not be the truth. A
+simple work around is to write a moving routine that should move for
+@math{x} moves in a faster way than calling move @math{x} times. This is
+often possible, and makes extension to scheme 5 easy. This scheme allows
+you to use a very large maximal framerate (say 100FPS) and to have the
+same results as method 2 (which is the maximally exact method)
+@end enumerate
+
+As you can see, designing the main loop isn't so easy. This is just a
+very simple example: a more advanced application might want to move one
+set of baddies at one framerate and another at a different
+framerate. This requires two such timings. Another complication is that
+there are many different ways to measure time exactly on different
+platforms. Under Linux you can measure using @code{gettimeofday}, but
+under DOS this is exact to just 1/18 of second and thats too low for
+smooth animation, and so on.
+
+That's why I decided to design a portable easy to use timer library, that
+makes it easy to implement all methods described above, combinations of
+them, and much more.  During the design I took care of the following
+things: quality of timing, how easy to use it is, speed, portability and
+to minimise unexpected situations (like race conditions in asynchronous
+interrupts and so on)
+
+@section The name of the game
+
+The timer library operates with @dfn{timers}. They should be created, you can
+measure time since last reset, pause them or set @dfn{handler} and
+@dfn{interval}. But handler is not yet activated at the given interval. Since
+timer library is not asynchronous, you must activate them yourself.
+
+For activating @dfn{groups} are used. You should process a group at some place
+in your program, whereupon all timers in the group are checked and their
+handlers activated if required. When the time spent since last activation is
+higher than the interval, the handler is activated more than once. Also, the
+interval to next invocation is calculated to keep frequency.  Simple scheduling
+is performed for handler --- handler is activated just once and then all other
+timers are checked before it is activated again. You can also define a
+multihandler --- a handler that is activated just once and receives as an
+argument a count of intervals.
+
+There are two special groups --- @code{asyncgroup}. Timers in this group are
+activated asynchronously (as though they were called from interrupts). Thisis
+not recommended, since the asynchronicity brings many problems and usually isn't
+required. Also it does not work on many platforms. @code{syncgroup} is the
+default group. The program is expected to process it quite often. If you don't
+need to use more than one group, you should use this one.
+
+Time in timerlib is bit strange, since it does not flow continuously but
+jumps. It is updated every time you call @code{tl_updatetime}. I did this in
+order to minimize context switches, but later I found this scheme very useful,
+since you normally look up the timer, do something and then reset it and don't
+want to worry about any time spent between lookup and reset. This helps to keep
+frequency of timers exact w/o any errors caused by such situations. At the other
+hand you need to call @code{tl_updatetime} at least once in your main loop.
+
+Maybe you don't know why you'd want to create more groups, but I found it quite
+useful.  For example, an autopilot in XaoS has such a special group --- I need
+to call it approx. every 1/20 of second, but just at one place in the
+program. Invocation of the autopilot when calculation is active would produce
+incorrect results, so I have a special group for autopilot and process it in
+just one place where I am sure it is safe.
+
+Timers can also be emulated. You can stop them and then control the flow of time
+for given timer. This should be quite useful; for example, when you want to
+precalculate animation at a given framerate.
+
+To control a group of timers, you can create @dfn{emulators}, which are just
+other timers controlled by you. They are useful in cases where you want to
+emulate fixed framerates (for animation rendering) or suchlike.
+
+@section Time functions
+
+@deftypefn Function void tl_update_time (void)
+Update time used by timerlib. This must be called at least once in the main loop
+otherwise time will not flow. See above.
+@end deftypefn
+@deftypefn Function void tl_sleep (int @var{time})
+Sleep for the given @var{time}. Similar to @code{usleep} in @sc{POSIX}.
+@end deftypefn
+@section Group functions
+
+@deftypefn Function tl_group* tl_create_group (void)
+Allocate and initialize the group header. Returns @code{NULL} when @code{malloc} fails.
+@end deftypefn
+@deftypefn Function void tl_free_group (tl_group *@var{group})
+Free memory storage used by group structure.
+@end deftypefn
+@deftypefn Function int tl_process_group (tl_group *@var{group}, int *@var{activated})
+Process timers in @code{group} and activate their handlers. Returns time until
+next invocation; the main loop should sleep for that long. The @var{activated}
+parameter is either @code{NULL}, or a pointer to a variable that is set to
+the number of activated handlers.
+@end deftypefn
+@section Timer functions
+
+@deftypefn Function tl_timer* tl_create_timer (void)
+Create timer structure.
+@end deftypefn
+@deftypefn Function void tl_free_timer (tl_timer *@var{timer})
+Free memory storage used by timer structure.
+@end deftypefn
+@deftypefn Function void tl_reset_timer (tl_timer *@var{timer});
+Reset timer to current time (the time of last actication of @code{tl_update_time}).
+@end deftypefn
+@deftypefn Function int tl_lookup_timer (tl_timer *@var{timer});
+Return time since last call of tl_reset_timer or last activation of handler.
+@end deftypefn
+@deftypefn Function void tl_set_interval (tl_timer *@var{timer}, int @var{interval});
+@end deftypefn
+@deftypefn Function void tl_set_handler (tl_timer *@var{timer}, void (*@var{handler}) (void *),void *userdata);
+@end deftypefn
+@deftypefn Function void tl_set_multihandler (tl_timer *@var{timer}, void (*@var{handler}) (void *,int),void *userdata);
+
+Handler, multihandler and interval control functions
+@end deftypefn
+
+
+@deftypefn Function void tl_add_timer (tl_group *@var{group}, tl_timer *@var{timer})
+Add timer to given group. A timer should be in only one group.
+@end deftypefn
+@deftypefn Function void tl_stop_timer (tl_timer *@var{timer})
+@end deftypefn
+@deftypefn Function void tl_resume_timer (tl_timer *@var{timer})
+Stop and resume timer.
+@end deftypefn
+
+@deftypefn Function void tl_slowdown_timer (tl_timer *@var{timer},int @var{time})
+The time in the timer is moved back to the given time.
+@end deftypefn
+
+@section Emulator functions
+@deftypefn Function struct timeemulator *tl_create_emulator (void);
+This function creates new a emulator --- you need to create one first before
+emulating.
+@end deftypefn
+@deftypefn Function void tl_free_emulator (struct timeemulator *@var{t});
+Destroy emulator's data.
+@end deftypefn
+@deftypefn Function void tl_elpased (struct timeemulator *@var{t}, int @var{elpased});
+Move emulated time.
+@end deftypefn
+@deftypefn Function void tl_emulate_timer (struct timer *@var{t}, struct timeemulator *@var{e});
+Set timer to the emulated mode; the passage of time is now controlled by the
+emulator @var{e}. All other behavior of timer keeps unchanged.
+@end deftypefn
+@deftypefn Function void tl_unemulate_timer (struct timer *@var{t});
+Disable emulated mode for the timer.
+@end deftypefn
+@section Example main loop
+
+@example
+while(1)
+@{
+  time=tl_process_group(syncgroup,activated); /*Call game control functions*/
+  update_keys();
+  if(activated) /*something changed*/
+    display();
+  else tl_sleep(time);
+@}
+@end example
+
+@node registry, index,timerlib ,Top
+@chapter XaoS function registry
+
+XaoS has an ui helper library, which provides functionality used by the user
+interface. All its useful functions are registered into a central registry.
+This registry is used to generate menus and dialogs as well as command line
+options or scripting language; so it is a very significant thing in XaoS design.
+
+This is not just useful for those who want to hack XaoS ui-helper layer, but
+also for authors of drivers, who can use this to add new driver dependent
+functions into XaoS's menu. The external user interface is also based on the
+registry.  The main idea behind external user interfaces@footnote{currently one
+for Tcl/Tk and Gtk is under development} is this: XaoS transfers its registry to
+the interface (using asimple description language). The user interface starts
+XaoS in its window and builds menus and dialogs based on the registry. Then,
+once user selects some function, the user interface creates a command in XaoS'
+scripting language and sends it back to XaoS' engine.
+
+Knowledge of this part is thus essential for many developers. Please pay
+attention. :)
+
+The implementation of the registry is in @code{xmenu.c}, and the header is
+@code{xmenu.h}. For historical reasons, it talks about menus and dialogs (it was
+originally designed for the GUI). I am keeping this terminology, since it is
+quite clean and easy to understand instead of talking in some cryptic abstract
+terms.
+
+@section Function description
+
+To add a function into the database, you need to put a description into the
+@var{menuitem} structure. It has the following definition:
+
+@findex menuitem
+@example
+typedef struct menuitem
+  @{
+    char *menuname;
+    char *key;
+    char *name;
+    char *shortname;
+    int type;
+    int flags;
+    void (*function) ();
+    int iparam;
+    void *pparam;
+    int (*control) (struct uih_context *);
+    menudialog *(*dialog) (struct uih_context *);
+  @}
+menuitem;
+@end example
+
+@defvar menuname
+Name of menu (or category) the function belongs in. The root of all categories
+is called @code{"root"}. XaoS also uses an @code{"animroot"} when animation
+replay is active. If you are adding a function, it is better to add it into some
+subcategory like @code{"ui"} (which will place it into the UI menu) or to create
+a new category for your functions, which will appear as a submenu of the main
+menu in the UI.
+@end defvar
+
+@defvar key
+@sc{ASCII} code of the hotkey that activates this function. Use @code{NULL} if
+none.
+@end defvar
+
+@defvar name
+Longer name of the function, used in the menu entry, or @code{xaos --help}
+listing.
+@end defvar
+
+@defvar shortname
+One-word name of function used in command language and other references to
+the function.
+@end defvar
+
+@defvar type
+Type of function --- this is @emph{not} the return type. @var{type} should be
+one of the following constants:
+@table @code
+@findex MENU_SUBMENU
+@item MENU_SUBMENU
+   A submenu. This is not a function, but a name for the submenu. You can fill
+   in the @var{key}, @var{name}, and @var{shortname}. The name of this new
+   submenu is placed in the field @var{pparam}.
+@findex MENU_NOPARAM
+@item MENU_NOPARAM
+   A normal function without any parameters. When activated,
+   @var{function} will be called with a pointer to @code{uih_context} as its
+   parameter.
+@findex MENU_INT
+@item MENU_INT
+   This should be used to simplify entering of many similar functions (handled
+   by just one universal function in the C code). The @var{function} is handled
+   in the same way as @code{MENU_NOPARAM}, but also one integer parameter taken
+   from @code{iparam} is passed in.
+@findex MENU_STRING
+@item MENU_STRING
+   Similar to @code{MENU_INT} but uses a string instead of an integer.
+@findex MENU_DIALOG
+@item MENU_DIALOG
+   If your function needs some paramters, use the dialog structure to describe
+   them. In the scripting language your function then have parameters; in
+   the user interface, a dialog will be displayed. @var{pparam} must point
+   to array of dialog entries (writing them will be described later).
+   If your function has just one parameter described in the dialog structure, it
+   will be called in the normal C way --- if you want a string parameter, one
+   pointer pointing to a string (in addition to @code{uih_context}) will be
+   passed to the functions.
+
+   If multiple parameters are requested, it is impossible to call
+   function in a C way without a special wrapper for each case. So it will
+   receive a pointer to an array of @code{dialogparam} unions, wich contain
+   one entry for each parameter. @code{dialogparam} is declared as follows:
+@example
+typedef union
+  @{
+    char *dstring;
+    int dint;
+    number_t number;
+    number_t dcoord[2];
+    xio_path dpath;
+    void *dummy;
+  @}
+dialogparam;
+@end example
+@findex MENU_CDIALOG
+@item MENU_CDIALOG
+   In some cases, it is useful to add some context specific default values
+   to the dialog structure. In this case you might use this type instead. In
+   this case the function @var{dialog} is called first, and it is expected to
+   return a pointer to the correct dialog structure. The dialog structure must
+   lie in static storage (since it is not freed), and must always have the same
+   fields, and differ only in the default values.
+   This function must also work correctly even when the pointer to
+   @code{uih_context} is @code{NULL}, since it is often called in the
+   initialization stages (parameter parsing etc.)
+@end table
+@end defvar
+@defvar flags
+The @var{flags} are used to set additional information about the function:
+@table @code
+@findex MENUFLAG_CHECKBOX
+@item MENUFLAG_CHECKBOX
+Some features act like check-boxes --- i.e. repeated calls to the function
+toggle the features. In menus it is useful to add a check-box for this function
+indicating whether the feature is on or off. This flag adds such a check-box.
+
+So that the UI can determine the current state of the checkbox, you need to
+define the function @var{control}, which returns @code{1} when enabled and
+@code{0} when disabled.  In order to let external GUIs work correctly you also
+need to call @code{uih_updatemenus("name")} every time the state of this
+function changes.
+
+In the scripting language, this adds a single parameter, either @code{#t} or
+@code{#f}. The engine then calls the function only when necessary. When
+@code{#t}, a dialog is requested; when @code{#f}, the function is called just as
+@code{NOPARAM}. I.e. the dialog is displayed only when enabling the feature.
+
+@findex MENUFLAG_DIALOGATDISABLE
+@item MENUFLAG_DIALOGATDISABLE
+Display dialog on disabling of this checkbox feature, instead of on enabling.
+@findex MENUFLAG_RADIO
+@item MENUFLAG_RADIO
+Other features act like radio-buttons. Control functions in this case receive
+the same parameter as is defined for @code{MENU_INT} or @code{MENU_STRING}
+types, and is expected to return @code{1} when enabled and @code{0}
+otherwise. You also need to call @code{uih_updatemenus} when the value is
+changed. No special parameter is added in the scripting language.
+
+@findex MENUFLAG_INTERRUPT
+@item MENUFLAG_INTERRUPT
+Interrupt current calculation when this function is called (used by functions
+with cause recalculation of the screen)
+
+@findex MENUFLAG_INCALC
+@item MENUFLAG_INCALC
+By default XaoS queues functions and calls them later when they are activated in
+the calculation. This flag disables this feature.
+
+@findex MENUFLAG_ATSTARTUP
+@item MENUFLAG_ATSTARTUP
+By default XaoS queues functions and them calls later when they are activated as
+command line parameters (in case the engine is not fully initialized yet).  This
+flag disables this feature.
+
+@findex MENUFLAG_NOMENU
+@item MENUFLAG_NOMENU
+If set, the function will not be visible in the menu.
+
+@findex MENUFLAG_NOPLAY
+@item MENUFLAG_NOPLAY
+If set, the function will not be available as a command in scripts (and therefore
+won't be usable by external GUIs).
+
+@findex MENUFLAG_NOOPTION
+@item MENUFLAG_NOOPTION
+If set, the function will not be available as a command line option.
+@end table
+@end defvar
+
+@section Initializing the menuitem structure as a static variable
+In most cases, menuitems should be written as static variables. Because the
+contents of this structure could change in future, please use one of the macros
+defined in @code{xmenu.h}. They provide a cleaner and easier to extend way to
+define these entries than does doing it by hand.
+
+For example to define a @code{MENU_NOPARAM} function, use the following macro:
+@defun MENUNOP (menuname, key, name, shortname, flags, function)
+@end defun
+Similar macros exist for other types too. They end in @code{CB} or @code{RB} for
+check-boxed or radio-box functions. See @code{src/ui-hlp/menu.c} for a large
+number of example definitions. They should look like this:
+
+@findex menuitem
+@example
+static menuitem menuitems[] =   /*XaoS menu specifications */
+@{
+  SUBMENU ("", NULL, "Root menu", "root"),
+  SUBMENU ("", NULL, "Replay only commands", "plc"),
+  MENUNOP ("comm", NULL, "print menus specifications of all menus",
+           "print_menus", MENUFLAG_NOMENU|MENUFLAG_NOPLAY|MENUFLAG_ATSTARTUP,
+           uih_printallmenus),
+           ...
+@end example
+
+@section Dialog description
+A dialog description is similar to a menuitem. It is an array of the following
+structures:
+@example
+typedef struct dialog
+  @{
+    char *question;
+    int type;
+    int defint;
+    char *defstr;
+    number_t deffloat;
+    number_t deffloat2;
+  @}
+menudialog;
+@end example
+It is terminated by an element with the @var{question} pointer set to
+@code{NULL}.
+
+The @var{question} contains the string the UI should display when it asks for
+this field.
+
+@var{type} should be one of the following values:
+@code{DIALOG_INT}, @code{DIALOG_FLOAT}, @code{DIALOG_STRING},
+@code{DIALOG_KEYSTRING} (the difference between string and keystring is that
+in the scripting language string is passed as @code{"hello"}, but keystring is
+passed as a Scheme keyword: @code{'hello}), @code{DIALOG_IFILE} (input file),
+@code{DIALOG_OFILE}, @code{DIALOG_CHOICE} (choice between different
+keystrings), @code{DIALOG_ONOFF} (boolean parameter), @code{DIALOG_COORD} (two
+floats --- a complex number)
+
+Set the corresponding @var{def*} field to set the default value. In the case of
+files, use a string in the format @code{"@var{[prefix]}*@var{[extension]}"}. For
+type @code{DIALOG_CHOICE} set @var{defstr} to a pointer to an array of strings,
+terminated by a @code{NULL} entry.
+
+To write dialog structures, as with menus, use macros defined in @code{xmenu.h}
+like:
+@example
+DIALOGSTR(question,default)
+@end example
+The definition should look like:
+
+@findex menudialog
+@example
+static menudialog uih_viewdialog[] =
+@{
+  DIALOGCOORD ("center:", 0, 0),
+  DIALOGFLOAT ("Radius:", 1),
+  DIALOGFLOAT ("Angle:", 0),
+  @{NULL@}
+@};
+@end example
+@section Modifying the registry
+@deftypefn Function void menu_add (menuitem *@var{item}, int @var{n});
+Add an array of @var{n} items to the database.
+@end deftypefn
+@deftypefn Function void menu_delete (menuitem *@var{items}, int @var{n});
+Remove an array of @var{n} items from the database.
+@end deftypefn
+@section Querying registry
+@deftypefn Function menuitem* menu_findkey (char *@var{key}, char *@var{root});
+Find item for given key. @var{root} is menu to start (submenus are searched
+recursively).
+@end deftypefn
+@deftypefn Function menuitem* menu_findcommand (char *@var{name});
+Find item for given short name.
+@end deftypefn
+@deftypefn Function char* menu_fullname (char *@var{menu}); 
+Return a long name for a menu, given a short name.
+@end deftypefn
+@deftypefn Function menuitem* menu_item (char *@var{menu}, int @var{n}); 
+Return the @var{n}th entry in the @var{menu}. Return @code{NULL} if that entry
+does not exist.
+@end deftypefn
+@deftypefn Function int menu_enabled (menuitem *@var{item}, struct uih_context *@var{c}); 
+Check whether the given item is activated (for check-boxed and radio-boxed
+functions).
+@end deftypefn
+@deftypefn Function int menu_havedialog (menuitem *@var{item}, struct uih_context *@var{c});
+Return whether this function has an associated dialog.
+@end deftypefn
+@defun menu_getdialog (@var{context}, @var{m})
+This macro returns a pointer to the dialog structure for a given menu item. (If
+the item doesn't have a dialog, garbage is returned).
+@end defun
+@deftypefn Function int menu_available (menuitem *@var{item}, char *@var{root});
+Check whether an item is available as one of the entries of @var{root} (or it's
+submenus)
+@end deftypefn
+
+@node    index,     , registry, Top
+@c        node-name,    next, previous,        up
+@unnumbered Index of functions, variables, types and constants
+
+@printindex fn
+
+@contents
+@bye