diff --git a/Makefile.am b/Makefile.am index 99b335ddc..f08166129 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,6 +1,6 @@ ## Process this file with automake to produce Makefile.in -SUBDIRS = intl po src lib client +SUBDIRS = intl po src lib client doc MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.guess \ config.h.in config.sub configure install-sh \ @@ -20,3 +20,12 @@ dist-hook: fi EXTRA_DIST = README AUTHORS COPYING e.spec + +docs: + $(MAKE) -C $(top_srcdir)/doc docs + +if HAVE_JADE +html-docs: + $(MAKE) -C $(top_srcdir)/doc html-docs +endif + diff --git a/configure.ac b/configure.ac index f1bf6d4c3..5c0080156 100644 --- a/configure.ac +++ b/configure.ac @@ -1,6 +1,7 @@ dnl Process this file with autoconf to produce a configure script. -AC_INIT(configure.in) +AC_INIT +AC_CONFIG_SRCDIR([configure.in]) ENLIGHTENMENT_MAJOR=0 ENLIGHTENMENT_MINOR=17 @@ -230,7 +231,34 @@ AC_MSG_ERROR(Cannot detect db loader: Have you installed imlib2_loaders?) ], AC_MSG_ERROR(Sorry. Enlightenment cannot be cross-compiled.)) -AC_OUTPUT([ -Makefile src/Makefile lib/Makefile client/Makefile intl/Makefile po/Makefile.in -]) + +dnl Checking for Perl: +AC_PATH_PROG(PERL,perl,0) +AC_SUBST(PERL) + + +dnl Look for jade for sgml translations. +AC_ARG_WITH(dbsheets, + [ --with-dbsheets=DIR use DIR to specify your DocBook stylesheets installation path.], + DB_STYLESHEETS="$withval", DB_STYLESHEETS="/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh") +AC_SUBST(DB_STYLESHEETS) +AC_PATH_PROG(JADE, jade) +AM_CONDITIONAL(HAVE_JADE, test "x$JADE" != "x" && test -d "$DB_STYLESHEETS") + + +AC_CONFIG_FILES([ +Makefile +src/Makefile +lib/Makefile +client/Makefile +intl/Makefile +po/Makefile.in +doc/Makefile +doc/kernel-doc +doc/html-customizations.dsl +]) +AC_CONFIG_COMMANDS([default],[[ +chmod +x doc/kernel-doc +]],[[]]) +AC_OUTPUT diff --git a/configure.in b/configure.in index f1bf6d4c3..97f0f3687 100644 --- a/configure.in +++ b/configure.in @@ -230,7 +230,32 @@ AC_MSG_ERROR(Cannot detect db loader: Have you installed imlib2_loaders?) ], AC_MSG_ERROR(Sorry. Enlightenment cannot be cross-compiled.)) + +dnl Checking for Perl: +AC_PATH_PROG(PERL,perl,0) +AC_SUBST(PERL) + + +dnl Look for jade for sgml translations. +AC_ARG_WITH(dbsheets, + [ --with-dbsheets=DIR use DIR to specify your DocBook stylesheets installation path.], + DB_STYLESHEETS="$withval", DB_STYLESHEETS="/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh") +AC_SUBST(DB_STYLESHEETS) +AC_PATH_PROG(JADE, jade) +AM_CONDITIONAL(HAVE_JADE, test "x$JADE" != "x" && test -d "$DB_STYLESHEETS") + + AC_OUTPUT([ -Makefile src/Makefile lib/Makefile client/Makefile intl/Makefile po/Makefile.in +Makefile +src/Makefile +lib/Makefile +client/Makefile +intl/Makefile +po/Makefile.in +doc/Makefile +doc/kernel-doc +doc/html-customizations.dsl +], [ +chmod +x doc/kernel-doc ]) diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 000000000..45b163779 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,46 @@ +## Process this file with automake to produce Makefile.in + +MAINTAINERCLEANFILES = Makefile.in + +EXTRA_DIST = \ +manual.raw \ +kernel-doc.in \ +stylesheet.css \ +figures/*.gif # Add any images you create here + + +## Fill in all source files that you documented +## with extractable comments here: +## +SOURCEDOC = $(top_srcdir)/src/e.h + +## For details on what can be specified in the +## comments, see the beginning of kernel-doc +## in this directory! -- cK. + + +SGMLFILE = $(PACKAGE)-manual.sgml + +docs: manual.raw $(SOURCEDOC) + ./kernel-doc -docbook $(SGMLFILE) + +if HAVE_JADE + +FULLNAME = $(PACKAGE)-manual-$(VERSION) + +html-docs: docs html-customizations.dsl + $(mkinstalldirs) ./$(FULLNAME)/figures + cd $(FULLNAME) && @JADE@ -t sgml -d ../html-customizations.dsl ../$(SGMLFILE) + - cd figures && cp -f *.gif ../$(FULLNAME)/figures + - cd figures && cp -f *.png ../$(FULLNAME)/figures + - cd figures && cp -f *.jpg ../$(FULLNAME)/figures + cp -f stylesheet.css $(FULLNAME)/stylesheet.css + tar cfvz $(FULLNAME).tar.gz $(FULLNAME) + +html-filetypes: filetypes.xsl + $(mkinstalldirs) ./$(FULLNAME)/filetypes + cp -fr filetypes-templates/* ./$(FULLNAME)/filetypes + ./generate-trees.sh ./$(FULLNAME)/filetypes + +endif + diff --git a/doc/figures/background.gif b/doc/figures/background.gif new file mode 100644 index 000000000..1dc11ce83 Binary files /dev/null and b/doc/figures/background.gif differ diff --git a/doc/figures/caution.gif b/doc/figures/caution.gif new file mode 100644 index 000000000..542232911 Binary files /dev/null and b/doc/figures/caution.gif differ diff --git a/doc/figures/note.gif b/doc/figures/note.gif new file mode 100644 index 000000000..45fe08649 Binary files /dev/null and b/doc/figures/note.gif differ diff --git a/doc/figures/warning.gif b/doc/figures/warning.gif new file mode 100644 index 000000000..9c1104c2b Binary files /dev/null and b/doc/figures/warning.gif differ diff --git a/doc/html-customizations.dsl.in b/doc/html-customizations.dsl.in new file mode 100644 index 000000000..4bf0404d0 --- /dev/null +++ b/doc/html-customizations.dsl.in @@ -0,0 +1,61 @@ + +]> + + + + + +;; my own customizations for HTML output: + +(define %admon-graphics-path% + ;; Path to admonition graphics + "figures/") + +(define %admon-graphics% + ;; Use graphics in admonitions? + #t) + +(define %indent-programlisting-lines% + ;; Indent lines in a 'ProgramListing'? + " ") + +(define %shade-verbatim% + ;; Should verbatim environments be shaded? + #t) + +(define ($shade-verbatim-attr$) + ;; Attributes used to create a shaded verbatim environment. + (list + (list "BORDER" "0") + (list "BGCOLOR" "#f0f0f0"))) + +(define %root-filename% + ;; Name for the root HTML document + "index") + +(define %body-attr% + ;; What attributes should be hung off of BODY? + (list + (list "BGCOLOR" "#FFFFFF") + (list "TEXT" "#0000A0") + (list "LINK" "#2020D0") + (list "VLINK" "#000060") + (list "ALINK" "#5050F0"))) + +(define %css-decoration% + ;; Enable CSS decoration of elements + #t) + +(define %stylesheet% + ;; Name of the stylesheet to use + "stylesheet.css") + +(define biblio-number + ;; Enumerate bibliography entries + #t) + + + + + diff --git a/doc/kernel-doc.in b/doc/kernel-doc.in new file mode 100644 index 000000000..4865a89bd --- /dev/null +++ b/doc/kernel-doc.in @@ -0,0 +1,1001 @@ +#!@PERL@ + +## This script is based on the script shipped with ## +## 2.4 Linux kernel sources. All copyright notices etc ## +## remain unchanged. --cK. ## + +## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## +## Copyright (C) 2000 Tim Waugh ## +## ## +## #define enhancements by Armin Kuster ## +## Copyright (c) 2000 MontaVista Software, Inc. ## +## ## +## This software falls under the GNU General Public License. ## +## Please read the COPYING file for more information ## + +# w.o. 03-11-2000: added the '-filelist' option. + +# +# This will read a 'c' file and scan for embedded comments in the +# style of gnome comments (+minor extensions - see below). +# + +# Note: This only supports 'c'. + +# usage: +# kerneldoc [ -docbook | -html | -text | -man ] +# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile +# or +# [ -nofunction 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. +# +# -nofunction funcname +# If set, then only generate documentation for the other function(s). All +# other functions are ignored. Cannot be used with -function together +# (yes thats a bug - perl hackers can fix it 8)) +# +# 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 (up to two words including 'struct') +# '@parameter' - name of a parameter +# '%CONST' - name of a constant. + +# match expressions used to find embedded type information +$type_constant = "\\\%([-_\\w]+)"; +$type_func = "(\\w+)\\(\\)"; +$type_param = "\\\@(\\w+)"; +$type_struct = "\\\&((struct\\s*)?[_\\w]+)"; +$type_env = "(\\\$\\w+)"; + + +# Output conversion substitutions. +# One for each output format + +# these work fairly well +%highlights_html = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_param, "\$1" ); +$blankline_html = "

