Added beginnings of an updated manual

This changeset adds scripts and frontmatter for a user manual
for LibGD.  The manual is written using naturaldoc.  That is, the
actual manual (minus some front-matter taken from the manual for
version 2.0.36) is generated from specially-formatted comments in
the source code.

bootstrap.sh has been modified to also trigger generation of the
manual.

7 files changed, 518 insertions, 0 deletions

diff --git a/docs/naturaldocs/license.txt b/docs/naturaldocs/license.txt
new file mode 100644
index 0000000..4164bce
--- /dev/null
+++ b/docs/naturaldocs/license.txt
@@ -0,0 +1,74 @@
+Title: License
+
+Credits and license terms:
+
+> In order to resolve any possible confusion regarding the authorship of
+> gd, the following copyright statement covers all of the authors who
+> have required such a statement. If you are aware of any oversights in
+> this copyright notice, please contact Pierre-A. Joye who will be
+> pleased to correct them.
+>
+>    Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
+>    2002, 2003, 2004 by Cold Spring Harbor Laboratory. Funded under
+>    Grant P41-RR02188 by the National Institutes of Health.
+>
+>    Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
+>    2004 by Boutell.Com, Inc.
+>
+>    Portions relating to GD2 format copyright 1999, 2000, 2001, 2002,
+>    2003, 2004 Philip Warner.
+>
+>    Portions relating to PNG copyright 1999, 2000, 2001, 2002, 2003,
+>    2004 Greg Roelofs.
+>
+>    Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002,
+>    2003, 2004 John Ellson (ellson@graphviz.org).
+>
+>    Portions relating to gdft.c copyright 2001, 2002, 2003, 2004 John
+>    Ellson (ellson@graphviz.org).
+>
+>    Portions copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+>    Pierre-Alain Joye (pierre@libgd.org).
+>
+>    Portions relating to JPEG and to color quantization copyright
+>    2000, 2001, 2002, 2003, 2004, Doug Becker and copyright (C) 1994,
+>    1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Thomas
+>    G. Lane. This software is based in part on the work of the
+>    Independent JPEG Group. See the file README-JPEG.TXT for more
+>    information.
+>
+>    Portions relating to GIF compression copyright 1989 by Jef
+>    Poskanzer and David Rowley, with modifications for thread safety
+>    by Thomas Boutell.
+>
+>    Portions relating to GIF decompression copyright 1990, 1991, 1993
+>    by David Koblas, with modifications for thread safety by Thomas
+>    Boutell.
+>
+>    Portions relating to WBMP copyright 2000, 2001, 2002, 2003, 2004
+>    Maurice Szmurlo and Johan Van den Brande.
+>
+>    Portions relating to GIF animations copyright 2004 Jaakko Hyvätti
+>    (jaakko.hyvatti@iki.fi)
+>
+> Permission has been granted to copy, distribute and modify gd in
+> any context without fee, including a commercial application,
+> provided that this notice is present in user-accessible supporting
+> documentation.
+>
+> This does not affect your ownership of the derived work itself,
+> and the intent is to assure proper credit for the authors of gd,
+> not to interfere with your productive use of gd. If you have
+> questions, ask. "Derived works" includes all programs that utilize
+> the library. Credit must be given in user-accessible
+> documentation.
+>
+> This software is provided "AS IS." The copyright holders disclaim
+> all warranties, either express or implied, including but not
+> limited to implied warranties of merchantability and fitness for a
+> particular purpose, with respect to this code and accompanying
+> documentation.
+>
+> Although their code does not appear in the current release, the
+> authors also wish to thank Hutchison Avenue Software Corporation
+> for their prior contributions.
diff --git a/docs/naturaldocs/nobgd.pl b/docs/naturaldocs/nobgd.pl
new file mode 100644
index 0000000..e1c3462
--- /dev/null
+++ b/docs/naturaldocs/nobgd.pl
@@ -0,0 +1,58 @@
+#!/usr/bin/env perl
+
+# Copy C source files (i.e. *.[ch]) from $src to $dest, first
+# stripping out uses of the macro BGD_DECLARE(<type>).  A line must
+# begin with 'BGD_DECLARE' for it to be considered a use.
+
+use strict;
+use warnings;
+
+use File::Basename;
+
+my ($src, $dest) = @ARGV;
+
+die "Invalid arguments: nobgd.pl <src-dir> <dest-dir>\n"
+  unless ($src && $dest && -d $src && -d $dest);
+
+for my $file (glob("$src/*.c"), glob("$src/*.h")) {
+  do {local $| = 1; print "."};
+  fixup($file, $dest);
+}
+print "\n";
+
+sub fixup {
+  my ($src, $destDir) = @_;
+  my $dest = $destDir . "/" . basename($src);
+
+  my $content = slurp($src);
+  $content =~ s{^ BGD_DECLARE \( ([^)]+) \)}{$1}gmx;
+  unslurp($dest, $content);
+}
+
+
+sub slurp {
+  my ($filename) = @_;
+  local $/; # no file separator
+  my $data;
+
+  open my $fh, "<", $filename
+    or die "Unable to read file '$filename'.\n";
+  $data = <$fh>;
+  close($fh);
+
+  return $data;
+}
+
+
+sub unslurp {
+  my ($filename, $data) = @_;
+
+  die "Refusing to overwrite file '$filename'\n" if -f $filename;
+
+  open my $fh, ">", $filename
+    or die "Unable to open '$filename' for writing.\n";
+  print {$fh} $data
+    or die "Error writing file '$filename'\n";
+  close ($fh);
+}
+
diff --git a/docs/naturaldocs/preamble.txt b/docs/naturaldocs/preamble.txt
new file mode 100644
index 0000000..ca2e43f
--- /dev/null
+++ b/docs/naturaldocs/preamble.txt
@@ -0,0 +1,95 @@
+Title: About LibGD @VERSION@
+
+What is gd?:
+
+gd is a graphics library. It allows your code to quickly draw images
+complete with lines, arcs, text, multiple colors, cut and paste from
+other images, and flood fills, and write out the result as a PNG or
+JPEG file. This is particularly useful in World Wide Web applications,
+where PNG and JPEG are two of the formats accepted for inline images
+by most browsers.
+
+gd is not a paint program. If you are looking for a paint program, you
+are looking in the wrong place. If you are not a programmer, you are
+looking in the wrong place, unless you are installing a required
+library in order to run an application.
+
+gd does not provide for every possible desirable graphics
+operation. It is not necessary or desirable for gd to become a
+kitchen-sink graphics package, but version 2.0 does include most
+frequently requested features, including both truecolor and palette
+images, resampling (smooth resizing of truecolor images) and so forth.
+
+gd basics: using gd in your program:
+
+gd lets you create PNG or JPEG images on the fly. To use gd in your
+program, include the file gd.h, and link with the gd library and the
+other required libraries; the syntax for most Unix flavors is:
+
+> -lgd -lpng -lz -ljpeg -lfreetype -lm
+
+Assuming that all of these libraries are available.
+
+If you want to use the provided simple fonts, include gdfontt.h,
+gdfonts.h, gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive
+results, install FreeType 2.x and use the gdImageStringFT function. If
+you are not using the provided Makefile and/or a library-based
+approach, be sure to include the source modules as well in your
+project.
+
+Here is a short example program. (For a more advanced example, see
+gddemo.c, included in the distribution. gddemo.c is NOT the same
+program; it demonstrates additional features!)
+
+>/* Bring in gd library functions */
+>#include "gd.h"
+>
+>/* Bring in standard I/O so we can output the PNG to a file */
+>#include <stdio.h>
+>
+>int main() {
+>  /* Declare the image */
+>  gdImagePtr im;
+>  /* Declare output files */
+>  FILE *pngout, *jpegout;
+>  /* Declare color indexes */
+>  int black;
+>  int white;
+>
+>  /* Allocate the image: 64 pixels across by 64 pixels tall */
+>  im = gdImageCreate(64, 64);
+>
+>  /* Allocate the color black (red, green and blue all minimum).
+>    Since this is the first color in a new image, it will
+>    be the background color. */
+>  black = gdImageColorAllocate(im, 0, 0, 0);  
+>
+>  /* Allocate the color white (red, green and blue all maximum). */
+>  white = gdImageColorAllocate(im, 255, 255, 255);  
+>  
+>  /* Draw a line from the upper left to the lower right,
+>    using white color index. */
+>  gdImageLine(im, 0, 0, 63, 63, white);  
+>
+>  /* Open a file for writing. "wb" means "write binary", important
+>    under MSDOS, harmless under Unix. */
+>  pngout = fopen("test.png", "wb");
+>
+>  /* Do the same for a JPEG-format file. */
+>  jpegout = fopen("test.jpg", "wb");
+>
+>  /* Output the image to the disk file in PNG format. */
+>  gdImagePng(im, pngout);
+>
+>  /* Output the same image in JPEG format, using the default
+>    JPEG quality setting. */
+>  gdImageJpeg(im, jpegout, -1);
+>
+>  /* Close the files. */
+>  fclose(pngout);
+>  fclose(jpegout);
+>
+>  /* Destroy the image in memory. */
+>  gdImageDestroy(im);
+>}
+>
diff --git a/docs/naturaldocs/project/Languages.txt b/docs/naturaldocs/project/Languages.txt
new file mode 100644
index 0000000..85d5fde
--- /dev/null
+++ b/docs/naturaldocs/project/Languages.txt
@@ -0,0 +1,113 @@
+Format: 1.51
+
+# This is the Natural Docs languages file for this project.  If you change
+# anything here, it will apply to THIS PROJECT ONLY.  If you'd like to change
+# something for all your projects, edit the Languages.txt in Natural Docs'
+# Config directory instead.
+
+
+# You can prevent certain file extensions from being scanned like this:
+# Ignore Extensions: [extension] [extension] ...
+
+
+#-------------------------------------------------------------------------------
+# SYNTAX:
+#
+# Unlike other Natural Docs configuration files, in this file all comments
+# MUST be alone on a line.  Some languages deal with the # character, so you
+# cannot put comments on the same line as content.
+#
+# Also, all lists are separated with spaces, not commas, again because some
+# languages may need to use them.
+#
+# Language: [name]
+# Alter Language: [name]
+#    Defines a new language or alters an existing one.  Its name can use any
+#    characters.  If any of the properties below have an add/replace form, you
+#    must use that when using Alter Language.
+#
+#    The language Shebang Script is special.  It's entry is only used for
+#    extensions, and files with those extensions have their shebang (#!) lines
+#    read to determine the real language of the file.  Extensionless files are
+#    always treated this way.
+#
+#    The language Text File is also special.  It's treated as one big comment
+#    so you can put Natural Docs content in them without special symbols.  Also,
+#    if you don't specify a package separator, ignored prefixes, or enum value
+#    behavior, it will copy those settings from the language that is used most
+#    in the source tree.
+#
+# Extensions: [extension] [extension] ...
+# [Add/Replace] Extensions: [extension] [extension] ...
+#    Defines the file extensions of the language's source files.  You can
+#    redefine extensions found in the main languages file.  You can use * to
+#    mean any undefined extension.
+#
+# Shebang Strings: [string] [string] ...
+# [Add/Replace] Shebang Strings: [string] [string] ...
+#    Defines a list of strings that can appear in the shebang (#!) line to
+#    designate that it's part of the language.  You can redefine strings found
+#    in the main languages file.
+#
+# Ignore Prefixes in Index: [prefix] [prefix] ...
+# [Add/Replace] Ignored Prefixes in Index: [prefix] [prefix] ...
+#
+# Ignore [Topic Type] Prefixes in Index: [prefix] [prefix] ...
+# [Add/Replace] Ignored [Topic Type] Prefixes in Index: [prefix] [prefix] ...
+#    Specifies prefixes that should be ignored when sorting symbols in an
+#    index.  Can be specified in general or for a specific topic type.
+#
+#------------------------------------------------------------------------------
+# For basic language support only:
+#
+# Line Comments: [symbol] [symbol] ...
+#    Defines a space-separated list of symbols that are used for line comments,
+#    if any.
+#
+# Block Comments: [opening sym] [closing sym] [opening sym] [closing sym] ...
+#    Defines a space-separated list of symbol pairs that are used for block
+#    comments, if any.
+#
+# Package Separator: [symbol]
+#    Defines the default package separator symbol.  The default is a dot.
+#
+# [Topic Type] Prototype Enders: [symbol] [symbol] ...
+#    When defined, Natural Docs will attempt to get a prototype from the code
+#    immediately following the topic type.  It stops when it reaches one of
+#    these symbols.  Use \n for line breaks.
+#
+# Line Extender: [symbol]
+#    Defines the symbol that allows a prototype to span multiple lines if
+#    normally a line break would end it.
+#
+# Enum Values: [global|under type|under parent]
+#    Defines how enum values are referenced.  The default is global.
+#    global       - Values are always global, referenced as 'value'.
+#    under type   - Values are under the enum type, referenced as
+#               'package.enum.value'.
+#    under parent - Values are under the enum's parent, referenced as
+#               'package.value'.
+#
+# Perl Package: [perl package]
+#    Specifies the Perl package used to fine-tune the language behavior in ways
+#    too complex to do in this file.
+#
+#------------------------------------------------------------------------------
+# For full language support only:
+#
+# Full Language Support: [perl package]
+#    Specifies the Perl package that has the parsing routines necessary for full
+#    language support.
+#
+#-------------------------------------------------------------------------------
+
+# The following languages are defined in the main file, if you'd like to alter
+# them:
+#
+#    Text File, Shebang Script, C/C++, C#, Java, JavaScript, Perl, Python,
+#    PHP, SQL, Visual Basic, Pascal, Assembly, Ada, Tcl, Ruby, Makefile,
+#    ActionScript, ColdFusion, R, Fortran
+
+# If you add a language that you think would be useful to other developers
+# and should be included in Natural Docs by default, please e-mail it to
+# languages [at] naturaldocs [dot] org.
diff --git a/docs/naturaldocs/project/Menu.txt b/docs/naturaldocs/project/Menu.txt
new file mode 100644
index 0000000..afefef0
--- /dev/null
+++ b/docs/naturaldocs/project/Menu.txt
@@ -0,0 +1,64 @@
+Format: 1.51
+
+
+# You can add a title and sub-title to your menu like this:
+# Title: [project name]
+# SubTitle: [subtitle]
+
+# You can add a footer to your documentation like this:
+# Footer: [text]
+# If you want to add a copyright notice, this would be the place to do it.
+
+# You can add a timestamp to your documentation like one of these:
+# Timestamp: Generated on month day, year
+# Timestamp: Updated mm/dd/yyyy
+# Timestamp: Last updated mon day
+#
+#   m     - One or two digit month.  January is "1"
+#   mm    - Always two digit month.  January is "01"
+#   mon   - Short month word.  January is "Jan"
+#   month - Long month word.  January is "January"
+#   d     - One or two digit day.  1 is "1"
+#   dd    - Always two digit day.  1 is "01"
+#   day   - Day with letter extension.  1 is "1st"
+#   yy    - Two digit year.  2006 is "06"
+#   yyyy  - Four digit year.  2006 is "2006"
+#   year  - Four digit year.  2006 is "2006"
+
+
+# --------------------------------------------------------------------------
+# 
+# Cut and paste the lines below to change the order in which your files
+# appear on the menu.  Don't worry about adding or removing files, Natural
+# Docs will take care of that.
+# 
+# You can further organize the menu by grouping the entries.  Add a
+# "Group: [name] {" line to start a group, and add a "}" to end it.
+# 
+# You can add text and web links to the menu by adding "Text: [text]" and
+# "Link: [name] ([URL])" lines, respectively.
+# 
+# The formatting and comments are auto-generated, so don't worry about
+# neatness when editing the file.  Natural Docs will clean it up the next
+# time it is run.  When working with groups, just deal with the braces and
+# forget about the indentation and comments.
+# 
+# --------------------------------------------------------------------------
+
+
+File: About LibGD 2.1.1-dev  (preamble.txt)
+File: gd.h  (gd.h)
+File: gd_interpolation.c  (gd_interpolation.c)
+File: gdImageCreate  (gd.c)
+File: License  (license.txt)
+File: Matrix  (gd_matrix.c)
+
+Group: Index  {
+
+   Index: Everything
+   Constant Index: Constants
+   File Index: Files
+   Function Index: Functions
+   Type Index: Types
+   }  # Group: Index
+
diff --git a/docs/naturaldocs/project/Topics.txt b/docs/naturaldocs/project/Topics.txt
new file mode 100644
index 0000000..2153090
--- /dev/null
+++ b/docs/naturaldocs/project/Topics.txt
@@ -0,0 +1,81 @@
+Format: 1.51
+
+# This is the Natural Docs topics file for this project.  If you change anything
+# here, it will apply to THIS PROJECT ONLY.  If you'd like to change something
+# for all your projects, edit the Topics.txt in Natural Docs' Config directory
+# instead.
+
+
+# If you'd like to prevent keywords from being recognized by Natural Docs, you
+# can do it like this:
+# Ignore Keywords: [keyword], [keyword], ...
+#
+# Or you can use the list syntax like how they are defined:
+# Ignore Keywords:
+#    [keyword]
+#    [keyword], [plural keyword]
+#    ...
+
+
+#-------------------------------------------------------------------------------
+# SYNTAX:
+#
+# Topic Type: [name]
+# Alter Topic Type: [name]
+#    Creates a new topic type or alters one from the main file.  Each type gets
+#    its own index and behavior settings.  Its name can have letters, numbers,
+#    spaces, and these charaters: - / . '
+#
+# Plural: [name]
+#    Sets the plural name of the topic type, if different.
+#
+# Keywords:
+#    [keyword]
+#    [keyword], [plural keyword]
+#    ...
+#    Defines or adds to the list of keywords for the topic type.  They may only
+#    contain letters, numbers, and spaces and are not case sensitive.  Plural
+#    keywords are used for list topics.  You can redefine keywords found in the
+#    main topics file.
+#
+# Index: [yes|no]
+#    Whether the topics get their own index.  Defaults to yes.  Everything is
+#    included in the general index regardless of this setting.
+#
+# Scope: [normal|start|end|always global]
+#    How the topics affects scope.  Defaults to normal.
+#    normal        - Topics stay within the current scope.
+#    start         - Topics start a new scope for all the topics beneath it,
+#                    like class topics.
+#    end           - Topics reset the scope back to global for all the topics
+#                    beneath it.
+#    always global - Topics are defined as global, but do not change the scope
+#                    for any other topics.
+#
+# Class Hierarchy: [yes|no]
+#    Whether the topics are part of the class hierarchy.  Defaults to no.
+#
+# Page Title If First: [yes|no]
+#    Whether the topic's title becomes the page title if it's the first one in
+#    a file.  Defaults to no.
+#
+# Break Lists: [yes|no]
+#    Whether list topics should be broken into individual topics in the output.
+#    Defaults to no.
+#
+# Can Group With: [type], [type], ...
+#    Defines a list of topic types that this one can possibly be grouped with.
+#    Defaults to none.
+#-------------------------------------------------------------------------------
+
+# The following topics are defined in the main file, if you'd like to alter
+# their behavior or add keywords:
+#
+#    Generic, Class, Interface, Section, File, Group, Function, Variable,
+#    Property, Type, Constant, Enumeration, Event, Delegate, Macro,
+#    Database, Database Table, Database View, Database Index, Database
+#    Cursor, Database Trigger, Cookie, Build Target
+
+# If you add something that you think would be useful to other developers
+# and should be included in Natural Docs by default, please e-mail it to
+# topics [at] naturaldocs [dot] org.
diff --git a/docs/naturaldocs/run_docs.sh b/docs/naturaldocs/run_docs.sh
new file mode 100755
index 0000000..dfe1e62
--- /dev/null
+++ b/docs/naturaldocs/run_docs.sh
@@ -0,0 +1,33 @@
+#!/bin/bash
+
+set -e
+
+# Version number
+VERSION=`(cd ../../; perl config/getver.pl)`
+
+# Clear away old docs and ensure the doc dir. is present.
+[ -d html ] && rm -rf html
+mkdir html
+
+# Create a lightly-processed copy of the source to use as input.  This
+# file skips all non-C code in src/ and removes the BGD_DECLARE()
+# macro from definitions so they don't show up in the docs.
+[ -d tmp ] && rm -rf tmp
+mkdir tmp
+perl nobgd.pl ../../src/ tmp/
+
+# Add the external docs.
+cp license.txt tmp/
+sed -e "s/@VERSION@/$VERSION/g" preamble.txt > tmp/preamble.txt
+# ^^^ hack to get the version number in the docs.
+
+# Run naturaldocs to create the manual.
+naturaldocs --rebuild --rebuild-output --documented-only \
+    -i tmp/ \
+    -o html html  \
+    --project project/
+
+# And cleanup the temp files.
+rm -rf Data tmp
+
+