* version.sgml.in, cipher-ref.sgml, digest-ref.sgml, misc-ref.sgml
authorWerner Koch <wk@gnupg.org>
Tue, 16 Apr 2002 10:17:54 +0000 (10:17 +0000)
committerWerner Koch <wk@gnupg.org>
Tue, 16 Apr 2002 10:17:54 +0000 (10:17 +0000)
* pubkey-ref.sgml, reference.sgml: Removed.
* gcrypt.texi: New. Based on the old sgml version.
* gpl.texi, fdl.texi: New.
* Makefile.am: Adjusted for use with texinfo.

doc/ChangeLog
doc/Makefile.am
doc/fdl.texi [new file with mode: 0644]
doc/gcrypt.texi [new file with mode: 0644]
doc/gpl.texi [new file with mode: 0644]

index 21a4637..9a0eb7b 100644 (file)
@@ -1,6 +1,14 @@
+2002-04-16  Werner Koch  <wk@gnupg.org>
+
+       * version.sgml.in, cipher-ref.sgml, digest-ref.sgml, misc-ref.sgml
+       * pubkey-ref.sgml, reference.sgml: Removed.
+       * gcrypt.texi: New. Based on the old sgml version.
+       * gpl.texi, fdl.texi: New.
+       * Makefile.am: Adjusted for use with texinfo.
+
 2000-12-21  Werner Koch  <wk@gnupg.org>
 
