Move texi from doc to man. Addresses #52.

git-svn-id: file:///svn/tokudb@1161 c7de825b-a66e-492c-adef-691d508d4ae1

man/texi/Makefile

+MANPAGES = tdb_create
+MANPAGES_TEXI = $(patsubst %,%.texi,$(MANPAGES))
+MANPAGES_POD = $(patsubst %,%.pod,$(MANPAGES))
+MANPAGES_3   = $(patsubst %,%.3,$(MANPAGES))
+
+SECTIONS = intro
+SECTIONS_TEXI = $(patsubst %,%.texi,$(SECTIONS))
+
+default: $(MANPAGES_3) tokudb.dvi
+
+tokudb.dvi: tokudb.texi $(MANPAGES_TEXI) $(SECTIONS_TEXI)
+	texi2dvi4a2ps tokudb.texi
+
+
+$(MANPAGES_POD): everyman.texi
+%.pod: %.texi
+	perl texi2pod.pl $< > $@
+%.3: %.pod
+	pod2man --center "TokuDB Programmer's Manual" --section 3 $< > $@

man/texi/everyman.texi

+@ifnottex
+@c man begin CONFORMINGTO
+The TokuDB embedded database provides a subset of the functionality of
+the Berkeley DB.  Programs that work with TokuDB probably work with
+with most versions of Berkeley DB with only recompilation or
+relinking.  The database files are incompatible, however, so to
+convert from one library to the other you would need to dump the
+database with one library's tool and load it with the other's.
+@c man end
+
+@c man begin COPYRIGHT
+Copyright @copyright{} 2007 Tokutek, Inc.  All rights reserved.
+@c man end
+@end ifnottex
+

man/texi/intro.texi

+@node Introduction to TokuDB
+@chapter Introduction to TokuDB
+
+TokuDB is an embedded transactional database that provides very fast
+insertions and range queries on dictionaries.
+
+TokUDB provides transactions with full ACID properties.
+
+TokuDB is a library that can be linked directly into applications,
+making it an @dfn{embedded} database.
+
+TokuDB provides an API that is very similar to the Berkeley@tie{}DB.
+
+@node Dictionaries and Associative Memories
+@section Dictionaries and Associative Memories
+
+Here we describe what we mean by ``dictionary''.
+
+A @dfn{dictionary} is an ordered set of key-data pairs. 
+@itemize @bullet
+@item
+An @dfn{insertion} stores a key-data pair into a dictionary. 
+(One of the API calls that inserts pairs is called @code{DB->put}.)
+
+@item
+A @dfn{point query} finds the data associated with a particular key.
+(One of the API calls that executes a point query is called @code{DB->get}.)
+
+@item
+A @dfn{range query} iterates through all the key-value pairs in a
+range.  For example, in a phone book, you could step through all the
+people whose last names are between @samp{Jones} and @samp{Smith}.  In
+the API, range queries are supported using cursors.
+@end itemize
+
+An @dfn{associative memory} is like a dictionary but it supports only
+insertions and point queries, but not range queries.  Often hash
+tables are used to implement associative memories.  (In some
+languages, such as Perl, an ``dictionary'' is really an associative
+memory.)
+
+@node Asymptotic Performance of Fractal Trees
+@section  Asymptotic Performance of Fractal Trees
+
+For in-memory dictionaries, trees are often the data structure of
+choice.  For example, red-black trees or AVL trees implement all of
+the above operations in @math{O(\log N)} time for in-memory data
+structures, where $math{N} is the number of entries in the dictionary
+(assuming constant-size key-data pairs).
+
+For disk-resident dictionaries, most systems (such as
+Berkeley@tie{}DB) employ B-trees, which can implement insertions and
+point queries with @math{O(\log_B N)} disk operations in the worst
+case, where @math{B} is the block size of the B-tree (assuming
+constant-size key-data pairs).
+
+The @dfn{effective block size} of a disk is the size at which the
+disk-head movement does not dominate the cost of storing or retrieving
+data off the disk.  The effective block size is difficult to calculate
+for actual disk systems, since it depends on how far the head must
+move (the disk head moves short distances faster than long distances,
+reducing the effective block size), whether the data is near the
+center of the disk (where the bandwidth is small and hence the
+effective block size tends to be small) or at the outer edge of the
+disk (where the bandwidth is larger), and on how much prefetching the
+operating system and disk firmware perform.
+
+TokuDB, on the other hand, employs @dfn{fractal trees}, a new class of
+data structures that provide the same API as B-trees, but are much
+faster.  Fractal tree point-queries have the same asymptotic cost as
+B-trees (@math{O(\log_B N)}), but insertions require only
+@math{O((\log N)/B)} disk operations on average, where @math{B} is the
+effective block size of the disk system. 
+
+How much faster is that in concrete terms?  In 2007, the effective
+block size of a disk is about a megabyte.  If you use 100-byte
+key-data pairs, then you can fit about 10,000 pairs into an effective
+block.  If you have a 100 Terabyte database then @math{N=2^{40}}, so
+on average a fractal tree requires about @math{(\log N)/B = 40/10000 =
+1/250} of a disk transfer per insertion.  That is, on average, you can
+perform 250 insertions per disk I/O.  In contrast, a traditional
+B-tree equires @math{\log_B N = 2} disk I/O's per insertion.  In
+practice, because of caching in main memory, traditional B-trees
+require 1 disk read and 1 disk write per insertion.  Thus TokuDB's
+insertions are orders of magnitude faster than dictionaries based on
+traditional B-trees.
+
+Range queries are also faster for TokuDB than in a typical B-tree.
+Since B-trees usually use blocks sizes that relatively small compared
+to the effective block size of the disk they require many disk-head
+movements to traverse a range.  Fractal trees use block sizes that are
+the effective block size of the disk.
+
+

