GIFBUILD(1)

📦
version 6.1.3 · 2 versions
, in arch rolling, fedora 44, nixpkgs unstable, ubuntu stonking

✨ gifbuild — GIFBUILD(1) ✨

okay so welcome to the GIFBUILD(1) page, straight out of the GIFLIB Documentation bestie 💖 this little icon of a program turns editable text GIF icon specs + named GIF files into a multi-image GIF you can use as a graphic resource file, and it can also dump existing GIFs back into that text format. both directions? lossless and mutually inverse, no cap 🔁✨

🌸 NAME 🌸

gifbuild — dump GIF data in a textual format, or undump it to a GIF 🫶

🎀 SYNOPSIS 🎀

gifbuild [-v] [-a] [-d] [-t translation-table] [-h] [gif-file]

💅 OPTIONS 💅

okay so here's the whole vibe of what this program does:

  • it converts 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
  • both directions are lossless and mutually inverse — the way that it just round-trips perfectly, obsessed 😌
  • when dumping a GIF, certain sanity checks are performed which may result in a warning emitted to standard error ⚠️
  • if no GIF file is given, gifbuild will try to read a text input from stdin ⌨️

🦋 SPECIFICATION SYNTAX 🦋

here's the syntax summary in informal BNF, bestie. the token NL represents a required newline 📝

    <gif-spec> ::= <header-block> <image-block>...

    <header-block> ::= <header-declaration>...

    <header-declaration ::=
              | screen width <digits> NL
              | screen height <digits> NL
              | screen colors <digits> NL
              | screen background <digits> NL
              | pixel aspect byte <digits> NL
              | screen map <color-table> NL

    <color-table> ::= <color-declaration>... end NL

    <color-declaration> ::= rgb <digits> <digits> <digits> [ is <key>] NL
                    | sort flag {on|off} NL

    <image-block> ::= include <file-name> NL
              | image NL
                   <image-declaration>...
                   <raster-picture>
                   [ <extension> ]

    <image-declarations> ::= image top <digits> NL
                   | image left <digits> NL
                   | image interlaced NL
                   | image map <color-table> NL
                   | image bits <digits> by <digits> [hex|ascii] NL <raster-block>

    <extension> := <comment> NL <extension-block> NL end NL
              | <plaintext> NL <extension-block> NL end NL
                    | graphics control NL <GCB-part> NL end NL
                    | netscape loop  <digits> NL
              | extension <hex-digits> NL <extension-block> NL end NL

    <GCB-part> ::= disposal mode <digits> NL
                    | user input flag {on|off} NL
                    | delay <digits> NL
                    | transparent index <digits> NL

if the data types of the screen height, screen width, screen background, image top, and image left declarations aren't obvious to you… bestie, what are you even doing with this software? 💀

the pixel aspect byte declaration sets an integer denominator for a fraction expressing the pixel aspect ratio. see the GIF standard for details; this field is actually long obsolete 🙈

a color table declares color indices (in ascending order from 0) and may associate them with key characters (these associations are absent when the map is more than 94 colors lang and raster blocks using it must use hex pairs). these characters can later be used in raster blocks. and since these must be printable and non-whitespace, you can only specify 94 colors per icon. life is like that sometimes 😭

a color table declaration can also set the table's sort flag with "sort flag on" or "sort flag off" on any line before the end. periodt ✨

an ascii raster block is just a block of key characters (used for a color map of 94 or fewer colors). a hex raster block uses hex digit pairs instead (used for a color map with more than 94 colors). the default is ASCII. it should be sized correctly for the image bits declaration that leads it. raster blocks from interlaced GIFs are dumped with the lines in non-interlaced order 🌀

the comment, plaintext or graphics control keywords lead defined GIF89 extension record data. the final GIF89 type, graphics control and application block, are not yet supported, but the code does recognize a Netscape loop block 👀 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 🛑

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

a graphics control block declaration creates a graphics control extension block; for the field semantics see the GIF89 standard, part 23 📖

a netscape loop declaration creates an application extension block containing a NETSCAPE 2.0 animation loop control with a specified repeat count (repeat count 0 means loop forever 🔁). this must be immediately after the header declaration. these loop blocks are interpreted by the Netscape/Mozilla/Firefox line of browsers 🌐

all <digits> tokens are interpreted as decimal numerals; <hex-digits> 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! 😈

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 🫡

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 📚

comments (preceded with #) will be ignored 🚫

👑 OPTIONS (round two, the actual flags) 👑

  • -v — Verbose mode (show progress). Enables printout of running scan lines 🔍
  • -d — Dump the input GIF file(s) into the text form described above 📤
  • -t — Specify name characters to use when dumping raster blocks. Only valid with -d option 🏷️
  • -h — Print one line of command line help, similar to Usage above 🙋
not me noticing -a chilling in the synopsis while the options list never says what it does 💀 i'm not gonna invent lore for it, so just know it's there, bestie. iykyk.

💀 BUGS 💀

Error checking is rudimentary. that's it. that's the whole bug report 🫠

🌈 EXAMPLE: 🌈

a sample icon file called sample.ico is included in the pic directory of the GIFLIB source distribution 🍓 go peek at it, it's giving reference material 💅

🫶 AUTHOR 🫶

Eric S. Raymond <esr@thyrsus.com> 👑

and that's the whole page bestie!! this was the GIFLIB release from 2 May 2012 — iconic, historic, slay 💖✨🎀🦋🌸

📦 where this page comes from