summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorcpk <cpk>2001-10-13 00:08:39 +0000
committercpk <cpk@7cbeb6ba-43b4-40fd-8cce-4c39aea84d33>2001-10-13 00:08:39 +0000
commit6c52152328afcfcc324d84af18b509ce4cddf4a9 (patch)
treeeb5af635f8e37ab5dc5d0510a3b89f355cf53bbb
parenta41a7d88753304d4458aeb3d4635e54c5b51703e (diff)
Documentation setup ...
SVN revision: 5479
-rw-r--r--Makefile.am11
-rw-r--r--configure.ac34
-rw-r--r--configure.in27
-rw-r--r--doc/Makefile.am46
-rw-r--r--doc/figures/background.gifbin0 -> 6432 bytes
-rw-r--r--doc/figures/caution.gifbin0 -> 1039 bytes
-rw-r--r--doc/figures/note.gifbin0 -> 1070 bytes
-rw-r--r--doc/figures/warning.gifbin0 -> 1052 bytes
-rw-r--r--doc/html-customizations.dsl.in61
-rw-r--r--doc/kernel-doc.in1001
-rw-r--r--doc/manual.raw283
-rw-r--r--doc/stylesheet.css20
-rw-r--r--po/ChangeLog39
13 files changed, 1517 insertions, 5 deletions
diff --git a/Makefile.am b/Makefile.am
index 99b335ddc..f08166129 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,6 +1,6 @@
1## Process this file with automake to produce Makefile.in 1## Process this file with automake to produce Makefile.in
2 2
3SUBDIRS = intl po src lib client 3SUBDIRS = intl po src lib client doc
4 4
5MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.guess \ 5MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.guess \
6 config.h.in config.sub configure install-sh \ 6 config.h.in config.sub configure install-sh \
@@ -20,3 +20,12 @@ dist-hook:
20 fi 20 fi
21 21
22EXTRA_DIST = README AUTHORS COPYING e.spec 22EXTRA_DIST = README AUTHORS COPYING e.spec
23
24docs:
25 $(MAKE) -C $(top_srcdir)/doc docs
26
27if HAVE_JADE
28html-docs:
29 $(MAKE) -C $(top_srcdir)/doc html-docs
30endif
31
diff --git a/configure.ac b/configure.ac
index f1bf6d4c3..5c0080156 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,6 +1,7 @@
1dnl Process this file with autoconf to produce a configure script. 1dnl Process this file with autoconf to produce a configure script.
2 2
3AC_INIT(configure.in) 3AC_INIT
4AC_CONFIG_SRCDIR([configure.in])
4 5
5ENLIGHTENMENT_MAJOR=0 6ENLIGHTENMENT_MAJOR=0
6ENLIGHTENMENT_MINOR=17 7ENLIGHTENMENT_MINOR=17
@@ -230,7 +231,34 @@ AC_MSG_ERROR(Cannot detect db loader: Have you installed imlib2_loaders?)
230], 231],
231AC_MSG_ERROR(Sorry. Enlightenment cannot be cross-compiled.)) 232AC_MSG_ERROR(Sorry. Enlightenment cannot be cross-compiled.))
232 233
233AC_OUTPUT([ 234
234Makefile src/Makefile lib/Makefile client/Makefile intl/Makefile po/Makefile.in 235dnl Checking for Perl:
236AC_PATH_PROG(PERL,perl,0)
237AC_SUBST(PERL)
238
239
240dnl Look for jade for sgml translations.
241AC_ARG_WITH(dbsheets,
242 [ --with-dbsheets=DIR use DIR to specify your DocBook stylesheets installation path.],
243 DB_STYLESHEETS="$withval", DB_STYLESHEETS="/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh")
244AC_SUBST(DB_STYLESHEETS)
245AC_PATH_PROG(JADE, jade)
246AM_CONDITIONAL(HAVE_JADE, test "x$JADE" != "x" && test -d "$DB_STYLESHEETS")
247
248
249AC_CONFIG_FILES([
250Makefile
251src/Makefile
252lib/Makefile
253client/Makefile
254intl/Makefile
255po/Makefile.in
256doc/Makefile
257doc/kernel-doc
258doc/html-customizations.dsl
235]) 259])
260AC_CONFIG_COMMANDS([default],[[
261chmod +x doc/kernel-doc
262]],[[]])
263AC_OUTPUT
236 264
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?)
230], 230],
231AC_MSG_ERROR(Sorry. Enlightenment cannot be cross-compiled.)) 231AC_MSG_ERROR(Sorry. Enlightenment cannot be cross-compiled.))
232 232
233
234dnl Checking for Perl:
235AC_PATH_PROG(PERL,perl,0)
236AC_SUBST(PERL)
237
238
239dnl Look for jade for sgml translations.
240AC_ARG_WITH(dbsheets,
241 [ --with-dbsheets=DIR use DIR to specify your DocBook stylesheets installation path.],
242 DB_STYLESHEETS="$withval", DB_STYLESHEETS="/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh")
243AC_SUBST(DB_STYLESHEETS)
244AC_PATH_PROG(JADE, jade)
245AM_CONDITIONAL(HAVE_JADE, test "x$JADE" != "x" && test -d "$DB_STYLESHEETS")
246
247
233AC_OUTPUT([ 248AC_OUTPUT([
234Makefile src/Makefile lib/Makefile client/Makefile intl/Makefile po/Makefile.in 249Makefile
250src/Makefile
251lib/Makefile
252client/Makefile
253intl/Makefile
254po/Makefile.in
255doc/Makefile
256doc/kernel-doc
257doc/html-customizations.dsl
258], [
259chmod +x doc/kernel-doc
235]) 260])
236 261
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 @@
1## Process this file with automake to produce Makefile.in
2
3MAINTAINERCLEANFILES = Makefile.in
4
5EXTRA_DIST = \
6manual.raw \
7kernel-doc.in \
8stylesheet.css \
9figures/*.gif # Add any images you create here
10
11
12## Fill in all source files that you documented
13## with extractable comments here:
14##
15SOURCEDOC = $(top_srcdir)/src/e.h
16
17## For details on what can be specified in the
18## comments, see the beginning of kernel-doc
19## in this directory! -- cK.
20
21
22SGMLFILE = $(PACKAGE)-manual.sgml
23
24docs: manual.raw $(SOURCEDOC)
25 ./kernel-doc -docbook <manual.raw >$(SGMLFILE)
26
27if HAVE_JADE
28
29FULLNAME = $(PACKAGE)-manual-$(VERSION)
30
31html-docs: docs html-customizations.dsl
32 $(mkinstalldirs) ./$(FULLNAME)/figures
33 cd $(FULLNAME) && @JADE@ -t sgml -d ../html-customizations.dsl ../$(SGMLFILE)
34 - cd figures && cp -f *.gif ../$(FULLNAME)/figures
35 - cd figures && cp -f *.png ../$(FULLNAME)/figures
36 - cd figures && cp -f *.jpg ../$(FULLNAME)/figures
37 cp -f stylesheet.css $(FULLNAME)/stylesheet.css
38 tar cfvz $(FULLNAME).tar.gz $(FULLNAME)
39
40html-filetypes: filetypes.xsl
41 $(mkinstalldirs) ./$(FULLNAME)/filetypes
42 cp -fr filetypes-templates/* ./$(FULLNAME)/filetypes
43 ./generate-trees.sh ./$(FULLNAME)/filetypes
44
45endif
46
diff --git a/doc/figures/background.gif b/doc/figures/background.gif
new file mode 100644
index 000000000..1dc11ce83
--- /dev/null
+++ b/doc/figures/background.gif
Binary files differ
diff --git a/doc/figures/caution.gif b/doc/figures/caution.gif
new file mode 100644
index 000000000..542232911
--- /dev/null
+++ b/doc/figures/caution.gif
Binary files differ
diff --git a/doc/figures/note.gif b/doc/figures/note.gif
new file mode 100644
index 000000000..45fe08649
--- /dev/null
+++ b/doc/figures/note.gif
Binary files differ
diff --git a/doc/figures/warning.gif b/doc/figures/warning.gif
new file mode 100644
index 000000000..9c1104c2b
--- /dev/null
+++ b/doc/figures/warning.gif
Binary files 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 @@
1<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
2<!ENTITY dbstyle SYSTEM "@DB_STYLESHEETS@/html/docbook.dsl" CDATA DSSSL>
3]>
4
5<style-sheet>
6<style-specification use="docbook">
7<style-specification-body>
8
9;; my own customizations for HTML output:
10
11(define %admon-graphics-path%
12 ;; Path to admonition graphics
13 "figures/")
14
15(define %admon-graphics%
16 ;; Use graphics in admonitions?
17 #t)
18
19(define %indent-programlisting-lines%
20 ;; Indent lines in a 'ProgramListing'?
21 " ")
22
23(define %shade-verbatim%
24 ;; Should verbatim environments be shaded?
25 #t)
26
27(define ($shade-verbatim-attr$)
28 ;; Attributes used to create a shaded verbatim environment.
29 (list
30 (list "BORDER" "0")
31 (list "BGCOLOR" "#f0f0f0")))
32
33(define %root-filename%
34 ;; Name for the root HTML document
35 "index")
36
37(define %body-attr%
38 ;; What attributes should be hung off of BODY?
39 (list
40 (list "BGCOLOR" "#FFFFFF")
41 (list "TEXT" "#0000A0")
42 (list "LINK" "#2020D0")
43 (list "VLINK" "#000060")
44 (list "ALINK" "#5050F0")))
45
46(define %css-decoration%
47 ;; Enable CSS decoration of elements
48 #t)
49
50(define %stylesheet%
51 ;; Name of the stylesheet to use
52 "stylesheet.css")
53
54(define biblio-number
55 ;; Enumerate bibliography entries
56 #t)
57
58</style-specification-body>
59</style-specification>
60<external-specification id="docbook" document="dbstyle">
61</style-sheet>
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 @@
1#!@PERL@
2
3## This script is based on the script shipped with ##
4## 2.4 Linux kernel sources. All copyright notices etc ##
5## remain unchanged. --cK. ##
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000 Tim Waugh <twaugh@redhat.com> ##
9## ##
10## #define enhancements by Armin Kuster <akuster@mvista.com> ##
11## Copyright (c) 2000 MontaVista Software, Inc. ##
12## ##
13## This software falls under the GNU General Public License. ##
14## Please read the COPYING file for more information ##
15
16# w.o. 03-11-2000: added the '-filelist' option.
17
18#
19# This will read a 'c' file and scan for embedded comments in the
20# style of gnome comments (+minor extensions - see below).
21#
22
23# Note: This only supports 'c'.
24
25# usage:
26# kerneldoc [ -docbook | -html | -text | -man ]
27# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
28# or
29# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
30#
31# Set output format using one of -docbook -html -text or -man. Default is man.
32#
33# -function funcname
34# If set, then only generate documentation for the given function(s). All
35# other functions are ignored.
36#
37# -nofunction funcname
38# If set, then only generate documentation for the other function(s). All
39# other functions are ignored. Cannot be used with -function together
40# (yes thats a bug - perl hackers can fix it 8))
41#
42# c files - list of 'c' files to process
43#
44# All output goes to stdout, with errors to stderr.
45
46#
47# format of comments.
48# In the following table, (...)? signifies optional structure.
49# (...)* signifies 0 or more structure elements
50# /**
51# * function_name(:)? (- short description)?
52# (* @parameterx: (description of parameter x)?)*
53# (* a blank line)?
54# * (Description:)? (Description of function)?
55# * (section header: (section description)? )*
56# (*)?*/
57#
58# So .. the trivial example would be:
59#
60# /**
61# * my_function
62# **/
63#
64# If the Description: header tag is ommitted, then there must be a blank line
65# after the last parameter specification.
66# e.g.
67# /**
68# * my_function - does my stuff
69# * @my_arg: its mine damnit
70# *
71# * Does my stuff explained.
72# */
73#
74# or, could also use:
75# /**
76# * my_function - does my stuff
77# * @my_arg: its mine damnit
78# * Description: Does my stuff explained.
79# */
80# etc.
81#
82# All descriptions can be multiline, apart from the short function description.
83#
84# All descriptive text is further processed, scanning for the following special
85# patterns, which are highlighted appropriately.
86#
87# 'funcname()' - function
88# '$ENVVAR' - environmental variable
89# '&struct_name' - name of a structure (up to two words including 'struct')
90# '@parameter' - name of a parameter
91# '%CONST' - name of a constant.
92
93# match expressions used to find embedded type information
94$type_constant = "\\\%([-_\\w]+)";
95$type_func = "(\\w+)\\(\\)";
96$type_param = "\\\@(\\w+)";
97$type_struct = "\\\&((struct\\s*)?[_\\w]+)";
98$type_env = "(\\\$\\w+)";
99
100
101# Output conversion substitutions.
102# One for each output format
103
104# these work fairly well
105%highlights_html = ( $type_constant, "<i>\$1</i>",
106 $type_func, "<b>\$1</b>",
107 $type_struct, "<i>\$1</i>",
108 $type_param, "<tt><b>\$1</b></tt>" );
109$blankline_html = "<p>";
110
111# sgml, docbook format
112%highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
113 $type_constant, "<constant>\$1</constant>",
114 $type_func, "<function>\$1</function>",
115 $type_struct, "<structname>\$1</structname>",
116 $type_env, "<envar>\$1</envar>",
117 $type_param, "<parameter>\$1</parameter>" );
118$blankline_sgml = "</para><para>\n";
119
120# gnome, docbook format
121%highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
122 $type_func, "<function>\$1</function>",
123 $type_struct, "<structname>\$1</structname>",
124 $type_env, "<envar>\$1</envar>",
125 $type_param, "<parameter>\$1</parameter>" );
126$blankline_gnome = "</para><para>\n";
127
128# these are pretty rough
129%highlights_man = ( $type_constant, "\$1",
130 $type_func, "\\\\fB\$1\\\\fP",
131 $type_struct, "\\\\fI\$1\\\\fP",
132 $type_param, "\\\\fI\$1\\\\fP" );
133$blankline_man = "";
134
135# text-mode
136%highlights_text = ( $type_constant, "\$1",
137 $type_func, "\$1",
138 $type_struct, "\$1",
139 $type_param, "\$1" );
140$blankline_text = "";
141
142
143sub usage {
144 print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
145 print " [ -function funcname [ -function funcname ...] ]\n";
146 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
147 print " < inputfile > outputfile\n";
148 exit 1;
149}
150
151# read arguments
152if ($#ARGV==-1) {
153 usage();
154}
155
156$verbose = 0;
157$output_mode = "man";
158%highlights = %highlights_man;
159$blankline = $blankline_man;
160$modulename = "API Documentation";
161$function_only = 0;
162$filelist = '';
163
164while ($ARGV[0] =~ m/^-(.*)/) {
165 $cmd = shift @ARGV;
166 if ($cmd eq "-html") {
167 $output_mode = "html";
168 %highlights = %highlights_html;
169 $blankline = $blankline_html;
170 } elsif ($cmd eq "-man") {
171 $output_mode = "man";
172 %highlights = %highlights_man;
173 $blankline = $blankline_man;
174 } elsif ($cmd eq "-text") {
175 $output_mode = "text";
176 %highlights = %highlights_text;
177 $blankline = $blankline_text;
178 } elsif ($cmd eq "-docbook") {
179 $output_mode = "sgml";
180 %highlights = %highlights_sgml;
181 $blankline = $blankline_sgml;
182 } elsif ($cmd eq "-gnome") {
183 $output_mode = "gnome";
184 %highlights = %highlights_gnome;
185 $blankline = $blankline_gnome;
186 } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
187 $modulename = shift @ARGV;
188 } elsif ($cmd eq "-function") { # to only output specific functions
189 $function_only = 1;
190 $function = shift @ARGV;
191 $function_table{$function} = 1;
192 } elsif ($cmd eq "-nofunction") { # to only output specific functions
193 $function_only = 2;
194 $function = shift @ARGV;
195 $function_table{$function} = 1;
196 } elsif ($cmd eq "-v") {
197 $verbose = 1;
198 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
199 usage();
200 }
201}
202
203
204# generate a sequence of code that will splice in highlighting information
205# using the s// operator.
206$dohighlight = "";
207foreach $pattern (keys %highlights) {
208# print "scanning pattern $pattern ($highlights{$pattern})\n";
209 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
210}
211
212##
213# dumps section contents to arrays/hashes intended for that purpose.
214#
215sub dump_section {
216 my $name = shift @_;
217 my $contents = join "\n", @_;
218
219 if ($name =~ m/$type_constant/) {
220 $name = $1;
221# print STDERR "constant section '$1' = '$contents'\n";
222 $constants{$name} = $contents;
223 } elsif ($name =~ m/$type_param/) {
224# print STDERR "parameter def '$1' = '$contents'\n";
225 $name = $1;
226 $parameters{$name} = $contents;
227 } else {
228# print STDERR "other section '$name' = '$contents'\n";
229 $sections{$name} = $contents;
230 push @sectionlist, $name;
231 }
232}
233
234##
235# output function
236#
237# parameters, a hash.
238# function => "function name"
239# parameterlist => @list of parameters
240# parameters => %parameter descriptions
241# sectionlist => @list of sections
242# sections => %descriont descriptions
243#
244
245sub output_highlight {
246 my $contents = join "\n", @_;
247 my $line;
248
249 eval $dohighlight;
250 foreach $line (split "\n", $contents) {
251 if ($line eq ""){
252 print $lineprefix, $blankline;
253 } else {
254 $line =~ s/\\\\\\/\&/g;
255 print $lineprefix, $line;
256 }
257 print "\n";
258 }
259}
260
261
262# output in html
263sub output_html {
264 my %args = %{$_[0]};
265 my ($parameter, $section);
266 my $count;
267 print "<h2>Function</h2>\n";
268
269 print "<i>".$args{'functiontype'}."</i>\n";
270 print "<b>".$args{'function'}."</b>\n";
271 print "(";
272 $count = 0;
273 foreach $parameter (@{$args{'parameterlist'}}) {
274 $type = $args{'parametertypes'}{$parameter};
275 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
276 # pointer-to-function
277 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
278 } else {
279 print "<i>".$type."</i> <b>".$parameter."</b>";
280 }
281 if ($count != $#{$args{'parameterlist'}}) {
282 $count++;
283 print ",\n";
284 }
285 }
286 print ")\n";
287
288 print "<h3>Arguments</h3>\n";
289 print "<dl>\n";
290 foreach $parameter (@{$args{'parameterlist'}}) {
291 print "<dt><b>".$parameter."</b>\n";
292 print "<dd>";
293 output_highlight($args{'parameters'}{$parameter});
294 }
295 print "</dl>\n";
296 foreach $section (@{$args{'sectionlist'}}) {
297 print "<h3>$section</h3>\n";
298 print "<blockquote>\n";
299 output_highlight($args{'sections'}{$section});
300 print "</blockquote>\n";
301 }
302 print "<hr>\n";
303}
304
305
306# output in html
307sub output_intro_html {
308 my %args = %{$_[0]};
309 my ($parameter, $section);
310 my $count;
311
312 foreach $section (@{$args{'sectionlist'}}) {
313 print "<h3>$section</h3>\n";
314 print "<ul>\n";
315 output_highlight($args{'sections'}{$section});
316 print "</ul>\n";
317 }
318 print "<hr>\n";
319}
320
321
322
323# output in sgml DocBook
324sub output_sgml {
325 my %args = %{$_[0]};
326 my ($parameter, $section);
327 my $count;
328 my $id;
329
330 $id = "API-".$args{'function'};
331 $id =~ s/[^A-Za-z0-9]/-/g;
332
333 print "<refentry>\n";
334 print "<refmeta>\n";
335 print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
336 print "</refmeta>\n";
337 print "<refnamediv>\n";
338 print " <refname>".$args{'function'}."</refname>\n";
339 print " <refpurpose>\n";
340 print " ";
341 output_highlight ($args{'purpose'});
342 print " </refpurpose>\n";
343 print "</refnamediv>\n";
344
345 print "<refsynopsisdiv>\n";
346 print " <title>Synopsis</title>\n";
347 print " <funcsynopsis>\n";
348 print " <funcdef>".$args{'functiontype'}." ";
349 print "<function>".$args{'function'}." ";
350 print "</function></funcdef>\n";
351
352# print "<refsect1>\n";
353# print " <title>Synopsis</title>\n";
354# print " <funcsynopsis>\n";
355# print " <funcdef>".$args{'functiontype'}." ";
356# print "<function>".$args{'function'}." ";
357# print "</function></funcdef>\n";
358
359 $count = 0;
360 if ($#{$args{'parameterlist'}} >= 0) {
361 foreach $parameter (@{$args{'parameterlist'}}) {
362 $type = $args{'parametertypes'}{$parameter};
363 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
364 # pointer-to-function
365 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
366 print " <funcparams>$2</funcparams></paramdef>\n";
367 } else {
368 print " <paramdef>".$type;
369 print " <parameter>$parameter</parameter></paramdef>\n";
370 }
371 }
372 } else {
373 print " <void>\n";
374 }
375 print " </funcsynopsis>\n";
376 print "</refsynopsisdiv>\n";
377# print "</refsect1>\n";
378
379 # print parameters
380 print "<refsect1>\n <title>Arguments</title>\n";
381# print "<para>\nArguments\n";
382 if ($#{$args{'parameterlist'}} >= 0) {
383 print " <variablelist>\n";
384 foreach $parameter (@{$args{'parameterlist'}}) {
385 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
386 print " <listitem>\n <para>\n";
387 $lineprefix=" ";
388 output_highlight($args{'parameters'}{$parameter});
389 print " </para>\n </listitem>\n </varlistentry>\n";
390 }
391 print " </variablelist>\n";
392 } else {
393 print " <para>\n None\n </para>\n";
394 }
395 print "</refsect1>\n";
396
397 # print out each section
398 $lineprefix=" ";
399 foreach $section (@{$args{'sectionlist'}}) {
400 print "<refsect1>\n <title>$section</title>\n <para>\n";
401# print "<para>\n$section\n";
402 if ($section =~ m/EXAMPLE/i) {
403 print "<example><para>\n";
404 }
405 output_highlight($args{'sections'}{$section});
406# print "</para>";
407 if ($section =~ m/EXAMPLE/i) {
408 print "</para></example>\n";
409 }
410 print " </para>\n</refsect1>\n";
411 }
412
413 print "</refentry>\n\n";
414}
415
416# output in sgml DocBook
417sub output_intro_sgml {
418 my %args = %{$_[0]};
419 my ($parameter, $section);
420 my $count;
421 my $id;
422
423 $id = $args{'module'};
424 $id =~ s/[^A-Za-z0-9]/-/g;
425
426 # print out each section
427 $lineprefix=" ";
428 foreach $section (@{$args{'sectionlist'}}) {
429 print "<refsect1>\n <title>$section</title>\n <para>\n";
430# print "<para>\n$section\n";
431 if ($section =~ m/EXAMPLE/i) {
432 print "<example><para>\n";
433 }
434 output_highlight($args{'sections'}{$section});
435# print "</para>";
436 if ($section =~ m/EXAMPLE/i) {
437 print "</para></example>\n";
438 }
439 print " </para>\n</refsect1>\n";
440 }
441
442 print "\n\n";
443}
444
445# output in sgml DocBook
446sub output_gnome {
447 my %args = %{$_[0]};
448 my ($parameter, $section);
449 my $count;
450 my $id;
451
452 $id = $args{'module'}."-".$args{'function'};
453 $id =~ s/[^A-Za-z0-9]/-/g;
454
455 print "<sect2>\n";
456 print " <title id=\"$id\">".$args{'function'}."</title>\n";
457
458# print "<simplesect>\n";
459# print " <title>Synopsis</title>\n";
460 print " <funcsynopsis>\n";
461 print " <funcdef>".$args{'functiontype'}." ";
462 print "<function>".$args{'function'}." ";
463 print "</function></funcdef>\n";
464
465 $count = 0;
466 if ($#{$args{'parameterlist'}} >= 0) {
467 foreach $parameter (@{$args{'parameterlist'}}) {
468 $type = $args{'parametertypes'}{$parameter};
469 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
470 # pointer-to-function
471 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
472 print " <funcparams>$2</funcparams></paramdef>\n";
473 } else {
474 print " <paramdef>".$type;
475 print " <parameter>$parameter</parameter></paramdef>\n";
476 }
477 }
478 } else {
479 print " <void>\n";
480 }
481 print " </funcsynopsis>\n";
482# print "</simplesect>\n";
483# print "</refsect1>\n";
484
485 # print parameters
486# print "<simplesect>\n <title>Arguments</title>\n";
487# if ($#{$args{'parameterlist'}} >= 0) {
488# print " <variablelist>\n";
489# foreach $parameter (@{$args{'parameterlist'}}) {
490# print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
491# print " <listitem>\n <para>\n";
492# $lineprefix=" ";
493# output_highlight($args{'parameters'}{$parameter});
494# print " </para>\n </listitem>\n </varlistentry>\n";
495# }
496# print " </variablelist>\n";
497# } else {
498# print " <para>\n None\n </para>\n";
499# }
500# print "</simplesect>\n";
501
502# print "<simplesect>\n <title>Arguments</title>\n";
503 if ($#{$args{'parameterlist'}} >= 0) {
504 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
505 print "<tgroup cols=\"2\">\n";
506 print "<colspec colwidth=\"2*\">\n";
507 print "<colspec colwidth=\"8*\">\n";
508 print "<tbody>\n";
509 foreach $parameter (@{$args{'parameterlist'}}) {
510 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
511 print " <entry>\n";
512 $lineprefix=" ";
513 output_highlight($args{'parameters'}{$parameter});
514 print " </entry></row>\n";
515 }
516 print " </tbody></tgroup></informaltable>\n";
517 } else {
518 print " <para>\n None\n </para>\n";
519 }
520# print "</simplesect>\n";
521
522 # print out each section
523 $lineprefix=" ";
524 foreach $section (@{$args{'sectionlist'}}) {
525 print "<simplesect>\n <title>$section</title>\n";
526# print "<para>\n$section\n";
527 if ($section =~ m/EXAMPLE/i) {
528 print "<example><programlisting>\n";
529 } else {
530 }
531 print "<para>\n";
532 output_highlight($args{'sections'}{$section});
533# print "</para>";
534 print "</para>\n";
535 if ($section =~ m/EXAMPLE/i) {
536 print "</programlisting></example>\n";
537 } else {
538 }
539 print " </simplesect>\n";
540 }
541
542 print "</sect2>\n\n";
543}
544
545##
546# output in man
547sub output_man {
548 my %args = %{$_[0]};
549 my ($parameter, $section);
550 my $count;
551
552 print ".TH \"$args{'module'}\" 4 \"$args{'function'}\" \"25 May 1998\" \"API Manual\" LINUX\n";
553
554 print ".SH NAME\n";
555 print $args{'function'}." \\- ".$args{'purpose'}."\n";
556
557 print ".SH SYNOPSIS\n";
558 print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
559 $count = 0;
560 $parenth = "(";
561 $post = ",";
562 foreach $parameter (@{$args{'parameterlist'}}) {
563 if ($count == $#{$args{'parameterlist'}}) {
564 $post = ");";
565 }
566 $type = $args{'parametertypes'}{$parameter};
567 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
568 # pointer-to-function
569 print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
570 } else {
571 $type =~ s/([^\*])$/\1 /;
572 print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
573 }
574 $count++;
575 $parenth = "";
576 }
577
578 print ".SH Arguments\n";
579 foreach $parameter (@{$args{'parameterlist'}}) {
580 print ".IP \"".$parameter."\" 12\n";
581 output_highlight($args{'parameters'}{$parameter});
582 }
583 foreach $section (@{$args{'sectionlist'}}) {
584 print ".SH \"$section\"\n";
585 output_highlight($args{'sections'}{$section});
586 }
587}
588
589sub output_intro_man {
590 my %args = %{$_[0]};
591 my ($parameter, $section);
592 my $count;
593
594 print ".TH \"$args{'module'}\" 4 \"$args{'module'}\" \"25 May 1998\" \"API Manual\" LINUX\n";
595
596 foreach $section (@{$args{'sectionlist'}}) {
597 print ".SH \"$section\"\n";
598 output_highlight($args{'sections'}{$section});
599 }
600}
601
602##
603# output in text
604sub output_text {
605 my %args = %{$_[0]};
606 my ($parameter, $section);
607
608 print "Function:\n\n";
609 $start=$args{'functiontype'}." ".$args{'function'}." (";
610 print $start;
611 $count = 0;
612 foreach $parameter (@{$args{'parameterlist'}}) {
613 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
614 # pointer-to-function
615 print $1.$parameter.") (".$2;
616 } else {
617 print $type." ".$parameter;
618 }
619 if ($count != $#{$args{'parameterlist'}}) {
620 $count++;
621 print ",\n";
622 print " " x length($start);
623 } else {
624 print ");\n\n";
625 }
626 }
627
628 print "Arguments:\n\n";
629 foreach $parameter (@{$args{'parameterlist'}}) {
630 print $parameter."\n\t".$args{'parameters'}{$parameter}."\n";
631 }
632 foreach $section (@{$args{'sectionlist'}}) {
633 print "$section:\n\n";
634 output_highlight($args{'sections'}{$section});
635 }
636 print "\n\n";
637}
638
639sub output_intro_text {
640 my %args = %{$_[0]};
641 my ($parameter, $section);
642
643 foreach $section (@{$args{'sectionlist'}}) {
644 print " $section:\n";
645 print " -> ";
646 output_highlight($args{'sections'}{$section});
647 }
648}
649
650##
651# generic output function - calls the right one based
652# on current output mode.
653sub output_function {
654# output_html(@_);
655 eval "output_".$output_mode."(\@_);";
656}
657
658##
659# generic output function - calls the right one based
660# on current output mode.
661sub output_intro {
662# output_html(@_);
663 eval "output_intro_".$output_mode."(\@_);";
664}
665
666
667##
668# takes a function prototype and spits out all the details
669# stored in the global arrays/hashes.
670sub dump_function {
671 my $prototype = shift @_;
672
673 $prototype =~ s/^static +//;
674 $prototype =~ s/^extern +//;
675 $prototype =~ s/^inline +//;
676 $prototype =~ s/^__inline__ +//;
677 $prototype =~ s/^#define +//; #ak added
678
679 # Yes, this truly is vile. We are looking for:
680 # 1. Return type (may be nothing if we're looking at a macro)
681 # 2. Function name
682 # 3. Function parameters.
683 #
684 # All the while we have to watch out for function pointer parameters
685 # (which IIRC is what the two sections are for), C types (these
686 # regexps don't even start to express all the possibilities), and
687 # so on.
688 #
689 # If you mess with these regexps, it's a good idea to check that
690 # the following functions' documentation still comes out right:
691 # - parport_register_device (function pointer parameters)
692 # - atomic_set (macro)
693 # - pci_match_device (long return type)
694
695 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
696 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
697 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
698 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
699 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
700 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
701 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
702 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
703 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
704 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
705 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
706 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
707 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
708 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
709 $return_type = $1;
710 $function_name = $2;
711 $args = $3;
712
713 # allow for up to fours args to function pointers
714 $args =~ s/(\([^\),]+),/\1#/g;
715 $args =~ s/(\([^\),]+),/\1#/g;
716 $args =~ s/(\([^\),]+),/\1#/g;
717# print STDERR "ARGS = '$args'\n";
718
719 foreach $arg (split ',', $args) {
720 # strip leading/trailing spaces
721 $arg =~ s/^\s*//;
722 $arg =~ s/\s*$//;
723
724 if ($arg =~ m/\(/) {
725 # pointer-to-function
726 $arg =~ tr/#/,/;
727 $arg =~ m/[^\(]+\(\*([^\)]+)\)/;
728 $param = $1;
729 $type = $arg;
730 $type =~ s/([^\(]+\(\*)$param/\1/;
731 } else {
732 # evil magic to get fixed array parameters to work
733 $arg =~ s/(.+\s+)(.+)\[.*/\1* \2/;
734# print STDERR "SCAN ARG: '$arg'\n";
735 @args = split('\s', $arg);
736
737# print STDERR " -> @args\n";
738 $param = pop @args;
739# print STDERR " -> @args\n";
740 if ($param =~ m/^(\*+)(.*)/) {
741 $param = $2;
742 push @args, $1;
743 }
744 $type = join " ", @args;
745 }
746
747 if ($type eq "" && $param eq "...")
748 {
749 $type="...";
750 $param="...";
751 $parameters{"..."} = "variable arguments";
752 }
753 elsif ($type eq "" && $param eq "")
754 {
755 $type="";
756 $param="void";
757 $parameters{void} = "no arguments";
758 }
759 if ($type ne "" && $parameters{$param} eq "") {
760 $parameters{$param} = "-- undescribed --";
761 print STDERR "Warning($file:$lineno): Function parameter '$param' not described in '$function_name'\n";
762 }
763
764 push @parameterlist, $param;
765 $parametertypes{$param} = $type;
766# print STDERR "param = '$param', type = '$type'\n";
767 }
768 } else {
769 print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n";
770 return;
771 }
772
773 if ($function_only==0 ||
774 ( $function_only == 1 && defined($function_table{$function_name})) ||
775 ( $function_only == 2 && !defined($function_table{$function_name})))
776 {
777 output_function({'function' => $function_name,
778 'module' => $modulename,
779 'functiontype' => $return_type,
780 'parameterlist' => \@parameterlist,
781 'parameters' => \%parameters,
782 'parametertypes' => \%parametertypes,
783 'sectionlist' => \@sectionlist,
784 'sections' => \%sections,
785 'purpose' => $function_purpose
786 });
787 }
788}
789
790######################################################################
791# main
792# states
793# 0 - normal code
794# 1 - looking for function name
795# 2 - scanning field start.
796# 3 - scanning prototype.
797$state = 0;
798$section = "";
799
800$doc_special = "\@\%\$\&";
801
802$doc_start = "^/\\*\\*\\s*\$";
803$doc_end = "\\*/";
804$doc_com = "\\s*\\*\\s*";
805$doc_func = $doc_com."(\\w+):?";
806$doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)";
807$doc_content = $doc_com."(.*)";
808$doc_block = $doc_com."DOC:\\s*(.*)?";
809
810%constants = ();
811%parameters = ();
812@parameterlist = ();
813%sections = ();
814@sectionlist = ();
815
816$contents = "";
817$section_default = "Description"; # default section
818$section_intro = "Introduction";
819$section = $section_default;
820
821while (<STDIN>)
822 {
823 if (/^!I(.*)/)
824 {
825 process_file("@top_srcdir@" . "/" . $1);
826 }
827 else
828 {
829 print;
830 }
831 }
832
833exit;
834
835sub process_file($) {
836 my ($file) = @_;
837
838 if (!open(IN,"<$file")) {
839 print STDERR "Error: Cannot open file $file\n";
840 return;
841 }
842
843 $lineno = 0;
844 while (<IN>) {
845 $lineno++;
846
847 if ($state == 0) {
848 if (/$doc_start/o) {
849 $state = 1; # next line is always the function name
850 }
851 } elsif ($state == 1) { # this line is the function name (always)
852 if (/$doc_block/o) {
853 $state = 4;
854 $contents = "";
855 if ( $1 eq "" ) {
856 $section = $section_intro;
857 } else {
858 $section = $1;
859 }
860 }
861 elsif (/$doc_func/o) {
862 $function = $1;
863 $state = 2;
864 if (/-(.*)/) {
865 $function_purpose = $1;
866 } else {
867 $function_purpose = "";
868 }
869 if ($verbose) {
870 print STDERR "Info($lineno): Scanning doc for $function\n";
871 }
872 } else {
873 print STDERR "WARN($lineno): Cannot understand $_ on line $lineno",
874 " - I thought it was a doc line\n";
875 $state = 0;
876 }
877 } elsif ($state == 2) { # look for head: lines, and include content
878 if (/$doc_sect/o) {
879 $newsection = $1;
880 $newcontents = $2;
881
882 if ($contents ne "") {
883 $contents =~ s/\&/\\\\\\amp;/g;
884 $contents =~ s/\</\\\\\\lt;/g;
885 $contents =~ s/\>/\\\\\\gt;/g;
886 dump_section($section, $contents);
887 $section = $section_default;
888 }
889
890 $contents = $newcontents;
891 if ($contents ne "") {
892 $contents .= "\n";
893 }
894 $section = $newsection;
895 } elsif (/$doc_end/) {
896
897 if ($contents ne "") {
898 $contents =~ s/\&/\\\\\\amp;/g;
899 $contents =~ s/\</\\\\\\lt;/g;
900 $contents =~ s/\>/\\\\\\gt;/g;
901 dump_section($section, $contents);
902 $section = $section_default;
903 $contents = "";
904 }
905
906# print STDERR "end of doc comment, looking for prototype\n";
907 $prototype = "";
908 $state = 3;
909 } elsif (/$doc_content/) {
910 # miguel-style comment kludge, look for blank lines after
911 # @parameter line to signify start of description
912 if ($1 eq "" && $section =~ m/^@/) {
913 $contents =~ s/\&/\\\\\\amp;/g;
914 $contents =~ s/\</\\\\\\lt;/g;
915 $contents =~ s/\>/\\\\\\gt;/g;
916 dump_section($section, $contents);
917 $section = $section_default;
918 $contents = "";
919 } else {
920 $contents .= $1."\n";
921 }
922 } else {
923 # i dont know - bad line? ignore.
924 print STDERR "WARNING($lineno): bad line: $_";
925 }
926 } elsif ($state == 3) { # scanning for function { (end of prototype)
927 if (m#\s*/\*\s+MACDOC\s*#io) {
928 # do nothing
929 }
930 elsif (/([^\{]*)/) {
931 $prototype .= $1;
932 }
933 if (/\{/ || /\#/ || /;/) { # added for #define AK
934 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
935 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
936 $prototype =~ s@^ +@@gos; # strip leading spaces
937 dump_function($prototype);
938
939 $function = "";
940 %constants = ();
941 %parameters = ();
942 %parametertypes = ();
943 @parameterlist = ();
944 %sections = ();
945 @sectionlist = ();
946 $prototype = "";
947
948 $state = 0;
949 }
950 } elsif ($state == 4) {
951 # Documentation block
952 if (/$doc_block/) {
953 dump_section($section, $contents);
954 output_intro({'sectionlist' => \@sectionlist,
955 'sections' => \%sections });
956 $contents = "";
957 $function = "";
958 %constants = ();
959 %parameters = ();
960 %parametertypes = ();
961 @parameterlist = ();
962 %sections = ();
963 @sectionlist = ();
964 $prototype = "";
965 if ( $1 eq "" ) {
966 $section = $section_intro;
967 } else {
968 $section = $1;
969 }
970 }
971 elsif (/$doc_end/)
972 {
973 dump_section($section, $contents);
974 output_intro({'sectionlist' => \@sectionlist,
975 'sections' => \%sections });
976 $contents = "";
977 $function = "";
978 %constants = ();
979 %parameters = ();
980 %parametertypes = ();
981 @parameterlist = ();
982 %sections = ();
983 @sectionlist = ();
984 $prototype = "";
985 $state = 0;
986 }
987 elsif (/$doc_content/)
988 {
989 if ( $1 eq "" )
990 {
991 $contents .= $blankline;
992 }
993 else
994 {
995 $contents .= $1 . "\n";
996 }
997 }
998 }
999 }
1000}
1001
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 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
2<!ENTITY efsd "<function>efsd</function>">
3]>
4
5
6<book id="efsd-documentation-howto">
7 <bookinfo>
8 <title>EFSD Documentation Howto</title>
9
10 <authorgroup>
11 <author>
12 <firstname>FIRSTNAME</firstname>
13 <othername>OTHER</othername>
14 <surname>LASTNAME</surname>
15 <affiliation>
16 <address>
17 <email>EMAIL</email>
18 </address>
19 </affiliation>
20 </author>
21 </authorgroup>
22
23 <copyright>
24 <year>2001</year>
25 <holder>Christian Kreibich</holder>
26 </copyright>
27
28 <legalnotice>
29 <para>
30 Permission is hereby granted, free of charge, to any person obtaining a copy
31 of this software and associated documentation files (the "Software"), to
32 deal in the Software without restriction, including without limitation the
33 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
34 sell copies of the Software, and to permit persons to whom the Software is
35 furnished to do so, subject to the following conditions:
36 </para>
37 <para>
38 The above copyright notice and this permission notice shall be included in
39 all copies of the Software and its documentation and acknowledgment shall be
40 given in the documentation and software packages that this Software was
41 used.
42 </para>
43 <para>
44 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
45 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
46 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
47 THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
48 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
49 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
50 </para>
51 </legalnotice>
52
53 <releaseinfo>
54 This is document is nowhere near being finished. Be patient.
55 </releaseinfo>
56
57 </bookinfo>
58
59 <toc></toc>
60
61 <chapter id="introduction">
62 <title>Introduction</title>
63 <para>
64 This is some sample documentation for you project. You'll need to be
65 familiar with <ulink url="http://docbook.org">DocBook</ulink>
66 to make best use of Enlightenment's documentation scheme.
67 </para>
68 <para>
69 See <link linkend="files" endterm="files.title"></link>
70 for an explanation of the documentation setup in you project.
71 </para>
72 <para>
73 <link linkend="comments" endterm="comments.title"></link> explains
74 the way you have to structure your comments so that they can be
75 extracted.
76 </para>
77 <para>
78 <link linkend="samples" endterm="samples.title"></link> contains a few
79 layout and markup examples to get you up to speed quickly.
80 </para>
81 </chapter>
82
83 <chapter id="files">
84 <title id="files.title">Documentation File Structure</title>
85 <para>
86 The entire documentation setup lives in the <filename>doc</filename>
87 directory. The file you need to edit is called <filename>manual.raw</filename>.
88 When you enter <command>make docs</command> in the toplevel directory,
89 it gets translated into a standard SGML file using a Perl script.
90 The script scans the file for any lines starting directly with the
91 string <command>!I&lt;filename&gt;</command>. Here,
92 <filename>filename</filename> is the name of a code
93 file in which you have put extractable comments. The Perl script will
94 then analyze the file and generate SGML DocBook statements for those
95 comments right into the output file.
96 </para>
97 <para>
98 The resulting file of that step is called <filename>$PACKAGE-manual-$VERSION.sgml</filename>
99 where PACKAGE and VERSION are automatically set during the build process.
100 This sgml file can be postprocessed with any SGML processor to generate
101 for example HTML, TeX or PDF output.
102 </para>
103 <para>
104 Suppport for HTML generation is included already through the
105 <command>make html-docs</command> target. In order to be able to use
106 that, you'll need to have <command>jade</command> installed, and appropriate
107 DocBook stylesheets. If the <command>configure</command> script doesn't automatically find
108 you stylesheets (on a Debian system it should), you can specify them when
109 calling <command>configure</command> or <command>autogen.sh</command> using
110 the <command>--with-dbsheets=DIR</command> option.
111 </para>
112 <para>
113 If everything worked out fine, you'll get a tarball of the HTML version
114 of your documentation and the extracted version in the docs directory,
115 named similarly to the SGML file.
116 </para>
117
118 </chapter>
119
120 <chapter id="comments">
121 <title id="comments.title">Writing Extractable Comments</title>
122 <para>
123 I'll simply give an example of a commented function here:
124
125 <programlisting>
126
127/**
128 * efsd_wait_event - blocking wait for next Efsd event.
129 * @ec: The Efsd connection
130 * @ev: Pointer to an allocated EfsdEvent.
131 *
132 * Blocks until an efsd event arrives, then returns it by filling
133 * in the @ev structure. Returns -1 when there was an error,
134 * >= 0 otherwise.
135 */
136int efsd_wait_event(EfsdConnection *ec, EfsdEvent *ev);
137 </programlisting>
138 As you can see, it's not hard -- just use two asterisks
139 to signal the start of an extractable comment. In the first
140 line, begin with the function name and a one-liner description.
141 Then, put each parameter in the following lines. Add an empty
142 line, and then a more verbose description. That's basically
143 it, you can also markup items differently as follows:
144
145 <itemizedlist mark="opencircle">
146 <listitem>
147 <para><command>funcname()</command> for function names</para>
148 </listitem>
149 <listitem>
150 <para><command>$ENVVAR</command> for environment variables</para>
151 </listitem>
152 <listitem>
153 <para><command>&amp;struct_name</command> for structures</para>
154 </listitem>
155 <listitem>
156 <para><command>%CONST</command> for constants/para>
157 </listitem>
158 </itemizedlist>
159 </para>
160 </chapter>
161
162 <chapter id="samples">
163 <title id="samples.title">DocBook Examples</title>
164 <section>
165 <title>Lists</title>
166 <para>
167 <itemizedlist mark="opencircle">
168 <listitem>
169 <para>This</para>
170 </listitem>
171 <listitem>
172 <para>is</para>
173 </listitem>
174 <listitem>
175 <para>a</para>
176 </listitem>
177 <listitem>
178 <para>list</para>
179 </listitem>
180 </itemizedlist>
181 </para>
182 </section>
183 <section>
184 <title>Code</title>
185 <para>
186 <programlisting>
187
188EfsdConnection *ec;
189
190if ( (ec = efsd_open()) == NULL)
191 {
192 /* Oops. Couldn't establish connection.
193 * Is Efsd really running ?
194 */
195 }
196
197/* ... various efsd commands ... */
198
199if (efsd_close(ec) < 0)
200 {
201 /* Ouch. Error when closing connection. */
202 }
203 </programlisting>
204 </para>
205 </section>
206 <section>
207 <title>Images</title>
208 <para>
209
210 <mediaobject>
211 <imageobject>
212 <imagedata fileref="figures/sampleimage.eps" format="eps">
213 </imageobject>
214 <imageobject>
215 <imagedata fileref="figures/sampleimage.gif" format="gif">
216 </imageobject>
217 <textobject>
218 <phrase>Sample image</phrase>
219 </textobject>
220 <caption>
221 <para>This is how you display images.</para>
222 </caption>
223 </mediaobject>
224
225 </para>
226 </section>
227 <section>
228 <title>Warnings, Notes</title>
229 <para>
230 <note>
231 <title>This is an example of a note.</title>
232 <para>
233 It's really simple to use.
234 </para>
235 </note
236 </para>
237 <para>
238 <caution>
239 <title>This is a warning.</title>
240 <para>
241 It's used just like a note.
242 </para>
243 </caution>
244 </para>
245 </section>
246 </chapter>
247
248 <bibliography>
249
250 <biblioentry id="bib-unp">
251 <bookbiblio>
252 <author>
253 <firstname>W. R.</firstname>
254 <surname>Stevens</surname>
255 </author>
256 <title>UNIX Network Programming</title>
257 <edition>Second Edition</edition>
258 <volumenum>Volume 1</volumenum>
259 <publisher>
260 <publishername>Prentice-Hall</publishername>
261 </publisher>
262 <date>1998</date>
263 </bookbiblio>
264 </biblioentry>
265
266 <biblioentry id="bib-apue">
267 <bookbiblio>
268 <author>
269 <firstname>W. R.</firstname>
270 <surname>Stevens</surname>
271 </author>
272 <title>Advanced Programming in the UNIX Environment</title>
273 <publisher>
274 <publishername>Addison-Wesley</publishername>
275 </publisher>
276 <date>1992</date>
277 </bookbiblio>
278 </biblioentry>
279
280 </bibliography>
281
282</book>
283
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 @@
1body { margin-left:10px;
2 margin-right:10px;
3 margin-top:10px;
4 margin-bottom:10px;
5 color:#0000a0;
6 font-size:12pt;
7 background-image:url(figures/background.gif);
8 background-repeat:no-repeat;
9 }
10
11th {
12 font-size:14pt;
13 }
14
15td {
16 font-size:12pt;
17 }
18
19div.mediaobject { align:center; }
20div.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 @@
12001-10-13 gettextize <bug-gnu-utils@gnu.org>
2
3 * Makefile.in.in: Upgrade to gettext-0.10.39.
4
52001-10-13 gettextize <bug-gnu-utils@gnu.org>
6
7 * Makefile.in.in: Upgrade to gettext-0.10.39.
8
92001-10-13 gettextize <bug-gnu-utils@gnu.org>
10
11 * Makefile.in.in: Upgrade to gettext-0.10.39.
12
13<<<<<<< ChangeLog
142001-10-08 gettextize <bug-gnu-utils@gnu.org>
15
16 * Makefile.in.in: Upgrade to gettext-0.10.39.
17
182001-10-08 gettextize <bug-gnu-utils@gnu.org>
19
20 * Makefile.in.in: Upgrade to gettext-0.10.39.
21
222001-09-25 gettextize <bug-gnu-utils@gnu.org>
23
24 * Makefile.in.in: Upgrade to gettext-0.10.39.
25
262001-09-25 gettextize <bug-gnu-utils@gnu.org>
27
28 * Makefile.in.in: Upgrade to gettext-0.10.39.
29
302001-09-10 gettextize <bug-gnu-utils@gnu.org>
31
32 * Makefile.in.in: Upgrade to gettext-0.10.39.
33
342001-09-10 gettextize <bug-gnu-utils@gnu.org>
35
36 * Makefile.in.in: Upgrade to gettext-0.10.39.
37
38=======
12001-10-09 gettextize <bug-gnu-utils@gnu.org> 392001-10-09 gettextize <bug-gnu-utils@gnu.org>
2 40
3 * Makefile.in.in: Upgrade to gettext-0.10.40. 41 * Makefile.in.in: Upgrade to gettext-0.10.40.
@@ -6,6 +44,7 @@
6 44
7 * Makefile.in.in: Upgrade to gettext-0.10.40. 45 * Makefile.in.in: Upgrade to gettext-0.10.40.
8 46
47>>>>>>> 1.6
92001-08-31 gettextize <bug-gnu-utils@gnu.org> 482001-08-31 gettextize <bug-gnu-utils@gnu.org>
10 49
11 * Makefile.in.in: Upgrade to gettext-0.10.39. 50 * Makefile.in.in: Upgrade to gettext-0.10.39.