"; + +# sgml, docbook format +%highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", + $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +$blankline_sgml = "\n"; + +# gnome, docbook format +%highlights_gnome = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +$blankline_gnome = "\n"; + +# these are pretty rough +%highlights_man = ( $type_constant, "\$1", + $type_func, "\\\\fB\$1\\\\fP", + $type_struct, "\\\\fI\$1\\\\fP", + $type_param, "\\\\fI\$1\\\\fP" ); +$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 ]\n"; + print " [ -function funcname [ -function funcname ...] ]\n"; + print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; + print " < inputfile > 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; +$filelist = ''; + +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 "-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 "-gnome") { + $output_mode = "gnome"; + %highlights = %highlights_gnome; + $blankline = $blankline_gnome; + } 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 "-nofunction") { # to only output specific functions + $function_only = 2; + $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 { + $line =~ s/\\\\\\/\&/g; + print $lineprefix, $line; + } + print "\n"; + } +} + + +# output in html +sub output_html { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + print "

Function

\n"; + + print "".$args{'functiontype'}."\n"; + print "".$args{'function'}."\n"; + print "("; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print "$1$parameter) ($2)"; + } else { + print "".$type." ".$parameter.""; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + } + } + print ")\n"; + + print "

Arguments

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameters'}{$parameter}); + } + print "
\n"; + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
\n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } + print "
\n"; +} + + +# output in html +sub output_intro_html { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
    \n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } + print "
