Initial revision

6 files changed, 1234 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..a257afb
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,19 @@
+EXTRA_DIST = asn1.tex asn1.ps asn1.html fdl.tex TODO
+SUBDIRS = scripts
+
+
+TEX_OBJECTS = asn1.tex ../lib/asn1-api.tex 
+
+asn1.ps: $(TEX_OBJECTS)
+	-$(LN_S) ../lib/asn1-api.tex .
+	-latex asn1.tex && latex asn1.tex && dvips asn1.dvi -o asn1.ps
+
+asn1.html: $(TEX_OBJECTS)
+	-latex2html asn1.tex -no_navigation -no_subdir 1 -split 0 -local_icons -html_version 3.2,math \
+	-info "" -white
+
+
+clean:
+	@-rm *.log *.aux *.toc
+	@-rm *.pl index.html asn1.dvi
+	@-rm WARNINGS asn1-api.tex
diff --git a/doc/TODO b/doc/TODO
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/TODO
diff --git a/doc/asn1.tex b/doc/asn1.tex
new file mode 100644
index 0000000..1ef06ed
--- /dev/null
+++ b/doc/asn1.tex
@@ -0,0 +1,142 @@
+\documentclass{book}
+\usepackage{html}
+\usepackage{fancyheadings}
+\usepackage{graphicx}
+
+\begin{document}
+
+\vspace*{\stretch{2}}
+
+\begin{center}
+\par
+Copyright \copyright\ 2001, 2002 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}
+
+
+\chapter{ASN.1 structures handling}
+
+\section{Introduction}
+ This file describes the forth version of ASN.1 parser I
+developed.
+The main difference from the first version is the use of pointers and the
+possibility to save/get ASN1 definitions in/from a C vector.
+Other differences are:
+\begin{itemize}
+\item write\_value function for type ANY
+\item the introduction of ENUMERATED type,
+\item negative integer are allowed in ASN.1 syntax files,
+\item PKIX1Implicit88.txt instead of Certificate.txt for the Certificate description
+\item functions naming 
+\item an easier way to set INTEGER and get OBJECT IDENTFIER  
+\end{itemize}
+
+
+\section{ASN.1 syntax}
+The parser is case sensitive. The comments begin with "-- " and end at the end of line.
+An example is in "Certificate.txt" file.
+The ASN.1 declarations must have this form:
+      
+\begin{verbatim}
+      object_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      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 also not allow the use of 
+"EXPORT" and "IMPORT" sections.
+
+The SIZE constraints are allowed but no check is done on them.
+
+
+
+\section{Naming}
+If you have 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 filed '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, receve the name "?1","?2", and so on. 
+The name "?LAST" indicates the last element of a SET\_OF or SEQUENCE\_OF.
+
+\section{Future developments}
+\begin{enumerate}
+\item type REAL 
+\item improve the error signaling with strings that give you more details. 
+   Examples: in case of ASN1 syntax error you will have the line number where the error is,  
+             if creating a der encoding the result is ASN\_VALUE\_NOT\_FOUND you will have the
+             name of the element without the value.
+\item improve the 'visit\_tree' function and change the output from stdout to a null terminated 
+   string.  
+
+\end{enumerate}
+
+\input{asn1-api}
+
+\input{fdl.tex}
+
+\end{document}
diff --git a/doc/fdl.tex b/doc/fdl.tex
new file mode 100644
index 0000000..c0fcbe3
--- /dev/null
+++ b/doc/fdl.tex
@@ -0,0 +1,367 @@
+% 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/Makefile.am b/doc/scripts/Makefile.am
new file mode 100644
index 0000000..7deb104
--- /dev/null
+++ b/doc/scripts/Makefile.am
@@ -0,0 +1,3 @@
+EXTRA_DIST = gdoc
+
+
diff --git a/doc/scripts/gdoc b/doc/scripts/gdoc
new file mode 100755
index 0000000..9597148
--- /dev/null
+++ b/doc/scripts/gdoc
@@ -0,0 +1,703 @@
+#!/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;
+	    }
+	}
+    }
+}
+