diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/asn1.tex | 242 | ||||
| -rw-r--r-- | doc/fdl.tex | 367 | ||||
| -rw-r--r-- | doc/scripts/.cvsignore | 2 | ||||
| -rw-r--r-- | doc/scripts/Makefile.am | 3 | ||||
| -rwxr-xr-x | doc/scripts/gdoc | 703 |
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'} . "\"> </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; - } - } - } -} - |