Updated Spanish translation
[gtk-doc.git] / gtkdoc-mktmpl.in
blob72ada86d28ea466101ca003d6ba0aefbd992c60e
1 #!@PERL@ -w
2 # -*- cperl -*-
4 # gtk-doc - GTK DocBook documentation generator.
5 # Copyright (C) 1998  Damon Chaplin
7 # This program is free software; you can redistribute it and/or modify
8 # it under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 2 of the License, or
10 # (at your option) any later version.
12 # This program is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with this program; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 #############################################################################
23 # Script      : gtkdoc-mktmpl
24 # Description : This creates or updates the template files which contain the
25 #                manually-edited documentation. (A 'template' is a simple text
26 #                form which is filled in with the description of a function,
27 #                macro, enum, or struct. For functions and macros it also
28 #                contains fields for describing the parameters.)
30 #                This script reads in the existing templates, found in
31 #                tmpl/*.sgml, moves these files to tmpl/*.sgml.bak, and then
32 #                recreates the .sgml files according to the structure given in
33 #                the file $MODULE-sections.txt.
35 #                Any new templates added, or new function parameters, are
36 #                marked with 'FIXME' so you can do a grep to see which parts
37 #                need updating.
39 #                Any templates which are no longer used (i.e. they are remove
40 #                from $MODULE-sections.txt) are placed in the file
41 #                tmpl/$MODULE-unused.sgml. If they are included again later
42 #                they are automatically copied back into position.
43 #                If you are certain that these templates will never be used
44 #                again you can delete them from tmpl/$MODULE-unused.sgml.
46 #                Any parameters to functions which are no longer used are
47 #                separated from the rest of the parameters with the line
48 #                '<!-- # Unused Parameters # -->'. It may be that the parameter
49 #                name has just been changed, in which case you can copy the
50 #                description to the parameter with the new name. You can delete
51 #                the unused parameter descriptions when no longer needed.
52 #############################################################################
54 use strict;
55 use Getopt::Long;
57 push @INC, '@PACKAGE_DATA_DIR@';
58 require "gtkdoc-common.pl";
60 # Options
62 # name of documentation module
63 my $MODULE;
64 my $TMPL_DIR;
65 my $FLAG_CHANGES;
66 my $PRINT_VERSION;
67 my $PRINT_HELP;
68 my $ONLY_SECTION_TMPL;
70 my %optctl = ('module' => \$MODULE,
71               'flag-changes' => \$FLAG_CHANGES,
72               'output-dir' => \$TMPL_DIR,
73               'only-section-tmpl' => \$ONLY_SECTION_TMPL,
74               'version' => \$PRINT_VERSION,
75               'help' => \$PRINT_HELP);
76 GetOptions(\%optctl, "module=s", "flag-changes!", "output-dir:s", "only-section-tmpl!", "version", "help");
78 if ($PRINT_VERSION) {
79     print "@VERSION@\n";
80     exit 0;
83 if (!$MODULE) {
84     $PRINT_HELP = 1;
87 if ($PRINT_HELP) {
88     print <<EOF;
89 gtkdoc-mktmpl version @VERSION@ - generate documentation templates
91 --module=MODULE_NAME Name of the doc module being parsed
92 --flag-changes       If specified, changes in templates are flagged
93 --output-dir=DIRNAME The directory where the results are stored
94 --only-section-tmpl  Only include section information in templates
95 --version            Print the version of this program
96 --help               Print this help
97 EOF
98     exit 0;
101 my $ROOT_DIR = ".";
103 # The directory containing the template files.
104 $TMPL_DIR = $TMPL_DIR ? $TMPL_DIR : "$ROOT_DIR/tmpl";
106 # This file contains the object hierarchy.
107 my $OBJECT_TREE_FILE = "$ROOT_DIR/$MODULE.hierarchy";
109 # The file containing signal handler prototype information.
110 my $SIGNALS_FILE = "$ROOT_DIR/$MODULE.signals";
112 # The file containing Arg information.
113 my $ARGS_FILE = "$ROOT_DIR/$MODULE.args";
115 # Set the flag to indicate changes, if requested.
116 my $CHANGES_FLAG = $FLAG_CHANGES ? "FIXME" : "";
118 # These global arrays store information on signals. Each signal has an entry
119 # in each of these arrays at the same index, like a multi-dimensional array.
120 my @SignalObjects;        # The GtkObject which emits the signal.
121 my @SignalNames;        # The signal name.
122 my @SignalReturns;        # The return type.
123 my @SignalFlags;        # Flags for the signal
124 my @SignalPrototypes;        # The rest of the prototype of the signal handler.
126 # These global arrays store information on Args. Each Arg has an entry
127 # in each of these arrays at the same index, like a multi-dimensional array.
128 my @ArgObjects;                # The GtkObject which has the Arg.
129 my @ArgNames;                # The Arg name.
130 my @ArgTypes;                # The Arg type - gint, GtkArrowType etc.
131 my @ArgFlags;                # How the Arg can be used - readable/writable etc.
133 # These global hashes store declaration info keyed on a symbol name.
134 my %Declarations;
135 my %DeclarationTypes;
136 my %DeclarationConditional;
137 my %DeclarationOutput;
139 # These global hashes store the existing documentation.
140 my %SymbolDocs;
141 my %SymbolTypes;
142 my %SymbolParams;
143 my %SymbolSourceFile;
144 my %SymbolSourceLine;
146 # These global arrays store GObject and subclasses and the hierarchy.
147 my @Objects;
148 my @ObjectLevels;
150 &ReadSignalsFile ($SIGNALS_FILE);
151 &ReadArgsFile ($ARGS_FILE);
152 &ReadObjectHierarchy;
154 &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-decl.txt", 0);
155 if (-f "$ROOT_DIR/$MODULE-overrides.txt") {
156     &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-overrides.txt", 1);
158 &ReadExistingTemplates;
160 my $changed = 0;
162 if (&UpdateTemplates ("$ROOT_DIR/$MODULE-sections.txt")) {
163   $changed = 1;
165 &OutputUnusedTemplates;
166 if (&CheckAllDeclarationsOutput) {
167   $changed = 1;
170 if ($changed || ! -e "$ROOT_DIR/tmpl.stamp") {
171     open (TIMESTAMP, ">$ROOT_DIR/tmpl.stamp")
172         || die "Can't create $ROOT_DIR/tmpl.stamp";
173     print (TIMESTAMP "timestamp");
174     close (TIMESTAMP);
177 #############################################################################
178 # Function    : ReadExistingTemplates
179 # Description : This reads in all the existing documentation, into the global
180 #                variables %SymbolDocs, %SymbolTypes, and %SymbolParams (a
181 #                hash of arrays).
182 # Arguments   : none
183 #############################################################################
185 sub ReadExistingTemplates {
186     %SymbolDocs = ();
187     %SymbolTypes = ();
188     %SymbolParams = ();
190     # Read the unused docs first, so they get overridden by any real docs.
191     # (though this shouldn't happen often).
192     my $unused_doc = "$TMPL_DIR/$MODULE-unused.sgml";
193     if (-e $unused_doc) {
194         &ReadTemplateFile ($unused_doc, 0);
195     }
197     while (<$TMPL_DIR/*.sgml>) {
198 #        print "Reading $_\n";
199         if ($_ eq $unused_doc) {
200 #            print "skipping $unused_doc\n";
201         } else {
202             &ReadTemplateFile ($_, 0);
203         }
204     }
208 #############################################################################
209 # Function    : UpdateTemplates
210 # Description : This collects the output for each section of the docs, and
211 #                outputs each file when the end of the section is found.
212 # Arguments   : $file - the file containing the sections of the docs.
213 #############################################################################
215 sub UpdateTemplates {
216     my ($file) = @_;
217 #    print "Reading: $file\n";
219     open (INPUT, $file)
220         || die "Can't open $file";
222     # Create the top output directory if it doesn't exist.
223     if (! -e $TMPL_DIR) {
224         mkdir ("$TMPL_DIR", 0777)
225             || die "Can't create directory: $TMPL_DIR";
226     }
228     my $filename = "";
229     my $title = "";
230     my $subsection = "";
231     my $output;
232     my $changed = 0;
233     while (<INPUT>) {
234         if (m/^#/) {
235             next;
237         } elsif (m/^<SECTION>/) {
238             $output = "";
240         } elsif (m/^<SUBSECTION\s*(.*)>/i) {
241             $subsection = $1;
242             next;
244         } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
245             $title = $1;
246 #            print "Section: $title\n";
248         } elsif (m/^<FILE>(.*)<\/FILE>/) {
249             $filename = $1;
251         } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
252             next;
254         } elsif (m/^<\/SECTION>/) {
255             if ($title eq "") {
256                 $title = $filename;
257             }
258 #            print "End of section: $title\n";
260             $filename =~ s/\s/_/g;
261             $filename .= ".sgml";
263             if (&OutputTemplateFile ($filename, $title, \$output)) {
264               $changed = 1;
265             }
267             $title = "";
268             $subsection = "";
270         } elsif (m/^(\S+)/) {
271             my $symbol = $1;
272 #            print "  Symbol: $symbol\n";
274             my $declaration = $Declarations{$1};
275             if (defined ($declaration)) {
276                 # We don't want templates for standard macros/functions of
277                 # GObjects or private declarations.
278                 if ($subsection ne "Standard" && $subsection ne "Private") {
279                     $output .= &OutputDeclaration ($DeclarationTypes {$symbol},
280                                                    $symbol, $declaration);
282                     $output .= &OutputSignalTemplates ($symbol);
283                     $output .= &OutputArgTemplates ($symbol);
284                 }
286                 # Note that the declaration has been output.
287                 $DeclarationOutput{$symbol} = 1;
289                 if ($declaration eq '##conditional##') {
290 #                    print "Conditional $DeclarationTypes{$symbol}\n";
291                 }
293             } else {
294                 &LogWarning ($file, $., "No declaration found for: $1");
295             }
296         }
297     }
298     close (INPUT);
300     return $changed;
304 #############################################################################
305 # Function    : CheckAllDeclarationsOutput
306 # Description : This steps through all the declarations that were loaded, and
307 #                makes sure that each one has been output, by checking the
308 #                corresponding flag in the %DeclarationOutput hash. It is
309 #                intended to check that any new declarations in new versions
310 #                of the module get added to the $MODULE-sections.txt file.
311 # Arguments   : none
312 #############################################################################
314 sub CheckAllDeclarationsOutput {
315     my $num_unused = 0;
317     my $old_unused_file = "$ROOT_DIR/$MODULE-unused.txt";
318     my $new_unused_file = "$ROOT_DIR/$MODULE-unused.new";
320     open (UNUSED, ">$new_unused_file")
321         || die "Can't open $new_unused_file";
322     my ($symbol);
323     foreach $symbol (sort keys (%Declarations)) {
324         if (!defined ($DeclarationOutput{$symbol})) {
325             print (UNUSED "$symbol\n");
326             $num_unused++;
327         }
328     }
329     close (UNUSED);
330     if ($num_unused != 0) {
331         &LogWarning ($old_unused_file, 1, "$num_unused unused declarations.".
332             "They should be added to $MODULE-sections.txt in the appropriate place.");
333     }
335     return &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 0);
339 #############################################################################
340 # Function    : OutputDeclaration
341 # Description : This returns the template for one symbol & declaration.
342 #                Note that it uses the global %SymbolDocs and %SymbolParams to
343 #                lookup any existing documentation.
344 # Arguments   : $type - the type of the symbol ('FUNCTION'/'MACRO' etc.)
345 #                $symbol - the symbol name.
346 #                $declaration - the declaration of the symbol.
347 #############################################################################
349 sub OutputDeclaration {
350     my ($type, $symbol, $declaration) = @_;
351     my ($output) = "";
353     #print "Outputting $type: $symbol\n";
355     # See if symbol already has a description.
356     my ($symbol_desc) = $SymbolDocs{$symbol};
357     my ($template_exists);
358     if (defined ($symbol_desc)) {
359         $template_exists = 1;
360         $symbol_desc =~ s/\s+$//;
361     } else {
362         $template_exists = 0;
363         $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>";
364     }
366     $output .= <<EOF;
367 <!-- ##### $type $symbol ##### -->
368 $symbol_desc
372     # For functions, function typedefs and macros, we output the arguments.
373     # For functions and function typedefs we also output the return value.
374     if ($type eq "FUNCTION" || $type eq "USER_FUNCTION") {
375         # Take out the return type
376         $declaration =~ s/<RETURNS>\s*(.*?)<\/RETURNS>\n//;
377         my $ret_type_decl = $1;
378         my $ret_type_modifier;
379         my $ret_type;
380         my $ret_type_pointer;
382         if ($ret_type_decl =~ m/((const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+|struct\s+|enum\s+)*)(\w+)\s*(\**\s*(const|G_CONST_RETURN)?\s*\**\s*(restrict)?\s*)/) {
383             $ret_type_modifier = defined($1) ? $1 : "";
384             $ret_type = $3;
385             $ret_type_pointer = $4;
386         } else {
387             $ret_type = "void";
388         }
390         my @fields = ParseFunctionDeclaration($declaration);
392         for (my $i = 0; $i <= $#fields; $i += 2) {
393             my $field_name = $fields[$i];
394             $output .= &OutputParam ($symbol, $field_name, $template_exists, 1, "");
395         }
397         if ($ret_type ne "void" || $ret_type_modifier || $ret_type_pointer) {
398             $output .= &OutputParam ($symbol, "Returns", $template_exists, 1, "");
399         }
401         $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
402         $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
403         $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
404         $output .= &OutputOldParams ($symbol);
405         $output .= "\n";
406     }
408     if ($type eq "MACRO") {
409         my @fields = ParseMacroDeclaration($declaration);
411         for (my $i = 0; $i <= $#fields; $i +=2) {
412             my $field_name = $fields[$i];
414             $output .= &OutputParam ($symbol, $field_name, $template_exists,
415                                      1, "");
416         }
417         $output .= &OutputParam ($symbol, "Returns", $template_exists, 0, "");
418         $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
419         $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
420         $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
421         $output .= &OutputOldParams ($symbol);
422         $output .= "\n";
423     }
425     if ($type eq "STRUCT") {
426         my $is_object_struct = CheckIsObject ($symbol);
427         my @fields = ParseStructDeclaration($declaration, $is_object_struct, 1);
429         for (my $i = 0; $i <= $#fields; $i += 2) {
430             my $field_name = $fields[$i];
431             $output .= &OutputParam ($symbol, $field_name, $template_exists, 1, "");
432         }
433         $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
434         $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
435         $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
436     }
438     if ($type eq "ENUM") {
439         my @members = ParseEnumDeclaration($declaration);
441         for my $member (@members) {
442             $output .= &OutputParam ($symbol, $member, $template_exists, 1, "");
443         }
444         $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
445         $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
446         $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
447     }
449     $output .= "\n";
451     # Remove the used docs from the hashes.
452     if ($template_exists) {
453         delete $SymbolDocs{$symbol};
454         delete $SymbolParams{$symbol};
455     }
457     return $output;
461 #############################################################################
462 # Function    : OutputParam
463 # Description : This outputs the part of a template for one parameter.
464 #                It first checks if the parameter is already described, and if
465 #                so it uses that description, and clears it so it isn't output
466 #                as an old param.
467 # Arguments   : $symbol - the symbol (function or macro) name.
468 #                $param_to_output - the parameter to add.
469 #                $template_exists - TRUE if the template already existed in
470 #                  template files. If it did, then we will flag any changes
471 #                  with 'FIXME'.
472 #                $force_output - TRUE if the parameter should be output even
473 #                  if it didn't already exist in the template. (The return
474 #                  values of macros are added manually if required, and so we
475 #                  never add it here - we only copy it if it already exists.)
476 #                $default_description - the default description of the
477 #                  parameter to be used if it doesn't already exist. (Signal
478 #                  handlers have a few common parameters.)
479 #############################################################################
481 sub OutputParam {
482     my ($symbol, $param_to_output, $template_exists,
483         $force_output, $default_description) = @_;
484     my ($j);
486     my ($params) = $SymbolParams{$symbol};
487     if (defined ($params)) {
488         for ($j = 0; $j <= $#$params; $j += 2) {
489             my $param_name = $$params[$j];
490             my $param_desc = $$params[$j + 1];
492             if ($param_name eq $param_to_output) {
493                 $param_desc =~ s/\s+$//;
494                 $$params[$j] = "";
495                 $$params[$j + 1] = "";
496                 return "\@$param_name: $param_desc\n";
497             }
498         }
499     }
501     # If the template was already in a file, flag the new parameter.
502     # If not, the template itself will be flagged, so we don't need to flag
503     # all the new parameters as well.
504     if ($force_output) {
505         if ($default_description ne "") {
506             $default_description =~ s/\s+$//;
507             return "\@$param_to_output: $default_description\n";
508         } else {
509             if ($template_exists) {
510                 return "\@$param_to_output: $CHANGES_FLAG\n";
511             } else {
512                 return "\@$param_to_output: \n";
513             }
514         }
515     }
516     return "";
520 #############################################################################
521 # Function    : OutputOldParams
522 # Description : This returns all the existing documentation for parameters of
523 #                the given function/macro/signal symbol which are unused, with
524 #                a comment before them.
525 # Arguments   : $symbol - the symbol (function/macro/signal) name.
526 #############################################################################
528 sub OutputOldParams {
529     my ($symbol) = @_;
530     my $output = "";
532     my ($params) = $SymbolParams{$symbol};
533     if (defined ($params)) {
534         my $j;
535         for ($j = 0; $j <= $#$params; $j += 2) {
536             my $param_name = $$params[$j];
537             my $param_desc = $$params[$j + 1];
539             if ($param_name ne "") {
540                 $param_desc =~ s/\s+$//;
542                 # There's no point keeping it if it has no docs.
543                 if ($param_desc ne "") {
544                   $output .= "\@$param_name: $param_desc\n";
545                 }
546             }
547         }
548     }
549     if ($output) {
550         $output = "<!-- # Unused Parameters # -->\n" . $output;
551     }
552     return $output;
556 #############################################################################
557 # Function    : OutputTemplateFile
558 # Description : This outputs one template file.
559 # Arguments   : $file - the basename of the file to output.
560 #                $title - the title from the $MODULE-sections.txt file. This
561 #                  will be overridden by any title given in the template file.
562 #                $output - reference to the templates to output.
563 #############################################################################
565 sub OutputTemplateFile {
566     my ($file, $title, $output) = @_;
568     my ($short_desc, $long_desc, $see_also, $stability, $image);
570     if (defined ($SymbolDocs{"$TMPL_DIR/$file:Title"})) {
571         $title = $SymbolDocs{"$TMPL_DIR/$file:Title"};
572         delete $SymbolDocs{"$TMPL_DIR/$file:Title"};
573     }
574     if (defined ($SymbolDocs{"$TMPL_DIR/$file:Short_Description"})) {
575         $short_desc = $SymbolDocs{"$TMPL_DIR/$file:Short_Description"};
576         delete $SymbolDocs{"$TMPL_DIR/$file:Short_Description"};
577     } else {
578         $short_desc = "";
579     }
580     if (defined ($SymbolDocs{"$TMPL_DIR/$file:Long_Description"})) {
581         $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
582         delete $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
583     } else {
584         $long_desc = "<para>\n\n</para>\n";
585     }
586     if (defined ($SymbolDocs{"$TMPL_DIR/$file:See_Also"})) {
587         $see_also = $SymbolDocs{"$TMPL_DIR/$file:See_Also"};
588         delete $SymbolDocs{"$TMPL_DIR/$file:See_Also"};
589     } else {
590         $see_also = "<para>\n\n</para>\n";
591     }
592     if (defined ($SymbolDocs{"$TMPL_DIR/$file:Stability_Level"})) {
593         $stability = $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
594         delete $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
595     } else {
596         $stability = "";
597     }
598     if (defined ($SymbolDocs{"$TMPL_DIR/$file:Image"})) {
599         $image = $SymbolDocs{"$TMPL_DIR/$file:Image"};
600         delete $SymbolDocs{"$TMPL_DIR/$file:Image"};
601     } else {
602         $image = "";
603     }
606     my $old_tmpl_file = "$TMPL_DIR/$file";
607     my $new_tmpl_file = "$TMPL_DIR/$file.new";
609     open (OUTPUT, ">$new_tmpl_file")
610         || die "Can't create $new_tmpl_file";
612     print (OUTPUT <<EOF);
613 <!-- ##### SECTION Title ##### -->
614 $title
616 <!-- ##### SECTION Short_Description ##### -->
617 $short_desc
619 <!-- ##### SECTION Long_Description ##### -->
620 $long_desc
622 <!-- ##### SECTION See_Also ##### -->
623 $see_also
625 <!-- ##### SECTION Stability_Level ##### -->
626 $stability
628 <!-- ##### SECTION Image ##### -->
629 $image
633     print (OUTPUT $$output) unless $ONLY_SECTION_TMPL;
634     close (OUTPUT);
636     return &UpdateFileIfChanged ($old_tmpl_file, $new_tmpl_file, 1);
640 #############################################################################
641 # Function    : OutputSignalTemplates
642 # Description : Outputs templates for signal handlers.
643 # Arguments   : $title - the title from the $MODULE-sections.txt file. If the
644 #                  file is describing a GtkObject subclass, the title should
645 #                  be the name of the class, e.g. 'GtkButton'.
646 #############################################################################
648 sub OutputSignalTemplates {
649     my ($title) = @_;
651     my $output = "";
652     my ($i, $template_exists);
653     for ($i = 0; $i <= $#SignalObjects; $i++) {
654         if ($SignalObjects[$i] eq $title) {
655 #            print "Found signal: $SignalObjects[$i]\n";
656             my ($symbol) = "$SignalObjects[$i]::$SignalNames[$i]";
658             # See if symbol already has a description.
659             my ($symbol_desc) = $SymbolDocs{$symbol};
660             if (defined ($symbol_desc)) {
661                 $template_exists = 1;
662                 $symbol_desc =~ s/\s+$//;
663                 delete $SymbolDocs{$symbol};
664             } else {
665                 $template_exists = 0;
666                 $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>";
667             }
669             $output .= <<EOF;
670 <!-- ##### SIGNAL $symbol ##### -->
671 $symbol_desc
674             my $sourceparams = $SymbolParams{$symbol};
675             my @params = split ("[,\n]", $SignalPrototypes[$i]);
676             my ($j, $name);
677             for ($j = 0; $j <= $#params; $j++) {
678                 my $param = $params[$j];
679                 $param =~ s/^\s+//;
680                 $param =~ s/\s*$//;
681                 if ($param =~ m/^\s*$/) { next; }
682                 if ($param =~ m/^void$/) { next; }
684                 if ($param =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)?\s*$/) {
685                     if (defined ($sourceparams)) {
686                         $name = $$sourceparams[2 * $j];
687                     } else {
688                         $name = $3;
689                     }
691                     if (!defined ($name)) {
692                         $name = "Param" . ($j + 1);
693                     }
695                     if ($j == 0) {
696                         $output .= &OutputParam ($symbol, $name,
697                                                  $template_exists, 1,
698                                                  "the object which received the signal.");
699                     } else {
700                         $output .= &OutputParam ($symbol, $name,
701                                                  $template_exists, 1, "");
702                     }
703                 }
704             }
706             if ($SignalReturns[$i] ne "void") {
707                 $output .= &OutputParam ($symbol, "Returns", $template_exists,
708                                          1, "");
709             }
710             $output .= &OutputOldParams ($symbol);
711             $output .= "\n";
712         }
713     }
714     return $output;
718 #############################################################################
719 # Function    : OutputArgTemplates
720 # Description : Outputs templates for Args.
721 # Arguments   : $title - the title from the $MODULE-sections.txt file. If the
722 #                  file is describing a GtkObject subclass, the title should
723 #                  be the name of the class, e.g. 'GtkButton'.
724 #############################################################################
726 sub OutputArgTemplates {
727     my ($title) = @_;
729     my $output = "";
730     my $i;
731     for ($i = 0; $i <= $#ArgObjects; $i++) {
732         if ($ArgObjects[$i] eq $title) {
733 #            print "Found arg: $ArgObjects[$i]\n";
734             # I've only used one colon so we don't clash with signals.
735             my ($symbol) = "$ArgObjects[$i]:$ArgNames[$i]";
737             # See if symbol already has a description.
738             my ($symbol_desc) = $SymbolDocs{$symbol};
739             if (defined ($symbol_desc)) {
740                 delete $SymbolDocs{$symbol};
741                 $symbol_desc =~ s/\s+$//;
742             } else {
743                 $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>";
744             }
746             $output .= <<EOF;
747 <!-- ##### ARG $symbol ##### -->
748 $symbol_desc
751         }
752     }
753     return $output;
757 #############################################################################
758 # Function    : OutputUnusedTemplates
759 # Description : This saves any unused documentation into $MODULE-unused.sgml.
760 # Arguments   : none
761 #############################################################################
763 sub OutputUnusedTemplates {
764     my ($old_unused_file) = "$TMPL_DIR/$MODULE-unused.sgml";
765     my ($new_unused_file) = "$TMPL_DIR/$MODULE-unused.new";
767     open (UNUSED, ">$new_unused_file")
768         || die "Can't open file: $new_unused_file";
770     my $output = "";
771     my ($symbol, $symbol_desc);
772     for $symbol (sort keys %SymbolDocs) {
773         $symbol_desc = $SymbolDocs{$symbol};
775 #        print "Unused: $symbol\n";
777         my $type = $SymbolTypes{$symbol};
778         if (!defined ($type)) {
779             $type = "UNKNOWN";
780             &LogWarning ($SymbolSourceFile{$symbol},$SymbolSourceLine{$symbol}, "Unused symbol $symbol has unknown type.");
781         }
783     $output .= <<EOF;
784 <!-- ##### $type $symbol ##### -->
785 $symbol_desc
789         my ($params) = $SymbolParams{$symbol};
790         if (defined ($params)) {
791             my $j;
792             for ($j = 0; $j <= $#$params; $j += 2) {
793                 my $param_name = $$params[$j];
794                 my $param_desc = $$params[$j + 1];
795                 $param_desc =~ s/\s+$//;
796                 $output .= "\@$param_name: $param_desc\n";
797             }
798         }
799         $output .= "\n";
800     }
802     print UNUSED $output;
803     close (UNUSED);
805     &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 1);
809 #############################################################################
810 # LIBRARY FUNCTIONS -        These functions are used in both gtkdoc-mkdb and
811 #                        gtkdoc-mktmpl and should eventually be moved to a
812 #                        separate library.
813 #############################################################################
815 #############################################################################
816 # Function    : ReadDeclarationsFile
817 # Description : This reads in a file containing the function/macro/enum etc.
818 #                declarations.
820 #                Note that in some cases there are several declarations with
821 #                the same name, e.g. for conditional macros. In this case we
822 #                set a flag in the %DeclarationConditional hash so the
823 #                declaration is not shown in the docs.
825 #                If a macro and a function have the same name, e.g. for
826 #                gtk_object_ref, the function declaration takes precedence.
828 #                Some opaque structs are just declared with 'typedef struct
829 #                _name name;' in which case the declaration may be empty.
830 #                The structure may have been found later in the header, so
831 #                that overrides the empty declaration.
833 # Arguments   : $file - the declarations file to read
834 #                $override - if declarations in this file should override
835 #                        any current declaration.
836 #############################################################################
838 sub ReadDeclarationsFile {
839     my ($file, $override) = @_;
841     if ($override == 0) {
842         %Declarations = ();
843         %DeclarationTypes = ();
844         %DeclarationConditional = ();
845         %DeclarationOutput = ();
846     }
848     open (INPUT, $file)
849         || die "Can't open $file";
850     my $declaration_type = "";
851     my $declaration_name;
852     my $declaration;
853     while (<INPUT>) {
854         if (!$declaration_type) {
855             if (m/^<([^>]+)>/) {
856                 $declaration_type = $1;
857                 $declaration_name = "";
858 #                print "Found declaration: $declaration_type\n";
859                 $declaration = "";
860             }
861         } else {
862             if (m%^<NAME>(.*)</NAME>%) {
863                 $declaration_name = $1;
864             } elsif (m%<DEPRECATED/>%) {
865                 # do nothing, just skip the line; we handle this
866                 # in mkdb
867             } elsif (m%^</$declaration_type>%) {
868 #                print "Found end of declaration: $declaration_name\n";
869                 # Check that the declaration has a name
870                 if ($declaration_name eq "") {
871                     print "ERROR: $declaration_type has no name $file:$.\n";
872                 }
874                 # Check if the symbol is already defined.
875                 if (defined ($Declarations{$declaration_name})
876                     && $override == 0) {
877                     # Function declarations take precedence.
878                     if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') {
879                         # Ignore it.
880                     } elsif ($declaration_type eq 'FUNCTION') {
881                         $Declarations{$declaration_name} = $declaration;
882                         $DeclarationTypes{$declaration_name} = $declaration_type;
883                     } elsif ($DeclarationTypes{$declaration_name}
884                               eq $declaration_type) {
885                         # If the existing declaration is empty, or is just a
886                         # forward declaration of a struct, override it.
887                         if ($declaration_type eq 'STRUCT') {
888                             if ($Declarations{$declaration_name} =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
889                                 $Declarations{$declaration_name} = $declaration;
890                             } elsif ($declaration =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
891                                 # Ignore an empty or forward declaration.
892                             } else {
893                                 &LogWarning ($file, $., "Structure $declaration_name has multiple definitions.");
894                             }
896                         } else {
897                             # set flag in %DeclarationConditional hash for
898                             # multiply defined macros/typedefs.
899                             $DeclarationConditional{$declaration_name} = 1;
900                         }
901                     } else {
902                         &LogWarning ($file, $., "$declaration_name has multiple definitions.");
903                     }
904                 } else {
905                     $Declarations{$declaration_name} = $declaration;
906                     $DeclarationTypes{$declaration_name} = $declaration_type;
907                 }
908                 $declaration_type = "";
909             } else {
910                 $declaration .= $_;
911             }
912         }
913     }
914     close (INPUT);
918 #############################################################################
919 # Function    : ReadSignalsFile
920 # Description : This reads in an existing file which contains information on
921 #                all GObject signals. It creates the arrays @SignalNames and
922 #                @SignalPrototypes containing info on the signals. The first
923 #                line of the SignalPrototype is the return type of the signal
924 #                handler. The remaining lines are the parameters passed to it.
925 #                The last parameter, "gpointer user_data" is always the same
926 #                so is not included.
927 # Arguments   : $file - the file containing the signal handler prototype
928 #                        information.
929 #############################################################################
931 sub ReadSignalsFile {
932     my ($file) = @_;
934     my $in_signal = 0;
935     my $signal_object;
936     my $signal_name;
937     my $signal_returns;
938     my $signal_flags;
939     my $signal_prototype;
941     # Reset the signal info.
942     @SignalObjects = ();
943     @SignalNames = ();
944     @SignalReturns = ();
945     @SignalFlags = ();
946     @SignalPrototypes = ();
948     if (! -f $file) {
949         return;
950     }
951     if (!open (INPUT, $file)) {
952         warn "Can't open $file - skipping signals\n";
953         return;
954     }
955     while (<INPUT>) {
956         if (!$in_signal) {
957             if (m/^<SIGNAL>/) {
958                 $in_signal = 1;
959                 $signal_object = "";
960                 $signal_name = "";
961                 $signal_returns = "";
962                 $signal_prototype = "";
963             }
964         } else {
965             if (m/^<NAME>(.*)<\/NAME>/) {
966                 $signal_name = $1;
967                 if ($signal_name =~ m/^(.*)::(.*)$/) {
968                     $signal_object = $1;
969                     ($signal_name = $2) =~ s/_/-/g;
970 #                    print "Found signal: $signal_name\n";
971                 } else {
972                     print "Invalid signal name: $signal_name\n";
973                 }
974             } elsif (m/^<RETURNS>(.*)<\/RETURNS>/) {
975                 $signal_returns = $1;
976             } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
977                 $signal_flags = $1;
978             } elsif (m%^</SIGNAL>%) {
979 #                print "Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}";
980                 push (@SignalObjects, $signal_object);
981                 push (@SignalNames, $signal_name);
982                 push (@SignalReturns, $signal_returns);
983                 push (@SignalFlags, $signal_flags);
984                 push (@SignalPrototypes, $signal_prototype);
985                 $in_signal = 0;
986             } else {
987                 $signal_prototype .= $_;
988             }
989         }
990     }
991     close (INPUT);
995 #############################################################################
996 # Function    : ReadTemplateFile
997 # Description : This reads in the manually-edited documentation file
998 #                corresponding to the file currently being created, so we can
999 #                insert the documentation at the appropriate places.
1000 #                It outputs %SymbolTypes, %SymbolDocs and %SymbolParams, which
1001 #                is a hash of arrays.
1002 #                NOTE: This function is duplicated in gtkdoc-mkdb (but
1003 #                slightly different).
1004 # Arguments   : $docsfile - the template file to read in.
1005 #                $skip_unused_params - 1 if the unused parameters should be
1006 #                        skipped.
1007 #############################################################################
1009 sub ReadTemplateFile {
1010     my ($docsfile, $skip_unused_params) = @_;
1012 #    print "Reading $docsfile\n";
1013     if (! -f $docsfile) {
1014         print "File doesn't exist: $docsfile\n";
1015         return 0;
1016     }
1018     my $CurrentType = "";         # Type of symbol being read.
1019     my $CurrentSymbol = "";        # Name of symbol being read.
1020     my $SymbolDoc = "";                # Description of symbol being read.
1021     my @Params;                        # Parameter names and descriptions of current
1022                                 #   function/macro/function typedef.
1023     my $CurrentParam = -1;        # Index of parameter currently being read.
1024                                 #   Note that the param array contains pairs
1025                                 #   of param name & description.
1026     my $InUnusedParameters = 0;        # True if we are reading in the unused params.
1028     open (DOCS, $docsfile)
1029         || die "Can't open file $docsfile: $!";
1030     while (<DOCS>) {
1031         if (m/^<!-- ##### ([A-Z_]+) (\S+) ##### -->/) {
1032             my $type = $1;
1033             my $symbol = $2;
1034             if ($symbol eq "Title"
1035                 || $symbol eq "Short_Description"
1036                 || $symbol eq "Long_Description"
1037                 || $symbol eq "See_Also"
1038                 || $symbol eq "Stability_Level"
1039                 || $symbol eq "Image") {
1040                 $symbol = $docsfile . ":" . $symbol;
1041             }
1043             #print "Found symbol: $symbol\n";
1044             # Remember file and line for the symbol
1045             $SymbolSourceFile{$symbol} = $docsfile;
1046             $SymbolSourceLine{$symbol} = $.;
1048             # Canonicalize signal and argument names to have -, not _
1049             if ($type eq "ARG" || $type eq "SIGNAL") {
1050               $symbol =~ s/_/-/g;
1051             }
1053             # Store previous symbol, but remove any trailing blank lines.
1054             if ($CurrentSymbol ne "") {
1055                 $SymbolDoc =~ s/\s+$//;
1056                 $SymbolTypes{$CurrentSymbol} = $CurrentType;
1057                 $SymbolDocs{$CurrentSymbol} = $SymbolDoc;
1059                 if ($CurrentParam >= 0) {
1060                     $SymbolParams{$CurrentSymbol} = [ @Params ];
1061                 } else {
1062                     # Delete any existing params in case we are overriding a
1063                     # previously read template.
1064                     delete $SymbolParams{$CurrentSymbol};
1065                 }
1066             }
1067             $CurrentType = $type;
1068             $CurrentSymbol = $symbol;
1069             $CurrentParam = -1;
1070             $InUnusedParameters = 0;
1071             $SymbolDoc = "";
1072             @Params = ();
1074         } elsif (m/^<!-- # Unused Parameters # -->/) {
1075             $InUnusedParameters = 1;
1076             next;
1078         } else {
1079             # Workaround for an old bug that left a mess in the templates.
1080             # This happened with macros with args spread over several lines.
1081             if (m/^\@\\$/) {
1082               # Skip the next line.
1083               $_ = <DOCS>;
1084               next;
1085             }
1087             # Workaround for an old bug that left '@:' at start of lines.
1088             if (m/^\@:$/) {
1089               next;
1090             }
1093             # Check if param found. Need to handle "..." and "format...".
1094             if (s/^\@([\w\.]+):\040?//) {
1095                 my $param_name = $1;
1096                 # Allow variations of 'Returns'
1097                 if ($param_name =~ m/^[Rr]eturns?$/) {
1098                     $param_name = "Returns";
1099                 }
1100 #                print "Found param: $param_name\n";
1101                 push (@Params, $param_name);
1102                 push (@Params, $_);
1103                 $CurrentParam += 2;
1104                 next;
1105             }
1107             # When outputting the DocBook we skip unused parameters.
1108             if (!$InUnusedParameters || !$skip_unused_params) {
1109                 if ($CurrentParam >= 0) {
1110                     $Params[$CurrentParam] .= $_;
1111                 } else {
1112                     $SymbolDoc .= $_;
1113                 }
1114             }
1115         }
1116     }
1118     # Remember to finish the current symbol doccs.
1119     if ($CurrentSymbol ne "") {
1121         $SymbolDoc =~ s/\s+$//;
1122         $SymbolTypes{$CurrentSymbol} = $CurrentType;
1123         $SymbolDocs{$CurrentSymbol} = $SymbolDoc;
1125         if ($CurrentParam >= 0) {
1126             $SymbolParams{$CurrentSymbol} = [ @Params ];
1127         } else {
1128             delete $SymbolParams{$CurrentSymbol};
1129         }
1130     }
1132     close (DOCS);
1133     return 1;
1137 #############################################################################
1138 # Function    : ReadObjectHierarchy
1139 # Description : This reads in the $MODULE-hierarchy.txt file containing all
1140 #                the GtkObject subclasses described in this module (and their
1141 #                ancestors).
1142 #                It places them in the @Objects array, and places their level
1143 #                in the widget hierarchy in the @ObjectLevels array, at the
1144 #                same index. GtkObject, the root object, has a level of 1.
1146 #               FIXME: the version in gtkdoc-mkdb also generates tree_index.sgml
1147 #               as it goes along, this should be split out into a separate
1148 #               function.
1150 # Arguments   : none
1151 #############################################################################
1153 sub ReadObjectHierarchy {
1154     @Objects = ();
1155     @ObjectLevels = ();
1157     if (! -f $OBJECT_TREE_FILE) {
1158         return;
1159     }
1160     if (!open (INPUT, $OBJECT_TREE_FILE)) {
1161         warn "Can't open $OBJECT_TREE_FILE - skipping object tree\n";
1162         return;
1163     }
1164     while (<INPUT>) {
1165         if (m/\S+/) {
1166             my $object = $&;
1167             my $level = (length($`)) / 2 + 1;
1168 #            print ("Level: $level  Object: $object\n");
1170             push (@Objects, $object);
1171             push (@ObjectLevels, $level);
1172         }
1173     }
1175     close (INPUT);
1179 #############################################################################
1180 # Function    : ReadArgsFile
1181 # Description : This reads in an existing file which contains information on
1182 #                all GObject args. It creates the arrays @ArgObjects, @ArgNames,
1183 #                @ArgTypes and @ArgFlags containing info on the args.
1184 # Arguments   : $file - the file containing the arg information.
1185 #############################################################################
1187 sub ReadArgsFile {
1188     my ($file) = @_;
1190     my $in_arg = 0;
1191     my $arg_object;
1192     my $arg_name;
1193     my $arg_type;
1194     my $arg_flags;
1196     # Reset the signal info.
1197     @ArgObjects = ();
1198     @ArgNames = ();
1199     @ArgTypes = ();
1200     @ArgFlags = ();
1202     if (! -f $file) {
1203         return;
1204     }
1205     if (!open (INPUT, $file)) {
1206         warn "Can't open $file - skipping args\n";
1207         return;
1208     }
1209     while (<INPUT>) {
1210         if (!$in_arg) {
1211             if (m/^<ARG>/) {
1212                 $in_arg = 1;
1213                 $arg_object = "";
1214                 $arg_name = "";
1215                 $arg_type = "";
1216                 $arg_flags = "";
1217             }
1218         } else {
1219             if (m/^<NAME>(.*)<\/NAME>/) {
1220                 $arg_name = $1;
1221                 if ($arg_name =~ m/^(.*)::(.*)$/) {
1222                     $arg_object = $1;
1223                     ($arg_name = $2) =~ s/_/-/g;
1224 #                    print "Found arg: $arg_name\n";
1225                 } else {
1226                     print "Invalid arg name: $arg_name\n";
1227                 }
1228             } elsif (m/^<TYPE>(.*)<\/TYPE>/) {
1229                 $arg_type = $1;
1230             } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
1231                 $arg_flags = $1;
1232             } elsif (m%^</ARG>%) {
1233 #                print "Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n";
1234                 push (@ArgObjects, $arg_object);
1235                 push (@ArgNames, $arg_name);
1236                 push (@ArgTypes, $arg_type);
1237                 push (@ArgFlags, $arg_flags);
1238                 $in_arg = 0;
1239             }
1240         }
1241     }
1242     close (INPUT);
1246 #############################################################################
1247 # Function    : CheckIsObject
1248 # Description : Returns 1 if the given name is a GObject or a subclass.
1249 #                It uses the global @Objects array.
1250 #                Note that the @Objects array only contains classes in the
1251 #                current module and their ancestors - not all GObject classes.
1252 # Arguments   : $name - the name to check.
1253 #############################################################################
1255 sub CheckIsObject {
1256     my ($name) = @_;
1258     my $object;
1259     foreach $object (@Objects) {
1260         if ($object eq $name) {
1261             return 1;
1262         }
1263     }
1264     return 0;