1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE refentry PUBLIC 3 "-//OASIS//DTD DocBook XML V4.1.2//EN" 4 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ 5<!ENTITY email "[email protected]"> 6]> 7<refentry id='gifbuild.1'> 8<refentryinfo><date>2 May 2012</date></refentryinfo> 9<refmeta> 10<refentrytitle>gifbuild</refentrytitle> 11<manvolnum>1</manvolnum> 12<refmiscinfo class="source">GIFLIB</refmiscinfo> 13<refmiscinfo class="manual">GIFLIB Documentation</refmiscinfo> 14</refmeta> 15<refnamediv id='name'> 16<refname>gifbuild</refname> 17<refpurpose>dump GIF data in a textual format, or undump it to a GIF</refpurpose> 18</refnamediv> 19 20<refsynopsisdiv id='synopsis'> 21 22<cmdsynopsis> 23 <command>gifbuild</command> 24 <arg choice='opt'>-v</arg> 25 <arg choice='opt'>-a</arg> 26 <arg choice='opt'>-d</arg> 27 <arg choice='opt'>-t <replaceable>translation-table</replaceable></arg> 28 <arg choice='opt'>-h</arg> 29 <arg choice='opt'><replaceable>gif-file</replaceable></arg> 30</cmdsynopsis> 31</refsynopsisdiv> 32 33<refsect1><title>Options</title> 34 35<para>A program to convert a series of editable text GIF icon specifications and 36named GIF files into a multi-image GIF, usable as a graphic resource file. 37It can also dump existing GIFs in this format. When dumping a GIF, 38certain sanity checks are performed which may result in a warning 39emitted to standard error.</para> 40 41<para>If no GIF file is given, gifbuild will try to read a text input 42from stdin.</para> 43 44</refsect1> 45<refsect1><title>Specification Syntax</title> 46 47<para>Here is a syntax summary in informal BNF. The token `NL' represents a 48required newline.</para> 49 50<programlisting> 51<gif-spec> ::= <header-block> <image-block>... 52 53<header-block> ::= <header-declaration>... 54 55<header-declaration ::= 56 | screen width <digits> NL 57 | screen height <digits> NL 58 | screen colors <digits> NL 59 | screen background <digits> NL 60 | pixel aspect byte <digits> NL 61 | screen map <color-table> NL 62 63<color-table> ::= <color-declaration>... end NL 64 65<color-declaration> ::= rgb <digits> <digits> <digits> [ is <key>] NL 66 | sort flag {on|off} NL 67 68<image-block> ::= include <file-name> NL 69 | image NL 70 <image-declaration>... 71 <raster-picture> 72 [ <extension> ] 73 74<image-declarations> ::= image top <digits> NL 75 | image left <digits> NL 76 | image interlaced NL 77 | image map <color-table> NL 78 | image bits <digits> by <digits> [hex|ascii] NL <raster-block> 79 80<extension> := <comment> NL <extension-block> NL end NL 81 | <plaintext> NL <extension-block> NL end NL 82 | graphics control NL <GCB-part> NL end NL 83 | netscape loop <digits> NL 84 | extension <hex-digits> NL <extension-block> NL end NL 85 86<GCB-part> ::= disposal mode <digits> NL 87 | user input flag {on|off} NL 88 | delay <digits> NL 89 | transparent index <digits> NL 90 91</programlisting> 92 93<para>If the data types of the <quote>screen height</quote>, 94<quote>screen width</quote>, <quote>screen background</quote>, 95<quote>image top</quote>, and <quote>image left</quote> declarations 96aren't obvious to you, what are you doing with this software?</para> 97 98<para>The <quote>pixel aspect byte</quote> declaration sets an integer 99denominator for a fraction expressing the puxel aspect ratio. See the 100GIF standard for details; this field is actually long obsolete.</para> 101 102<para>A color table declares color indices (in ascending order from 0) 103and may associate them with key characters (these associations are 104absent when the map is more than 94 colors lang and raster blocks 105using it must use hex pairs). These characters can later be used in 106raster blocks. As these must be printable and non-whitespace, you can 107only specify 94 colors per icon. Life is like that sometimes.</para> 108 109<para>A color table declaration can also set the table's sort flag with 110"sort flag on" or "sort flag off" on any line before the end.</para> 111 112<para>An <quote>ascii</quote> raster block is just a block of key 113characters (used for a color map of 94 or fewer colors). A 114<quote>hex</quote> raster block uses hex digit pairs instead (used for 115a color map with more than 94 colors). The default is ASCII. It 116should be sized correctly for the <quote>image bits</quote> 117declaration that leads it. Raster blocks from interlaced GIFs are 118dumped with the lines in non-interlaced order.</para> 119 120<para>The <quote>comment</quote>, <quote>plaintext</quote> or 121<quote>ggraphics control</quote> keywords lead defined GIF89 extension 122record data. The final GIF89 type, graphics control and application 123block, are not yet supported, but the code does recognize a Netscape 124loop block. You can also say <quote>extension</quote> followed by a 125hexadecimal record type. All of these extension declarations must be 126followed by an extension block, which is terminated by the keyword 127<quote>end</quote> on its own line.</para> 128 129<para>An extension block is a series of text lines, each interpreted 130as a string of bytes to fill an extension block (the terminating 131newline is stripped). Text may include standard C-style octal and hex 132escapes preceded by a backslash.</para> 133 134<para>A graphics control block declaration creates a graphics control 135extension block; for the field semantics see the GIF89 standard, part 13623.</para> 137 138<para>A netscape loop declaration creates an application extension 139block containing a NETSCAPE 2.0 animation loop control with a 140specified repeat count (repeat count 0 means loop forever). This must 141be immediately after the header declaration. These loop blocks are 142interpreted by the Netscape/Mozilla/Firefox line of browsers.</para> 143 144<para>All <digits> tokens are interpreted as decimal numerals; 145<hex-digits> tokens are interpreted as two hex digits (a byte). All 146coordinates are zero-origin with the top left corner (0,0). Range 147checking is weak and signedness checking nonexistent; caveat 148hacker!</para> 149 150<para>In general, the amount of whitespace and order of declarations within a 151header or image block is not significant, except that a raster picture 152must immediately follow its <quote>image bits</quote> bits declaration.</para> 153 154<para>The <quote>include</quote> declaration includes a named GIF as 155the next image. The global color maps of included GIFs are merged 156with the base table defined by any <quote>screen color</quote> 157declaration. All images of an included multi-image GIF will be 158included in order.</para> 159 160<para>Comments (preceded with <quote>#</quote>) will be ignored.</para> 161 162</refsect1> 163<refsect1><title>Options</title> 164 165<variablelist> 166<varlistentry> 167<term>-v</term> 168<listitem> 169<para>Verbose mode (show progress). 170Enables printout of running scan lines.</para> 171</listitem> 172</varlistentry> 173 174<varlistentry> 175<term>-d</term> 176<listitem> 177<para> Dump the input GIF file(s) into the text form described 178above.</para> 179</listitem> 180</varlistentry> 181 182<varlistentry> 183<term>-t</term> 184<listitem> 185<para>Specify name characters to use when dumping raster blocks. Only 186valid with -d option.</para> 187</listitem> 188</varlistentry> 189 190<varlistentry> 191<term>-h</term> 192<listitem> 193<para>Print one line of command line help, similar to Usage 194above.</para> 195</listitem> 196</varlistentry> 197</variablelist> 198 199</refsect1> 200<refsect1><title>Bugs</title> 201 202<para>Error checking is rudimentary.</para> 203 204</refsect1> 205<refsect1><title>Example:</title> 206 207<para>A sample icon file called <filename>sample.ico</filename> is 208included in the pic directory of the GIFLIB source 209distribution.</para> 210 211</refsect1> 212<refsect1><title>Author</title> 213 214<para>Eric S. Raymond <email>&email;</email></para> 215 216</refsect1> 217</refentry> 218