man/texi/tdb_create.texi

+@section @code{db_create}
+@setfilename tokudb
+@settitle db_create
+
+@c man title db_create tokudb
+@unnumberedsubsec Synopsis
+@c man begin SYNOPSIS
+@code{#include <db.h>}
+
+@code{int db_create(DB **}@var{dbp}@code{, DB_ENV *}@var{env}@code{, u_int32_t }@var{flags}@code{);}
+@c man end
+@unnumberedsubsec Description
+@c man begin DESCRIPTION
+@code{db_create} creates a @code{DB} handle, allocating memory and initializing its contents.
+
+After creating the handle, you open a database using @code{(*}@var{dbp}@code{)->open(...)}.
+
+To free the memory associated with the handle call @code{(*}@var{dbp}@code{)->close(...)}
+(or @code{->remove} or @code{->rename} or @code{->verify\}when those are ready).
+
+The handle contains a field called @code{app_private} which is declared
+as type @code{void*}.  This field is provided for the use of the
+application and is not further used by TokuDB.  One typical use of
+@code{app_private} is to pass information about the database to a
+user-defined sort-order function.
+@c man end
+@unnumberedsubsec Parameters
+@c man begin PARAMETERS
+@table @var
+@item dbp
+A pointer to a @code{DB} variable.  The @code{db_create} function does something like @code{*}@var{dbp}@code{=malloc(...)}.
+
+@item env
+If @var{env}@code{==NULL} then the database is not part of an environment
+(hence it has no transactions, locking, or recovery).
+
+Otherwise the database is created within the specified environment,
+and inherits the properties of that environment.  (For example if
+logging for recovery is enabled by the environment, then the database
+will have logging too.)
+
+@item flags
+The @var{flags} parameter must be set to 0.
+
+@end table
+
+@c man end
+@unnumberedsubsec Return Value
+@c man begin RETURNVALUE
+Returns zero on success.  The following non-zero errors can be returned:
+@table @code
+@item EINVAL
+You passed invalid parameters to this operation.
+@end table
+@c man end
+
+@unnumberedsubsec Notes
+@c man begin NOTES
+TokuDB allows at most a few thousand databases per file.
+@c man end
+
+@include everyman.texi
+@bye
+

man/texi/tokudb.texi

+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename tokudb.info
+@settitle The TokuDB Embedded Database
+@c %**end of header
+
+@copying
+Copyright @copyright{} 2007, Tokutek, Inc.
+@end copying
+
+@titlepage
+@title TokuDB Programmmer's Manual
+@subtitle for the Tokutek Embedded Database
+@author Tokutek, Inc.
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage 
+
+@contents
+
+@ifnottex
+@node Top
+@top TokuDB
+@menu tdb_create::
+
+@insertcopying
+@end ifnottex
+
+@include intro.texi
+
+@node TokuDB C API
+@chapter TokuDB C API
+
+@include tdb_create.texi
+
+@node Index
+@unnumbered Index
+
+@printindex
+
+@bye
+