Remove.

5 files changed, 0 insertions, 1317 deletions

diff --git a/doc/asn1.tex b/doc/asn1.tex
deleted file mode 100644
index b5ac45e..0000000
--- a/doc/asn1.tex
+++ /dev/null
@@ -1,242 +0,0 @@
-\documentclass{book}
-\usepackage{fancyheadings}
-
-\newcommand{\HRule}{\rule{\linewidth}{0.4mm}}
-
-\begin{document}
-
-{\Large{ASN.1 structures parser}}
-\vspace{-.3cm}
-\\
-\HRule
-\vspace{-.6cm}
-\\
-\begin{flushright}
-This is part of the GnuTLS project\\
-\end{flushright}
-
-\vspace*{\stretch{2}}
-
-\begin{center}
-\par
-Copyright \copyright\ 2001, 2002, 2003  Fabio Fiorina\\
-\setlength{\parskip}{4mm}
-\par
-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, no Front-Cover Texts and
-no Back-Cover Texts.  A copy of the license is included in the
-chapter entitled "GNU Free Documentation License".
-\end{center}
-
-\setlength{\parindent}{2mm}
-
-\setlength{\parskip}{1mm}
-
-\tableofcontents
-
-\chapter{ASN.1 structures handling}
-
-\section{Introduction}
- This document describes the version 0.2.4 of library 'libtasn1' developed
-for ASN1 (Abstract Syntax Notation One) structures management.
-The main features of this library are:
-\begin{itemize}
-\item on line ASN1 structure management that doesn't require any
-C code file generation.
-\item off line ASN1 structure management with C code file generation 
-containing an array.
-\item DER (Distinguish Encoding Rules) encoding
-\item no limits for INTEGER and ENUMERATED values  
-\end{itemize}
-
-
-\section{ASN.1 syntax}
-The parser is case sensitive. The comments begin with "-- " and end at the end of lines.
-An example is in "pkix.asn" file.
-ASN.1 definitions must have this syntax:
-      
-\begin{verbatim}
-      definitions_name {<object definition>}
-
-      DEFINITIONS <EXPLICIT or IMPLICIT> TAGS ::=
-
-      BEGIN 
-
-      <type and constants definitions>
-
-      END
-\end{verbatim}
-
-\par
-The token "::=" must be separate from others elements, so this is a wrong declaration:
-      Version ::=INTEGER 
-the correct one is :   Version ::= INTEGER
-Here is the list of types that the parser can manage:
-\begin{itemize}
-
-\item      INTEGER
-\item      ENUMERATED
-\item      BOOLEAN
-\item      OBJECT IDENTIFIER
-\item      NULL
-\item      BIT STRING
-\item      OCTET STRING
-\item      UTCTime
-\item      GeneralizedTime
-\item      GeneralString
-\item      SEQUENCE
-\item      SEQUENCE OF
-\item      SET 
-\item      SET OF
-\item      CHOICE
-\item      ANY
-\item      ANY DEFINED BY
-\end{itemize}
-
-This version doesn't manage REAL type. It doesn't allow the  
-"EXPORT" and "IMPORT" sections too.
-
-The SIZE constraints are allowed, but no check is done on them.
-
-
-
-\section{Naming}
-With this definitions:
-
-\begin{verbatim}
-      Example { 1 2 3 4 }
-
-      DEFINITIONS EXPLICIT TAGS ::=
-
-      BEGIN 
-
-      Group ::= SEQUENCE {
-         id   OBJECT IDENTIFIER,
-         value  Value
-      }
-
-      Value ::= SEQUENCE {
-         value1  INTEGER,
-         value2  BOOLEAN 
-      }
-
-      END
-\end{verbatim}
-
-to identify the type 'Group' you have to use the null terminated string "Example.Group".
-Others examples:
-Field 'id' in 'Group' type :  "Example.Group.id"
-Field 'value1' in field 'value' in type 'Group':   "Example.Group.value.value1" 
-These strings are used in functions that are described below.
-Elements of structured types that don't have a name, receive the name "?1","?2", and so on. 
-The name "?LAST" indicates the last element of a SET\_OF or SEQUENCE\_OF.
-
-\section{Library Notes}
-The header file of this library is libtasn1.h .
-The main type used in it is ASN1\_TYPE, and it's used to
-store the ASN1 definitions and structures (instances).
-The constant ASN1\_TYPE\_EMPTY can be used for the variable initialization.
-\par
-Example:  ASN1\_TYPE  definitions=ASN1\_TYPE\_EMPTY;
-\par 
-Some functions require a parameter named errorDescription of char* type.
-The array must be already allocated and must have at least
-MAX\_ERROR\_DESCRIPTION\_SIZE bytes
-(E.g: char Description[MAX\_ERROR\_DESCRIPTION\_SIZE];). 
-\par
-MAX\_NAME\_SIZE indicates the maximum number of characters of a name inside
-a file with ASN1 definitions. 
-
-\section{Future developments}
-\begin{enumerate}
-\item add functions for a C code file generation containing equivalent 
-data structures (not a single array like now).
-\item type REAL 
-\end{enumerate}
-
-
-\chapter{Utilities}
-
-\section{asn1Parser}
-asn1Parser reads one file with ASN1 definitions and generates a file 
-with an array to use with libasn1 functions.
-\par
-Usage:  asn1Parser [options] file
-\par
-Options:
-\begin{itemize}
-\item -h : shows the help message.
-\item -v : shows version information and exit.
-\item -c : checks the syntax only.
-\item -o file : output file.
-\item -n name : array name.
-\end{itemize}
-
-
-\section{asn1Coding}
-asn1Coding generates a DER encoding from a file with ASN1 definitions
-and another one with assignments.
-The file with assignments must have this syntax:
-\par
-InstanceName  Asn1Definition
-\par
-nameString  value
-\par 
-nameString  value
-\par
-...
-\par
-The output file is a binary file with the DER encoding.
-\par
-Usage:  asn1Coding [options] file1 file2
-\begin{itemize}
-\item file1 : file with ASN1 definitions.
-\item file2 : file with assignments.
-\end{itemize}
-
-\par
-Options:
-\begin{itemize}
-\item -h : shows the help message.
-\item -v : shows version information and exit.
-\item -c : checks the syntax only.
-\item -o file : output file.
-\end{itemize}
-
-\section{asn1Decoding}
-asn1Decoding generates an ASN1 structure from a file with ASN1 definitions
-and a binary file with a DER encoding.
-\par
-Usage:  asn1Decoding [options] file1 file2 type
-\begin{itemize}
-\item file1 : file with ASN1 definitions.
-\item file2 : binary file with a DER encoding.
-\item type : ASN1 definition name.
-\end{itemize}
- 
-
-\par
-Options:
-\begin{itemize}
-\item -h : shows the help message.
-\item -v : shows version information and exit.
-\item -c : checks the syntax only.
-\item -o file : output file.
-\end{itemize} 
-
-\chapter{Function reference}
-\input{asn1-api}
-
-\input{fdl.tex}
-
-\end{document}
-
-
-
-
-
-
-
-
diff --git a/doc/fdl.tex b/doc/fdl.tex
deleted file mode 100644
index c0fcbe3..0000000
--- a/doc/fdl.tex
+++ /dev/null
@@ -1,367 +0,0 @@
-% fdl.tex 
-% This file is a chapter.  It must be included in a larger document to work
-% properly.
-
-\chapter{GNU Free Documentation License}
-
-Version 1.1, March 2000\\
-
- 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.
-
-\section*{Preamble}
-
-The purpose of this License is to make a manual, textbook, or other
-written document ``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.
-
-\section{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
-ASCII without markup, Texinfo input format, \LaTeX~input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML designed for human modification.  Opaque formats include
-PostScript, PDF, proprietary formats that can be read and edited only
-by proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated 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.
-
-
-\section{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.
-
-
-\section{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.
-
-
-\section{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:
-
-\begin{itemize}
-
-\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 ``Acknowledgements'' or ``Dedications'',
-   preserve the section's title, and preserve in the section all the
-   substance and tone of each of the contributor acknowledgements
-   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{itemize}
-
-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.
-
-
-\section{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 ``Acknowledgements'',
-and any sections entitled ``Dedications''.  You must delete all sections
-entitled ``Endorsements.''
-
-
-\section{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.
-
-
-
-\section{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.
-
-
-\section{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.
-
-
-\section{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.
-
-
-\section{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
-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.
-
-\section*{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:
-
-\begin{quote}
-
-      Copyright \copyright\ YEAR  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 LIST THEIR TITLES, with the
-      Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-      A copy of the license is included in the section entitled ``GNU
-      Free Documentation License''.
-
-\end{quote}
-
-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 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.
-
diff --git a/doc/scripts/.cvsignore b/doc/scripts/.cvsignore
deleted file mode 100644
index 282522d..0000000
--- a/doc/scripts/.cvsignore
+++ /dev/null
@@ -1,2 +0,0 @@
-Makefile
-Makefile.in
diff --git a/doc/scripts/Makefile.am b/doc/scripts/Makefile.am
deleted file mode 100644
index 7deb104..0000000
--- a/doc/scripts/Makefile.am
+++ /dev/null
@@ -1,3 +0,0 @@
-EXTRA_DIST = gdoc
-
-
diff --git a/doc/scripts/gdoc b/doc/scripts/gdoc
deleted file mode 100755
index 9597148..0000000
--- a/doc/scripts/gdoc
+++ /dev/null
@@ -1,703 +0,0 @@
-#!/usr/bin/perl
-
-## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
-##                    hacked to allow -tex option --nmav         ##
-##                                                               ##
-## This software falls under the GNU Public License. Please read ##
-##              the COPYING file for more information            ##
-
-#
-# This will read a 'c' file and scan for embedded comments in the
-# style of gnome comments (+minor extensions - see below).
-#
-# This program is modified by Nikos Mavroyanopoulos, for the gnutls
-# project.
-
-# Note: This only supports 'c'.
-
-# usage:
-# gdoc [ -docbook | -html | -text | -man | -tex ]
-#      [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
-#
-#  Set output format using one of -docbook -html -text or -man.  Default is man.
-#
-#  -function funcname
-#	If set, then only generate documentation for the given function(s).  All
-#	other functions are ignored.
-#
-#  c files - list of 'c' files to process
-#
-#  All output goes to stdout, with errors to stderr.
-
-#
-# format of comments.
-# In the following table, (...)? signifies optional structure.
-#                         (...)* signifies 0 or more structure elements
-# /**
-#  * function_name(:)? (- short description)?
-# (* @parameterx: (description of parameter x)?)*
-# (* a blank line)?
-#  * (Description:)? (Description of function)?
-#  * (section header: (section description)? )*
-#  (*)?*/
-#
-# So .. the trivial example would be:
-#
-# /**
-#  * my_function
-#  **/
-#
-# If the Description: header tag is ommitted, then there must be a blank line
-# after the last parameter specification.
-# e.g.
-# /**
-#  * my_function - does my stuff
-#  * @my_arg: its mine damnit
-#  *
-#  * Does my stuff explained. 
-#  */
-#
-#  or, could also use:
-# /**
-#  * my_function - does my stuff
-#  * @my_arg: its mine damnit
-#  * Description: Does my stuff explained. 
-#  */
-# etc.
-#
-# All descriptions can be multiline, apart from the short function description.
-#
-# All descriptive text is further processed, scanning for the following special
-# patterns, which are highlighted appropriately.
-#
-# 'funcname()' - function
-# '$ENVVAR' - environmental variable
-# '&struct_name' - name of a structure
-# '@parameter' - name of a parameter
-# '%CONST' - name of a constant.
-
-#
-# Extensions for LaTeX:
-#
-# 1. the symbol '->' will be replaced with a rightarrow
-# 2. x^y with ${x}^{y}$.
-# 3. xxx\: with xxx:
-
-
-# match expressions used to find embedded type information
-$type_constant = "\\\%(\\w+)";
-#$type_func = "(\\w+\\(\\))";
-$type_func = "(\\(w||\\\\)+\\(\\))";
-$type_param = "\\\@(\\w+)";
-$type_struct = "\\\&(\\w+)";
-$type_env = "(\\\$\\w+)";
-
-
-# Output conversion substitutions.
-#  One for each output format
-
-# these work fairly well
-%highlights_html = ( $type_constant, "<i>\$1</i>",
-		     $type_func, "<b>\$1</b>",
-		     $type_struct, "<i>\$1</i>",
-		     $type_param, "<tt><b>\$1</b></tt>" );
-$blankline_html = "<p>";
-
-%highlights_tex = ( $type_constant, "{\\\\it \$1}",
-		     $type_func, "{\\\\bf \$1}",
-		     $type_struct, "{\\\\it \$1}",
-		     $type_param, "{\\\\bf \$1}" );
-$blankline_tex = "\\par";
-
-# sgml, docbook format
-%highlights_sgml = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
-		     $type_func, "<function>\$1</function>",
-		     $type_struct, "<structname>\$1</structname>",
-		     $type_env, "<envar>\$1</envar>",
-		     $type_param, "<parameter>\$1</parameter>" );
-$blankline_sgml = "</para><para>\n";
-
-# these are pretty rough
-%highlights_man = ( $type_constant, "\\n.I \\\"\$1\\\"\\n",
-		    $type_func, "\\n.B \\\"\$1\\\"\\n",
-		    $type_struct, "\\n.I \\\"\$1\\\"\\n",
-		    $type_param."([\.\, ]*)\n?", "\\n.I \\\"\$1\$2\\\"\\n" );
-$blankline_man = "";
-
-# text-mode
-%highlights_text = ( $type_constant, "\$1",
-		     $type_func, "\$1",
-		     $type_struct, "\$1",
-		     $type_param, "\$1" );
-$blankline_text = "";
-
-
-sub usage {
-    print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -tex ]\n";
-    print "         [ -function funcname [ -function funcname ...] ]\n";
-    print "         c source file(s) > outputfile\n";
-    exit 1;
-}
-
-# read arguments
-if ($#ARGV==-1) {
-    usage();
-}
-
-$verbose = 0;
-$output_mode = "man";
-%highlights = %highlights_man;
-$blankline = $blankline_man;
-$modulename = "API Documentation";
-$function_only = 0;
-while ($ARGV[0] =~ m/^-(.*)/) {
-    $cmd = shift @ARGV;
-    if ($cmd eq "-html") {
-	$output_mode = "html";
-	%highlights = %highlights_html;
-	$blankline = $blankline_html;
-    } elsif ($cmd eq "-man") {
-	$output_mode = "man";
-	%highlights = %highlights_man;
-	$blankline = $blankline_man;
-    } elsif ($cmd eq "-tex") {
-	$output_mode = "tex";
-	%highlights = %highlights_tex;
-	$blankline = $blankline_tex;
-    } elsif ($cmd eq "-text") {
-	$output_mode = "text";
-	%highlights = %highlights_text;
-	$blankline = $blankline_text;
-    } elsif ($cmd eq "-docbook") {
-	$output_mode = "sgml";
-	%highlights = %highlights_sgml;
-	$blankline = $blankline_sgml;
-    } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
-	$modulename = shift @ARGV;
-    } elsif ($cmd eq "-function") { # to only output specific functions
-	$function_only = 1;
-	$function = shift @ARGV;
-	$function_table{$function} = 1;
-    } elsif ($cmd eq "-v") {
-	$verbose = 1;
-    } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
-	usage();
-    }
-}
-
-
-# generate a sequence of code that will splice in highlighting information
-# using the s// operator.
-$dohighlight = "";
-foreach $pattern (keys %highlights) {
-#    print "scanning pattern $pattern ($highlights{$pattern})\n";
-    $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
-}
-
-##
-# dumps section contents to arrays/hashes intended for that purpose.
-#
-sub dump_section {
-    my $name = shift @_;
-    my $contents = join "\n", @_;
-
-    if ($name =~ m/$type_constant/) {
-	$name = $1;
-#	print STDERR "constant section '$1' = '$contents'\n";
-	$constants{$name} = $contents;
-    } elsif ($name =~ m/$type_param/) {
-#	print STDERR "parameter def '$1' = '$contents'\n";
-	$name = $1;
-	$parameters{$name} = $contents;
-    } else {
-#	print STDERR "other section '$name' = '$contents'\n";
-	$sections{$name} = $contents;
-	push @sectionlist, $name;
-    }
-}
-
-##
-# output function
-#
-# parameters, a hash.
-#  function => "function name"
-#  parameterlist => @list of parameters
-#  parameters => %parameter descriptions
-#  sectionlist => @list of sections
-#  sections => %descriont descriptions
-#  
-
-sub output_highlight {
-    my $contents = join "\n", @_;
-    my $line;
-
-    eval $dohighlight;
-    foreach $line (split "\n", $contents) {
-	if ($line eq ""){
-	    print $lineprefix, $blankline;
-	} else {
-	    print $lineprefix, $line;
-	}
-	print "\n";
-    }
-}
-
-
-# output in html
-sub output_html {
-    my %args = %{$_[0]};
-    my ($parameter, $section);
-    my $count;
-    print "\n\n<a name=\"". $args{'function'} . "\">&nbsp</a><h2>Function</h2>\n";
-
-    print "<i>".$args{'functiontype'}."</i>\n";
-    print "<b>".$args{'function'}."</b>\n";
-    print "(";
-    $count = 0;
-    foreach $parameter (@{$args{'parameterlist'}}) {
-	print "<i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
-	if ($count != $#{$args{'parameterlist'}}) {
-	    $count++;
-	    print ", ";
-	}
-    }
-    print ")\n";
-
-    print "<h3>Arguments</h3>\n";
-    print "<dl>\n";
-    foreach $parameter (@{$args{'parameterlist'}}) {
-	print "<dt><i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
-	print "<dd>";
-	output_highlight($args{'parameters'}{$parameter});
-    }
-    print "</dl>\n";
-    foreach $section (@{$args{'sectionlist'}}) {
-	print "<h3>$section</h3>\n";
-	print "<ul>\n";
-	output_highlight($args{'sections'}{$section});
-	print "</ul>\n";
-    }
-    print "<hr>\n";
-}
-
-# output in tex
-sub output_tex {
-    my %args = %{$_[0]};
-    my ($parameter, $section);
-    my $count;
-    my $func = $args{'function'};
-    my $param;
-    my $param2;
-    my $sec;
-    my $check;
-    my $type;
-
-    $func =~ s/_/\\_/g;
-
-    print "\n\n\\subsection{". $func . "}\n\\label{" . $args{'function'} . "}\n";
-
-    $type = $args{'functiontype'};
-    $type =~ s/_/\\_/g;
-
-    print "{\\it ".$type."}\n";
-    print "{\\bf ".$func."}\n";
-    print "(\n";
-    $count = 0;
-    foreach $parameter (@{$args{'parameterlist'}}) {
-        $param = $args{'parametertypes'}{$parameter};
-        $param2 = $parameter;
-	$param =~ s/_/\\_/g;
-        $param2 =~ s/_/\\_/g;
-
-	print "{\\it ".$param."} {\\bf ".$param2."}\n";
-	if ($count != $#{$args{'parameterlist'}}) {
-	    $count++;
-	    print ", ";
-	}
-    }
-    print ")\n";
-
-    print "\n{\\large{Arguments}}\n";
-
-    print "\\begin{itemize}\n";
-    $check=0;
-    foreach $parameter (@{$args{'parameterlist'}}) {
-        $param1 = $args{'parametertypes'}{$parameter};
-        $param1 =~ s/_/\\_/g;
-        $param2 = $parameter;
-	$param2 =~ s/_/\\_/g;
-
-	$check = 1;
-	print "\\item {\\it ".$param1."} {\\bf ".$param2."}: \n";
-#	print "\n";
-
-	$param3 = $args{'parameters'}{$parameter};
-	$param3 =~ s/_/\\_/g;
-	$param3 =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
-
-	output_highlight($param3);
-    }
-    if ($check==0) {
-	print "\\item void\n";
-    }
-    print "\\end{itemize}\n";
-
-    foreach $section (@{$args{'sectionlist'}}) {
-	$sec = $section;
-	$sec =~ s/_/\\_/g;
-	$sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
-
-	print "\n\\par{\\large{$sec}}\\par\n";
-	print "\\begin{rmfamily}\n";
-
-	$sec = $args{'sections'}{$section};
-	$sec =~ s/_/\\_/g;
-	$sec =~ s/\\:/:/g;
-	$sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
-	$sec =~ s/->/\$\\rightarrow\$/g;
-	$sec =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
-
-	output_highlight($sec);
-	print "\\end{rmfamily}\n";
-    }
-    print "\n";
-}
-
-
-# output in sgml DocBook
-sub output_sgml {
-    my %args = %{$_[0]};
-    my ($parameter, $section);
-    my $count;
-    my $id;
-
-    $id = $args{'module'}."-".$args{'function'};
-    $id =~ s/[^A-Za-z0-9]/-/g;
-
-    print "<refentry>\n";
-    print "<refmeta>\n";
-    print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
-    print "</refmeta>\n";
-    print "<refnamediv>\n";
-    print " <refname>".$args{'function'}."</refname>\n";
-    print " <refpurpose>\n";
-    print "  ".$args{'purpose'}."\n";
-    print " </refpurpose>\n";
-    print "</refnamediv>\n";
-
-    print "<refsynopsisdiv>\n";
-    print " <title>Synopsis</title>\n";
-    print "  <funcsynopsis>\n";
-    print "   <funcdef>".$args{'functiontype'}." ";
-    print "<function>".$args{'function'}." ";
-    print "</function></funcdef>\n";
-
-#    print "<refsect1>\n";
-#    print " <title>Synopsis</title>\n";
-#    print "  <funcsynopsis>\n";
-#    print "   <funcdef>".$args{'functiontype'}." ";
-#    print "<function>".$args{'function'}." ";
-#    print "</function></funcdef>\n";
-
-    $count = 0;
-    if ($#{$args{'parameterlist'}} >= 0) {
-	foreach $parameter (@{$args{'parameterlist'}}) {
-	    print "   <paramdef>".$args{'parametertypes'}{$parameter};
-	    print " <parameter>$parameter</parameter></paramdef>\n";
-	}
-    } else {
-	print "  <void>\n";
-    }
-    print "  </funcsynopsis>\n";
-    print "</refsynopsisdiv>\n";
-#    print "</refsect1>\n";
-
-    # print parameters
-    print "<refsect1>\n <title>Arguments</title>\n";
-#    print "<para>\nArguments\n";
-    if ($#{$args{'parameterlist'}} >= 0) {
-	print " <variablelist>\n";
-	foreach $parameter (@{$args{'parameterlist'}}) {
-	    print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
-	    print "   <listitem>\n    <para>\n";
-	    $lineprefix="     ";
-	    output_highlight($args{'parameters'}{$parameter});
-	    print "    </para>\n   </listitem>\n  </varlistentry>\n";
-	}
-	print " </variablelist>\n";
-    } else {
-	print " <para>\n  None\n </para>\n";
-    }
-    print "</refsect1>\n";
-
-    # print out each section
-    $lineprefix="   ";
-    foreach $section (@{$args{'sectionlist'}}) {
-	print "<refsect1>\n <title>$section</title>\n <para>\n";
-#	print "<para>\n$section\n";
-	if ($section =~ m/EXAMPLE/i) {
-	    print "<example><para>\n";
-	}
-	output_highlight($args{'sections'}{$section});
-#	print "</para>";
-	if ($section =~ m/EXAMPLE/i) {
-	    print "</para></example>\n";
-	}
-	print " </para>\n</refsect1>\n";
-    }
-
-    print "\n\n";
-}
-
-##
-# output in man
-sub output_man {
-    my %args = %{$_[0]};
-    my ($parameter, $section);
-    my $count;
-
-    print ".TH \"$args{'module'}\" \"$args{'function'}\" \"25 May 1998\" \"API Manual\" GNOME\n";
-
-    print ".SH Function\n";
-
-    print ".I \"".$args{'functiontype'}."\"\n";
-    print ".B \"".$args{'function'}."\"\n";
-    print "(\n";
-    $count = 0;
-    foreach $parameter (@{$args{'parameterlist'}}) {
-	print ".I \"".$args{'parametertypes'}{$parameter}."\"\n.B \"".$parameter."\"\n";
-	if ($count != $#{$args{'parameterlist'}}) {
-	    $count++;
-	    print ",\n";
-	}
-    }
-    print ")\n";
-
-    print ".SH Arguments\n";
-    foreach $parameter (@{$args{'parameterlist'}}) {
-	print ".IP \"".$args{'parametertypes'}{$parameter}." ".$parameter."\" 12\n";
-	output_highlight($args{'parameters'}{$parameter});
-    }
-    foreach $section (@{$args{'sectionlist'}}) {
-	print ".SH \"$section\"\n";
-	output_highlight($args{'sections'}{$section});
-    }
-}
-
-##
-# output in text
-sub output_text {
-    my %args = %{$_[0]};
-    my ($parameter, $section);
-
-    print "Function = ".$args{'function'}."\n";
-    print "  return type: ".$args{'functiontype'}."\n\n";
-    foreach $parameter (@{$args{'parameterlist'}}) {
-	print " ".$args{'parametertypes'}{$parameter}." ".$parameter."\n";
-	print "    -> ".$args{'parameters'}{$parameter}."\n";
-    }
-    foreach $section (@{$args{'sectionlist'}}) {
-	print " $section:\n";
-	print "    -> ";
-	output_highlight($args{'sections'}{$section});
-    }
-}
-
-##
-# generic output function - calls the right one based
-# on current output mode.
-sub output_function {
-#    output_html(@_);
-    eval "output_".$output_mode."(\@_);";
-}
-
-
-##
-# takes a function prototype and spits out all the details
-# stored in the global arrays/hsahes.
-sub dump_function {
-    my $prototype = shift @_;
-
-    if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
-	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
-	$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
-	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
-	$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/)  {
-	$return_type = $1;
-	$function_name = $2;
-	$args = $3;
-
-#	print STDERR "ARGS = '$args'\n";
-
-	foreach $arg (split ',', $args) {
-	    # strip leading/trailing spaces
-	    $arg =~ s/^\s*//;
-	    $arg =~ s/\s*$//;
-#	    print STDERR "SCAN ARG: '$arg'\n";
-	    @args = split('\s', $arg);
-
-#	    print STDERR " -> @args\n";
-	    $param = pop @args;
-#	    print STDERR " -> @args\n";
-	    if ($param =~ m/^(\*+)(.*)/) {
-		$param = $2;
-		push @args, $1;
-	    }
-	    $type = join " ", @args;
-
-	    if ($parameters{$param} eq "" && $param != "void") {
-		$parameters{$param} = "-- undescribed --";
-		print STDERR "Warning($lineno): Function parameter '$param' not described in '$function_name'\n";
-	    }
-
-	    push @parameterlist, $param;
-	    $parametertypes{$param} = $type;
-
-#	    print STDERR "param = '$param', type = '$type'\n";
-	}
-    } else {
-	print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n";
-	return;
-    }
-
-    if ($function_only==0 || defined($function_table{$function_name})) {
-	output_function({'function' => $function_name,
-			 'module' => $modulename,
-			 'functiontype' => $return_type,
-			 'parameterlist' => \@parameterlist,
-			 'parameters' => \%parameters,
-			 'parametertypes' => \%parametertypes,
-			 'sectionlist' => \@sectionlist,
-			 'sections' => \%sections,
-			 'purpose' => $function_purpose
-			 });
-    }
-}
-
-######################################################################
-# main
-# states
-# 0 - normal code
-# 1 - looking for function name
-# 2 - scanning field start.
-# 3 - scanning prototype.
-$state = 0;
-$section = "";
-
-$doc_special = "\@\%\$\&";
-
-$doc_start = "^/\\*\\*\$";
-$doc_end = "\\*/";
-$doc_com = "\\s*\\*\\s*";
-$doc_func = $doc_com."(\\w+):?";
-$doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)";
-$doc_content = $doc_com."(.*)";
-
-%constants = ();
-%parameters = ();
-@parameterlist = ();
-%sections = ();
-@sectionlist = ();
-
-$contents = "";
-$section_default = "Description";	# default section
-$section = $section_default;
-
-$lineno = 0;
-foreach $file (@ARGV) {
-    if (!open(IN,"<$file")) {
-	print STDERR "Error: Cannot open file $file\n";
-	next;
-    }
-    while (<IN>) {
-	$lineno++;
-
-	if ($state == 0) {
-	    if (/$doc_start/o) {
-		$state = 1;		# next line is always the function name
-	    }
-	} elsif ($state == 1) {	# this line is the function name (always)
-	    if (/$doc_func/o) {
-		$function = $1;
-		$state = 2;
-		if (/-(.*)/) {
-		    $function_purpose = $1;
-		} else {
-		    $function_purpose = "";
-		}
-		if ($verbose) {
-		    print STDERR "Info($lineno): Scanning doc for $function\n";
-		}
-	    } else {
-		print STDERR "WARN($lineno): Cannot understand $_ on line $lineno",
-		" - I thought it was a doc line\n";
-		$state = 0;
-	    }
-	} elsif ($state == 2) {	# look for head: lines, and include content
-	    if (/$doc_sect/o) {
-		$newsection = $1;
-		$newcontents = $2;
-
-		if ($contents ne "") {
-		    dump_section($section, $contents);
-		    $section = $section_default;
-		}
-
-		$contents = $newcontents;
-		if ($contents ne "") {
-		    $contents .= "\n";
-		}
-		$section = $newsection;
-	    } elsif (/$doc_end/) {
-
-		if ($contents ne "") {
-		    dump_section($section, $contents);
-		    $section = $section_default;
-		    $contents = "";
-		}
-
-#	    print STDERR "end of doc comment, looking for prototype\n";
-		$prototype = "";
-		$state = 3;
-	    } elsif (/$doc_content/) {
-		# miguel-style comment kludge, look for blank lines after
-		# @parameter line to signify start of description
-		if ($1 eq "" && $section =~ m/^@/) {
-		    dump_section($section, $contents);
-		    $section = $section_default;
-		    $contents = "";
-		} else {
-		    $contents .= $1."\n";
-		}
-	    } else {
-		# i dont know - bad line?  ignore.
-		print STDERR "WARNING($lineno): bad line: $_"; 
-	    }
-	} elsif ($state == 3) {	# scanning for function { (end of prototype)
-	    if (m#\s*/\*\s+MACDOC\s*#io) {
-	      # do nothing
-	    }
-	    elsif (/([^\{]*)/) {
-		$prototype .= $1;
-	    }
-	    if (/\{/) {
-		$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
-		$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
-		$prototype =~ s@^ +@@gos; # strip leading spaces
-		dump_function($prototype);
-
-		$function = "";
-		%constants = ();
-		%parameters = ();
-		%parametertypes = ();
-		@parameterlist = ();
-		%sections = ();
-		@sectionlist = ();
-		$prototype = "";
-
-		$state = 0;
-	    }
-	}
-    }
-}
-