GIFLIB Code

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY email         "esr@thyrsus.com">
]>
<refentry id='icon2gif.1'>
<refentryinfo><date>2 May 2012</date></refentryinfo>
<refmeta>
<refentrytitle>icon2gif</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">GIFLIB</refmiscinfo>
<refmiscinfo class="manual">GIFLIB Documentation</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>icon2gif</refname>
<refpurpose>dump GIF data in a textual format, or undump it to a GIF</refpurpose>
</refnamediv>

<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>icon2gif</command>
      <arg choice='opt'>-v</arg>
      <arg choice='opt'>-a</arg>
      <arg choice='opt'>-d</arg>
      <arg choice='opt'>-t <replaceable>translation-table</replaceable></arg>
      <arg choice='opt'>-h</arg>
      <arg choice='opt'><replaceable>gif-file</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Options</title>

<para>A program to convert a series of editable text GIF icon specifications and
named GIF files into a multi-image GIF, usable as a graphic resource file.
It can also dump existing GIFs in this format.</para>

<para>If no gif-file is given, icon2gif will try to read a text input
from stdin.</para>

</refsect1>
<refsect1><title>Specification Syntax</title>

<para>Here is a syntax summary in informal BNF.  The token `NL' represents a
required newline.</para>

<programlisting>
&lt;gif-spec&gt; ::= &lt;header-block&gt; &lt;image-block&gt;...

&lt;header-block&gt; ::= &lt;header-declaration&gt;...

&lt;header-declaration ::=
		| screen width &lt;digits&gt; NL
		| screen height &lt;digits&gt; NL
		| screen colors &lt;digits&gt; NL
		| screen background &lt;digits&gt; NL
		| screen map &lt;color-table&gt; NL

&lt;color-table&gt; ::= &lt;color-declaration&gt;... end NL

&lt;color-declaration&gt; ::= rgb &lt;digits&gt; &lt;digits&gt; &lt;digits&gt; is &lt;key&gt; NL

&lt;image-block&gt; ::= include &lt;file-name&gt; NL
		| image NL
			&lt;image-declaration&gt;...
			&lt;raster-picture&gt;
			[ &lt;extension&gt; ]

&lt;image-declarations&gt; ::= image top &lt;digits&gt; NL
			| image left &lt;digits&gt; NL
			| image interlaced NL
			| image map &lt;color-table&gt; NL
			| image bits &lt;digits&gt; by &lt;digits&gt; NL &lt;raster-block&gt;

&lt;extension&gt; := &lt;comment&gt; NL &lt;extension-block&gt; NL end NL
		| &lt;plaintext&gt; NL &lt;extension-block&gt; NL end NL
		| extension &lt;hex-digits&gt; NL &lt;extension-block&gt; NL end NL
</programlisting>

<para>If the semantics of the `screen height', `screen width', `screen
background', `image top', `image left' declarations aren't obvious to
you, what are you doing with this software?</para>

<para>A color table declares color indices (in ascending order from 0) and
assiciates them with key characters.  These characters can later be used in
raster blocks.  As these must be printable and non-whitespace, you can only
specify 94 colors per icon.  Life is like that sometimes.</para>

<para>A raster block is just a block of key characters.  It should be
sized correctly for the `image bits' declaration that leads it.</para>

<para>The `comment' or `plaintext' keywords lead defined GIF89 extension
record data (the other two GIF89 types, graphics control and application
block, are not yet supported).  You can also say `extension' followed
by a hexadecimal record type.  All of these extension declarations
must be followed by an extension block, which is terminated by the
keyword `end' on its own line.</para>

<para>An extension block is a series of text lines, each interpreted
as a string of bytes to fill an argument block (the terminating
newline is stripped).  Text may include standard C-style octal and hex
escapes preceded by a backslash.</para>

<para>All &lt;digits&gt; tokens are interpreted as decimal numerals;
&lt;hex-digits&gt; tokens are interpreted as two hex digits (a byte). All
coordinates are zero-origin with the top left corner (0,0).  Range
checking is weak and signedness checking nonexistent; caveat
hacker!</para>

<para>In general, the amount of whitespace and order of declarations within a 
header or image block is not significant, except that a raster picture
must immediately follow its `image bits' bits declaration.</para>

<para>The `include' declaration includes a named GIF as the next
image.  The global color maps of included GIFs are merged with the
base table defined by any `screen color' declaration.  All images of
an included multi-image GIF will be included in order.</para>

<para>Comments may be preceded with `#' and will be ignored.</para>

</refsect1>
<refsect1><title>Options</title>

<variablelist>
<varlistentry>
<term>-v</term>
<listitem>
<para>Verbose mode (show progress).
Enables printout of running scan lines.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-d</term>
<listitem>
<para> Dump the input GIF file(s) into the text form described
above.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-t</term>
<listitem>
<para>Specify name characters to use when dumping raster blocks.  Only
valid with -d option.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-h</term>
<listitem>
<para>Print one line of command line help, similar to Usage
above.</para>
</listitem>
</varlistentry>
</variablelist>

</refsect1>
<refsect1><title>Bugs</title>

<para>Because there are only 94 characters unambiguously usable for
raster blocks, an attempt to dump a GIF with a larger color map will
fail.</para>

<para>Error checking is rudimentary.</para>

</refsect1>
<refsect1><title>Example:</title>

<para>A sample icon file called `sample.ico' is included in the pic
directory of the GIFLIB source distribution.</para>

</refsect1>
<refsect1><title>Author</title>

<para>Eric S. Raymond <email>&email;</email></para>

</refsect1>
</refentry>