diff options
author | Chris Reuter <chris@blit.ca> | 2013-11-15 23:40:32 -0500 |
---|---|---|
committer | Chris Reuter <chris@blit.ca> | 2013-11-18 18:21:27 -0500 |
commit | 3c1202e5bb91e04cfb54d211f553030c29a855c1 (patch) | |
tree | b62e086955e4f403ce2b5111edca590f6bcede4f /docs/naturaldocs | |
parent | 769fb1534c878e827a3cbb9cc89241b31f394bfa (diff) | |
download | libgd-3c1202e5bb91e04cfb54d211f553030c29a855c1.tar.gz |
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.
Diffstat (limited to 'docs/naturaldocs')
-rw-r--r-- | docs/naturaldocs/license.txt | 74 | ||||
-rw-r--r-- | docs/naturaldocs/nobgd.pl | 58 | ||||
-rw-r--r-- | docs/naturaldocs/preamble.txt | 95 | ||||
-rw-r--r-- | docs/naturaldocs/project/Languages.txt | 113 | ||||
-rw-r--r-- | docs/naturaldocs/project/Menu.txt | 64 | ||||
-rw-r--r-- | docs/naturaldocs/project/Topics.txt | 81 | ||||
-rwxr-xr-x | docs/naturaldocs/run_docs.sh | 33 |
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 + + |