-       Renamed the gcryptref(.sgml files and removed the GnuPG stuff.
+       Renamed the gcryptref.sgml files and removed the GnuPG stuff.
 
 Tue Oct 26 14:10:21 CEST 1999  Werner Koch  <wk@gnupg.de>
 
index af75204..3f73533 100644 (file)
@@ -1,31 +1,7 @@
 ## Process this file with automake to create Makefile.in
 
-sgml_source = reference.sgml \
-              cipher-ref.sgml digest-ref.sgml misc-ref.sgml pubkey-ref.sgml 
+DISTCLEANFILES = gcrypt.cps
 
-EXTRA_DIST = $(sgml_source) version.sgml.in \
-             reference.dvi reference.html reference.ps reference.texi
-
-pkgdata_DATA = reference.dvi reference.ps reference.html reference.texi
-
-BUILT_SOURCES = version.sgml \
-             reference.dvi reference.html reference.ps reference.texi
-CLEANFILES = reference.aux reference.log reference.tex reference.dvi
-
-reference.sgml : version.sgml
-
-
-%.ps : %.dvi
-       dvips -o $@ $<
-
-# we might want something like this: -V generate-book-toc  
-# or use a custom stylesheet.
-%.dvi : %.sgml
-       $(DB2ANY) --mode dvi $<
-
-%.html : %.sgml
-       $(DB2ANY) --mode html $<
-
-%.texi : %.sgml
-       $(DB2ANY) --mode texinfo $<
+info_TEXINFOS = gcrypt.texi
+gcrypt_TEXINFOS = gpl.texi fdl.texi
 
diff --git a/doc/fdl.texi b/doc/fdl.texi
new file mode 100644 (file)
index 0000000..50028ab
--- /dev/null
@@ -0,0 +1,402 @@
+@node Free Documentation License
+@appendix GNU Free Documentation License
+
+@cindex FDL, GNU Free Documentation License
+@center Version 1.1, March 2000
+
+@display
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially.  Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License.  The ``Document'', below, refers to any
+such manual or work.  Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject.  (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent.  A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
+@acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
+for human modification.  Opaque formats include PostScript,
+@acronym{PDF}, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols.  If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page.  If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles.  Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''.  You must delete all sections
+entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation.  Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License provided that you also include the
+original English version of this License.  In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License.  Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License.  However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+@end enumerate
+
+@page
+@appendixsubsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{your name}.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.1
+  or any later version published by the Free Software Foundation;
+  with the Invariant Sections being @var{list their titles}, with the
+  Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
+  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+@end group
+@end smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant.  If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi
new file mode 100644 (file)
index 0000000..9124a27
--- /dev/null
@@ -0,0 +1,1248 @@
+\input texinfo                  @c -*- Texinfo -*-
+@c Copyright (C) 2000, 2002 Free Software Foundation, Inc.
+@c 
+@c This file is part of the libgcrypt.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.1 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, with no the Front-Cover texts, and with no
+@c Back-Cover Texts. 
+@c A copy of the license is included in the file 'fdl.texi'.
+@c
+@setfilename gcrypt.info
+@settitle The `Libgcrypt' Reference Manual
+
+@dircategory GNU Libraries
+@direntry
+* libgcrypt: (gcrypt) Cryptographic function library.
+@end direntry
+
+@include version.texi
+
+@c Unify some of the indices.
+@syncodeindex tp fn
+@syncodeindex pg fn
+
+@ifinfo
+This file documents the `Libgcrypt' library.
+
+This is Edition @value{EDITION}, last updated @value{UPDATED}, of
+@cite{The `Libgcrypt' Reference Manual}, for Version
+@value{VERSION}.
+
+Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no the Front-Cover texts, and with no
+Back-Cover Texts.  A copy of the license is included in the section
+entitled ``GNU Free Documentation License''.
+@end ifinfo
+
+@iftex
+@shorttitlepage The `Libgcrypt' Reference Manual
+@end iftex
+@titlepage
+@center @titlefont{The `Libgcrypt'}
+@sp 1
+@center @titlefont{Reference Manual}
+@sp 6
+@center Edition @value{EDITION}
+@sp 1
+@center last updated @value{UPDATED}
+@sp 1
+@center for version @value{VERSION}
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no the Front-Cover texts, and with no
+Back-Cover Texts.  A copy of the license is included in the section
+entitled ``GNU Free Documentation License''.
+@end titlepage
+@page
+
+@ifnottex
+@node Top
+@top Main Menu
+This is Edition @value{EDITION}, last updated @value{UPDATED}, of
+@cite{The `Libgcrypt' Reference Manual}, for Version
+@value{VERSION} of the @acronym{GPGME} library.
+@end ifnottex
+
+@menu
+* Introduction::                How to use this manual.
+* Preparation::                 What you should do before using the library.
+* Cipher Functions::            All about ciphers.
+* Hash Functions::              How to use cryptographic hash functions.
+* Public Key Functions::        How to use asymmetric encryption.
+* Random Numbers::              How to create random.
+* Utilities::                   Helper functions.
+* Error Handling::              Error codes and such.
+
+Appendices
+
+* Copying::                     The GNU General Public License says how you
+                                can copy and share `GnuPG Made Easy'.
+* Free Documentation License::  This manual is under the GNU Free
+                                Documentation License.
+
+Indices
+
+* Concept Index::               Index of concepts and programs.
+* Function and Data Index::     Index of functions, variables and data types.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Getting Started::             
+* Features::                    
+* Overview::                    
+
+Preparation
+
+* Header::                      
+* Version Check::               
+* Building the source::         
+
+Error Handling
+
+* Error values::                
+* Error strings::               
+
+@end detailmenu
+@end menu
+
+@c **********************************************************
+@c *******************  Introduction  ***********************
+@c **********************************************************
+@node Introduction
+@chapter Introduction
+`Libgcrypt' is a library to provide cryptographic building blocks.
+
+@menu
+* Getting Started::             
+* Features::                    
+* Overview::                    
+@end menu
+
+@node Getting Started
+@section Getting Started
+
+This manual documents the `Libgcrypt' library programming interface.
+All functions and data types provided by the library are explained.
+
+The reader is assumed to possess basic knowledge about applied
+cryptography.
+
+This manual can be used in several ways.  If read from the beginning
+to the end, it gives a good introduction into the library and how it
+can be used in an application.  Forward references are included where
+necessary.  Later on, the manual can be used as a reference manual to
+get just the information needed about any particular interface of the
+library.  Experienced programmers might want to start looking at the
+examples at the end of the manual, and then only read up those parts
+of the interface which are unclear.
+
+
+@node Features
+@section Features
+
+`Libgcrypt' has a couple of advantages over other libraries doing a
+similar job.
+
+@table @asis
+@item It's Free Software
+Anybody can use, modify, and redistribute it under the terms of the GNU
+General Public License (@pxref{Copying}).
+
+@item It encapsulates the low level cryptography
+`Libgcrypt' a high level interface to cryptographic buiilding blocks
+using an extendable and flexible API.
+
+@end table
+
+
+@node Overview
+@section Overview
+
+Blurb
+
+The `Libgcrypt' library is thread-safe.
+
+
+@c **********************************************************
+@c *******************  Preparation  ************************
+@c **********************************************************
+@node Preparation
+@chapter Preparation
+
+To use `Libgcrypt', you have to perform some changes to your sources and
+the build system.  The necessary changes are small and explained in the
+following sections.  At the end of this chapter, it is described how the
+library is initialized, and how the requirements of the library are
+verified.
+
+@menu
+* Header::                      
+* Version Check::               
+* Building the source::         
+@end menu
+
+
+@node Header
+@section Header
+
+All interfaces (data types and functions) of the library are defined
+in the header file `gcrypt.h'.  You must include this in all programs
+using the library, either directly or through some other header file,
+like this:
+
+@example
+#include <gcrypt.h>
+@end example
+
+The name space of `Libgcrypt' is @code{gcry_*} for function names,
+@code{Gcry*} for data types and @code{GCRY_*} for other symbols.  In
+addition the same name prefixes with one prepended underscore are
+reserved for internal use and should never be used by an application.
+
+@node Version Check
+@section Version Check
+
+It is often desirable to check that the version of `Libgcrypt' used is
+indeed one which fits all requirements.  Even with binary compatibility
+new features may have been introduced but due to problem with the
+dynamic linker an old version is actually used.  So you may want to
+check that the version is okay right after program startup.
+
+@deftypefun const char *gcry_check_version (const char *@var{req_version})
+
+Check that the the version of the library is at minimum the one given as
+a string in @var{req_version} and return the actual version string of
+the library; return NULL if the condition is not met.  If @code{NULL} is
+passed to this function no check is done and only the version string is
+returned.  It is a pretty good idea to run this function as soon as
+possible, because it may also intializes some subsystems.  In a
+multithreaded environment if should be called before any more threads
+are created.
+@end deftypefun
+
+@node Building the source
+@section Building the source
+
+If you want to compile a source file including the `gcry.h' header
+file, you must make sure that the compiler can find it in the
+directory hierarchy.  This is accomplished by adding the path to the
+directory in which the header file is located to the compilers include
+file search path (via the @option{-I} option).
+
+However, the path to the include file is determined at the time the
+source is configured.  To solve this problem, `Libgrypt' ships with a small
+helper program @command{libgcrypt-config} that knows the path to the
+include file and other configuration options.  The options that need
+to be added to the compiler invocation at compile time are output by
+the @option{--cflags} option to @command{libgcrypt-config}.  The following
+example shows how it can be used at the command line:
+
+@example
+gcc -c foo.c `libgcrypt-config --cflags`
+@end example
+
+Adding the output of @samp{libgcrypt-config --cflags} to the compilers
+command line will ensure that the compiler can find the `Libgcrypt' header
+file.
+
+A similar problem occurs when linking the program with the library.
+Again, the compiler has to find the library files.  For this to work,
+the path to the library files has to be added to the library search path
+(via the @option{-L} option).  For this, the option @option{--libs} to
+@command{libgcrypt-config} can be used.  For convenience, this option
+also outputs all other options that are required to link the program
+with the `Libgcrypt' libararies (in particular, the @samp{-lgcrypt}
+option).  The example shows how to link @file{foo.o} with the `Libgcrypt'
+library to a program @command{foo}.
+
+@example
+gcc -o foo foo.o `libgcrypt-config --libs`
+@end example
+
+Of course you can also combine both examples to a single command by
+specifying both options to @command{libgcrypt-config}:
+
+@example
+gcc -o foo foo.c `libgcrypt-config --cflags --libs`
+@end example
+
+
+@c **********************************************************
+@c *******************  Ciphers  ****************************
+@c **********************************************************
+@c @include cipher-ref.texi
+@node Cipher Functions
+@chapter Cipher Functions
+
+
+@deftypefun GCRY_CIPHER_HD gcry_cipher_open (int @var{algo}, int @var{mode}, unsigned int @var{flags})
+
+This function creates the context required for most of the othercipher
+functions.  In case of an error @code{NULL} is returned.
+@end deftypefun
+
+@deftypefun void gcry_cipher_close (GCRY_CIPHER_HD @var{h})
+
+This function releases the context created by @code{gcry_cipher_open}.
+@end deftypefun
+
+
+@deftypefun int gcry_cipher_ctl (GCRY_CIPHER_HD @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
+
+@code{gcry_cipher_ctl} controls various aspects of the cipher module and
+specific cipher contexts.  Usually some more specialzed functions are
+used for this purpose.
+@end deftypefun
+
+@deftypefun int gcry_cipher_setkey (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})
+
+Set the key used for encryption or decryption.  Note, that this is
+implemented as a macro.
+@end deftypefun
+
+@deftypefun int gcry_cipher_setiv (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})
+
+Set the initialization vector used for encryption or decryption.  Note,
+that this is implemented as a macro.
+@end deftypefun
+
+@deftypefun int gcry_cipher_sync (GCRY_CIPHER_HD @var{h})
+
+Peform the a ``sync'' operation which is only used with certain modes.
+@end deftypefun
+
+
+@c ***********************************************
+@c ***********  cipher info   ********************
+@c ***********************************************
+@deftypefun int gcry_cipher_info (GCRY_CIPHER_HD @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
+
+@code{gcry_cipher_info} is used to retrieve various
+information about a cipher context or the cipher module in general.
+Currently no information is available.
+@end deftypefun
+
+@deftypefun int gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
+
+fixme
+
+@end deftypefun
+
+@deftypefun const char *gcry_cipher_algo_name (int @var{algo})
+
+@code{gcry_cipher_algo_name} returns a string with the name of the
+cipher algorithm @var{algo}.  If the algorithm s not known or an other
+error occured, an empty string is return.  This function will never
+return @code{NULL}.
+@end deftypefun
+
+@deftypefun int gcry_cipher_map_name (const char *@var{name})
+
+@code{gcry_cipher_map_name} returns the algorithm identifier for the
+cipher algorithm described by the string @var{name}.  If this algorithm
+is not available @code{0} is returned.
+@end deftypefun
+
+@deftypefun int gcry_cipher_mode_from_oid (const char *@var{string})
+
+Return the cipher mode associated with an @acronym{ASN.1} object
+identifier.  The object identifier is expected to be in the
+@acronym{IETF}-style dotted decimal notation.  The function returns
+@code{0} for an unknown object identifier or when no mode is associated
+with it.
+@end deftypefun
+
+@c ******************************************
+@c *******  cipher en/decrypt  **************
+@c ******************************************
+
+@deftypefun int gcry_cipher_encrypt (GCRY_CIPHER_HD @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
+
+@code{gcry_cipher_encrypt} is used to encrypt the data.
+This function can either work in place or with two buffers.
+Overlapping buffers are not allowed.
+@end deftypefun
+
+@deftypefun int gcry_cipher_decrypt (GCRY_CIPHER_HD @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
+
+@code{gcry_cipher_encrypt} is used to decrypt the data.
+This function can either work in place or with two buffers.
+Overlapping buffers are not allowed.
+@end deftypefun
+
+@c **********************************************************
+@c *******************  Hash Functions  *********************
+@c **********************************************************
+@node Hash Functions
+@chapter Hash Functions
+
+How to use cryptographic hash functions.
+
+
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_open</refname>
+    <refname>gcry_md_enable</refname>
+    <refname>gcry_md_close</refname>
+    <refpurpose>create and destroy a message digest context</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>GCRY_MD_HD <function>gcry_md_open</function></funcdef>
+       <paramdef>int <parameter>algo</parameter></paramdef>
+       <paramdef>unsigned int <parameter>flags</parameter></paramdef>
+      </funcprototype>
+      <funcprototype>
+       <funcdef>void <function>gcry_md_enable</function></funcdef>
+       <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+       <paramdef>int <parameter>algo</parameter></paramdef>
+      </funcprototype>
+      <funcprototype>
+       <funcdef>void <function>gcry_md_close</function></funcdef>
+       <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_open</secondary>
+            </indexterm>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_enable</secondary>
+            </indexterm>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_close</secondary>
+            </indexterm>
+  <function>gcry_md_open</function> creates the context required for
+  the message digest functions.  The hash algorithm may optionally be
+  specified. It is possible to use these functions as MAC functons; therefore
+  the flag <literal/GCRY_MD_FLAG_HMAC/ must be given along with the
+  hash functions.  Other MAC algorithms than  HMAC are currently not
+  supported.  The key for the MAC must be set using
+  the <function>gcry_md_setkey</> function.
+  <function>gcry_md_close</function> releases all resources associated
+  with the context.
+  <function>gcry_md_enable</function> may be used to enable hash
+  algorithms.  This function may be used multiple times to create
+  a hash context for multiple algorithms.  Adding an already enabled algorithm
+  has no effect.  A algorithm must be enabled prios to calculate hash
+  algorithms.
+  </para>
+</refentry>
+
+<!--**********************************************
+***********  md_copy *****************************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_copy</refname>
+    <refpurpose>create and copy of a message digest context</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>GCRY_MD_HD <function>gcry_md_copy</function></funcdef>
+       <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_copy</secondary>
+            </indexterm>
+  <function>gcry_md_copy</function> creates an excat copy of the given context.
+  This is useful to calculate hashes with a common initial part of the
+  plaintext.
+  </para>
+</refentry>
+
+<!--**********************************************
+***********  md_reset  ***************************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_reset</refname>
+    <refpurpose>reset a message digest context</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>void <function>gcry_md_reset</function></funcdef>
+       <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_reset</secondary>
+            </indexterm>
+  <function>gcry_md_reset</function> is used to reuse a message context
+  without the overhead of an open and close operation.
+  </para>
+</refentry>
+
+
+<!--**********************************************
+***********  md_ctl  *****************************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_ctl</refname>
+    <refname>gcry_md_final</refname>
+    <refname>gcry_md_setkey</refname>
+    <refpurpose>perform special operations on a digest context</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>int <function>gcry_md_ctl</function></funcdef>
+       <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+       <paramdef>int <parameter>cmd</parameter></paramdef>
+       <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
+       <paramdef>size_t <parameter>buflen</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_ctl</secondary>
+            </indexterm>
+  <function>gcry_md_ctl</function> is a multi-purpose function
+  to control the behaviour of all gcry_md functions or one instance
+  of it.
+  </para>
+  <para>
+  Currently defined values for <parameter>cmd</> are:
+  </para>
+  <para>
+    <literal>GCRYCTL_FINALIZE</> and the convenience macro
+    <function>gcry_md_final(a)</>
+  </para>
+  <para>
+    <literal>GCRYCTL_SET_KEY</> and the convenience macro
+    <function>gcry_md_setkey(a)</>.  This is used to turn these
+    hash functions into MAC functions. The key may be any string
+    of the speicified length.  The type of the MAC is determined
+    by special flags set with the open function.
+    NEW:  There is now a function to do this
+  </para>
+</refentry>
+
+<!--**********************************************
+***********  md_write, putc  *********************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_write</refname>
+    <refname>gcry_md_putc</refname>
+    <refpurpose>calculate the message digest of a buffer</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>int <function>gcry_md_write</function></funcdef>
+       <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+       <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
+       <paramdef>size_t <parameter>buflen</parameter></paramdef>
+      </funcprototype>
+      <funcprototype>
+       <funcdef>int <function>gcry_md_putc</function></funcdef>
+       <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+       <paramdef>int <parameter>c</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_write</secondary></indexterm>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_putc</secondary></indexterm>
+  <function>gcry_md_write</function> is used to actually calulate the message
+  digest of a buffer.  This function updates the internal state of the message
+  digest.
+  </para>
+  <para>
+  <function>gcry_md_putc</function> is a macro which is used to update
+  the message digest by one byte.  this is the preferred way to calculate
+  a digest if only a few bytes at a time are available.
+  </para>
+</refentry>
+
+<!--**********************************************
+***********  md_read *****************************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_read</refname>
+    <refpurpose>read out the message digest</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>unsigned char * <function>gcry_md_read</function></funcdef>
+       <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+       <paramdef>int <parameter>algo</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_read</secondary>
+            </indexterm>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_putc</secondary>
+            </indexterm>
+  <function>gcry_md_read</function> returns the message digest after finalizing
+  the calculation.  This function may be used as often as required but it
+  will alwas return the same value for one handle.  The returned message
+  digest is allocated within the message context and therefore valid until
+  the conext is released.  <parameter>algo</> may be given as 0 to return the
+  only enbaled message digest or it may specify one of the enabled algorithms.
+  The function will return NULL if the algorithm has not been enabled.
+  </para>
+</refentry>
+
+
+<!--**********************************************
+***********  md_info  ****************************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_info</refname>
+    <refpurpose>get information about a handle</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>int <function>gcry_md_info</function></funcdef>
+       <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
+       <paramdef>int        <parameter>what</parameter></paramdef>
+       <paramdef>void * <parameter>buffer</parameter></paramdef>
+       <paramdef>size_t <parameter>buflen</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_info</secondary>
+            </indexterm>
+  <function>gcry_md_info</function> returns some information about the
+  handle or an global parameter.
+  </para>
+  <para>
+  The only defined value for <parameter>what</> is
+  <literal>GCRYCTL_IS_SECURE</literal> to return whether the handle
+  has been allocated in secure memory. Buffer and buflen are not needed
+  in this cases.  The convenience macro <function>gcry_md_is_secure(a)</>
+  may be also used for this purpose.
+  </para>
+</refentry>
+
+
+<!--**********************************************
+***********  md_algo_info  ***********************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_algo_info</refname>
+    <refname>gcry_md_test_algo</refname>
+    <refname>gcry_md_get_algo_dlen</refname>
+    <refpurpose>get information about an algorithm</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>int <function>gcry_md_algo_info</function></funcdef>
+       <paramdef>int        <parameter>algo</parameter></paramdef>
+       <paramdef>int        <parameter>what</parameter></paramdef>
+       <paramdef>void * <parameter>buffer</parameter></paramdef>
+       <paramdef>size_t <parameter>buflen</parameter></paramdef>
+      </funcprototype>
+      <funcprototype>
+       <funcdef>unsigned int <function>gcry_md_get_algo_dlen</function></funcdef>
+       <paramdef>int <parameter>algo</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_algo_info</secondary>
+            </indexterm>
+  <function>gcry_md_algo_info</function> returns some information about an
+  algorithm.  On error the value -1 is return and a more detailed error
+  description is available with <function>gcry_errno</>.
+  </para>
+  <para>
+  The defined values for <parameter>what</> are
+  <literal>GCRYCTL_TEST_ALGO</literal> to return whether the algorithm
+  is supported. Buffer and buflen are not needed
+  in this cases.  The convenience macro <function>gcry_md_test_algo(a)</>
+  may be used for this purpose.
+  </para>
+  <para>
+  <literal>GCRYCTL_GET_ASNOID</literal> to return whether the ASN.1
+  object identifier.  IF buffer is specified as NULL, only the required
+  length for the buffer is returned.
+  </para>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_get_algo_dlen</secondary>
+            </indexterm>
+  <function>gcry_md_get_algo_dlen</function> returns the length of the
+  digest for a given algorithm in bytes.
+  </para>
+</refentry>
+
+
+<!--**********************************************
+***********  md_algo_name, map_name  *************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_algo_name</refname>
+    <refname>gcry_md_map_name</refname>
+    <refpurpose>map algorithm to string</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>const char * <function>gcry_md_algo_name</function></funcdef>
+       <paramdef>int        <parameter>algo</parameter></paramdef>
+      </funcprototype>
+      <funcprototype>
+       <funcdef>int <function>gcry_md_map_name</function></funcdef>
+       <paramdef>const char*<parameter>name</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_algo_name</secondary>
+            </indexterm>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_map_name</secondary>
+            </indexterm>
+  These both functions are used to map a string with the algorithm name to
+  the internal algorithm identifier value and vice versa.
+  </para>
+  <para>
+  <function>gcry_md_algo_name</> never returns NULL even in cases where the
+  algorithm string is not available.  Instead a string consisting of a
+  single question mark is returned.  Do not use this function to test
+  for the existence of an algorithm.
+  </para>
+  <para>
+  <function>gcry_md_map_name</> returns 0 if the algorithm is not known
+  to &libgcrypt;.
+  </para>
+</refentry>
+
+
+
+<!--**********************************************
+***********  md_hash_buffer  *********************
+***********************************************-->
+<refentry>
+  <refnamediv>
+    <refname>gcry_md_hash_buffer</refname>
+    <refpurpose>fast message calculation</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>int <function>gcry_md_hash_buffer</function></funcdef>
+       <paramdef>int  <parameter>algo</parameter></paramdef>
+       <paramdef>char * <parameter>digest</parameter></paramdef>
+       <paramdef>const char * <parameter>buffer</parameter></paramdef>
+       <paramdef>size_t <parameter>buflen</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>hash functions</primary>
+            <secondary>gcry_md_hash_buffer</secondary>
+            </indexterm>
+  <function>gcry_md_hash_buffer</function> is a shortcut function
+  to calculate a message digest of a buffer.  This function does not require
+  a context and immediatley returns the message digest.
+  <parameter>digest</> must be string large enough to hold the digest
+  given by algo.  This length may be obtained by using the function
+  <function>gcry_md_get_algo_dlen</> but in most cases it will be a statically
+  allocated buffer.
+  </para>
+</refentry>
+
+
+
+
+@c **********************************************************
+@c *******************  Public Key  *************************
+@c **********************************************************
+@node Public Key Functions
+@chapter Public Key Functions
+
+How to use asymmetric encryption.
+
+<refentry>
+  <refnamediv>
+    <refname>gcry_pk_encrypt</refname>
+    <refpurpose>do a public key encryption</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>int <function>gcry_pk_encrypt</function></funcdef>
+       <paramdef>GCRY_SEXP *<parameter>result</parameter></paramdef>
+       <paramdef>GCRY_SEXP  <parameter>data</parameter></paramdef>
+       <paramdef>GCRY_SEXP  <parameter>pkey</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>public key functions</primary>
+            <secondary>gcry_pk_encrypt</secondary>
+            </indexterm>
+  <function>gcry_pk_encrypt</function> performs public key encryption
+  operations.  The caller has to provide a public key as the &sexp;
+  <parameter>pkey</> and <parameter>data</> as a &sexp;
+  with just one MPI in it.  The function returns a &sexp; which may
+  be passed tp to pk_decrypt.
+  Later versions of this functions may take more complex input data.
+
+  Returns: 0 or an errorcode.
+  </para>
+  <literallayout>
+  s_data = (<replaceable/mpi/)
+  s_pkey = <replaceable/key-as-defined-in-sexp_to_key/
+  r_ciph = (enc-val
+            (<replaceable/algo/
+              (<replaceable/param_name1/ <replaceable/mpi/)
+              ...
+              (<replaceable/param_namen/ <replaceable/mpi/)
+            ))
+  </literallayout>
+</refentry>
+
+
+<!--
+int gcry_pk_decrypt( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
+
+
+
+int gcry_pk_sign(    GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
+int gcry_pk_verify(  GCRY_SEXP sigval, GCRY_SEXP data, GCRY_SEXP pkey );
+int gcry_pk_testkey( GCRY_SEXP key );
+int gcry_pk_genkey(  GCRY_SEXP *r_key, GCRY_SEXP s_parms );
+
+int gcry_pk_ctl( int cmd, void *buffer, size_t buflen);
+int gcry_pk_algo_info( int algo, int what, void *buffer, size_t *nbytes);
+#define gcry_pk_test_algo(a) \
+           gcry_pk_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
+
+const char *gcry_pk_algo_name( int algo );
+int gcry_pk_map_name( const char* name );
+unsigned int gcry_pk_get_nbits( GCRY_SEXP key );
+    -->
+
+
+@c **********************************************************
+@c *******************  Random  *****************************
+@c **********************************************************
+@node Random Numbers
+@chapter Random Numbers
+
+
+@deftypefun void gcry_randomize (unsigned char *@var{buffer}, size_t @var{length}, enum gcry_random_level @var{level})
+
+Fill @var{buffer} with @var{length} random bytes using a random quality
+as defined by @var{level}.
+@end deftypefun
+
+@deftypefun void *gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level})
+
+Allocate a memory block consisting of @var{nbytes} fresh random bytes
+using a random quality as defined by @var{level}.
+@end deftypefun
+
+@deftypefun void *gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level})
+
+Allocate a memory block consisting of @var{nbytes} fresh random bytes
+using a random quality as defined by @var{level}.  This fuinction
+differs from @code{gcry_random_bytes} in that the returned buffer is
+allcated in a ``secure'' area of the memory.
+@end deftypefun
+
+
+
+@c **********************************************************
+@c *******************  Utilities  **************************
+@c **********************************************************
+@node Utilities
+@chapter Utilities
+
+Helper functions.
+
+      <funcprototype>
+       <funcdef>int <function>gcry_control</function></funcdef>
+       <paramdef>enum gcry_ctl_cmds<parameter>cmd</parameter></paramdef>
+       <paramdef><parameter>...</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>gcry_control</primary></indexterm>
+  This function is used to control various aspects of &libgcrypt;
+  FIXME: Explain all commands here.
+  </para>
+</refentry>
+
+
+
+
+
+<refentry>
+  <refnamediv>
+    <refname>gcry_set_allocation_handler</refname>
+    <refname>gcry_set_outofcore_handler</refname>
+        <refpurpose>Use application defined malloc functions</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>void <function>gcry_set_allocation_handler</></funcdef>
+       <paramdef>void *(*<parameter>alloc_func</>)(size_t n)</paramdef>
+       <paramdef>void *(*<parameter>alloc_secure_func</>)(size_t n)</paramdef>
+       <paramdef>int (*<parameter>is_secure_func</>)(const void *p)</paramdef>
+       <paramdef>void *(*<parameter>realloc_func</>)(void *p, size_t n)</paramdef>
+       <paramdef>void (*<parameter>free_func</>)(void *p)</paramdef>
+      </funcprototype>
+      <funcprototype>
+       <funcdef>void <function>gcry_set_outofcore_handler</></funcdef>
+
+        <paramdef>int (*<parameter>h</>)( void*, size_t, unsigned int ),
+                                       void *opaque )</paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>gcry_set_allocation_handler</primary></indexterm>
+  <indexterm><primary>gcry_set_outofcore_handler</primary></indexterm>
+
+  FIXME
+  </para>
+</refentry>
+
+
+<refentry>
+  <refnamediv>
+    <refname>gcry_set_fatalerror_handler</refname>
+        <refpurpose>change the default fatal error handler</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>void <function>gcry_set_fatalerror_handler</></funcdef>
+       <paramdef>void (*<parameter>func</>)(
+             void *, int, const char*)</paramdef>
+        <paramdef>void *<parameter>opaque</></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>gcry_set_fatalerror_handler</primary></indexterm>
+  At certain places the &libgcrypt; may need to call a fatal error fucntion
+  which does terminate the process.  To allow an application to do
+  some emergency cleanup, it may register a fatal error handler with
+  the library.  This handler is assumed to terminate the application;
+  however if it returns &libgcrypt; will abort anyway.
+     </para>
+  <para>
+The handler is called with the opaque value registered here, an
+errorcode from &libgcrypt; and some descriptive text string.
+  </para>
+</refentry>
+
+
+<refentry>
+  <refnamediv>
+    <refname>gcry_set_gettext_handler</refname>
+        <refpurpose>Change the default gettext function</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>void <function>gcry_set_gettext_handler</></funcdef>
+       <paramdef>const char *(*<parameter>func</>)(const char*)</paramdef>
+        <paramdef>void *<parameter>opaque</></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>gcry_set_log_handler</primary></indexterm>
+  FIXME!!
+  </para>
+</refentry>
+
+
+
+<!--
+void gcry_set_log_handler( void (*f)(void*,int, const char*, va_list ),
+                                                            void
+                                                             *opaque
+                                                             );
+-->
+
+<refentry>
+  <refnamediv>
+    <refname>gcry_set_log_handler</refname>
+        <refpurpose>Change the default logging function</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>void <function>gcry_set_log_handler</></funcdef>
+       <paramdef>void (*<parameter>func</>)
+         (void*, int, const char*, va_list)</paramdef>
+        <paramdef>void *<parameter>opaque</></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>gcry_set_log_handler</primary></indexterm>
+  &libgcrypt; has it;s own logging functions.  Applications which 
+  need to use their own, should provide a log function to &libgcrypt;
+so that it will use this function instead.
+
+Fixme: Describe how this is intended to work.
+  </para>
+</refentry>
+
+<!--
+void *gcry_malloc( size_t n );
+void *gcry_calloc( size_t n, size_t m );
+void *gcry_malloc_secure( size_t n );
+void *gcry_calloc_secure( size_t n, size_t m );
+void *gcry_realloc( void *a, size_t n );
+void *gcry_xmalloc( size_t n );
+void *gcry_xcalloc( size_t n, size_t m );
+void *gcry_xmalloc_secure( size_t n );
+void *gcry_xcalloc_secure( size_t n, size_t m );
+void *gcry_xrealloc( void *a, size_t n );
+char *gcry_xstrdup( const char * a);
+void  gcry_free( void *a );
+int   gcry_is_secure( const void *a );
+-->
+
+<refentry>
+  <refnamediv>
+    <refname>gcry_malloc</refname>
+    <refname>gcry_calloc</refname>
+    <refname>gcry_malloc_secure</refname>
+    <refname>gcry_calloc_secure</refname>
+    <refname>gcry_realloc</refname>
+    <refname>gcry_xmalloc</refname>
+    <refname>gcry_xcalloc</refname>
+    <refname>gcry_xmalloc_secure</refname>
+    <refname>gcry_xcalloc_secure</refname>
+    <refname>gcry_xrealloc</refname>
+    <refname>gcry_xstrdup</refname>
+
+ <!-- WORk WORK -->
+    <refname>gcry_malloc</refname>
+    <refname>gcry_malloc</refname>
+    
+        <refpurpose>Change the default logging function</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>
+      #include &lt;gcrypt.h&gt;
+      </funcsynopsisinfo>
+      <funcprototype>
+       <funcdef>void <function>gcry_set_log_handler</></funcdef>
+       <paramdef>void (*<parameter>func</>)
+         (void*, int, const char*, va_list)</paramdef>
+        <paramdef>void *<parameter>opaque</></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1><title>Description</title>
+  <para>
+  <indexterm><primary>gcry_set_log_handler</primary></indexterm>
+  &libgcrypt; has it;s own logging functions.  Applications which 
+  need to use their own, should provide a log function to &libgcrypt;
+so that it will use this function instead.
+
+Fixme: Describe how this is intended to work.
+  </para>
+</refentry>
+
+
+
+
+@c **********************************************************
+@c *******************  Errors  ****************************
+@c **********************************************************
+@node Error Handling
+@chapter Error Handling
+
+@menu
+* Error values::                
+* Error strings::               
+@end menu
+
+@node Error values
+@section Error values
+
+
+@node Error strings
+@section Error strings
+
+@deftypefun {const char *} gcry_strerror (@w{int @var{err}})
+The function @code{gcry_strerror} returns a pointer to a statically
+allocated string containing a description of the error with the error
+value @var{err}.  This string can be used to output a diagnostic
+message to the user.
+@end deftypefun
+
+
+
+
+@c **********************************************************
+@c *******************  Appendices  *************************
+@c **********************************************************
+
+@include gpl.texi
+
+@include fdl.texi
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Function and Data Index
+@unnumbered Function and Data Index
+
+@printindex fn
+
+@summarycontents
+@contents
+@bye
diff --git a/doc/gpl.texi b/doc/gpl.texi
new file mode 100644 (file)
index 0000000..ca0508f
--- /dev/null
@@ -0,0 +1,397 @@
+@node Copying
+@appendix GNU GENERAL PUBLIC LICENSE
+
+@cindex GPL, GNU General Public License
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
+59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@appendixsubsec Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software---to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+@iftex
+@appendixsubsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate
+@item
+This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The ``Program'', below,
+refers to any such program or work, and a ``work based on the Program''
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term ``modification''.)  Each licensee is addressed as ``you''.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+@item
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+@item
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+@enumerate a
+@item
+You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+@item
+If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License.  (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+@end enumerate
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+@item
+You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+@enumerate a
+@item
+Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+@item
+Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+@item
+Accompany it with the information you received as to the offer
+to distribute corresponding source code.  (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+@end enumerate
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+@item
+You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+@item
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and ``any
+later version'', you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+@item
+If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
+
+@item
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+@end enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+@page
+@unnumberedsec How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the ``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the program's name and an idea of what it does.}
+Copyright (C) 19@var{yy}  @var{name of author}
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+type `show w'.  This is free software, and you are welcome
+to redistribute it under certain conditions; type `show c' 
+for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than @samp{show w} and
+@samp{show c}; they could even be mouse-clicks or menu items---whatever
+suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the program, if
+necessary.  Here is a sample; alter the names:
+
+@smallexample
+@group
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written 
+by James Hacker.
+
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end group
+@end smallexample
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.