From 6c52152328afcfcc324d84af18b509ce4cddf4a9 Mon Sep 17 00:00:00 2001 From: cpk Date: Sat, 13 Oct 2001 00:08:39 +0000 Subject: [PATCH] Documentation setup ... SVN revision: 5479 --- Makefile.am | 11 +- configure.ac | 36 +- configure.in | 27 +- doc/Makefile.am | 46 ++ doc/figures/background.gif | Bin 0 -> 6432 bytes doc/figures/caution.gif | Bin 0 -> 1039 bytes doc/figures/note.gif | Bin 0 -> 1070 bytes doc/figures/warning.gif | Bin 0 -> 1052 bytes doc/html-customizations.dsl.in | 61 ++ doc/kernel-doc.in | 1001 ++++++++++++++++++++++++++++++++ doc/manual.raw | 283 +++++++++ doc/stylesheet.css | 20 + po/ChangeLog | 39 ++ 13 files changed, 1518 insertions(+), 6 deletions(-) create mode 100644 doc/Makefile.am create mode 100644 doc/figures/background.gif create mode 100644 doc/figures/caution.gif create mode 100644 doc/figures/note.gif create mode 100644 doc/figures/warning.gif create mode 100644 doc/html-customizations.dsl.in create mode 100644 doc/kernel-doc.in create mode 100644 doc/manual.raw create mode 100644 doc/stylesheet.css 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 0000000000000000000000000000000000000000..1dc11ce83a7d0e6f12de6cbaed746c0e5deb47d2 GIT binary patch literal 6432 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 Ee>uaYC;$Ke literal 0 HcmV?d00001 diff --git a/doc/figures/caution.gif b/doc/figures/caution.gif new file mode 100644 index 0000000000000000000000000000000000000000..54223291154fed2f9639ce2707976ec58f44169b GIT binary patch literal 1039 zcmZ?wbh9u|lwgox_|5Sh{s9!`7`) zTel`}-MV$}UWUDUlh2)FICt*cwQCI5t^vtw_wF&=yJvXsp5?uJPS2k+Jb!NZ{JG`x z=g;52XL$eq{rB$--@gld|1RgdJ(|D$SrA+HAyGpqN^7x16zrMq{!ibMp=6~-(4c99<%wR z=lEzgH#IP+?pT$g`C;jexlBBNo_IO0=v$GV+9Oerpc~DlP;%tKgT`Z#V$4EkL{=v; zaW)#7)%@r_aPX#>5Fh`Y-v{$g32`gkn0k?^DW$2?_JPMq28Kof%}^J&9pNUYcvyH^ zranA$=y~&6-RTjl4}Cj!q6ciK{6%`g178e&67#J8C85tTH8XFrM z92^`S9UUGX9v>ecARr(iAt53nA|oRsBqSsyB_$>%CMPE+C@3f?DJd!{Dl021EG#T7 zEiEoCE-x=HFfcGNF)=bSGBYzXG&D3dH8nOiHa9mnI5;>tIXOByIy*Z%JUl!-Jv}}? zK0iM{KtMo2K|w-7LPJACL_|bIMMXwNMn^|SNJvOYNl8jdN=r*iOiWBoO-)WtPESuy zP*6}&QBhJ-Qd3h?R8&+|RaI72R##V7SXfwDSy@_IT3cINTwGjTU0q&YUSD5dU|?Wj zVPRroVq;@tWMpJzWo2e&W@l$-XlQ6@X=!R|YHMq2Y;0_8ZEbFDZf|dIaBy&OadC2T za&vQYbaZreb#-=jc6WDoczAeud3kzzdV70&e0+R;eSLm@et&;|fPjF3fq{a8f`fyD zgoK2Jg@uNOhKGlTh=_=ZiHVAeii?YjjEszpjg5|uj*pLzkdTm(k&%*;l9Q8@l$4Z} zm6ev3mY0{8n3$NEnVFiJnwy)OoSdAUot>VZo}ZteprD|kp`oIpqNAguq@<*!rKP5( zrl+T;sHmu^si~@}s;jH3tgNi9t*x%EuCK4Ju&}VPv9YqUva_?Zw6wIfwY9dkwzs#p zxVX5vxw*Q!y1To(yu7@dCU$jHda z$;ryf%FD~k%*@Qq&CSlv&d<-!(9qD)(b3Y<($mw^)YR0~)z#M4*4Nk9*x1lt)=I7_<=;-L_>FMg~>g((4 z?Ck9A?d|UF?(gsK@bK{Q@$vHV^7Hfa^z`)g_4W4l_V@Sq`1ttw`T6?#`uqF){QUg= z{r&#_{{R2~EC2ui02lxm000R70RIUbNbsCNg9H;Q6xgd2rBVHES(3_Ku{tyHgqN;d+?Tzju!Z);;TuQDVJwRQAHSkR)YFdrEO!v&XBk zJwOwl{a4GHz*-^KY@Rd5rovJavBo?tB{Lyo6k9@$D)OJx<0pIB#+rEO&f%|l4*kcd o_`qJ2pi}&6ogi$&oxc>r#EMbwId40)HiwBGBuL!a2L=QHJ03R*g8%>k literal 0 HcmV?d00001 diff --git a/doc/figures/warning.gif b/doc/figures/warning.gif new file mode 100644 index 0000000000000000000000000000000000000000..9c1104c2b15445dd0824fd6515659ee0fe18bfd9 GIT binary patch literal 1052 zcmeHG&1=(e0DVo%7HbcgOo>=$KTg3N?8@v)L4uu*Wm2|w7mJ7m-NYeQ<`fNst{-gH zFn0)2C7>b!DFnRyWC)cilI^esda&T7hYgk~Lh8jLf;0XP9`|@W-t9deyphrKLy-&% z79D^F7}yqmfCECnSwH}iKpL00umtG6h$SORMKfh6jeZtMpZ#ji$ztIRaMmh zEfmsZnE-_2h$In3A*xCUsR1=js}Z6DI>YEJtLwS}7z|^utif?jplNHf*#cUvmI;`C zziFBlV9~T?S$5k_r?Us_?PGs||Fl3qZ2bEI=s&nmd)MP#Qi1N-@~vmDl{m)~TAi))WhOkCPn3Z5%1`%*jnZAb7!@1gPPg@=K{SYIGf{obyZgePn&I~mRM zIoCk^vfShUy4LNWnD(!*OLB*2uQN=Ym!3v^_4dl=Pj;;Gz#|UMNR;Eq)oWvScO<97 zyK(r@;K@9Ce=cu6i!Z>P|8001xvKE);`Av#$M(C9mQy#DzRgV?^bGMYDqk{u&KaJ3 zU-1=2b{nx{ugB+K65i`gFp1Iaf%x&j9n1JZecW7F%}mcv#I|oXB2&Z9&%7$#GO4+h QO1&1l=Xra8>T)6W7esUR#{d8T literal 0 HcmV?d00001 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.