\n"; +} + + + +# output in sgml DocBook +sub output_sgml { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print "".$args{'function'}."\n"; + print "\n"; + print "\n"; + print " ".$args{'function'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." "; + print "\n"; + +# print "\n"; +# print " Synopsis\n"; +# print " \n"; +# print " ".$args{'functiontype'}." "; +# print "".$args{'function'}." "; +# print "\n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1$parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; + print "\n"; +# print "\n"; + + # print parameters + print "\n Arguments\n"; +# print "\nArguments\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print " \n $parameter\n"; + print " \n \n"; + $lineprefix=" "; + output_highlight($args{'parameters'}{$parameter}); + print " \n \n \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + print "\n"; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n \n"; +# print "\n$section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + output_highlight($args{'sections'}{$section}); +# print ""; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + print " \n\n"; + } + + print "\n\n"; +} + +# output in sgml DocBook +sub output_intro_sgml { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = $args{'module'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n \n"; +# print "\n$section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + output_highlight($args{'sections'}{$section}); +# print ""; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } + print " \n\n"; + } + + print "\n\n"; +} + +# output in sgml DocBook +sub output_gnome { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = $args{'module'}."-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print " ".$args{'function'}."\n"; + +# print "\n"; +# print " Synopsis\n"; + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." "; + print "\n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1 $parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; +# print "\n"; +# print "\n"; + + # print parameters +# print "\n Arguments\n"; +# if ($#{$args{'parameterlist'}} >= 0) { +# print " \n"; +# foreach $parameter (@{$args{'parameterlist'}}) { +# print " \n $parameter\n"; +# print " \n \n"; +# $lineprefix=" "; +# output_highlight($args{'parameters'}{$parameter}); +# print " \n \n \n"; +# } +# print " \n"; +# } else { +# print " \n None\n \n"; +# } +# print "\n"; + +# print "\n Arguments\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + print "\n"; + print "\n"; + print "\n"; + print "\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print " $parameter\n"; + print " \n"; + $lineprefix=" "; + output_highlight($args{'parameters'}{$parameter}); + print " \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } +# print "\n"; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n"; +# print "\n$section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print "\n"; + output_highlight($args{'sections'}{$section}); +# print ""; + print "\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print " \n"; + } + + print "\n\n"; +} + +## +# output in man +sub output_man { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 4 \"$args{'function'}\" \"25 May 1998\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'function'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n"; + $count = 0; + $parenth = "("; + $post = ","; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($count == $#{$args{'parameterlist'}}) { + $post = ");"; + } + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n"; + } else { + $type =~ s/([^\*])$/\1 /; + print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n"; + } + $count++; + $parenth = ""; + } + + print ".SH Arguments\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameters'}{$parameter}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +sub output_intro_man { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 4 \"$args{'module'}\" \"25 May 1998\" \"API Manual\" LINUX\n"; + + 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:\n\n"; + $start=$args{'functiontype'}." ".$args{'function'}." ("; + print $start; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print $1.$parameter.") (".$2; + } else { + print $type." ".$parameter; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + print " " x length($start); + } else { + print ");\n\n"; + } + } + + print "Arguments:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print $parameter."\n\t".$args{'parameters'}{$parameter}."\n"; + } + foreach $section (@{$args{'sectionlist'}}) { + print "$section:\n\n"; + output_highlight($args{'sections'}{$section}); + } + print "\n\n"; +} + +sub output_intro_text { + my %args = %{$_[0]}; + my ($parameter, $section); + + 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."(\@_);"; +} + +## +# generic output function - calls the right one based +# on current output mode. +sub output_intro { +# output_html(@_); + eval "output_intro_".$output_mode."(\@_);"; +} + + +## +# takes a function prototype and spits out all the details +# stored in the global arrays/hashes. +sub dump_function { + my $prototype = shift @_; + + $prototype =~ s/^static +//; + $prototype =~ s/^extern +//; + $prototype =~ s/^inline +//; + $prototype =~ s/^__inline__ +//; + $prototype =~ s/^#define +//; #ak added + + # Yes, this truly is vile. We are looking for: + # 1. Return type (may be nothing if we're looking at a macro) + # 2. Function name + # 3. Function parameters. + # + # All the while we have to watch out for function pointer parameters + # (which IIRC is what the two sections are for), C types (these + # regexps don't even start to express all the possibilities), and + # so on. + # + # If you mess with these regexps, it's a good idea to check that + # the following functions' documentation still comes out right: + # - parport_register_device (function pointer parameters) + # - atomic_set (macro) + # - pci_match_device (long return type) + + 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*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $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*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { + $return_type = $1; + $function_name = $2; + $args = $3; + + # allow for up to fours args to function pointers + $args =~ s/(\([^\),]+),/\1#/g; + $args =~ s/(\([^\),]+),/\1#/g; + $args =~ s/(\([^\),]+),/\1#/g; +# print STDERR "ARGS = '$args'\n"; + + foreach $arg (split ',', $args) { + # strip leading/trailing spaces + $arg =~ s/^\s*//; + $arg =~ s/\s*$//; + + if ($arg =~ m/\(/) { + # pointer-to-function + $arg =~ tr/#/,/; + $arg =~ m/[^\(]+\(\*([^\)]+)\)/; + $param = $1; + $type = $arg; + $type =~ s/([^\(]+\(\*)$param/\1/; + } else { + # evil magic to get fixed array parameters to work + $arg =~ s/(.+\s+)(.+)\[.*/\1* \2/; +# 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 ($type eq "" && $param eq "...") + { + $type="..."; + $param="..."; + $parameters{"..."} = "variable arguments"; + } + elsif ($type eq "" && $param eq "") + { + $type=""; + $param="void"; + $parameters{void} = "no arguments"; + } + if ($type ne "" && $parameters{$param} eq "") { + $parameters{$param} = "-- undescribed --"; + print STDERR "Warning($file:$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 || + ( $function_only == 1 && defined($function_table{$function_name})) || + ( $function_only == 2 && !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 = "^/\\*\\*\\s*\$"; +$doc_end = "\\*/"; +$doc_com = "\\s*\\*\\s*"; +$doc_func = $doc_com."(\\w+):?"; +$doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)"; +$doc_content = $doc_com."(.*)"; +$doc_block = $doc_com."DOC:\\s*(.*)?"; + +%constants = (); +%parameters = (); +@parameterlist = (); +%sections = (); +@sectionlist = (); + +$contents = ""; +$section_default = "Description"; # default section +$section_intro = "Introduction"; +$section = $section_default; + +while () + { + if (/^!I(.*)/) + { + process_file("@top_srcdir@" . "/" . $1); + } + else + { + print; + } + } + +exit; + +sub process_file($) { + my ($file) = @_; + + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + return; + } + + $lineno = 0; + while () { + $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_block/o) { + $state = 4; + $contents = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$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 "") { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + dump_section($section, $contents); + $section = $section_default; + } + + $contents = $newcontents; + if ($contents ne "") { + $contents .= "\n"; + } + $section = $newsection; + } elsif (/$doc_end/) { + + if ($contents ne "") { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + 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/^@/) { + $contents =~ s/\&/\\\\\\amp;/g; + $contents =~ s/\/\\\\\\gt;/g; + 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 (/\{/ || /\#/ || /;/) { # added for #define AK + $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; + } + } elsif ($state == 4) { + # Documentation block + if (/$doc_block/) { + dump_section($section, $contents); + output_intro({'sectionlist' => \@sectionlist, + 'sections' => \%sections }); + $contents = ""; + $function = ""; + %constants = (); + %parameters = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_end/) + { + dump_section($section, $contents); + output_intro({'sectionlist' => \@sectionlist, + 'sections' => \%sections }); + $contents = ""; + $function = ""; + %constants = (); + %parameters = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + $state = 0; + } + elsif (/$doc_content/) + { + if ( $1 eq "" ) + { + $contents .= $blankline; + } + else + { + $contents .= $1 . "\n"; + } + } + } + } +} + diff --git a/doc/manual.raw b/doc/manual.raw new file mode 100644 index 000000000..431e37200 --- /dev/null +++ b/doc/manual.raw @@ -0,0 +1,283 @@ +efsd"> +]> + + + + + EFSD Documentation Howto + + + + FIRSTNAME + OTHER + LASTNAME + +
+ EMAIL +
+ + + + + + 2001 + Christian Kreibich + + + + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to + deal in the Software without restriction, including without limitation the + rights to use, copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + + The above copyright notice and this permission notice shall be included in + all copies of the Software and its documentation and acknowledgment shall be + given in the documentation and software packages that this Software was + used. + + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER + IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + + + + This is document is nowhere near being finished. Be patient. + + + + + + + + Introduction + + This is some sample documentation for you project. You'll need to be + familiar with DocBook + to make best use of Enlightenment's documentation scheme. + + + See + for an explanation of the documentation setup in you project. + + + explains + the way you have to structure your comments so that they can be + extracted. + + + contains a few + layout and markup examples to get you up to speed quickly. + + + + + Documentation File Structure + + The entire documentation setup lives in the doc + directory. The file you need to edit is called manual.raw. + When you enter make docs in the toplevel directory, + it gets translated into a standard SGML file using a Perl script. + The script scans the file for any lines starting directly with the + string !I<filename>. Here, + filename is the name of a code + file in which you have put extractable comments. The Perl script will + then analyze the file and generate SGML DocBook statements for those + comments right into the output file. + + + The resulting file of that step is called $PACKAGE-manual-$VERSION.sgml + where PACKAGE and VERSION are automatically set during the build process. + This sgml file can be postprocessed with any SGML processor to generate + for example HTML, TeX or PDF output. + + + Suppport for HTML generation is included already through the + make html-docs target. In order to be able to use + that, you'll need to have jade installed, and appropriate + DocBook stylesheets. If the configure script doesn't automatically find + you stylesheets (on a Debian system it should), you can specify them when + calling configure or autogen.sh using + the --with-dbsheets=DIR option. + + + If everything worked out fine, you'll get a tarball of the HTML version + of your documentation and the extracted version in the docs directory, + named similarly to the SGML file. + + + + + + Writing Extractable Comments + + I'll simply give an example of a commented function here: + + + +/** + * efsd_wait_event - blocking wait for next Efsd event. + * @ec: The Efsd connection + * @ev: Pointer to an allocated EfsdEvent. + * + * Blocks until an efsd event arrives, then returns it by filling + * in the @ev structure. Returns -1 when there was an error, + * >= 0 otherwise. + */ +int efsd_wait_event(EfsdConnection *ec, EfsdEvent *ev); + + As you can see, it's not hard -- just use two asterisks + to signal the start of an extractable comment. In the first + line, begin with the function name and a one-liner description. + Then, put each parameter in the following lines. Add an empty + line, and then a more verbose description. That's basically + it, you can also markup items differently as follows: + + + + funcname() for function names + + + $ENVVAR for environment variables + + + &struct_name for structures + + + %CONST for constants/para> + + + + + + + DocBook Examples +
+ Lists + + + + This + + + is + + + a + + + list + + + +
+
+ Code + + + +EfsdConnection *ec; + +if ( (ec = efsd_open()) == NULL) + { + /* Oops. Couldn't establish connection. + * Is Efsd really running ? + */ + } + +/* ... various efsd commands ... */ + +if (efsd_close(ec) < 0) + { + /* Ouch. Error when closing connection. */ + } + + +
+
+ Images + + + + + + + + + + + Sample image + + + This is how you display images. + + + + +
+
+ Warnings, Notes + + + This is an example of a note. + + It's really simple to use. + + + + + This is a warning. + + It's used just like a note. + + + +
+ + + + + + + + W. R. + Stevens + + UNIX Network Programming + Second Edition + Volume 1 + + Prentice-Hall + + 1998 + + + + + + + W. R. + Stevens + + Advanced Programming in the UNIX Environment + + Addison-Wesley + + 1992 + + + + + + + diff --git a/doc/stylesheet.css b/doc/stylesheet.css new file mode 100644 index 000000000..660965075 --- /dev/null +++ b/doc/stylesheet.css @@ -0,0 +1,20 @@ +body { margin-left:10px; + margin-right:10px; + margin-top:10px; + margin-bottom:10px; + color:#0000a0; + font-size:12pt; + background-image:url(figures/background.gif); + background-repeat:no-repeat; + } + +th { + font-size:14pt; + } + +td { + font-size:12pt; + } + +div.mediaobject { align:center; } +div.caption { align:center; } diff --git a/po/ChangeLog b/po/ChangeLog index d4806687a..f394d3ab9 100644 --- a/po/ChangeLog +++ b/po/ChangeLog @@ -1,3 +1,41 @@ +2001-10-13 gettextize + + * Makefile.in.in: Upgrade to gettext-0.10.39. + +2001-10-13 gettextize + + * Makefile.in.in: Upgrade to gettext-0.10.39. + +2001-10-13 gettextize + + * Makefile.in.in: Upgrade to gettext-0.10.39. + +<<<<<<< ChangeLog +2001-10-08 gettextize + + * Makefile.in.in: Upgrade to gettext-0.10.39. + +2001-10-08 gettextize + + * Makefile.in.in: Upgrade to gettext-0.10.39. + +2001-09-25 gettextize + + * Makefile.in.in: Upgrade to gettext-0.10.39. + +2001-09-25 gettextize + + * Makefile.in.in: Upgrade to gettext-0.10.39. + +2001-09-10 gettextize + + * Makefile.in.in: Upgrade to gettext-0.10.39. + +2001-09-10 gettextize + + * Makefile.in.in: Upgrade to gettext-0.10.39. + +======= 2001-10-09 gettextize * Makefile.in.in: Upgrade to gettext-0.10.40. @@ -6,6 +44,7 @@ * Makefile.in.in: Upgrade to gettext-0.10.40. +>>>>>>> 1.6 2001-08-31 gettextize * Makefile.in.in: Upgrade to gettext-0.10.39.