From 9f2d63a3ae0117625bc5032997147ad7ea06579f Mon Sep 17 00:00:00 2001
From: uz <uz@b7a2c559-68d2-44c3-8de9-860c34a00d81>
Date: Thu, 15 Mar 2012 21:42:21 +0000
Subject: [PATCH] Some more work on the sp65 docs.

git-svn-id: svn://svn.cc65.org/cc65/trunk@5617 b7a2c559-68d2-44c3-8de9-860c34a00d81
---
 doc/sp65.sgml | 123 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 121 insertions(+), 2 deletions(-)

diff --git a/doc/sp65.sgml b/doc/sp65.sgml
index afde57a0b..a499dec15 100644
--- a/doc/sp65.sgml
+++ b/doc/sp65.sgml
@@ -130,21 +130,119 @@ attribute lists see <ref id="attr-lists" name="below">.
 
 
 
+<sect>Processing pipeline<label id="processing-pipeline"><p>
+
+sp65 consists of
+
+<itemize>
+<item>Front ends that read graphics data,
+<item>processors for graphics data,
+<item>converters
+<item>and output modules for several formats.
+</itemize>
+
+These modules can be combined to a pipeline that reads data, does some
+optional bitmap processing, converts the bitmap into a target format, and
+writes this binary data to disk in one of several forms.
+
+
+
 <sect>Attribute lists<label id="attr-lists"><p>
 
+As described in <ref id="processing-pipeline" name="Processing pipeline">,
+sp65 consists of lots of different modules that may be combined in different
+ways, to convert an input bitmap to some output.
+
+Many of the processors and converters have options to change the way, they're
+working. To avoid having lots of command line options that must be parsed on
+high level and passed down to the relevant parts of the program, sp65 features
+something called "attribute lists". Attribute lists are lists of
+attribute/value pairs. These lists are parsed by the main program module
+without any knowledge about their meaning. Lower level parts just grab the
+attributes they need.
+
+In general, attribute lists look like this:
+
+<tscreen><verb>
+        attr1=val1[,attr2=val2[,...]]
+</verb></tscreen>
+
+Instead of the comma, colons may also be used (even mixed).
+
+To simplify things and to make the most common options look "normal", some
+mandatory attributes may be given without an attribute name. If the attribute
+name is missing, the default name is determined by the position. For example,
+the option <tt/<ref id="option--read" name="--read">/ does always need a file
+name. The attribute name for the file name is "name". To avoid having to type
+
+<tscreen><verb>
+        sp65 --read name=ball.pcx ...
+</verb></tscreen>
+
+the first attribute gets the default name "name" assigned. So if the first
+attribute doesn't have a name, it is assumed that it is the file name. This
+means that instead of the line above, one can also use
+
+<tscreen><verb>
+        sp65 --read ball.pcx ...
+</verb></tscreen>
+
+The second attribute for <tt/--read/ is the format of the input file. So when
+using
+
+<tscreen><verb>
+        sp65 --read ball.pic:pcx ...
+</verb></tscreen>
+
+a PCX file named "ball.pic" is read. The long form would be
+
+<tscreen><verb>
+        sp65 --read name=ball.pic:format=pcx ...
+</verb></tscreen>
+
+Changing the order of the attributes is possible only when explicitly
+specifying the names of the attributes. Using
+
+<tscreen><verb>
+        sp65 --read pcx:ball.pic ...
+</verb></tscreen>
+
+will make sp65 complain, because it tries to read a file named "pcx" with an
+(unknown) format of "ball.pic". The following however will work:
+
+<tscreen><verb>
+        sp65 --read format=pcx:name=ball.pic ...
+</verb></tscreen>
+
+The attributes that are valid for each processor or converter are listed
+below.
+
 
 
 <sect>Input formats<label id="input-formats"><p>
 
+Input formats are either specified explicitly when using <tt/<ref
+id="option--read" name="--read">/, or are determined by looking at the
+extension of the file name given.
+
 <sect1>PCX<p>
 
+While sp65 is prepared for more, this is currently the only possible input
+format. There are no additional attributes for this format.
+
 
 
 <sect>Conversions<label id="conversions"><p>
 
+<sect1>GEOS bitmap<p>
+
 
 <sect1>GEOS icon<p>
 
+The current bitmap working copy is converted to GEOS icon format. A GEOS icon
+has the same format as a C64 high resolution sprite (24x21, monochrome, 63
+bytes). There are no additional attributes for this conversion.
+
 
 <sect1>Koala image<p>
 
@@ -169,7 +267,8 @@ is determined by looking at the file name extension.
 <sect1>Binary<p>
 
 For this format, the processed data is written to the output file in raw
-binary format. There are not attributes for this output format.
+binary format. There are no additional attributes (besides "name" and
+"format") for this output format.
 
 
 <sect1>Assembler code<p>
@@ -200,9 +299,29 @@ assembler format. There are several attributes for this output format:
 
 
 
-
 <sect1>C code<p>
 
+When using C output format, a small piece of C source code is generated that
+defines the data containing the output in an array of <tt/unsigned char/.
+
+Possible attributes for this format are:
+
+<descrip>
+  <tag/base/
+  The value for this attribute specifies the numeric base for the data values.
+  It may be either 10 or 16. The default is 16. If the base is 16, the numbers
+  are prefixed by 0x. For base 10, there is no prefix.
+
+  <tag/bytesperline/
+  The value for this attribute specifies the number of bytes output in
+  one line of the assembler file. The default is 16.
+
+  <tag/ident/
+  This mandatory specifies the identifier which is used as the name of the
+  variable that holds the output data.
+
+</descrip>
+
 
 
 <sect>Bugs/Feedback<p>
-- 
2.39.5