gtkdoc-mkdb.in

   1 #!@PERL@ -w
   2 # -*- cperl -*-
   3 #
   4 # gtk-doc - GTK DocBook documentation generator.
   5 # Copyright (C) 1998  Damon Chaplin
   6 #
   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.
  11 #
  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.
  16 #
  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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  20 #
  21
  22 #############################################################################
  23 # Script      : gtkdoc-mkdb
  24 # Description : This creates the DocBook files from the edited templates.
  25 #
  26 #               NOTE: When creating SGML IDS, we append ":CAPS" to all
  27 #               all-caps identifiers to prevent name clashes. (It basically
  28 #               never is the case that mixed-case identifiers would collide.)
  29 #               See the CreateValidSGMLID function.
  30 #############################################################################
  31
  32 use strict;
  33 use Getopt::Long;
  34
  35 unshift @INC, '@PACKAGE_DATA_DIR@';
  36 require "gtkdoc-common.pl";
  37
  38 # Options
  39
  40 # name of documentation module
  41 my $MODULE;
  42 my $TMPL_DIR;
  43 my $SGML_OUTPUT_DIR;
  44 my @SOURCE_DIRS;
  45 my $SOURCE_SUFFIXES = "";
  46 my $IGNORE_FILES = "";
  47 my $PRINT_VERSION;
  48 my $PRINT_HELP;
  49 my $OUTPUT_ALL_SYMBOLS;
  50 my $MAIN_SGML_FILE;
  51 my $EXPAND_CONTENT_FILES = "";
  52 my $SGML_MODE;
  53 my $DEFAULT_STABILITY;
  54 my $DEFAULT_INCLUDES;
  55 my $OUTPUT_FORMAT;
  56
  57 my %optctl = (module => \$MODULE,
  58               'source-dir' => \@SOURCE_DIRS,
  59               'source-suffixes' => \$SOURCE_SUFFIXES,
  60               'ignore-files' => \$IGNORE_FILES,
  61               'output-dir' => \$SGML_OUTPUT_DIR,
  62               'tmpl-dir' => \$TMPL_DIR,
  63               'version' => \$PRINT_VERSION,
  64               'help' => \$PRINT_HELP,
  65               'main-sgml-file' => \$MAIN_SGML_FILE,
  66               'expand-content-files' => \$EXPAND_CONTENT_FILES,
  67               'outputallsymbols' => \$OUTPUT_ALL_SYMBOLS,
  68               'sgml-mode' => \$SGML_MODE,
  69               'default-stability' => \$DEFAULT_STABILITY,
  70               'default-includes' => \$DEFAULT_INCLUDES,
  71               'output-format' => \$OUTPUT_FORMAT);
  72 GetOptions(\%optctl, "module=s", "source-dir:s", "source-suffixes:s", "ignore-files:s", "output-dir:s", "tmpl-dir:s", "version", "outputallsymbols", "expand-content-files:s", "main-sgml-file:s", "extra-db-files:s", "help", "sgml-mode", "default-stability:s", "default-includes:s", "output-format:s");
  73
  74 if ($PRINT_VERSION) {
  75     print "@VERSION@\n";
  76     exit 0;
  77 }
  78
  79 if (!$MODULE) {
  80     $PRINT_HELP = 1;
  81 }
  82
  83 if ($DEFAULT_STABILITY && $DEFAULT_STABILITY ne "Stable"
  84     && $DEFAULT_STABILITY ne "Private" && $DEFAULT_STABILITY ne "Unstable") {
  85     $PRINT_HELP = 1;
  86 }
  87
  88 if ($PRINT_HELP) {
  89     print "gtkdoc-mkdb version @VERSION@\n";
  90     print "\n--module=MODULE_NAME   Name of the doc module being parsed";
  91     print "\n--source-dir=DIRNAME   Directories which contain inline reference material";
  92     print "\n--source-suffixes=SUFFIXES Suffixes of source files to scan, comma-separated";
  93     print "\n--ignore-files=FILES   Files or directories which should not be scanned";
  94     print "\n                       May be used more than once for multiple directories";
  95     print "\n--output-dir=DIRNAME   Directory to put the generated DocBook files in";
  96     print "\n--tmpl-dir=DIRNAME     Directory in which template files may be found";
  97     print "\n--main-sgml-file=FILE  File containing the toplevel DocBook file.";
  98     print "\n--expand-content-files=FILES Extra DocBook files to expand abbreviations in.";
  99     print "\n--output-format=FORMAT The format to use for the generated docbook, XML or SGML.";
 100     print "\n--sgml-mode            Allow DocBook markup in inline documentation.";
 101     print "\n--default-stability=LEVEL Specify default stability Level. Valid values are";
 102     print "\n                       Stable, Unstable, or Private.";
 103     print "\n--default-includes=FILENAMES Specify default includes for section Synopsis";
 104     print "\n--version              Print the version of this program";
 105     print "\n--help                 Print this help\n";
 106     exit 0;
 107 }
 108
 109 my ($empty_element_end, $doctype_header);
 110
 111 if (lc($OUTPUT_FORMAT) eq "xml") {
 112     if (!$MAIN_SGML_FILE) {
 113         # backwards compatibility
 114         if (-e "${MODULE}-docs.sgml") {
 115             $MAIN_SGML_FILE="${MODULE}-docs.sgml";
 116         } else {
 117             $MAIN_SGML_FILE="${MODULE}-docs.xml";
 118         }
 119     }
 120     $OUTPUT_FORMAT = "xml";
 121     $empty_element_end = "/>";
 122
 123     if (-e $MAIN_SGML_FILE) {
 124         open(INPUT, "<$MAIN_SGML_FILE") || die "Can't open $MAIN_SGML_FILE";
 125         $doctype_header = "";
 126         while (<INPUT>) {
 127             if (/^\s*<(book|chapter|article)/) {
 128                 if ($_ !~ m/http:\/\/www.w3.org\/200[13]\/XInclude/) {
 129                     $doctype_header = "";
 130                 }
 131                 last;
 132             }
 133             $doctype_header .= $_;
 134         }
 135         close(INPUT);
 136     } else {
 137         $doctype_header =
 138 "<?xml version=\"1.0\"?>\n" .
 139 "<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\"\n" .
 140 "               \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">\n";
 141     }
 142     $doctype_header =~ s/<!DOCTYPE \w+/<!DOCTYPE refentry/;
 143 } else {
 144     if (!$MAIN_SGML_FILE) {
 145         $MAIN_SGML_FILE="${MODULE}-docs.sgml";
 146     }
 147     $OUTPUT_FORMAT = "sgml";
 148     $doctype_header = "";
 149     $empty_element_end = ">";
 150 }
 151
 152 my $ROOT_DIR = ".";
 153
 154 # All the files are written in subdirectories beneath here.
 155 $TMPL_DIR = $TMPL_DIR ? $TMPL_DIR : "$ROOT_DIR/tmpl";
 156
 157 # This is where we put all the DocBook output.
 158 $SGML_OUTPUT_DIR = $SGML_OUTPUT_DIR ? $SGML_OUTPUT_DIR : "$ROOT_DIR/$OUTPUT_FORMAT";
 159
 160 # This file contains the object hierarchy.
 161 my $OBJECT_TREE_FILE = "$ROOT_DIR/$MODULE.hierarchy";
 162
 163 # This file contains the interfaces.
 164 my $INTERFACES_FILE = "$ROOT_DIR/$MODULE.interfaces";
 165
 166 # This file contains the prerequisites.
 167 my $PREREQUISITES_FILE = "$ROOT_DIR/$MODULE.prerequisites";
 168
 169 # This file contains signal arguments and names.
 170 my $SIGNALS_FILE = "$ROOT_DIR/$MODULE.signals";
 171
 172 # The file containing Arg information.
 173 my $ARGS_FILE = "$ROOT_DIR/$MODULE.args";
 174
 175 # These global arrays store information on signals. Each signal has an entry
 176 # in each of these arrays at the same index, like a multi-dimensional array.
 177 my @SignalObjects;      # The GtkObject which emits the signal.
 178 my @SignalNames;        # The signal name.
 179 my @SignalReturns;      # The return type.
 180 my @SignalFlags;        # Flags for the signal
 181 my @SignalPrototypes;   # The rest of the prototype of the signal handler.
 182
 183 # These global arrays store information on Args. Each Arg has an entry
 184 # in each of these arrays at the same index, like a multi-dimensional array.
 185 my @ArgObjects;         # The GtkObject which has the Arg.
 186 my @ArgNames;           # The Arg name.
 187 my @ArgTypes;           # The Arg type - gint, GtkArrowType etc.
 188 my @ArgFlags;           # How the Arg can be used - readable/writable etc.
 189 my @ArgNicks;           # The nickname of the Arg.
 190 my @ArgBlurbs;          # Docstring of the Arg.
 191 my @ArgDefaults;        # Default value of the Arg.
 192 my @ArgRanges;          # The range of the Arg type
 193 # These global hashes store declaration info keyed on a symbol name.
 194 my %Declarations;
 195 my %DeclarationTypes;
 196 my %DeclarationConditional;
 197 my %DeclarationOutput;
 198 my %Deprecated;
 199 my %Since;
 200 my %StabilityLevel;
 201 my %StructHasTypedef;
 202
 203 # These global hashes store the existing documentation.
 204 my %SymbolDocs;
 205 my %SymbolTypes;
 206 my %SymbolParams;
 207
 208 # These global hashes store documentation scanned from the source files.
 209 my %SourceSymbolDocs;
 210 my %SourceSymbolParams;
 211
 212 # all documentation goes in here, so we can do coverage analysis
 213 my %AllSymbols;
 214 my %AllIncompleteSymbols;
 215 my %AllDocumentedSymbols;
 216
 217 # Undeclared yet documented symbols
 218 my %UndeclaredSymbols;
 219
 220 # These global arrays store GtkObject and subclasses and the hierarchy.
 221 my @Objects;
 222 my @ObjectLevels;
 223
 224 my %Interfaces;
 225 my %Prerequisites;
 226
 227 # holds the symbols which are mentioned in $MODULE-sections.txt
 228 my %KnownSymbols;
 229
 230 # Standard C preprocessor directives, which we ignore for '#' abbreviations.
 231 my %PreProcessorDirectives;
 232 $PreProcessorDirectives{"assert"} = 1;
 233 $PreProcessorDirectives{"define"} = 1;
 234 $PreProcessorDirectives{"elif"} = 1;
 235 $PreProcessorDirectives{"else"} = 1;
 236 $PreProcessorDirectives{"endif"} = 1;
 237 $PreProcessorDirectives{"error"} = 1;
 238 $PreProcessorDirectives{"if"} = 1;
 239 $PreProcessorDirectives{"ifdef"} = 1;
 240 $PreProcessorDirectives{"ifndef"} = 1;
 241 $PreProcessorDirectives{"include"} = 1;
 242 $PreProcessorDirectives{"line"} = 1;
 243 $PreProcessorDirectives{"pragma"} = 1;
 244 $PreProcessorDirectives{"unassert"} = 1;
 245 $PreProcessorDirectives{"undef"} = 1;
 246 $PreProcessorDirectives{"warning"} = 1;
 247
 248 # Create the root DocBook output directory if it doens't exist.
 249 if (! -e $SGML_OUTPUT_DIR) {
 250     mkdir ("$SGML_OUTPUT_DIR", 0777)
 251         || die "Can't create directory: $SGML_OUTPUT_DIR";
 252 }
 253
 254 # Function and other declaration output settings.
 255 my $RETURN_TYPE_FIELD_WIDTH = 20;
 256 my $SYMBOL_FIELD_WIDTH = 36;
 257 my $SIGNAL_FIELD_WIDTH = 16;
 258
 259 &ReadKnownSymbols ("$ROOT_DIR/$MODULE-sections.txt");
 260 &ReadSignalsFile ($SIGNALS_FILE);
 261 &ReadArgsFile ($ARGS_FILE);
 262 &ReadObjectHierarchy;
 263 &ReadInterfaces;
 264 &ReadPrerequisites;
 265
 266 &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-decl.txt", 0);
 267 if (-f "$ROOT_DIR/$MODULE-overrides.txt") {
 268     &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-overrides.txt", 1);
 269 }
 270
 271 for my $dir (@SOURCE_DIRS) {
 272     &ReadSourceDocumentation ($dir);
 273 }
 274
 275 my $changed = &OutputSGML ("$ROOT_DIR/$MODULE-sections.txt");
 276
 277 # If any of the DocBook SGML files have changed, update the timestamp file (so
 278 # it can be used for Makefile dependencies).
 279 if ($changed || ! -e "$ROOT_DIR/sgml.stamp") {
 280     open (TIMESTAMP, ">$ROOT_DIR/sgml.stamp")
 281         || die "Can't create $ROOT_DIR/sgml.stamp";
 282     print (TIMESTAMP "timestamp");
 283     close (TIMESTAMP);
 284 }
 285
 286 #############################################################################
 287 # Function    : OutputObjectList
 288 # Description : This outputs the alphabetical list of objects, in a columned
 289 #               table. FIXME: Currently this also outputs ancestor objects
 290 #               which may not actually be in this module.
 291 # Arguments   : none
 292 #############################################################################
 293
 294 sub OutputObjectList {
 295     my $cols = 3;
 296     my $old_object_index = "$SGML_OUTPUT_DIR/object_index.sgml";
 297     my $new_object_index = "$SGML_OUTPUT_DIR/object_index.new";
 298
 299     open (OUTPUT, ">$new_object_index")
 300         || die "Can't create $new_object_index";
 301     print (OUTPUT <<EOF);
 302 <informaltable pgwide="1" frame="none">
 303 <tgroup cols="$cols">
 304 <colspec colwidth="1*"${empty_element_end}
 305 <colspec colwidth="1*"${empty_element_end}
 306 <colspec colwidth="1*"${empty_element_end}
 307 <tbody>
 308 EOF
 309
 310     my $count = 0;
 311     my $object;
 312     foreach $object (sort(@Objects)) {
 313         my $xref = &MakeXRef ($object);
 314         if ($count % $cols == 0) { print (OUTPUT "<row>\n"); }
 315         print (OUTPUT "<entry>$xref</entry>\n");
 316         if ($count % $cols == ($cols - 1)) { print (OUTPUT "</row>\n"); }
 317         $count++;
 318     }
 319     if ($count == 0) {
 320         # emit an empty row, since empty tables are invalid
 321         print (OUTPUT "<row><entry> </entry></row>\n");
 322     }
 323
 324     print (OUTPUT <<EOF);
 325 </tbody></tgroup></informaltable>
 326 EOF
 327     close (OUTPUT);
 328
 329     &UpdateFileIfChanged ($old_object_index, $new_object_index, 0);
 330 }
 331
 332
 333 #############################################################################
 334 # Function    : OutputSGML
 335 # Description : This collects the output for each section of the docs, and
 336 #               outputs each file when the end of the section is found.
 337 # Arguments   : $file - the $MODULE-sections.txt file which contains all of
 338 #               the functions/macros/structs etc. being documented, organised
 339 #               into sections and subsections.
 340 #############################################################################
 341
 342 sub OutputSGML {
 343     my ($file) = @_;
 344
 345 #    print "Reading: $file\n";
 346     open (INPUT, $file)
 347         || die "Can't open $file";
 348     my $book_top = "";
 349     my $book_bottom = "";
 350     my $includes = (defined $DEFAULT_INCLUDES) ? $DEFAULT_INCLUDES : "";
 351     my $section_includes = "";
 352     my $in_section = 0;
 353     my $title = "";
 354     my $subsection = "";
 355     my $synopsis;
 356     my $details;
 357     my $num_symbols;
 358     my $changed = 0;
 359     my $signals_synop = "";
 360     my $signals_desc = "";
 361     my $args_synop = "";
 362     my $child_args_synop = "";
 363     my $style_args_synop = "";
 364     my $args_desc = "";
 365     my $child_args_desc = "";
 366     my $style_args_desc = "";
 367     my $hierarchy = "";
 368     my $interfaces = "";
 369     my $implementations = "";
 370     my $prerequisites = "";
 371     my $derived = "";
 372     my @file_objects = ();
 373
 374     while (<INPUT>) {
 375         if (m/^#/) {
 376             next;
 377
 378         } elsif (m/^<SECTION>/) {
 379             $synopsis = "";
 380             $details = "";
 381             $num_symbols = 0;
 382             $in_section = 1;
 383             @file_objects = ();
 384
 385         } elsif (m/^<SUBSECTION\s*(.*)>/i) {
 386             $synopsis .= "\n";
 387             $subsection = $1;
 388
 389         } elsif (m/^<SUBSECTION>/) {
 390
 391         } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
 392             $title = $1;
 393 #           print "Section: $title\n";
 394
 395             # We don't want warnings if object & class structs aren't used.
 396             $DeclarationOutput{$title} = 1;
 397             $DeclarationOutput{"${title}Class"} = 1;
 398
 399         } elsif (m/^<FILE>(.*)<\/FILE>/) {
 400             my $sym;
 401
 402             $file = $1;
 403             %SymbolDocs = ();
 404             %SymbolTypes = ();
 405             %SymbolParams = ();
 406             &ReadTemplateFile ("$TMPL_DIR/$file", 1);
 407             &MergeSourceDocumentation;
 408
 409         } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
 410             if ($in_section) {
 411                 $section_includes = $1;
 412             } else {
 413                 if (defined $DEFAULT_INCLUDES) {
 414                     print <<EOF;
 415 WARNING: Default <INCLUDE> being overridden by command line option
 416 EOF
 417                 }
 418                 else {
 419                     $includes = $1;
 420                 }
 421             }
 422
 423         } elsif (m/^<\/SECTION>/) {
 424             if ($title eq "") {
 425                 $title = $file;
 426             }
 427 #           print "End of section: $title\n";
 428
 429             $file =~ s/\s/_/g;
 430
 431             my $section_id = $SourceSymbolDocs{"$TMPL_DIR/$file:Section_Id"};
 432             if (defined ($section_id) && $section_id !~ m/^\s*$/) {
 433                 # Do nothing. Use section_id as it is.
 434             } elsif (&CheckIsObject ($title)) {
 435                 # GtkObjects use their class name as the ID.
 436                 $section_id = &CreateValidSGMLID ($title);
 437             } else {
 438                 $section_id = &CreateValidSGMLID ("$MODULE-$title");
 439             }
 440
 441             if ($num_symbols > 0) {
 442                 if (lc($OUTPUT_FORMAT) eq "xml") {
 443                     $book_bottom .= "    <xi:include href=\"xml/$file.xml\"/>\n";
 444                 } else {
 445                     $book_top.="<!ENTITY $section_id SYSTEM \"sgml/$file.sgml\">\n";
 446                     $book_bottom .= "    &$section_id;\n";
 447                 }
 448
 449                 if (defined ($SourceSymbolDocs{"$TMPL_DIR/$file:Include"})) {
 450                     if ($section_includes) {
 451                         print <<EOF;
 452 WARNING: Section <INCLUDE> for file $file being overridden by inline comments
 453 EOF
 454                     }
 455                     $section_includes = $SourceSymbolDocs{"$TMPL_DIR/$file:Include"};
 456                 }
 457                 if ($section_includes eq "") {
 458                     $section_includes = $includes;
 459                 }
 460
 461                 if ($signals_synop ne '') {
 462                     $signals_synop = <<EOF;
 463 <refsect1 role="signal_proto">
 464 <title role="signal_proto.title">Signals</title>
 465 <synopsis>
 466
 467 ${signals_synop}</synopsis>
 468 </refsect1>
 469 EOF
 470                     $signals_desc  = <<EOF;
 471 <refsect1 role="signals">
 472 <title role="signals.title">Signal Details</title>
 473 $signals_desc
 474 </refsect1>
 475 EOF
 476                 }
 477
 478                 if ($args_synop ne '') {
 479                     $args_synop = <<EOF;
 480 <refsect1 role="properties">
 481 <title role="properties.title">Properties</title>
 482 <synopsis>
 483
 484 ${args_synop}</synopsis>
 485 </refsect1>
 486 EOF
 487                     $args_desc  = <<EOF;
 488 <refsect1 role="property_details">
 489 <title role="property_details.title">Property Details</title>
 490 $args_desc
 491 </refsect1>
 492 EOF
 493                 }
 494
 495                 if ($child_args_synop ne '') {
 496                     $args_synop .= <<EOF;
 497 <refsect1 role="child_properties">
 498 <title role="child_properties.title">Child Properties</title>
 499 <synopsis>
 500
 501 ${child_args_synop}</synopsis>
 502 </refsect1>
 503 EOF
 504                     $args_desc .= <<EOF;
 505 <refsect1 role="child_property_details">
 506 <title role="child_property_details.title">Child Property Details</title>
 507 $child_args_desc
 508 </refsect1>
 509 EOF
 510                 }
 511
 512                 if ($style_args_synop ne '') {
 513                     $args_synop .= <<EOF;
 514 <refsect1 role="style_properties">
 515 <title role="style_properties.title">Style Properties</title>
 516 <synopsis>
 517
 518 ${style_args_synop}</synopsis>
 519 </refsect1>
 520 EOF
 521                     $args_desc .= <<EOF;
 522 <refsect1 role="style_properties_details">
 523 <title role="style_properties_details.title">Style Property Details</title>
 524 $style_args_desc
 525 </refsect1>
 526 EOF
 527                 }
 528
 529                 if ($hierarchy ne "") {
 530                     $hierarchy = <<EOF;
 531 <refsect1 role="object_hierarchy">
 532 <title role="object_hierarchy.title">Object Hierarchy</title>
 533 $hierarchy
 534 </refsect1>
 535 EOF
 536                 }
 537
 538                 if ($interfaces ne "") {
 539                     $interfaces = <<EOF;
 540 <refsect1 role="impl_interfaces">
 541 <title role="impl_interfaces.title">Implemented Interfaces</title>
 542 $interfaces
 543 </refsect1>
 544 EOF
 545                 }
 546
 547                 if ($implementations ne "") {
 548                     $implementations = <<EOF;
 549 <refsect1 role="implementations">
 550 <title role="implementations.title">Known Implementations</title>
 551 $implementations
 552 </refsect1>
 553 EOF
 554                 }
 555
 556                 if ($prerequisites ne "") {
 557                     $prerequisites = <<EOF;
 558 <refsect1 role="prerequisites">
 559 <title role="prerequisites.title">Prerequisites</title>
 560 $prerequisites
 561 </refsect1>
 562 EOF
 563                 }
 564
 565                 if ($derived ne "") {
 566                     $derived = <<EOF;
 567 <refsect1 role="derived_interfaces">
 568 <title role="derived_interfaces.title">Known Derived Interfaces</title>
 569 $derived
 570 </refsect1>
 571 EOF
 572                 }
 573
 574                 my $file_changed = &OutputSGMLFile ($file, $title, $section_id,
 575                                                     $section_includes,
 576                                                     \$synopsis, \$details,
 577                                                     \$signals_synop, \$signals_desc,
 578                                                     \$args_synop, \$args_desc,
 579                                                     \$hierarchy, \$interfaces,
 580                                                     \$implementations,
 581                                                     \$prerequisites, \$derived,
 582                                                     \@file_objects);
 583                 if ($file_changed) {
 584                     $changed = 1;
 585                 }
 586             }
 587             $title = "";
 588             $subsection = "";
 589             $in_section = 0;
 590             $section_includes = "";
 591             $signals_synop = "";
 592             $signals_desc = "";
 593             $args_synop = "";
 594             $child_args_synop = "";
 595             $style_args_synop = "";
 596             $args_desc = "";
 597             $child_args_desc = "";
 598             $style_args_desc = "";
 599             $hierarchy = "";
 600             $interfaces = "";
 601             $implementations = "";
 602             $prerequisites = "";
 603             $derived = "";
 604
 605         } elsif (m/^(\S+)/) {
 606             my $symbol = $1;
 607 #           print "  Symbol: $symbol\n";
 608
 609             my $declaration = $Declarations{$symbol};
 610             if (defined ($declaration)) {
 611                 # We don't want standard macros/functions of GtkObjects,
 612                 # or private declarations.
 613                 if ($subsection ne "Standard" && $subsection ne "Private") {
 614                     if (&CheckIsObject ($symbol)) {
 615                         push @file_objects, $symbol;
 616                     }
 617                     my ($synop, $desc) = &OutputDeclaration ($symbol,
 618                                                              $declaration);
 619                     my ($sig_synop, $sig_desc) = &GetSignals ($symbol);
 620                     my ($arg_synop, $child_arg_synop, $style_arg_synop,
 621                         $arg_desc, $child_arg_desc, $style_arg_desc) = &GetArgs ($symbol);
 622                     my $hier = &GetHierarchy ($symbol);
 623                     my $ifaces = &GetInterfaces ($symbol);
 624                     my $impls = &GetImplementations ($symbol);
 625                     my $prereqs = &GetPrerequisites ($symbol);
 626                     my $der = &GetDerived ($symbol);
 627                     $synopsis .= $synop;
 628                     $details .= $desc;
 629                     $signals_synop .= $sig_synop;
 630                     $signals_desc .= $sig_desc;
 631                     $args_synop .= $arg_synop;
 632                     $child_args_synop .= $child_arg_synop;
 633                     $style_args_synop .= $style_arg_synop;
 634                     $args_desc .= $arg_desc;
 635                     $child_args_desc .= $child_arg_desc;
 636                     $style_args_desc .= $style_arg_desc;
 637                     $hierarchy .= $hier;
 638                     $interfaces .= $ifaces;
 639                     $implementations .= $impls;
 640                     $prerequisites .= $prereqs;
 641                     $derived .= $der;
 642                 }
 643
 644                 # Note that the declaration has been output.
 645                 $DeclarationOutput{$symbol} = 1;
 646             } elsif ($subsection ne "Standard" && $subsection ne "Private") {
 647                 $UndeclaredSymbols{$symbol} = 1;
 648                 print "WARNING: No declaration found for: $symbol\n";
 649             }
 650             $num_symbols++;
 651         }
 652     }
 653     close (INPUT);
 654
 655     &OutputMissingDocumentation;
 656     &OutputUndeclaredSymbols;
 657
 658     if ($OUTPUT_ALL_SYMBOLS) {
 659         &OutputAllSymbols;
 660     }
 661
 662     for $file (split (' ', $EXPAND_CONTENT_FILES)) {
 663         my $file_changed = &OutputExtraFile ($file);
 664         if ($file_changed) {
 665             $changed = 1;
 666         }
 667     }
 668
 669     &OutputBook ($book_top, $book_bottom);
 670
 671     return $changed;
 672 }
 673
 674
 675 #############################################################################
 676 # Function    : ReadKnownSymbols
 677 # Description : This collects the names of non-private symbols from the
 678 #               $MODULE-sections.txt file.
 679 # Arguments   : $file - the $MODULE-sections.txt file which contains all of
 680 #               the functions/macros/structs etc. being documented, organised
 681 #               into sections and subsections.
 682 #############################################################################
 683
 684 sub ReadKnownSymbols {
 685     my ($file) = @_;
 686
 687     my $subsection = "";
 688
 689 #    print "Reading: $file\n";
 690     open (INPUT, $file)
 691         || die "Can't open $file";
 692
 693     while (<INPUT>) {
 694         if (m/^#/) {
 695             next;
 696
 697         } elsif (m/^<SECTION>/) {
 698             $subsection = "";
 699
 700         } elsif (m/^<SUBSECTION\s*(.*)>/i) {
 701             $subsection = $1;
 702
 703         } elsif (m/^<SUBSECTION>/) {
 704             next;
 705
 706         } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
 707             next;
 708
 709         } elsif (m/^<FILE>(.*)<\/FILE>/) {
 710             next;
 711
 712         } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
 713             next;
 714
 715         } elsif (m/^<\/SECTION>/) {
 716             next;
 717
 718         } elsif (m/^(\S+)/) {
 719             my $symbol = $1;
 720
 721             if ($subsection ne "Standard" && $subsection ne "Private") {
 722                 $KnownSymbols{$symbol} = 1;
 723             }
 724             else {
 725                 $KnownSymbols{$symbol} = 0;
 726             }
 727         }
 728     }
 729     close (INPUT);
 730 }
 731
 732
 733 #############################################################################
 734 # Function    : OutputDeclaration
 735 # Description : Returns the synopsis and detailed description DocBook
 736 #               describing one function/macro etc.
 737 # Arguments   : $symbol - the name of the function/macro begin described.
 738 #               $declaration - the declaration of the function/macro.
 739 #############################################################################
 740
 741 sub OutputDeclaration {
 742     my ($symbol, $declaration) = @_;
 743
 744     my $type = $DeclarationTypes {$symbol};
 745     if ($type eq 'MACRO') {
 746         return &OutputMacro ($symbol, $declaration);
 747     } elsif ($type eq 'TYPEDEF') {
 748         return &OutputTypedef ($symbol, $declaration);
 749     } elsif ($type eq 'STRUCT') {
 750         return &OutputStruct ($symbol, $declaration);
 751     } elsif ($type eq 'ENUM') {
 752         return &OutputEnum ($symbol, $declaration);
 753     } elsif ($type eq 'UNION') {
 754         return &OutputUnion ($symbol, $declaration);
 755     } elsif ($type eq 'VARIABLE') {
 756         return &OutputVariable ($symbol, $declaration);
 757
 758     } elsif ($type eq 'FUNCTION') {
 759         return &OutputFunction ($symbol, $declaration, $type);
 760     } elsif ($type eq 'USER_FUNCTION') {
 761         return &OutputFunction ($symbol, $declaration, $type);
 762     } else {
 763         die "Unknown symbol type";
 764     }
 765 }
 766
 767
 768 #############################################################################
 769 # Function    : OutputSymbolTraits
 770 # Description : Returns the Since and StabilityLevel paragraphs for a symbol.
 771 # Arguments   : $symbol - the name of the function/macro begin described.
 772 #############################################################################
 773
 774 sub OutputSymbolTraits {
 775     my ($symbol) = @_;
 776     my $desc = "";
 777
 778     if (exists $Since{$symbol}) {
 779         $desc .= "<para role=\"since\">Since $Since{$symbol}</para>";
 780     }
 781     if (exists $StabilityLevel{$symbol}) {
 782         $desc .= "<para role=\"stability\">Stability Level: $StabilityLevel{$symbol}</para>";
 783     }
 784     return $desc;
 785 }
 786
 787
 788 #############################################################################
 789 # Function    : OutputMacro
 790 # Description : Returns the synopsis and detailed description of a macro.
 791 # Arguments   : $symbol - the macro.
 792 #               $declaration - the declaration of the macro.
 793 #############################################################################
 794
 795 sub OutputMacro {
 796     my ($symbol, $declaration) = @_;
 797     my $id = &CreateValidSGMLID ($symbol);
 798     my $condition = &MakeConditionDescription ($symbol);
 799     my $synop = &MakeReturnField("#define") . "<link linkend=\"$id\">$symbol</link>";
 800     my $desc;
 801     my $padding = "";
 802     my $args = "";
 803     my $pad;
 804
 805     if ($declaration =~ m/^\s*#\s*define(\s+)\w+(\([^\)]*\))/) {
 806         $padding = $1;
 807         $args = $2;
 808
 809         if (length ($symbol) < $SYMBOL_FIELD_WIDTH) {
 810             $synop .= (' ' x ($SYMBOL_FIELD_WIDTH - length ($symbol)));
 811         }
 812
 813         # Try to align all the lines of args correctly.
 814         $pad = ' ' x ($RETURN_TYPE_FIELD_WIDTH + $SYMBOL_FIELD_WIDTH + 1);
 815         my $args_padded = $args;
 816         $args_padded =~ s/ *\\\n */\n$pad/gm;
 817         $synop .= &CreateValidSGML ($args_padded);
 818     }
 819     $synop .= "\n";
 820
 821     if ($args ne "") {
 822         $desc = "<refsect2>\n<title><anchor id=\"$id\" role=\"macro\"${condition}${empty_element_end}${symbol}()</title>\n";
 823     } else {
 824         $desc = "<refsect2>\n<title><anchor id=\"$id\" role=\"macro\"${condition}${empty_element_end}$symbol</title>\n";
 825     }
 826     $desc .= MakeIndexterms($symbol);
 827
 828     # Don't output the macro definition if is is a conditional macro or it
 829     # looks like a function, i.e. starts with "g_" or "_?gnome_", or it is
 830     # longer than 2 lines, otherwise we get lots of complicated macros like
 831     # g_assert.
 832     if (!defined ($DeclarationConditional{$symbol}) && ($symbol !~ m/^g_/)
 833         && ($symbol !~ m/^_?gnome_/) && (($declaration =~ tr/\n//) < 2)) {
 834         $declaration = &CreateValidSGML ($declaration);
 835         $desc .= "<programlisting>$declaration</programlisting>\n";
 836     } else {
 837         $desc .= "<programlisting>" . &MakeReturnField("#define") . "$symbol";
 838         # Align each line so that if should all line up OK.
 839         $pad = ' ' x ($RETURN_TYPE_FIELD_WIDTH - length ("#define "));
 840         $args =~ s/\n/\n$pad/gm;
 841         $desc .= &CreateValidSGML ($args);
 842         $desc .= "</programlisting>\n";
 843     }
 844
 845     $desc .= &MakeDeprecationNote($symbol);
 846
 847     my $parameters = &OutputParamDescriptions ("MACRO", $symbol);
 848     my $parameters_output = 0;
 849
 850     if (defined ($SymbolDocs{$symbol})) {
 851         my $symbol_docs = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
 852
 853         # Try to insert the parameter table at the author's desired position.
 854         # Otherwise we need to tag it onto the end.
 855         if ($symbol_docs =~ s/<!--PARAMETERS-->/$parameters/) {
 856           $parameters_output = 1;
 857         }
 858         $desc .= $symbol_docs;
 859     }
 860
 861     if ($parameters_output == 0) {
 862         $desc .= $parameters;
 863     }
 864
 865     $desc .= OutputSymbolTraits ($symbol);
 866     $desc .= "</refsect2>\n";
 867     return ($synop, $desc);
 868 }
 869
 870
 871 #############################################################################
 872 # Function    : OutputTypedef
 873 # Description : Returns the synopsis and detailed description of a typedef.
 874 # Arguments   : $symbol - the typedef.
 875 #               $declaration - the declaration of the typedef,
 876 #                 e.g. 'typedef unsigned int guint;'
 877 #############################################################################
 878
 879 sub OutputTypedef {
 880     my ($symbol, $declaration) = @_;
 881     my $id = &CreateValidSGMLID ($symbol);
 882     my $condition = &MakeConditionDescription ($symbol);
 883     my $synop = &MakeReturnField("typedef") . "<link linkend=\"$id\">$symbol</link>;\n";
 884     my $desc = "<refsect2>\n<title><anchor id=\"$id\" role=\"typedef\"${condition}${empty_element_end}$symbol</title>\n";
 885
 886     $desc .= MakeIndexterms($symbol);
 887
 888     if (!defined ($DeclarationConditional{$symbol})) {
 889         $declaration = &CreateValidSGML ($declaration);
 890         $desc .= "<programlisting>$declaration</programlisting>\n";
 891     }
 892
 893     $desc .= &MakeDeprecationNote($symbol);
 894
 895     if (defined ($SymbolDocs{$symbol})) {
 896         $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
 897     }
 898     $desc .= OutputSymbolTraits ($symbol);
 899     $desc .= "</refsect2>\n";
 900     return ($synop, $desc);
 901 }
 902
 903
 904 #############################################################################
 905 # Function    : OutputStruct
 906 # Description : Returns the synopsis and detailed description of a struct.
 907 #               We check if it is a widget struct, and if so we only output
 908 #               parts of it that are noted as public fields.
 909 #               We also use a different SGML ID for widget structs, since the
 910 #               original ID is used for the entire RefEntry.
 911 # Arguments   : $symbol - the struct.
 912 #               $declaration - the declaration of the struct.
 913 #############################################################################
 914
 915 sub OutputStruct {
 916     my ($symbol, $declaration) = @_;
 917
 918     my $is_widget_struct = 0;
 919     my $default_to_public = 1;
 920     if (&CheckIsObject ($symbol)) {
 921 #       print "Found widget struct: $symbol\n";
 922         $is_widget_struct = 1;
 923         $default_to_public = 0;
 924     }
 925
 926     my $id;
 927     my $condition;
 928     if ($is_widget_struct) {
 929         $id = &CreateValidSGMLID ($symbol . "_struct");
 930         $condition = &MakeConditionDescription ($symbol . "_struct");
 931     } else {
 932         $id = &CreateValidSGMLID ($symbol);
 933         $condition = &MakeConditionDescription ($symbol);
 934     }
 935
 936     # Determine if it is a simple struct or it also has a typedef.
 937     my $has_typedef = 0;
 938     if ($StructHasTypedef{$symbol} || $declaration =~ m/^\s*typedef\s+/) {
 939       $has_typedef = 1;
 940     }
 941
 942     my $synop;
 943     my $desc;
 944     if ($has_typedef) {
 945         # For structs with typedefs we just output the struct name.
 946         $synop = &MakeReturnField("") . "<link linkend=\"$id\">$symbol</link>;\n";
 947         $desc = "<refsect2>\n<title><anchor id=\"$id\" role=\"struct\"${condition}${empty_element_end}$symbol</title>\n";
 948     } else {
 949         $synop = &MakeReturnField("struct") . "<link linkend=\"$id\">$symbol</link>;\n";
 950         $desc = "<refsect2>\n<title><anchor id=\"$id\" role=\"struct\"${condition}${empty_element_end}struct $symbol</title>\n";
 951     }
 952
 953     $desc .= MakeIndexterms($symbol);
 954
 955     # Form a pretty-printed, private-data-removed form of the declaration
 956
 957     my $decl_out = "";
 958     if ($declaration =~ m/^\s*$/) {
 959 #       print "Found opaque struct: $symbol\n";
 960         $decl_out = "typedef struct _$symbol $symbol;";
 961     } elsif ($declaration =~ m/^\s*struct\s+\w+\s*;\s*$/) {
 962 #       print "Found opaque struct: $symbol\n";
 963         $decl_out = "struct $symbol;";
 964     } else {
 965         my $public = $default_to_public;
 966         my $new_declaration = "";
 967         my $decl_line;
 968         my $decl = $declaration;
 969
 970         if ($decl =~ m/^\s*(typedef\s+)?struct\s*\w*\s*(?:\/\*.*\*\/)?\s*{(.*)}\s*\w*\s*;\s*$/s) {
 971             my $struct_contents = $2;
 972
 973             foreach $decl_line (split (/\n/, $struct_contents)) {
 974 #               print "Struct line: $decl_line\n";
 975                 if ($decl_line =~ m%/\*\s*<\s*public\s*>\s*\*/%) {
 976                     $public = 1;
 977                 } elsif ($decl_line =~ m%/\*\s*<\s*(private|protected)\s*>\s*\*/%) {
 978                     $public = 0;
 979                 } elsif ($public) {
 980                     $new_declaration .= $decl_line . "\n";
 981                 }
 982             }
 983
 984             if ($new_declaration) {
 985                 # Strip any blank lines off the ends.
 986                 $new_declaration =~ s/^\s*\n//;
 987                 $new_declaration =~ s/\n\s*$/\n/;
 988
 989                 if ($has_typedef) {
 990                     $decl_out = "typedef struct {\n" . $new_declaration
 991                       . "} $symbol;\n";
 992                 } else {
 993                     $decl_out = "struct $symbol {\n" . $new_declaration
 994                       . "};\n";
 995                 }
 996             }
 997         } else {
 998             print "WARNING: Couldn't parse struct:\n$declaration\n";
 999         }
1000
1001         # If we couldn't parse the struct or it was all private, output an
1002         # empty struct declaration.
1003         if ($decl_out eq "") {
1004             if ($has_typedef) {
1005                 $decl_out = "typedef struct _$symbol $symbol;";
1006             } else {
1007                 $decl_out = "struct $symbol;";
1008             }
1009         }
1010     }
1011
1012     $decl_out = &CreateValidSGML ($decl_out);
1013     $desc .= "<programlisting>$decl_out</programlisting>\n";
1014
1015     $desc .= &MakeDeprecationNote($symbol);
1016
1017     if (defined ($SymbolDocs{$symbol})) {
1018         $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
1019     }
1020
1021     # Create a table of fields and descriptions
1022
1023     # FIXME: Inserting &nbsp's into the produced type declarations here would
1024     #        improve the output in most situations ... except for function
1025     #        members of structs!
1026     my @fields = ParseStructDeclaration($declaration, !$default_to_public,
1027                                         0, \&MakeXRef,
1028                                         sub {
1029                                             "<structfield>$_[0]</structfield>";
1030                                         });
1031     my $params = $SymbolParams{$symbol};
1032
1033     # If no parameters are filled in, we don't generate the description
1034     # table, for backwards compatibility
1035
1036     my $found = 0;
1037     if (defined $params) {
1038         for (my $i = 1; $i <= $#$params; $i += 2) {
1039             if ($params->[$i] =~ /\S/) {
1040                 $found = 1;
1041                 last;
1042             }
1043         }
1044     }
1045
1046     if ($found) {
1047         my %field_descrs = @$params;
1048
1049             $desc .= <<EOF;
1050 <variablelist role="struct">
1051 EOF
1052         while (@fields) {
1053             my $field_name = shift @fields;
1054             my $text = shift @fields;
1055             my $field_descr = $field_descrs{$field_name};
1056
1057             $desc .= "<varlistentry>\n<term>$text</term>\n";
1058             if (defined $field_descr) {
1059                 $desc .= "<listitem><simpara>".&ExpandAbbreviations($symbol, $field_descr)."</simpara></listitem>\n";
1060             } else {
1061                 $desc .= "<listitem></listitem>\n";
1062             }
1063             $desc .= "</varlistentry>\n";
1064         }
1065
1066         $desc .= "</variablelist>";
1067     }
1068     $desc .= OutputSymbolTraits ($symbol);
1069     $desc .= "</refsect2>\n";
1070     return ($synop, $desc);
1071 }
1072
1073
1074 #############################################################################
1075 # Function    : OutputEnum
1076 # Description : Returns the synopsis and detailed description of a enum.
1077 # Arguments   : $symbol - the enum.
1078 #               $declaration - the declaration of the enum.
1079 #############################################################################
1080
1081 sub OutputEnum {
1082     my ($symbol, $declaration) = @_;
1083     my $id = &CreateValidSGMLID ($symbol);
1084     my $condition = &MakeConditionDescription ($symbol);
1085     my $synop = &MakeReturnField("enum") . "<link linkend=\"$id\">$symbol</link>;\n";
1086     my $desc = "<refsect2>\n<title><anchor id=\"$id\" role=\"enum\"${condition}${empty_element_end}enum $symbol</title>\n";
1087
1088     $desc .= MakeIndexterms($symbol);
1089
1090     $declaration = &CreateValidSGML ($declaration);
1091     $desc .= "<programlisting>$declaration</programlisting>\n";
1092
1093     $desc .= &MakeDeprecationNote($symbol);
1094
1095     if (defined ($SymbolDocs{$symbol})) {
1096         $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
1097     }
1098
1099     # Create a table of fields and descriptions
1100
1101     my @members = ParseEnumDeclaration($declaration);
1102     my $params = $SymbolParams{$symbol};
1103
1104     # If no parameters are filled in, we don't generate the description
1105     # table, for backwards compatibility
1106
1107     my $found = 0;
1108     if (defined $params) {
1109         for (my $i = 1; $i <= $#$params; $i += 2) {
1110             if ($params->[$i] =~ /\S/) {
1111                 $found = 1;
1112                 last;
1113             }
1114         }
1115     }
1116
1117     if ($found) {
1118         my %member_descrs = @$params;
1119
1120             $desc .= <<EOF;
1121 <variablelist role="enum">
1122 EOF
1123         for my $member_name (@members) {
1124             my $member_descr = $member_descrs{$member_name};
1125
1126             $id = &CreateValidSGMLID ($member_name);
1127             $condition = &MakeConditionDescription ($member_name);
1128             $desc .= "<varlistentry>\n<term><anchor id=\"$id\" role=\"constant\"${condition}${empty_element_end}<literal>$member_name</literal></term>\n";
1129             if (defined $member_descr) {
1130                 $desc .= "<listitem><simpara>".&ExpandAbbreviations($symbol, $member_descr)."</simpara></listitem>\n";
1131             } else {
1132                 $desc .= "<listitem></listitem>\n";
1133             }
1134             $desc .= "</varlistentry>\n";
1135         }
1136
1137         $desc .= "</variablelist>";
1138     }
1139
1140     $desc .= OutputSymbolTraits ($symbol);
1141     $desc .= "</refsect2>\n";
1142     return ($synop, $desc);
1143 }
1144
1145
1146 #############################################################################
1147 # Function    : OutputUnion
1148 # Description : Returns the synopsis and detailed description of a union.
1149 # Arguments   : $symbol - the union.
1150 #               $declaration - the declaration of the union.
1151 #############################################################################
1152
1153 sub OutputUnion {
1154     my ($symbol, $declaration) = @_;
1155     my $id = &CreateValidSGMLID ($symbol);
1156     my $condition = &MakeConditionDescription ($symbol);
1157     my $synop = &MakeReturnField("union") . "<link linkend=\"$id\">$symbol</link>;\n";
1158     my $desc = "<refsect2>\n<title><anchor id=\"$id\" role=\"union\"${condition}${empty_element_end}union $symbol</title>\n";
1159
1160     $desc .= MakeIndexterms($symbol);
1161
1162     $declaration = &CreateValidSGML ($declaration);
1163     $desc .= "<programlisting>$declaration</programlisting>\n";
1164
1165     $desc .= &MakeDeprecationNote($symbol);
1166
1167     if (defined ($SymbolDocs{$symbol})) {
1168         $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
1169     }
1170     $desc .= OutputSymbolTraits ($symbol);
1171     $desc .= "</refsect2>\n";
1172     return ($synop, $desc);
1173 }
1174
1175
1176 #############################################################################
1177 # Function    : OutputVariable
1178 # Description : Returns the synopsis and detailed description of a variable.
1179 # Arguments   : $symbol - the extern'ed variable.
1180 #               $declaration - the declaration of the variable.
1181 #############################################################################
1182
1183 sub OutputVariable {
1184     my ($symbol, $declaration) = @_;
1185     my $id = &CreateValidSGMLID ($symbol);
1186     my $condition = &MakeConditionDescription ($symbol);
1187
1188     my $synop;
1189     if ($declaration =~ m/^\s*extern\s+((const\s+|unsigned\s+)*\w+)(\s+\*+|\*+|\s)(\s*)([A-Za-z]\w*)\s*;/) {
1190         my $mod = defined ($1) ? $1 : "";
1191         my $ptr = defined ($3) ? $3 : "";
1192         my $space = defined ($4) ? $4 : "";
1193         $synop = &MakeReturnField("extern") . "$mod$ptr$space<link linkend=\"$id\">$symbol</link>;\n";
1194
1195     } else {
1196         $synop = &MakeReturnField("extern") . "<link linkend=\"$id\">$symbol</link>;\n";
1197     }
1198
1199     my $desc = "<refsect2>\n<title><anchor id=\"$id\" role=\"variable\"${condition}${empty_element_end}$symbol</title>\n";
1200
1201     $desc .= MakeIndexterms($symbol);
1202
1203     $declaration = &CreateValidSGML ($declaration);
1204     $desc .= "<programlisting>$declaration</programlisting>\n";
1205
1206     $desc .= &MakeDeprecationNote($symbol);
1207
1208     if (defined ($SymbolDocs{$symbol})) {
1209         $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
1210     }
1211     $desc .= OutputSymbolTraits ($symbol);
1212     $desc .= "</refsect2>\n";
1213     return ($synop, $desc);
1214 }
1215
1216
1217 #############################################################################
1218 # Function    : OutputFunction
1219 # Description : Returns the synopsis and detailed description of a function.
1220 # Arguments   : $symbol - the function.
1221 #               $declaration - the declaration of the function.
1222 #############################################################################
1223
1224 sub OutputFunction {
1225     my ($symbol, $declaration, $symbol_type) = @_;
1226     my $id = &CreateValidSGMLID ($symbol);
1227     my $condition = &MakeConditionDescription ($symbol);
1228
1229     # Take out the return type
1230     $declaration =~ s/<RETURNS>\s*((const\s+|G_CONST_RETURN\s+|unsigned\s+|struct\s+|enum\s+)*)(\w+)\s*(\**\s*(const|G_CONST_RETURN)?\s*\**\s*(restrict)?\s*)<\/RETURNS>\n//;
1231     my $type_modifier = defined($1) ? $1 : "";
1232     my $type = $3;
1233     my $pointer = $4;
1234 #   print "$symbol pointer is $pointer\n";
1235     my $xref = &MakeXRef ($type);
1236     my $start = "";
1237     if ($symbol_type eq 'USER_FUNCTION') {
1238 #       $start = "typedef ";
1239     }
1240
1241     # We output const rather than G_CONST_RETURN.
1242     $type_modifier =~ s/G_CONST_RETURN/const/g;
1243     $pointer =~ s/G_CONST_RETURN/const/g;
1244
1245     my $ret_type_len = length ($start) + length ($type_modifier)
1246         + length ($pointer) + length ($type);
1247     my $ret_type_output;
1248     my $symbol_len;
1249     if ($ret_type_len < $RETURN_TYPE_FIELD_WIDTH) {
1250         $ret_type_output = "$start$type_modifier$xref$pointer"
1251             . (' ' x ($RETURN_TYPE_FIELD_WIDTH - $ret_type_len));
1252         $symbol_len = 0;
1253     } else {
1254 #       $ret_type_output = "$start$type_modifier$xref$pointer\n"
1255 #           . (' ' x $RETURN_TYPE_FIELD_WIDTH);
1256
1257         $ret_type_output = "$start$type_modifier$xref$pointer ";
1258         $symbol_len = $ret_type_len + 1 - $RETURN_TYPE_FIELD_WIDTH;
1259     }
1260
1261     $symbol_len += length ($symbol);
1262     my $char1 = my $char2 = my $char3 = "";
1263     if ($symbol_type eq 'USER_FUNCTION') {
1264         $symbol_len += 3;
1265         $char1 = "(";
1266         $char2 = "*";
1267         $char3 = ")";
1268     }
1269
1270     my ($symbol_output, $symbol_desc_output);
1271     if ($symbol_len < $SYMBOL_FIELD_WIDTH) {
1272         $symbol_output = "$char1<link linkend=\"$id\">$char2$symbol</link>$char3"
1273             . (' ' x ($SYMBOL_FIELD_WIDTH - $symbol_len));
1274         $symbol_desc_output = "$char1$char2$symbol$char3"
1275             . (' ' x ($SYMBOL_FIELD_WIDTH - $symbol_len));
1276     } else {
1277         $symbol_output = "$char1<link linkend=\"$id\">$char2$symbol</link>$char3\n"
1278             . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH));
1279         $symbol_desc_output = "$char1$char2$symbol$char3\n"
1280             . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH));
1281     }
1282
1283     my $synop = $ret_type_output . $symbol_output . '(';
1284     my $desc = "<refsect2>\n<title><anchor id=\"$id\" role=\"function\"${condition}${empty_element_end}${symbol} ()</title>\n";
1285
1286     $desc .= MakeIndexterms($symbol);
1287
1288     $desc  .= "<programlisting>${ret_type_output}$symbol_desc_output(";
1289
1290     my $param_num = 0;
1291     while ($declaration ne "") {
1292         #print "$declaration";
1293
1294         if ($declaration =~ s/^[\s,]+//) {
1295             # skip whitespace and commas
1296             next;
1297
1298         } elsif ($declaration =~ s/^void\s*[,\n]//) {
1299             $synop .= "void";
1300             $desc  .= "void";
1301
1302         } elsif ($declaration =~ s/^...\s*[,\n]//) {
1303             if ($param_num == 0) {
1304                 $synop .= "...";
1305                 $desc  .= "...";
1306             } else {
1307                 $synop .= ",\n"
1308                     . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH))
1309                     . " ...";
1310                 $desc  .= ",\n"
1311                     . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH))
1312                     . " ...";
1313             }
1314
1315         # allow alphanumerics, '_', '[' & ']' in param names
1316         # Try to match a standard parameter (keep in sync with gtkdoc-mktmpl)
1317         #                                $1                                                                                                                                    $2                             $3                                                           $4       $5
1318         } elsif ($declaration =~ s/^\s*((?:G_CONST_RETURN|G_GNUC_UNUSED|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b)?\s*\*?\s*(?:const\b|restrict\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*[,\n]//) {
1319             my $pre     = defined($1) ? $1 : "";
1320             my $type    = $2;
1321             my $ptr     = defined($3) ? $3 : "";
1322             my $name    = defined($4) ? $4 : "";
1323             my $array   = defined($5) ? $5 : "";
1324
1325             $pre  =~ s/\s+/ /g;
1326             $type =~ s/\s+/ /g;
1327             $ptr  =~ s/\s+/ /g;
1328             $ptr  =~ s/\s+$//;
1329             if ($ptr && $ptr !~ m/\*$/) { $ptr .= " "; }
1330
1331             #print "$symbol: '$pre' '$type' '$ptr' '$name' '$array'\n";
1332
1333             if (($name eq "") && $pre =~ m/^((un)?signed .*)\s?/ ) {
1334                 $name = $type;
1335                 $type = "$1";
1336                 $pre = "";
1337             }
1338
1339             my $xref = &MakeXRef ($type);
1340             my $label   = "$pre$xref $ptr$name$array";
1341
1342             #print "$symbol: '$pre' '$type' '$ptr' '$name' '$array'\n";
1343
1344             if ($param_num == 0) {
1345                 $synop .= "$label";
1346                 $desc  .= "$label";
1347             } else {
1348                 $synop .= ",\n"
1349                     . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH))
1350                     . " $label";
1351                 $desc  .= ",\n"
1352                     . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH))
1353                     . " $label";
1354             }
1355
1356         # Try to match parameters which are functions (keep in sync with gtkdoc-mktmpl)
1357         #                              $1                                       $2          $3      $4                        $5                    $7             $8
1358         } elsif ($declaration =~ s/^(const\s+|G_CONST_RETURN\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*\*+\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]//) {
1359             my $mod1 = defined($1) ? $1 : "";
1360             if (defined($2)) { $mod1 .= $2; }
1361             my $type = $3;
1362             my $ptr1 = $4;
1363             my $mod2 = defined($5) ? $5 : "";
1364             my $func_ptr = $6;
1365             my $name = $7;
1366             my $func_params = $8;
1367
1368             if ($ptr1 && $ptr1 !~ m/\*$/) { $ptr1 .= " "; }
1369             $func_ptr  =~ s/\s+//g;
1370             my $xref = &MakeXRef ($type);
1371             my $label = "$mod1$xref$ptr1$mod2 ($func_ptr$name) ($func_params)";
1372
1373             #print "Type: $mod1$type$ptr1$mod2($func_ptr$name)($func_params)\n";
1374             if ($param_num == 0) {
1375                 $synop .= "$label";
1376                 $desc  .= "$label";
1377             } else {
1378                 $synop .= ",\n"
1379                     . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH))
1380                     . " $label";
1381                 $desc  .= ",\n"
1382                     . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH))
1383                     . " $label";
1384             }
1385
1386         } else {
1387             print "###Can't parse args for function $symbol: $declaration\n";
1388             last;
1389         }
1390         $param_num++;
1391     }
1392     $synop .= ");\n";
1393     $desc  .= ");</programlisting>\n";
1394
1395     $desc .= &MakeDeprecationNote($symbol);
1396
1397     my $parameters = &OutputParamDescriptions ("FUNCTION", $symbol);
1398     my $parameters_output = 0;
1399
1400     if (defined ($SymbolDocs{$symbol})) {
1401         my $symbol_docs = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
1402
1403         # Try to insert the parameter table at the author's desired position.
1404         # Otherwise we need to tag it onto the end.
1405         if ($symbol_docs =~ s/<!--PARAMETERS-->/$parameters/) {
1406           $parameters_output = 1;
1407         }
1408         $desc .= $symbol_docs;
1409     }
1410
1411     if ($parameters_output == 0) {
1412         $desc .= $parameters;
1413     }
1414
1415     $desc .= OutputSymbolTraits ($symbol);
1416     $desc .= "</refsect2>\n";
1417     return ($synop, $desc);
1418 }
1419
1420
1421 #############################################################################
1422 # Function    : OutputParamDescriptions
1423 # Description : Returns the DocBook output describing the parameters of a
1424 #               function, macro or signal handler.
1425 # Arguments   : $symbol_type - 'FUNCTION', 'MACRO' or 'SIGNAL'. Signal
1426 #                 handlers have an implicit user_data parameter last.
1427 #               $symbol - the name of the function/macro being described.
1428 #############################################################################
1429
1430 sub OutputParamDescriptions {
1431     my ($symbol_type, $symbol) = @_;
1432     my $output = "";
1433     if (defined ($SymbolParams{$symbol})) {
1434         my $returns = "";
1435         my $params = $SymbolParams{$symbol};
1436         my $params_desc = "";
1437         my $j;
1438         for ($j = 0; $j <= $#$params; $j += 2) {
1439             my $param_name = $$params[$j];
1440             my $param = $$params[$j + 1];
1441             if ($param_name eq "Returns") {
1442                 $returns = &ExpandAbbreviations($symbol, $param);
1443             } else {
1444                 if ($param_name eq "Varargs") {
1445                     $param_name = "...";
1446                 }
1447                 $param = &ExpandAbbreviations($symbol, $param);
1448                 $params_desc .= "<varlistentry><term><parameter>$param_name</parameter>&nbsp;:</term>\n<listitem><simpara>$param</simpara></listitem></varlistentry>\n";
1449             }
1450         }
1451
1452         # Signals have an implicit user_data parameter which we describe.
1453         if ($symbol_type eq "SIGNAL") {
1454             $params_desc .= "<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>\n<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>\n";
1455         }
1456
1457         # Start a table if we need one.
1458         if ($params_desc || $returns) {
1459             $output .= <<EOF;
1460 <variablelist role="params">
1461 EOF
1462
1463             if ($params_desc ne "") {
1464 #               $output .= "<varlistentry><term>Parameters:</term><listitem></listitem></varlistentry>\n";
1465                 $output .= $params_desc;
1466             }
1467
1468             # Output the returns info last.
1469             if ($returns) {
1470                 $output .= "<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>$returns</simpara></listitem></varlistentry>\n";
1471             }
1472
1473             # Finish the table.
1474             $output .= "</variablelist>";
1475         }
1476     }
1477     return $output;
1478 }
1479
1480
1481 #############################################################################
1482 # Function    : ParseStabilityLevel
1483 # Description : Parses a stability level and outputs a warning if it isn't
1484 #               valid.
1485 # Arguments   : $stability - the stability text.
1486 #               $message - description of where the level is from, to use in
1487 #               any error message.
1488 # Returns     : The parsed stability level string.
1489 #############################################################################
1490
1491 sub ParseStabilityLevel {
1492     my ($stability, $message) = @_;
1493
1494     $stability =~ s/^\s*//;
1495     $stability =~ s/\s*$//;
1496     if ($stability =~ m/^stable$/i) {
1497         $stability = "Stable";
1498     } elsif ($stability =~ m/^unstable$/i) {
1499         $stability = "Unstable";
1500     } elsif ($stability =~ m/^private$/i) {
1501         $stability = "Private";
1502     } else {
1503         print <<EOF;
1504 WARNING: $message is $stability.
1505 It should be one of these: Stable, Unstable, or Private.
1506 EOF
1507     }
1508     return $stability;
1509 }
1510
1511
1512 #############################################################################
1513 # Function    : OutputSGMLFile
1514 # Description : Outputs the final DocBook file for one section.
1515 # Arguments   : $file - the name of the file.
1516 #               $title - the title from the $MODULE-sections.txt file, which
1517 #                 will be overridden by the title in the template file.
1518 #               $section_id - the SGML id to use for the toplevel tag.
1519 #               $includes - comma-separates list of include files added at top
1520 #                 of synopsis, with '<' '>' around them (if not already enclosed in "").
1521 #               $synopsis - reference to the DocBook for the Synopsis part.
1522 #               $details - reference to the DocBook for the Details part.
1523 #               $signal_synop - reference to the DocBook for the Signal Synopsis part
1524 #               $signal_desc - reference to the DocBook for the Signal Description part
1525 #               $args_synop - reference to the DocBook for the Arg Synopsis part
1526 #               $args_desc - reference to the DocBook for the Arg Description part
1527 #               $hierarchy - reference to the DocBook for the Object Hierarchy part
1528 #               $interfaces - reference to the DocBook for the Interfaces part
1529 #               $implementations - reference to the DocBook for the Known Implementations part
1530 #               $prerequisites - reference to the DocBook for the Prerequisites part
1531 #               $derived - reference to the DocBook for the Derived Interfaces part
1532 #               $file_objects - reference to an array of objects in this file
1533 #############################################################################
1534
1535 sub OutputSGMLFile {
1536     my ($file, $title, $section_id, $includes, $synopsis, $details, $signals_synop, $signals_desc, $args_synop, $args_desc, $hierarchy, $interfaces, $implementations, $prerequisites, $derived, $file_objects) = @_;
1537
1538     # The edited title overrides the one from the sections file.
1539     my $new_title = $SymbolDocs{"$TMPL_DIR/$file:Title"};
1540     if (defined ($new_title) && $new_title !~ m/^\s*$/) {
1541         $title = $new_title;
1542 #       print "Found title: $title\n";
1543     }
1544     my $short_desc = $SymbolDocs{"$TMPL_DIR/$file:Short_Description"};
1545     if (!defined ($short_desc) || $short_desc =~ m/^\s*$/) {
1546 #       $short_desc = "one line description goes here.";
1547         $short_desc = "";
1548     } else {
1549         $short_desc = &ExpandAbbreviations("$title:Short_description",
1550                                            $short_desc);
1551 #       print "Found short_desc: $short_desc";
1552     }
1553     my $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
1554     if (!defined ($long_desc) || $long_desc =~ m/^\s*$/) {
1555         $long_desc = "<para>\nA longer description goes here.\n</para>\n";
1556     } else {
1557         $long_desc = &ExpandAbbreviations("$title:Long_description",
1558                                           $long_desc);
1559 #       print "Found long_desc: $long_desc";
1560     }
1561     my $see_also = $SymbolDocs{"$TMPL_DIR/$file:See_Also"};
1562     if (!defined ($see_also) || $see_also =~ m%^\s*(<para>)?\s*(</para>)?\s*$%) {
1563         $see_also = "";
1564     } else {
1565         $see_also = &ExpandAbbreviations("$title:See_Also", $see_also);
1566 #       print "Found see_also: $see_also";
1567     }
1568     if ($see_also) {
1569         $see_also = "<refsect1>\n<title>See Also</title>\n$see_also\n</refsect1>\n";
1570     }
1571     my $stability = $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
1572     if (!defined ($stability) || $stability =~ m/^\s*$/) {
1573         $stability = "";
1574     } else {
1575         $stability = &ParseStabilityLevel($stability, "Section stability level for $file");
1576 #       print "Found stability: $stability";
1577     }
1578     if ($stability) {
1579         $stability = "<refsect1>\n<title>Stability Level</title>\n$stability, unless otherwise indicated\n</refsect1>\n";
1580     } elsif ($DEFAULT_STABILITY) {
1581         $stability = "<refsect1>\n<title>Stability Level</title>\n$DEFAULT_STABILITY, unless otherwise indicated\n</refsect1>\n";
1582     }
1583
1584     my ($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) =
1585         gmtime (time);
1586     my $month = (qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec))[$mon];
1587     $year += 1900;
1588
1589     my $include_output = "";
1590     my $include;
1591     foreach $include (split (/,/, $includes)) {
1592         if ($include =~ m/^\".+\"$/) {
1593             $include_output .= "#include ${include}\n";
1594         }
1595         else {
1596             $include =~ s/^\s+|\s+$//gs;
1597             $include_output .= "#include &lt;${include}&gt;\n";
1598         }
1599     }
1600
1601     my $old_sgml_file = "$SGML_OUTPUT_DIR/$file.$OUTPUT_FORMAT";
1602     my $new_sgml_file = "$SGML_OUTPUT_DIR/$file.$OUTPUT_FORMAT.new";
1603
1604     open (OUTPUT, ">$new_sgml_file")
1605         || die "Can't create $new_sgml_file";
1606
1607     my $object_anchors = "";
1608     foreach my $object (@$file_objects) {
1609         next if ($object eq $section_id);
1610         my $id = CreateValidSGMLID($object);
1611 #       print "Debug: Adding anchor for $object\n";
1612         $object_anchors .= "<anchor id=\"$id\"$empty_element_end";
1613     }
1614
1615     # We used to output this, but is messes up our UpdateFileIfChanged code
1616     # since it changes every day (and it is only used in the man pages):
1617     # "<refentry id="$section_id" revision="$mday $month $year">"
1618
1619     if (lc($OUTPUT_FORMAT) eq "xml") {
1620         print OUTPUT $doctype_header;
1621     }
1622
1623     print OUTPUT <<EOF;
1624 <refentry id="$section_id">
1625 <refmeta>
1626 <refentrytitle role="top_of_page">$title</refentrytitle>
1627 <manvolnum>3</manvolnum>
1628 <refmiscinfo>\U$MODULE\E Library</refmiscinfo>
1629 </refmeta>
1630
1631 <refnamediv>
1632 <refname>$title</refname>
1633 <refpurpose>$short_desc</refpurpose>
1634 <!--[<xref linkend="desc" endterm="desc.title"/>]-->
1635 </refnamediv>
1636 $stability
1637 <refsynopsisdiv role="synopsis">
1638 <title role="synopsis.title">Synopsis</title>
1639 $object_anchors
1640 <synopsis>
1641
1642 $include_output
1643
1644 $${synopsis}</synopsis>
1645 </refsynopsisdiv>
1646
1647 $$hierarchy
1648 $$prerequisites
1649 $$derived
1650 $$interfaces
1651 $$implementations
1652 $$args_synop
1653 $$signals_synop
1654
1655 <refsect1 role="desc">
1656 <title role="desc.title">Description</title>
1657 $long_desc
1658 </refsect1>
1659
1660 <refsect1 role="details">
1661 <title role="details.title">Details</title>
1662 $$details
1663 </refsect1>
1664 $$args_desc
1665 $$signals_desc
1666
1667 $see_also
1668
1669 <refsect1><refsect2 /><refsect2 /></refsect1>
1670 </refentry>
1671 EOF
1672 # This above is a hack to get a final <hr> in the output
1673
1674     close (OUTPUT);
1675
1676     return &UpdateFileIfChanged ($old_sgml_file, $new_sgml_file, 0);
1677 }
1678
1679
1680 #############################################################################
1681 # Function    : OutputExtraFile
1682 # Description : Copies an "extra" DocBook file into the output directory,
1683 #               expanding abbreviations
1684 # Arguments   : $file - the source file.
1685 #############################################################################
1686 sub OutputExtraFile {
1687     my ($file) = @_;
1688
1689     my $basename;
1690
1691     ($basename = $file) =~ s!^.*/!!;
1692
1693     my $old_sgml_file = "$SGML_OUTPUT_DIR/$basename";
1694     my $new_sgml_file = "$SGML_OUTPUT_DIR/$basename.new";
1695
1696     my $contents;
1697
1698     open(EXTRA_FILE, "<$file") || die "Can't open $file";
1699
1700     {
1701         local $/;
1702         $contents = <EXTRA_FILE>;
1703     }
1704
1705     open (OUTPUT, ">$new_sgml_file")
1706         || die "Can't create $new_sgml_file";
1707
1708     print OUTPUT &ExpandAbbreviations ("$basename file", $contents);
1709     close (OUTPUT);
1710
1711     return &UpdateFileIfChanged ($old_sgml_file, $new_sgml_file, 0);
1712 }
1713
1714 #############################################################################
1715 # Function    : OutputBook
1716 # Description : Outputs the SGML entities that need to be included into the
1717 #               main SGML file for the module.
1718 # Arguments   : $book_top - the declarations of the entities, which are added
1719 #                 at the top of the main SGML file.
1720 #               $book_bottom - the references to the entities, which are
1721 #                 added in the main SGML file at the desired position.
1722 #############################################################################
1723
1724 sub OutputBook {
1725     my ($book_top, $book_bottom) = @_;
1726
1727     my $old_file = "$SGML_OUTPUT_DIR/$MODULE-doc.top";
1728     my $new_file = "$SGML_OUTPUT_DIR/$MODULE-doc.top.new";
1729
1730     open (OUTPUT, ">$new_file")
1731         || die "Can't create $new_file";
1732     print OUTPUT $book_top;
1733     close (OUTPUT);
1734
1735     &UpdateFileIfChanged ($old_file, $new_file, 0);
1736
1737
1738     $old_file = "$SGML_OUTPUT_DIR/$MODULE-doc.bottom";
1739     $new_file = "$SGML_OUTPUT_DIR/$MODULE-doc.bottom.new";
1740
1741     open (OUTPUT, ">$new_file")
1742         || die "Can't create $new_file";
1743     print OUTPUT $book_bottom;
1744     close (OUTPUT);
1745
1746     &UpdateFileIfChanged ($old_file, $new_file, 0);
1747
1748
1749     # If the main SGML file hasn't been created yet, we create it here.
1750     # The user can tweak it later.
1751     if ($MAIN_SGML_FILE && ! -e $MAIN_SGML_FILE) {
1752       open (OUTPUT, ">$MAIN_SGML_FILE")
1753         || die "Can't create $MAIN_SGML_FILE";
1754
1755       if (lc($OUTPUT_FORMAT) eq "xml") {
1756           print OUTPUT <<EOF;
1757 <?xml version="1.0"?>
1758 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
1759                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
1760 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
1761 EOF
1762       } else {
1763         print OUTPUT <<EOF;
1764 <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
1765 EOF
1766         print OUTPUT $book_top;
1767         print OUTPUT <<EOF;
1768 ]>
1769 <book id="index">
1770 EOF
1771       }
1772
1773 print OUTPUT <<EOF;
1774   <bookinfo>
1775     <title>$MODULE Reference Manual</title>
1776     <releaseinfo>
1777       for $MODULE [VERSION]
1778       The latest version of this documentation can be found on-line at
1779       <ulink role="online-location" url="http://[SERVER]/$MODULE/index.html">http://[SERVER]/$MODULE/</ulink>.
1780     </releaseinfo>
1781   </bookinfo>
1782
1783   <chapter>
1784     <title>[Insert title here]</title>
1785 EOF
1786       print OUTPUT $book_bottom;
1787
1788       print OUTPUT <<EOF;
1789   </chapter>
1790 </book>
1791 EOF
1792
1793       close (OUTPUT);
1794     }
1795 }
1796
1797
1798 #############################################################################
1799 # Function    : CreateValidSGMLID
1800 # Description : Creates a valid SGML 'id' from the given string.
1801 #               NOTE: SGML ids are case-insensitive, so we have a few special
1802 #                     cases to avoid clashes of ids.
1803 # Arguments   : $id - the string to be converted into a valid SGML id.
1804 #############################################################################
1805
1806 sub CreateValidSGMLID {
1807     my ($id) = $_[0];
1808
1809     # Append ":CAPS" to all all-caps identifiers
1810
1811     # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
1812     if ($id eq "_") { return "gettext-macro"; }
1813
1814     if ($id !~ /[a-z]/) { $id .= ":CAPS" };
1815
1816     $id =~ s/[_ ]/-/g;
1817     $id =~ s/[,\.]//g;
1818     $id =~ s/^-*//;
1819     $id =~ s/::/-/g;
1820
1821     return $id;
1822 }
1823
1824
1825 #############################################################################
1826 # Function    : CreateValidSGML
1827 # Description : This turns any chars which are used in SGML into entities,
1828 #               e.g. '<' into '&lt;'
1829 # Arguments   : $text - the text to turn into proper SGML.
1830 #############################################################################
1831
1832 sub CreateValidSGML {
1833     my ($text) = @_;
1834     $text =~ s/&/&amp;/g;       # Do this first, or the others get messed up.
1835     $text =~ s/</&lt;/g;
1836     $text =~ s/>/&gt;/g;
1837     return $text;
1838 }
1839
1840 #############################################################################
1841 # Function    : ConvertSGMLChars
1842 # Description : This is used for text in source code comment blocks, to turn
1843 #               chars which are used in SGML into entities, e.g. '<' into
1844 #               '&lt;'. Depending on $SGML_MODE, this is done
1845 #               unconditionally or only if the character doesn't seem to be
1846 #               part of an SGML construct (tag or entity reference).
1847 # Arguments   : $text - the text to turn into proper SGML.
1848 #############################################################################
1849
1850 sub ConvertSGMLChars {
1851     my ($symbol, $text) = @_;
1852
1853     if ($SGML_MODE) {
1854         # For the SGML mode only convert to entities outside CDATA sections.
1855         return &ModifyXMLElements ($text, $symbol,
1856                                    "<!\\[CDATA\\[|<programlisting[^>]*>",
1857                                    \&ConvertSGMLCharsEndTag,
1858                                    \&ConvertSGMLCharsCallback);
1859     } else {
1860         # For the simple non-sgml mode, convert to entities everywhere.
1861         $text =~ s/&/&amp;/g;   # Do this first, or the others get messed up.
1862         $text =~ s/</&lt;/g;
1863         $text =~ s/>/&gt;/g;
1864         return $text;
1865     }
1866 }
1867
1868
1869 sub ConvertSGMLCharsEndTag {
1870   if ($_[0] eq "<!\[CDATA\[") {
1871     return "]]>";
1872   } else {
1873     return "</programlisting>";
1874   }
1875 }
1876
1877 sub ConvertSGMLCharsCallback {
1878   my ($text, $symbol, $tag) = @_;
1879
1880   if ($tag =~ m/^<programlisting/) {
1881     # We can handle <programlisting> specially here.
1882     return &ModifyXMLElements ($text, $symbol,
1883                                "<!\\[CDATA\\[",
1884                                \&ConvertSGMLCharsEndTag,
1885                                \&ConvertSGMLCharsCallback2);
1886   } elsif ($tag eq "") {
1887     # If we're not in CDATA convert to entities.
1888     $text =~ s/&(?![a-zA-Z#]+;)/&amp;/g;        # Do this first, or the others get messed up.
1889     $text =~ s/<(?![a-zA-Z\/!])/&lt;/g;
1890     $text =~ s/(?<![a-zA-Z0-9"'\/-])>/&gt;/g;
1891
1892     # Handle "#include <xxxxx>"
1893     $text =~ s/#include(\s+)<([^>]+)>/#include$1&lt;$2&gt;/g;
1894   }
1895
1896   return $text;
1897 }
1898
1899 sub ConvertSGMLCharsCallback2 {
1900   my ($text, $symbol, $tag) = @_;
1901
1902   # If we're not in CDATA convert to entities.
1903   # We could handle <programlisting> differently, though I'm not sure it helps.
1904   if ($tag eq "") {
1905     $text =~ s/&(?![a-zA-Z#]+;)/&amp;/g;        # Do this first, or the others get messed up.
1906 #    $text =~ s/&/&amp;/g;      # Do this first, or the others get messed up.
1907     $text =~ s/<(?![a-zA-Z\/!])/&lt;/g;
1908     $text =~ s/(?<![a-zA-Z0-9"'\/-])>/&gt;/g;
1909
1910     # Handle "#include <xxxxx>"
1911     $text =~ s/#include(\s+)<([^>]+)>/#include$1&lt;$2&gt;/g;
1912   }
1913
1914   return $text;
1915 }
1916
1917
1918 #############################################################################
1919 # Function    : ExpandAbbreviations
1920 # Description : This turns the abbreviations function(), macro(), @param,
1921 #               %constant, and #symbol into appropriate DocBook markup.
1922 #               CDATA sections and <programlisting> parts are skipped.
1923 # Arguments   : $symbol - the symbol being documented, for error messages.
1924 #               $text - the text to expand.
1925 #############################################################################
1926
1927 sub ExpandAbbreviations {
1928   my ($symbol, $text) = @_;
1929
1930   # Convert "|[" and "]|" into the start and end of program listing examples.
1931   $text =~ s%\|\[%<informalexample><programlisting>%g;
1932   $text =~ s%\]\|%</programlisting></informalexample>%g;
1933
1934   return &ModifyXMLElements ($text, $symbol,
1935                              "<!\\[CDATA\\[|<programlisting[^>]*>",
1936                              \&ExpandAbbreviationsEndTag,
1937                              \&ExpandAbbreviationsCallback);
1938 }
1939
1940
1941 # Returns the end tag corresponding to the given start tag.
1942 sub ExpandAbbreviationsEndTag {
1943   if ($_[0] eq "<!\[CDATA\[") {
1944     return "]]>";
1945   } else {
1946     return "</programlisting>";
1947   }
1948 }
1949
1950 # Called inside or outside each CDATA or <programlisting> section.
1951 sub ExpandAbbreviationsCallback {
1952   my ($text, $symbol, $tag) = @_;
1953
1954   if ($tag =~ m/^<programlisting/) {
1955     # Handle any embedded CDATA sections.
1956     return &ModifyXMLElements ($text, $symbol,
1957                                "<!\\[CDATA\\[",
1958                                \&ExpandAbbreviationsEndTag,
1959                                \&ExpandAbbreviationsCallback2);
1960   } elsif ($tag eq "") {
1961     # We are outside any CDATA or <programlisting> sections, so we expand
1962     # any gtk-doc abbreviations.
1963
1964     # Convert 'function()' or 'macro()'
1965     $text =~ s/(\w+)\s*\(\)/&MakeXRef($1, &tagify($1 . "()", "function"));/eg;
1966
1967     # Convert '@param'
1968     $text =~ s/\@(\w+((\.|->)\w+)*)/<parameter>$1<\/parameter>/g;
1969
1970     # Convert '%constant'. Also allow negative numbers, e.g. %-1.
1971     $text =~ s/\%(-?\w+)/&MakeXRef($1, &tagify($1, "literal"));/eg;
1972
1973     # Convert '#symbol'
1974     $text =~ s/#([\w\-:]+)/&MakeHashXRef($1, "type");/eg;
1975   }
1976
1977   return $text;
1978 }
1979
1980 # This is called inside a <programlisting>
1981 sub ExpandAbbreviationsCallback2 {
1982   my ($text, $symbol, $tag) = @_;
1983
1984   if ($tag eq "") {
1985     # We are inside a <programlisting> but outside any CDATA sections,
1986     # so we expand any gtk-doc abbreviations.
1987     $text =~ s/#(\w+)/&MakeHashXRef($1, "");/eg;
1988   }
1989
1990   return $text;
1991 }
1992
1993 sub MakeHashXRef {
1994     my ($symbol, $tag) = @_;;
1995     my $text = $symbol;
1996
1997     # Check for things like '#include', '#define', and skip them.
1998     if ($PreProcessorDirectives{$symbol}) {
1999       return "#$symbol";
2000     }
2001
2002     # Get rid of any special '-struct' suffix.
2003     $text =~ s/-struct$//;
2004
2005     # If the symbol is in the form "Object::signal", then change the symbol to
2006     # "Object-signal" and use "signal" as the text.
2007     if ($symbol =~ s/::/-/) {
2008       $text = "\"$'\"";
2009     }
2010
2011     # If the symbol is in the form "Object:property", then change the symbol to
2012     # "Object--property" and use "property" as the text.
2013     if ($symbol =~ s/:/--/) {
2014       $text = "\"$'\"";
2015     }
2016
2017     if ($tag ne "") {
2018       $text = tagify ($text, $tag);
2019     }
2020
2021     return &MakeXRef($symbol, $text);
2022 }
2023
2024
2025 #############################################################################
2026 # Function    : ModifyXMLElements
2027 # Description : Looks for given XML element tags within the text, and calls
2028 #               the callback on pieces of text inside & outside those elements.
2029 #               Used for special handling of text inside things like CDATA
2030 #               and <programlisting>.
2031 # Arguments   : $text - the text.
2032 #               $symbol - the symbol currently being documented (only used for
2033 #                      error messages).
2034 #               $start_tag_regexp - the regular expression to match start tags.
2035 #                      e.g. "<!\\[CDATA\\[|<programlisting[^>]*>" to match
2036 #                      CDATA sections or programlisting elements.
2037 #               $end_tag_func - function which is passed the matched start tag
2038 #                      and should return the appropriate end tag string.
2039 #               $callback - callback called with each part of the text. It is
2040 #                      called with a piece of text, the symbol being
2041 #                      documented, and the matched start tag or "" if the text
2042 #                      is outside the XML elements being matched.
2043 #############################################################################
2044 sub ModifyXMLElements {
2045     my ($text, $symbol, $start_tag_regexp, $end_tag_func, $callback) = @_;
2046     my ($before_tag, $start_tag, $end_tag_regexp, $end_tag);
2047     my $result = "";
2048
2049     while ($text =~ m/$start_tag_regexp/s) {
2050       $before_tag = $`;
2051       $start_tag = $&;
2052       $text = $';
2053
2054       $result .= &$callback ($before_tag, $symbol, "");
2055       $result .= $start_tag;
2056
2057       $end_tag_regexp = &$end_tag_func ($start_tag);
2058
2059       if ($text =~ m/$end_tag_regexp/s) {
2060         $before_tag = $`;
2061         $end_tag = $&;
2062         $text = $';
2063
2064         $result .= &$callback ($before_tag, $symbol, $start_tag);
2065         $result .= $end_tag;
2066       } else {
2067         print "WARNING: Can't find tag end: $end_tag_regexp in docs for: $symbol\n";
2068         # Just assume it is all inside the tag.
2069         $result .= &$callback ($text, $symbol, $start_tag);
2070         $text = "";
2071       }
2072     }
2073
2074     # Handle any remaining text outside the tags.
2075     $result .= &$callback ($text, $symbol, "");
2076
2077     return $result;
2078 }
2079
2080 sub noop {
2081   return $_[0];
2082 }
2083
2084 # Adds a tag around some text.
2085 # e.g tagify("Text", "literal") => "<literal>Text</literal>".
2086 sub tagify {
2087    my ($text, $elem) = @_;
2088    return "<" . $elem . ">" . $text . "</" . $elem . ">";
2089 }
2090
2091
2092 #############################################################################
2093 # Function    : MakeXRef
2094 # Description : This returns a cross-reference link to the given symbol.
2095 #               Though it doesn't try to do this for a few standard C types
2096 #               that it knows won't be in the documentation.
2097 # Arguments   : $symbol - the symbol to try to create a XRef to.
2098 #               $text - text text to put inside the XRef, defaults to $symbol
2099 #############################################################################
2100
2101 sub MakeXRef {
2102     my ($symbol, $text) = ($_[0], $_[1]);
2103     if (!defined($text)) {
2104         $text = $symbol;
2105
2106         # Get rid of special '-struct' suffix.
2107         $text =~ s/-struct$//;
2108     }
2109
2110     #print "Getting type link for $symbol -> $text\n";
2111
2112     my $symbol_id = &CreateValidSGMLID ($symbol);
2113     return "<link linkend=\"$symbol_id\">$text</link>";
2114 }
2115
2116
2117 #############################################################################
2118 # Function    : MakeIndexterms
2119 # Description : This returns a indexterm elements for the given symbol
2120 # Arguments   : $symbol - the symbol to create indexterms for
2121 #############################################################################
2122
2123 sub MakeIndexterms {
2124   my ($symbol) = $_[0];
2125   my $terms =  "";
2126
2127   if (exists $Deprecated{$symbol}) {
2128       $terms .= "<indexterm role=\"deprecated\"><primary>$symbol</primary></indexterm>"
2129   }
2130   if (exists $Since{$symbol}) {
2131      my $since = $Since{$symbol};
2132      $since =~ s/^\s+//;
2133      $since =~ s/\s+$//;
2134      if ($since ne "") {
2135          $terms .= "<indexterm role=\"$since\"><primary>$symbol</primary></indexterm>";
2136      }
2137   }
2138   if ($terms eq "") {
2139      $terms .= "<indexterm><primary>$symbol</primary></indexterm>";
2140   }
2141
2142   return $terms;
2143  }
2144
2145 #############################################################################
2146 # Function    : MakeDeprecationNote
2147 # Description : This returns a deprecation warning for the given symbol.
2148 # Arguments   : $symbol - the symbol to try to create a warning for.
2149 #############################################################################
2150
2151 sub MakeDeprecationNote {
2152     my ($symbol) = $_[0];
2153     my $desc = "";
2154     my $note = "";
2155     if (exists $Deprecated{$symbol}) {
2156         $desc .= "<warning>";
2157
2158         if ($Deprecated{$symbol} =~ /^\s*([0-9\.]+)\s*:/) {
2159                 $desc .= "<para><literal>$symbol</literal> has been deprecated since version $1 and should not be used in newly-written code.";
2160         } else {
2161                 $desc .= "<para><literal>$symbol</literal> is deprecated and should not be used in newly-written code.";
2162         }
2163         if ($Deprecated{$symbol} ne "") {
2164             $note = &ExpandAbbreviations($symbol, $Deprecated{$symbol});
2165             $note =~ s/^\s*([0-9\.]+)\s*:\s*//;
2166             $note =~ s/^\s+//;
2167             $note =~ s/\s+$//;
2168             $note =~ s%\n{2,}%\n</para>\n<para>\n%g;
2169             $desc .= " " . $note;
2170         }
2171         $desc .= "</para></warning>\n";
2172     }
2173     return $desc;
2174 }
2175
2176 #############################################################################
2177 # Function    : MakeConditionDescription
2178 # Description : This returns a sumary of conditions for the given symbol.
2179 # Arguments   : $symbol - the symbol to try to create the sumary.
2180 #############################################################################
2181
2182 sub MakeConditionDescription {
2183     my ($symbol) = $_[0];
2184     my $desc = "";
2185
2186     if (exists $Deprecated{$symbol}) {
2187         if ($desc ne "") {
2188             $desc .= "|";
2189         }
2190
2191         if ($Deprecated{$symbol} =~ /^\s*(.*?)\s*$/) {
2192                 $desc .= "deprecated:$1";
2193         } else {
2194                 $desc .= "deprecated";
2195         }
2196     }
2197
2198     if (exists $Since{$symbol}) {
2199         if ($desc ne "") {
2200             $desc .= "|";
2201         }
2202
2203         if ($Since{$symbol} =~ /^\s*(.*?)\s*$/) {
2204                 $desc .= "since:$1";
2205         } else {
2206                 $desc .= "since";
2207         }
2208     }
2209
2210     if (exists $StabilityLevel{$symbol}) {
2211         if ($desc ne "") {
2212             $desc .= "|";
2213         }
2214         $desc .= "stability:".$StabilityLevel{$symbol};
2215     }
2216
2217     if ($desc ne "") {
2218         $desc=" condition=\"".$desc."\"";
2219         #print "condition for '$symbol' = '$desc'\n";
2220     }
2221     return $desc;
2222 }
2223
2224 #############################################################################
2225 # Function    : GetHierarchy
2226 # Description : Returns the DocBook output describing the ancestors and
2227 #               immediate children of a GObject subclass. It uses the
2228 #               global @Objects and @ObjectLevels arrays to walk the tree.
2229 # Arguments   : $object - the GtkObject subclass.
2230 #############################################################################
2231
2232 sub GetHierarchy {
2233     my ($object) = @_;
2234
2235     # Find object in the objects array.
2236     my $found = 0;
2237     my @children = ();
2238     my $i;
2239     my $level;
2240     my $j;
2241     for ($i = 0; $i < @Objects; $i++) {
2242         if ($found) {
2243             if ($ObjectLevels[$i] <= $level) {
2244             last;
2245         }
2246             elsif ($ObjectLevels[$i] == $level + 1) {
2247                 push (@children, $Objects[$i]);
2248             }
2249         }
2250         elsif ($Objects[$i] eq $object) {
2251             $found = 1;
2252             $j = $i;
2253             $level = $ObjectLevels[$i];
2254         }
2255     }
2256     if (!$found) {
2257         return "";
2258     }
2259
2260     # Walk up the hierarchy, pushing ancestors onto the ancestors array.
2261     my @ancestors = ();
2262     push (@ancestors, $object);
2263 #    print "Level: $level\n";
2264     while ($level > 1) {
2265         $j--;
2266         if ($ObjectLevels[$j] < $level) {
2267             push (@ancestors, $Objects[$j]);
2268             $level = $ObjectLevels[$j];
2269 #           print "Level: $level\n";
2270         }
2271     }
2272
2273     # Output the ancestors list, indented and with links.
2274     my $hierarchy = "<synopsis>\n\n";
2275     $level = 0;
2276     for ($i = $#ancestors; $i >= 0; $i--) {
2277         my $link_text;
2278         # Don't add a link to the current widget, i.e. when i == 0.
2279         if ($i > 0) {
2280             my $ancestor_id = &CreateValidSGMLID ($ancestors[$i]);
2281             $link_text = "<link linkend=\"$ancestor_id\">$ancestors[$i]</link>";
2282         } else {
2283             $link_text = "$ancestors[$i]";
2284         }
2285         if ($level == 0) {
2286             $hierarchy .= "  $link_text\n";
2287         } else {
2288 #           $hierarchy .= ' ' x ($level * 6 - 3) . "|\n";
2289             $hierarchy .= ' ' x ($level * 6 - 3) . "+----$link_text\n";
2290         }
2291         $level++;
2292     }
2293     for ($i = 0; $i <= $#children; $i++) {
2294       my $id = &CreateValidSGMLID ($children[$i]);
2295       my $link_text = "<link linkend=\"$id\">$children[$i]</link>";
2296       $hierarchy .= ' ' x ($level * 6 - 3) . "+----$link_text\n";
2297     }
2298     $hierarchy .= "</synopsis>\n";
2299
2300     return $hierarchy;
2301 }
2302
2303
2304 #############################################################################
2305 # Function    : GetInterfaces
2306 # Description : Returns the DocBook output describing the interfaces
2307 #               implemented by a class. It uses the global %Interfaces hash.
2308 # Arguments   : $object - the GtkObject subclass.
2309 #############################################################################
2310
2311 sub GetInterfaces {
2312     my ($object) = @_;
2313     my $text = "";
2314     my $i;
2315
2316     # Find object in the objects array.
2317     if (exists($Interfaces{$object})) {
2318         my @ifaces = split(' ', $Interfaces{$object});
2319         $text = <<EOF;
2320 <para>
2321 $object implements
2322 EOF
2323         for ($i = 0; $i <= $#ifaces; $i++) {
2324             my $id = &CreateValidSGMLID ($ifaces[$i]);
2325             $text .= " <link linkend=\"$id\">$ifaces[$i]</link>";
2326             if ($i < $#ifaces - 1) {
2327                 $text .= ', ';
2328             }
2329             elsif ($i < $#ifaces) {
2330                 $text .= ' and ';
2331             }
2332             else {
2333                 $text .= '.';
2334             }
2335         }
2336         $text .= <<EOF;
2337 </para>
2338 EOF
2339     }
2340
2341     return $text;
2342 }
2343
2344 #############################################################################
2345 # Function    : GetImplementations
2346 # Description : Returns the DocBook output describing the implementations
2347 #               of an interface. It uses the global %Interfaces hash.
2348 # Arguments   : $object - the GtkObject subclass.
2349 #############################################################################
2350
2351 sub GetImplementations {
2352     my ($object) = @_;
2353     my @impls = ();
2354     my $text = "";
2355     my $i;
2356     foreach my $key (keys %Interfaces) {
2357         if ($Interfaces{$key} =~ /\b$object\b/) {
2358             push (@impls, $key);
2359         }
2360     }
2361     if ($#impls >= 0) {
2362         $text = <<EOF;
2363 <para>
2364 $object is implemented by
2365 EOF
2366         for ($i = 0; $i <= $#impls; $i++) {
2367             my $id = &CreateValidSGMLID ($impls[$i]);
2368             $text .= " <link linkend=\"$id\">$impls[$i]</link>";
2369             if ($i < $#impls - 1) {
2370                 $text .= ', ';
2371             }
2372             elsif ($i < $#impls) {
2373                 $text .= ' and ';
2374             }
2375             else {
2376                 $text .= '.';
2377             }
2378         }
2379         $text .= <<EOF;
2380 </para>
2381 EOF
2382     }
2383     return $text;
2384 }
2385
2386
2387 #############################################################################
2388 # Function    : GetPrerequisites
2389 # Description : Returns the DocBook output describing the prerequisites
2390 #               of an interface. It uses the global %Prerequisites hash.
2391 # Arguments   : $iface - the interface.
2392 #############################################################################
2393
2394 sub GetPrerequisites {
2395     my ($iface) = @_;
2396     my $text = "";
2397     my $i;
2398
2399     if (exists($Prerequisites{$iface})) {
2400         $text = <<EOF;
2401 <para>
2402 $iface requires
2403 EOF
2404         my @prereqs = split(' ', $Prerequisites{$iface});
2405         for ($i = 0; $i <= $#prereqs; $i++) {
2406             my $id = &CreateValidSGMLID ($prereqs[$i]);
2407             $text .= " <link linkend=\"$id\">$prereqs[$i]</link>";
2408             if ($i < $#prereqs - 1) {
2409                 $text .= ', ';
2410             }
2411             elsif ($i < $#prereqs) {
2412                 $text .= ' and ';
2413             }
2414             else {
2415                 $text .= '.';
2416             }
2417         }
2418         $text .= <<EOF;
2419 </para>
2420 EOF
2421     }
2422     return $text;
2423 }
2424
2425 #############################################################################
2426 # Function    : GetDerived
2427 # Description : Returns the DocBook output describing the derived interfaces
2428 #               of an interface. It uses the global %Prerequisites hash.
2429 # Arguments   : $iface - the interface.
2430 #############################################################################
2431
2432 sub GetDerived {
2433     my ($iface) = @_;
2434     my $text = "";
2435     my $i;
2436
2437     my @derived = ();
2438     foreach my $key (keys %Prerequisites) {
2439         if ($Prerequisites{$key} =~ /\b$iface\b/) {
2440             push (@derived, $key);
2441         }
2442     }
2443     if ($#derived >= 0) {
2444         $text = <<EOF;
2445 <para>
2446 $iface is required by
2447 EOF
2448         for ($i = 0; $i <= $#derived; $i++) {
2449             my $id = &CreateValidSGMLID ($derived[$i]);
2450             $text .= " <link linkend=\"$id\">$derived[$i]</link>";
2451             if ($i < $#derived - 1) {
2452                 $text .= ', ';
2453             }
2454             elsif ($i < $#derived) {
2455                 $text .= ' and ';
2456             }
2457             else {
2458                 $text .= '.';
2459             }
2460         }
2461         $text .= <<EOF;
2462 </para>
2463 EOF
2464     }
2465     return $text;
2466 }
2467
2468
2469 #############################################################################
2470 # Function    : GetSignals
2471 # Description : Returns the synopsis and detailed description DocBook output
2472 #               for the signal handlers of a given GtkObject subclass.
2473 # Arguments   : $object - the GtkObject subclass, e.g. 'GtkButton'.
2474 #############################################################################
2475
2476 sub GetSignals {
2477     my ($object) = @_;
2478     my $synop = "";
2479     my $desc = "";
2480
2481     my $i;
2482     for ($i = 0; $i <= $#SignalObjects; $i++) {
2483         if ($SignalObjects[$i] eq $object) {
2484 #           print "Found signal: $SignalNames[$i]\n";
2485             my $name = $SignalNames[$i];
2486             my $symbol = "${object}::${name}";
2487             my $id = &CreateValidSGMLID ("$object-$name");
2488
2489             my $pad = ' ' x (46 - length($name));
2490             $synop .= "  &quot;<link linkend=\"$id\">$name</link>&quot;$pad ";
2491
2492             $desc .= "<refsect2><title><anchor id=\"$id\"${empty_element_end}The <literal>&quot;$name&quot;</literal> signal</title>\n";
2493             $desc .= MakeIndexterms($symbol);
2494             $desc .= "<programlisting>";
2495
2496             $SignalReturns[$i] =~ m/\s*(const\s+)?(\w+)\s*(\**)/;
2497             my $type_modifier = defined($1) ? $1 : "";
2498             my $type = $2;
2499             my $pointer = $3;
2500             my $xref = &MakeXRef ($type);
2501
2502             my $ret_type_len = length ($type_modifier) + length ($pointer)
2503                 + length ($type);
2504             my $ret_type_output = "$type_modifier$xref$pointer"
2505                 . (' ' x ($RETURN_TYPE_FIELD_WIDTH - $ret_type_len));
2506
2507             $desc  .= "${ret_type_output}user_function " . &MakeReturnField("") . " (";
2508
2509             my $sourceparams = $SourceSymbolParams{$symbol};
2510             my @params = split ("\n", $SignalPrototypes[$i]);
2511             my $j;
2512             my $l;
2513             my $type_len = length("gpointer");
2514             my $name_len = length("user_data");
2515             # do two passes, the first one is to calculate padding
2516             for ($l = 0; $l < 2; $l++) {
2517                 for ($j = 0; $j <= $#params; $j++) {
2518                     # allow alphanumerics, '_', '[' & ']' in param names
2519                     if ($params[$j] =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$/) {
2520                         $type = $1;
2521                         $pointer = $2;
2522                         if (defined($sourceparams)) {
2523                             $name = $$sourceparams[2 * $j];
2524                         }
2525                         else {
2526                             $name = $3;
2527                         }
2528                         if (!defined($name)) {
2529                             $name = "arg$j";
2530                         }
2531                         if ($l == 0) {
2532                             if (length($type) + length($pointer) > $type_len) {
2533                                 $type_len = length($type) + length($pointer);
2534                             }
2535                             if (length($name) > $name_len) {
2536                                 $name_len = length($name);
2537                             }
2538                         }
2539                         else {
2540                             $xref = &MakeXRef ($type);
2541                             $pad = ' ' x ($type_len - length($type) - length($pointer));
2542                             $desc .= "$xref$pad $pointer$name,\n";
2543                             $desc .= (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH));
2544                         }
2545                      } else {
2546                          print "###Can't parse arg: $params[$j]\nArgs:$SignalPrototypes[$i]\n";
2547                      }
2548                 }
2549             }
2550             $xref = &MakeXRef ("gpointer");
2551             $pad = ' ' x ($type_len - length("gpointer"));
2552             $desc  .= "$xref$pad user_data)";
2553
2554             my $flags = $SignalFlags[$i];
2555             my $flags_string = "";
2556
2557             if (defined ($flags)) {
2558               if ($flags =~ m/f/) {
2559                 $flags_string = "Run First";
2560               }
2561               elsif ($flags =~ m/l/) {
2562                 $flags_string = "Run Last";
2563               }
2564               elsif ($flags =~ m/c/) {
2565                 $flags_string = "Cleanup";
2566               }
2567               if ($flags =~ m/r/) {
2568                 if ($flags_string) { $flags_string .= " / "; }
2569                 $flags_string .= "No Recursion";
2570               }
2571               if ($flags =~ m/d/) {
2572                 if ($flags_string) { $flags_string .= " / "; }
2573                 $flags_string .= "Has Details";
2574               }
2575               if ($flags =~ m/a/) {
2576                 if ($flags_string) { $flags_string .= " / "; }
2577                 $flags_string .= "Action";
2578               }
2579               if ($flags =~ m/h/) {
2580                 if ($flags_string) { $flags_string .= " / "; }
2581                 $flags_string .= "No Hooks";
2582               }
2583             }
2584
2585             if ($flags_string)
2586               {
2587                 $synop .= ": $flags_string\n";
2588
2589                 $pad = ' ' x (5 + $name_len - length("user_data"));
2590                 $desc  .= "$pad : $flags_string</programlisting>\n";
2591               }
2592             else
2593               {
2594                 $synop .= "\n";
2595                 $desc  .= "</programlisting>\n";
2596               }
2597
2598             my $parameters = &OutputParamDescriptions ("SIGNAL", $symbol);
2599             my $parameters_output = 0;
2600
2601             $AllSymbols{$symbol} = 1;
2602             if (defined ($SymbolDocs{$symbol})) {
2603                 my $symbol_docs = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
2604
2605                 # Try to insert the parameter table at the author's desired
2606                 # position. Otherwise we need to tag it onto the end.
2607                 if ($symbol_docs =~ s/<!--PARAMETERS-->/$parameters/) {
2608                   $parameters_output = 1;
2609                 }
2610                 $desc .= $symbol_docs;
2611
2612                 if (!IsEmptyDoc($SymbolDocs{$symbol})) {
2613                     $AllDocumentedSymbols{$symbol} = 1;
2614                 }
2615             }
2616
2617             if ($parameters_output == 0) {
2618                 $desc .= $parameters;
2619               }
2620
2621             if (exists $Since{$symbol}) {
2622               $desc .= "<para>Since $Since{$symbol}</para>";
2623             }
2624             if (exists $StabilityLevel{$symbol}) {
2625               $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
2626             }
2627             $desc .= "</refsect2>";
2628         }
2629     }
2630     return ($synop, $desc);
2631 }
2632
2633
2634 #############################################################################
2635 # Function    : GetArgs
2636 # Description : Returns the synopsis and detailed description DocBook output
2637 #               for the Args of a given GtkObject subclass.
2638 # Arguments   : $object - the GtkObject subclass, e.g. 'GtkButton'.
2639 #############################################################################
2640
2641 sub GetArgs {
2642     my ($object) = @_;
2643     my $synop = "";
2644     my $desc = "";
2645     my $child_synop = "";
2646     my $child_desc = "";
2647     my $style_synop = "";
2648     my $style_desc = "";
2649
2650     my $i;
2651     for ($i = 0; $i <= $#ArgObjects; $i++) {
2652         if ($ArgObjects[$i] eq $object) {
2653 #           print "Found arg: $ArgNames[$i]\n";
2654             my $name = $ArgNames[$i];
2655             # Remember only one colon so we don't clash with signals.
2656             my $symbol = "${object}:${name}";
2657             # I've used two dashes here for the same reason.
2658             my $id = &CreateValidSGMLID ("$object--$name");
2659
2660             my $type = $ArgTypes[$i];
2661             my $type_output;
2662             my $range = $ArgRanges[$i];
2663             my $range_output = CreateValidSGML($range);
2664             my $default = $ArgDefaults[$i];
2665             my $default_output = CreateValidSGML($default);
2666
2667             if ($type eq "GtkSignal") {
2668                 $type = "GtkSignalFunc, gpointer";
2669                 $type_output = &MakeXRef ("GtkSignalFunc") . ", "
2670                     . &MakeXRef ("gpointer");
2671             } elsif ($type eq "GtkString") {
2672                 $type = "gchar*";
2673                 $type_output = &MakeXRef ("gchar") . "*";
2674             } else {
2675                 $type_output = &MakeXRef ($type);
2676             }
2677
2678             my $flags = $ArgFlags[$i];
2679             my $flags_string = "";
2680
2681             if ($flags =~ m/r/) {
2682                 $flags_string = "Read";
2683             }
2684             if ($flags =~ m/w/) {
2685                 if ($flags_string) { $flags_string .= " / "; }
2686                 $flags_string .= "Write";
2687             }
2688             if ($flags =~ m/x/) {
2689                 if ($flags_string) { $flags_string .= " / "; }
2690                 $flags_string .= "Construct";
2691             }
2692             if ($flags =~ m/X/) {
2693                 if ($flags_string) { $flags_string .= " / "; }
2694                 $flags_string .= "Construct Only";
2695             }
2696
2697             $AllSymbols{$symbol} = 1;
2698             my $blurb;
2699             if (defined($SymbolDocs{$symbol}) &&
2700                 !IsEmptyDoc($SymbolDocs{$symbol})) {
2701                 $blurb = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
2702                 $AllDocumentedSymbols{$symbol} = 1;
2703             }
2704             else {
2705                 if (!($ArgBlurbs[$i] eq "")) {
2706                     $AllDocumentedSymbols{$symbol} = 1;
2707                 }
2708                 $blurb = "<para>" . &CreateValidSGML ($ArgBlurbs[$i]) . "</para>";
2709             }
2710
2711             my $pad1 = " " x (24 - length ($name));
2712             my $pad2 = " " x (20 - length ($type));
2713             my $kind = "";
2714
2715             if ($flags =~ m/c/) {
2716                 $kind = "child property";
2717             }
2718             elsif ($flags =~ m/s/) {
2719                 $kind = "style property";
2720             }
2721             else {
2722                 $kind = "property";
2723             }
2724
2725             my $arg_synop = "  &quot;<link linkend=\"$id\">$name</link>&quot;$pad1 $type_output $pad2 : $flags_string\n";
2726             my $arg_desc = "<refsect2><title><anchor id=\"$id\"${empty_element_end}The <literal>&quot;$name&quot;</literal> $kind</title>\n";
2727             $arg_desc .= MakeIndexterms($symbol);
2728             $arg_desc .= "<programlisting>  &quot;$name&quot;$pad1 $type_output $pad2 : $flags_string</programlisting>\n";
2729             $arg_desc .= $blurb;
2730             if ($range ne "") {
2731                 $arg_desc .= "<para>Allowed values: $range_output</para>\n";
2732             }
2733             if ($default ne "") {
2734                 $arg_desc .= "<para>Default value: $default_output</para>\n";
2735             }
2736             if (exists $Since{$symbol}) {
2737               $arg_desc .= "<para>Since $Since{$symbol}</para>\n";
2738             }
2739             if (exists $StabilityLevel{$symbol}) {
2740               $arg_desc .= "<para>Stability Level $StabilityLevel{$symbol}</para>\n";
2741             }
2742             $arg_desc .= "</refsect2>\n";
2743
2744             if ($flags =~ m/c/) {
2745                 $child_synop .= $arg_synop;
2746                 $child_desc .= $arg_desc;
2747             }
2748             elsif ($flags =~ m/s/) {
2749                 $style_synop .= $arg_synop;
2750                 $style_desc .= $arg_desc;
2751             }
2752             else {
2753                 $synop .= $arg_synop;
2754                 $desc .= $arg_desc;
2755             }
2756         }
2757     }
2758     return ($synop, $child_synop, $style_synop, $desc, $child_desc, $style_desc);
2759 }
2760
2761
2762 #############################################################################
2763 # Function    : ReadSourceDocumentation
2764 # Description : This reads in the documentation embedded in comment blocks
2765 #               in the source code (for Gnome).
2766 #
2767 #               Parameter descriptions override any in the template files.
2768 #               Function descriptions are placed before any description from
2769 #               the template files.
2770 #
2771 #               It recursively descends the source directory looking for .c
2772 #               files and scans them looking for specially-formatted comment
2773 #               blocks.
2774 #
2775 # Arguments   : $source_dir - the directory to scan.
2776 #############m###############################################################
2777
2778 sub ReadSourceDocumentation {
2779     my ($source_dir) = @_;
2780     my ($file, $dir, @suffix_list, $suffix);
2781 #    print "Scanning source directory: $source_dir\n";
2782
2783     # This array holds any subdirectories found.
2784     my (@subdirs) = ();
2785
2786     @suffix_list = split (/,/, $SOURCE_SUFFIXES);
2787
2788     opendir (SRCDIR, $source_dir)
2789         || die "Can't open source directory $source_dir: $!";
2790
2791     foreach $file (readdir (SRCDIR)) {
2792       if ($file =~ /^\./) {
2793         next;
2794       } elsif (-d "$source_dir/$file") {
2795         push (@subdirs, $file);
2796       } elsif (@suffix_list) {
2797         foreach $suffix (@suffix_list) {
2798           if ($file =~ m/\.\Q${suffix}\E$/) {
2799             &ScanSourceFile ("$source_dir/$file");
2800           }
2801         }
2802       } elsif ($file =~ m/\.[ch]$/) {
2803         &ScanSourceFile ("$source_dir/$file");
2804       }
2805     }
2806     closedir (SRCDIR);
2807
2808     # Now recursively scan the subdirectories.
2809     foreach $dir (@subdirs) {
2810         next if ($IGNORE_FILES =~ m/(\s|^)\Q${dir}\E(\s|$)/);
2811         &ReadSourceDocumentation ("$source_dir/$dir");
2812     }
2813 }
2814
2815
2816 #############################################################################
2817 # Function    : ScanSourceFile
2818 # Description : Scans one source file looking for specially-formatted comment
2819 #               blocks. Later &MergeSourceDocumentation is used to merge any
2820 #               documentation found with the documentation already read in
2821 #               from the template files.
2822 #
2823 # Arguments   : $file - the file to scan.
2824 #############################################################################
2825
2826 sub ScanSourceFile {
2827     my ($file) = @_;
2828     my $basename;
2829
2830     if ($file =~ m/^.*[\/\\]([^\/\\]*)$/) {
2831         $basename = $1;
2832     } else {
2833         print "WARNING: Can't find basename of file $file\n";
2834         $basename = $file;
2835     }
2836
2837     # Check if the basename is in the list of files to ignore.
2838     if ($IGNORE_FILES =~ m/(\s|^)\Q${basename}\E(\s|$)/) {
2839         return;
2840     }
2841
2842     #print "DEBUG: Scanning $file\n";
2843
2844     open (SRCFILE, $file)
2845         || die "Can't open $file: $!";
2846     my $in_comment_block = 0;
2847     my $symbol;
2848     my ($in_description, $in_return, $in_since, $in_stability, $in_deprecated);
2849     my ($description, $return_desc, $return_start, $return_style);
2850     my ($since_desc, $stability_desc, $deprecated_desc);
2851     my $current_param;
2852     my $ignore_broken_returns;
2853     my @params;
2854     while (<SRCFILE>) {
2855         # Look for the start of a comment block.
2856         if (!$in_comment_block) {
2857             if (m%^\s*/\*.*\*/%) {
2858                 #one-line comment - not gtkdoc
2859             } elsif (m%^\s*/\*\*\s%) {
2860 #             print "Found comment block start\n";
2861
2862                 $in_comment_block = 1;
2863
2864                 # Reset all the symbol data.
2865                 $symbol = "";
2866                 $in_description = 0;
2867                 $in_return = 0;
2868                 $in_since = 0;
2869                 $in_deprecated = 0;
2870                 $in_stability = 0;
2871                 $description = "";
2872                 $return_desc = "";
2873                 $return_style = "";
2874                 $since_desc = "";
2875                 $deprecated_desc = "";
2876                 $stability_desc = "";
2877                 $current_param = -1;
2878                 $ignore_broken_returns = 0;
2879                 @params = ();
2880             }
2881             next;
2882         }
2883
2884         # We're in a comment block. Check if we've found the end of it.
2885         if (m%^\s*\*+/%) {
2886             if (!$symbol) {
2887                 print <<EOF;
2888 WARNING: Symbol name not found at the start of the comment block.
2889  $file line $.
2890 EOF
2891             } else {
2892                 # Add the return value description onto the end of the params.
2893                 if ($return_desc) {
2894                     push (@params, "Returns");
2895                     push (@params, $return_desc);
2896                     if ($return_style eq 'broken') {
2897                         print <<EOF;
2898 WARNING: Free-form return value description in $symbol.
2899          Use `Returns:' to avoid ambiguities.
2900 EOF
2901                     }
2902                 }
2903                 # Convert special SGML characters
2904                 $description = &ConvertSGMLChars ($symbol, $description);
2905                 my $k;
2906                 for ($k = 1; $k <= $#params; $k += 2) {
2907                     $params[$k] = &ConvertSGMLChars ($symbol, $params[$k]);
2908                 }
2909
2910                 # Handle Section docs
2911                 if ($symbol =~ m/SECTION:\s*(.*)/) {
2912                     my $real_symbol=$1;
2913                     my $k;
2914
2915                     #print "SECTION DOCS found in source for : '$real_symbol'\n";
2916                     $ignore_broken_returns = 1;
2917                     for ($k = 0; $k <= $#params; $k += 2) {
2918                         #print "   '".$params[$k]."'\n";
2919                         $params[$k] = "\L$params[$k]";
2920                         if ($params[$k] eq "short_description") {
2921                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Short_Description"}=$params[$k+1];
2922                         } elsif ($params[$k] eq "see_also") {
2923                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:See_Also"}=$params[$k+1];
2924                         } elsif ($params[$k] eq "title") {
2925                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Title"}=$params[$k+1];
2926                         } elsif ($params[$k] eq "stability") {
2927                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Stability_Level"}=$params[$k+1];
2928                         } elsif ($params[$k] eq "section_id") {
2929                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Section_Id"}=$params[$k+1];
2930                         } elsif ($params[$k] eq "include") {
2931                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Include"}=$params[$k+1];
2932                         }
2933                     }
2934                     $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Long_Description"}=$description;
2935                     # FIXME $SourceSymbolTypes{XXX} = "STRUCT,SIGNAL,ARG,FUNCTION,MACRO";
2936                 } else {
2937                     #print "SYMBOL DOCS found in source for : '$symbol' ",length($description), "\n";
2938                     $SourceSymbolDocs{$symbol} = $description;
2939                     $SourceSymbolParams{$symbol} = [ @params ];
2940                     # FIXME $SourceSymbolTypes{XXX} = "";
2941                 }
2942
2943                 if ($since_desc) {
2944                     $Since{$symbol} = &ConvertSGMLChars ($symbol, $since_desc);
2945                 }
2946
2947                 if ($stability_desc) {
2948                     $stability_desc = &ParseStabilityLevel($stability_desc, "Stability level for $symbol");
2949                     $StabilityLevel{$symbol} = &ConvertSGMLChars ($symbol, $stability_desc);
2950                 }
2951
2952                 if ($deprecated_desc) {
2953                     if (exists $Deprecated{$symbol}) {
2954                     }
2955                     else {
2956                         print <<EOF;
2957 WARNING: $symbol is deprecated in the inline comments
2958          but no deprecation guards were found around the declaration.
2959          (See the --deprecated-guards option for gtkdoc-scan.)
2960 EOF
2961                     }
2962                     $Deprecated{$symbol} = &ConvertSGMLChars ($symbol, $deprecated_desc);
2963                 }
2964             }
2965
2966             $in_comment_block = 0;
2967             next;
2968         }
2969
2970         # Get rid of ' * ' at start of every line in the comment block.
2971         s%^\s*\*\s?%%;
2972         # But make sure we don't get rid of the newline at the end.
2973         if (!$_) {
2974             $_ = "\n";
2975         }
2976 #       print "DEBUG: scanning :$_";
2977
2978         # If we haven't found the symbol name yet, look for it.
2979         if (!$symbol) {
2980             if (m%^\s*(SECTION:\s*\S+)%) {
2981                 $symbol = $1;
2982                 #print "SECTION DOCS found in source for : '$symbol'\n";
2983                 $ignore_broken_returns = 1;
2984             } elsif (m%^\s*([\w:-]*\w)\s*:?%) {
2985                 $symbol = $1;
2986                 #print "SYMBOL DOCS found in source for : '$symbol'\n";
2987             }
2988             next;
2989         }
2990
2991         # If we're in the return value description, add it to the end.
2992         if ($in_return) {
2993             # If we find another valid returns line, we assume that the first
2994             # one was really part of the description.
2995             if (m/^\s*(returns:|return\s+value:)/i) {
2996                 if ($return_style eq 'broken') {
2997                     $description .= $return_start . $return_desc;
2998                 }
2999                 $return_start = $1;
3000                 if ($return_style eq 'sane') {
3001                     print <<EOF
3002 WARNING: Multiple Returns for $symbol
3003 EOF
3004                 }
3005                 $return_style = 'sane';
3006                 $ignore_broken_returns = 1;
3007                 $return_desc = $';
3008             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3009                 $description .= $return_start . $return_desc;
3010                 $return_start = $1;
3011                 $return_style = 'broken';
3012                 $return_desc = $';
3013             } elsif (m%^\s*since:%i) {
3014                 $since_desc = $';
3015                 $in_since = 1;
3016                 $in_return = 0;
3017             } elsif (m%^\s*stability:%i) {
3018                 $stability_desc = $';
3019                 $in_stability = 1;
3020                 $in_return = 0;
3021             } elsif (m%^\s*deprecated:%i) {
3022                 $deprecated_desc = $';
3023                 $in_deprecated = 1;
3024                 $in_return = 0;
3025             } else {
3026                 $return_desc .= $_;
3027             }
3028             next;
3029         }
3030
3031         if ($in_since) {
3032             if (m/^\s*(returns:|return\s+value:)/i) {
3033                 if ($return_style eq 'broken') {
3034                     $description .= $return_start . $return_desc;
3035                 }
3036                 $return_start = $1;
3037                 if ($return_style eq 'sane') {
3038                     print <<EOF
3039 WARNING: Multiple Returns for $symbol
3040 EOF
3041                 }
3042                 $return_style = 'sane';
3043                 $ignore_broken_returns = 1;
3044                 $return_desc = $';
3045                 $in_return = 1;
3046                 $in_since = 0;
3047             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3048                 $return_start = $1;
3049                 $return_style = 'broken';
3050                 $return_desc = $';
3051                 $in_return = 1;
3052                 $in_since = 0;
3053             } elsif (m%^\s*deprecated:%i) {
3054                 $deprecated_desc = $';
3055                 $in_deprecated = 1;
3056                 $in_since = 0;
3057             } elsif (m%^\s*stability:%i) {
3058                 $stability_desc = $';
3059                 $in_stability = 1;
3060                 $in_since = 0;
3061             } else {
3062                 $since_desc .= $_;
3063             }
3064             next;
3065         }
3066
3067         if ($in_stability) {
3068             if (m/^\s*(returns:|return\s+value:)/i) {
3069                 if ($return_style eq 'broken') {
3070                     $description .= $return_start . $return_desc;
3071                 }
3072                 $return_start = $1;
3073                 if ($return_style eq 'sane') {
3074                     print <<EOF
3075 WARNING: Multiple Returns for $symbol
3076 EOF
3077                 }
3078                 $return_style = 'sane';
3079                 $ignore_broken_returns = 1;
3080                 $return_desc = $';
3081                 $in_return = 1;
3082                 $in_stability = 0;
3083             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3084                 $return_start = $1;
3085                 $return_style = 'broken';
3086                 $return_desc = $';
3087                 $in_return = 1;
3088                 $in_stability = 0;
3089             } elsif (m%^\s*deprecated:%i) {
3090                 $deprecated_desc = $';
3091                 $in_deprecated = 1;
3092                 $in_stability = 0;
3093             } elsif (m%^\s*since:%i) {
3094                 $since_desc = $';
3095                 $in_since = 1;
3096                 $in_stability = 0;
3097             } else {
3098                 $stability_desc .= $_;
3099             }
3100             next;
3101         }
3102
3103         if ($in_deprecated) {
3104             if (m/^\s*(returns:|return\s+value:)/i) {
3105                 if ($return_style eq 'broken') {
3106                     $description .= $return_start . $return_desc;
3107                 }
3108                 $return_start = $1;
3109                 if ($return_style eq 'sane') {
3110                     print <<EOF
3111 WARNING: Multiple Returns for $symbol
3112 EOF
3113                 }
3114                 $return_style = 'sane';
3115                 $ignore_broken_returns = 1;
3116                 $return_desc = $';
3117                 $in_return = 1;
3118                 $in_deprecated = 0;
3119             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3120                 $return_start = $1;
3121                 $return_style = 'broken';
3122                 $return_desc = $';
3123                 $in_return = 1;
3124                 $in_deprecated = 0;
3125             } elsif (m%^\s*since:%i) {
3126                 $since_desc = $';
3127                 $in_since = 1;
3128                 $in_deprecated = 0;
3129             } elsif (m%^\s*stability:%i) {
3130                 $stability_desc = $';
3131                 $in_stability = 1;
3132                 $in_deprecated = 0;
3133             } else {
3134                 $deprecated_desc .= $_;
3135             }
3136             next;
3137         }
3138
3139         # If we're in the description part, check for the 'Returns:' line.
3140         # If that isn't found, add the text to the end.
3141         if ($in_description) {
3142             # Get rid of 'Description:'
3143             s%^\s*Description:%%;
3144
3145             if (m/^\s*(returns:|return\s+value:)/i) {
3146                 if ($return_style eq 'broken') {
3147                     $description .= $return_start . $return_desc;
3148                 }
3149                 $return_start = $1;
3150                 if ($return_style eq 'sane') {
3151                     print <<EOF
3152 WARNING: Multiple Returns for $symbol
3153 EOF
3154                 }
3155                 $return_style = 'sane';
3156                 $ignore_broken_returns = 1;
3157                 $return_desc = $';
3158                 $in_return = 1;
3159                 next;
3160             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3161                 $return_start = $1;
3162                 $return_style = 'broken';
3163                 $return_desc = $';
3164                 $in_return = 1;
3165                 next;
3166             } elsif (m%^\s*since:%i) {
3167                 $since_desc = $';
3168                 $in_since = 1;
3169                 next;
3170             } elsif (m%^\s*deprecated:%i) {
3171                 $deprecated_desc = $';
3172                 $in_deprecated = 1;
3173                 next;
3174             } elsif (m%^\s*stability:%i) {
3175                 $stability_desc = $';
3176                 $in_stability = 1;
3177                 next;
3178             }
3179
3180             $description .= $_;
3181             next;
3182         }
3183
3184         # We must be in the parameters. Check for the empty line below them.
3185         if (m%^\s*$%) {
3186             $in_description = 1;
3187             next;
3188         }
3189
3190         # Look for a parameter name.
3191         if (m%^\s*@(\S+)\s*:%) {
3192             my $param_name = $1;
3193             #print "Found parameter: $param_name\n";
3194             # Allow '...' as the Varargs parameter.
3195             if ($param_name eq "...") {
3196                 $param_name = "Varargs";
3197             }
3198             if ("\L$param_name" eq "returns") {
3199                 $return_style = 'sane';
3200                 $ignore_broken_returns = 1;
3201             }
3202             push (@params, $param_name);
3203             push (@params, $');
3204             $current_param += 2;
3205             next;
3206         }
3207
3208         # We must be in the middle of a parameter description, so add it on
3209         # to the last element in @params.
3210         if ($current_param == -1) {
3211             print <<EOF
3212 ERROR parsing comment block file : parameter expected -
3213  $file:$.
3214 EOF
3215         } else {
3216             $params[$#params] .= $_;
3217         }
3218     }
3219     close (SRCFILE);
3220 }
3221
3222 #############################################################################
3223 # Function    : OutputMissingDocumentation
3224 # Description : Outputs report of documentation coverage to a file
3225 #
3226 # Arguments   : none
3227 #############################################################################
3228
3229 sub OutputMissingDocumentation {
3230      my $n_documented = 0;
3231      my $n_incomplete = 0;
3232      my $total = 0;
3233      my $symbol;
3234      my $percent;
3235      my $msg;
3236      my $buffer = "";
3237      my $buffer_deprecated = "";
3238      my $buffer_descriptions = "";
3239
3240      open (UNDOCUMENTED, ">$ROOT_DIR/$MODULE-undocumented.txt")
3241           || die "Can't create $ROOT_DIR/$MODULE-undocumented.txt";
3242
3243      foreach $symbol (sort (keys (%AllSymbols))) {
3244           if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include)/) {
3245               $total++;
3246               if (exists ($AllDocumentedSymbols{$symbol})) {
3247                   $n_documented++;
3248                   if (exists ($AllIncompleteSymbols{$symbol})) {
3249                       $n_incomplete++;
3250                       $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
3251                   }
3252               } elsif (exists $Deprecated{$symbol}) {
3253                   if (exists ($AllIncompleteSymbols{$symbol})) {
3254                       $n_incomplete++;
3255                       $buffer_deprecated .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
3256                   } else {
3257                       $buffer_deprecated .= $symbol . "\n";
3258                   }
3259               } else {
3260                   if (exists ($AllIncompleteSymbols{$symbol})) {
3261                       $n_incomplete++;
3262                       $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
3263                   } else {
3264                       $buffer .= $symbol . "\n";
3265                   }
3266               }
3267           } elsif ($symbol =~ /:(Long_Description|Short_Description)/) {
3268               $total++;
3269               #my $len1=(exists($SymbolDocs{$symbol}))?length($SymbolDocs{$symbol}):-1;
3270               #my $len2=(exists($AllDocumentedSymbols{$symbol}))?length($AllDocumentedSymbols{$symbol}):-1;
3271               #print "%%%% $symbol : $len1,$len2\n";
3272               if (((exists ($SymbolDocs{$symbol})) && (length ($SymbolDocs{$symbol}) > 0))
3273               || ((exists ($AllDocumentedSymbols{$symbol})) && (length ($AllDocumentedSymbols{$symbol}) > 0))) {
3274                   $n_documented++;
3275               } else {
3276                   $symbol =~ m/^.*\/(.*)$/;
3277                   $buffer_descriptions .= $1 . "\n";
3278               }
3279           }
3280      }
3281
3282      $buffer .= "\n" . $buffer_deprecated . "\n" . $buffer_descriptions;
3283
3284      if ($total == 0) {
3285           $percent = 100;
3286      } else {
3287           $percent = ($n_documented / $total) * 100.0;
3288      }
3289
3290      printf UNDOCUMENTED "%.0f%% symbol docs coverage.\n", $percent;
3291      print UNDOCUMENTED "$n_documented symbols documented.\n";
3292      print UNDOCUMENTED "$n_incomplete symbols incomplete.\n";
3293      print UNDOCUMENTED ($total - $n_documented) . " not documented.\n\n\n";
3294
3295      print UNDOCUMENTED $buffer;
3296
3297      close (UNDOCUMENTED);
3298
3299      printf (("%.0f%% symbol docs coverage ($n_documented symbols documented, $n_incomplete symbols incomplete, " . ($total - $n_documented) . " not documented)\nSee $MODULE-undocumented.txt for a list of missing docs.\nThe doc coverage percentage doesn't include intro sections.\n"), $percent);
3300 }
3301
3302
3303 #############################################################################
3304 # Function    : OutputUndeclaredSymbols
3305 # Description : Outputs symbols that are undeclared yet documented to a file
3306 #
3307 # Arguments   : none
3308 #############################################################################
3309
3310 sub OutputUndeclaredSymbols {
3311     open(UNDECLARED, ">$ROOT_DIR/$MODULE-undeclared.txt")
3312         || die "Can't create $ROOT_DIR/$MODULE-undeclared.txt";
3313
3314     if (%UndeclaredSymbols) {
3315         print UNDECLARED (join("\n", sort keys %UndeclaredSymbols));
3316         print UNDECLARED "\n";
3317         print "See $MODULE-undeclared.txt for the list of undeclared symbols.\n"
3318     }
3319     close(UNDECLARED);
3320 }
3321
3322
3323 #############################################################################
3324 # Function    : OutputAllSymbols
3325 # Description : Outputs list of all symbols to a file
3326 #
3327 # Arguments   : none
3328 #############################################################################
3329
3330 sub OutputAllSymbols {
3331      my $n_documented = 0;
3332      my $total = 0;
3333      my $symbol;
3334      my $percent;
3335      my $msg;
3336
3337      open (SYMBOLS, ">$ROOT_DIR/$MODULE-symbols.txt")
3338           || die "Can't create $ROOT_DIR/$MODULE-symbols.txt";
3339
3340      foreach $symbol (sort (keys (%AllSymbols))) {
3341           print SYMBOLS $symbol . "\n"
3342      }
3343
3344      close (SYMBOLS);
3345 }
3346
3347
3348 #############################################################################
3349 # Function    : MergeSourceDocumentation
3350 # Description : This merges documentation read from a source file into the
3351 #               documentation read in from a template file.
3352 #
3353 #               Parameter descriptions override any in the template files.
3354 #               Function descriptions are placed before any description from
3355 #               the template files.
3356 #
3357 # Arguments   : none
3358 #############################################################################
3359
3360 sub MergeSourceDocumentation {
3361     my $symbol;
3362     my @Symbols;
3363
3364     if (scalar %SymbolDocs) {
3365         @Symbols=keys (%SymbolDocs);
3366     }
3367     else {
3368         @Symbols=keys (%SourceSymbolDocs);
3369     }
3370     foreach $symbol (@Symbols) {
3371         $AllSymbols{$symbol} = 1;
3372
3373         my $have_tmpl_docs = 0;
3374
3375         ## See if the symbol is documented out-of-line
3376         my $tmpl_doc = $SymbolDocs{$symbol};
3377         $tmpl_doc = defined ($tmpl_doc) ? $tmpl_doc : "";
3378         $tmpl_doc =~ s/<\/?[a-z]+>//g;
3379         $tmpl_doc =~ s/\s//g;
3380         if ($tmpl_doc ne "") {
3381             $have_tmpl_docs = 1;
3382         }
3383
3384         #print "merging $symbol\n";
3385
3386         if (exists ($SourceSymbolDocs{$symbol})) {
3387             my $src_doc = $SourceSymbolDocs{$symbol};
3388             my $tmpl_doc = $SymbolDocs{$symbol};
3389             my $type = $DeclarationTypes {$symbol};
3390
3391             #print "... from source\n";
3392
3393             my $item = "Parameter";
3394             if (defined ($type)) {
3395                 if ($type eq 'STRUCT') {
3396                     $item = "Field";
3397                 } elsif ($type eq 'ENUM') {
3398                     $item = "Value";
3399                 } elsif ($type eq 'UNION') {
3400                     $item = "Field";
3401                 }
3402             } else {
3403                 $type="SIGNAL";
3404             }
3405
3406             $tmpl_doc = defined ($tmpl_doc) ? $tmpl_doc : "";
3407             $src_doc =~ s/^\s+//;
3408             $src_doc =~ s/\s+$//;
3409
3410             # Don't output warnings for overridden titles as titles are
3411             # automatically generated in the -sections.txt file so are often
3412             # overridden.
3413             if ($have_tmpl_docs && $symbol !~ m/:Title$/) {
3414                     print <<EOF;
3415 WARNING: Documentation in template file for $symbol being overridden by inline comments
3416 EOF
3417             }
3418
3419             if ($src_doc ne "") {
3420                  $AllDocumentedSymbols{$symbol} = 1;
3421             }
3422
3423             # Convert <!--PARAMETERS--> with any blank lines around it to
3424             # a </para> followed by <!--PARAMETERS--> followed by <para>.
3425             $src_doc =~ s%\n+\s*<!--PARAMETERS-->\s*\n+%\n</para>\n<!--PARAMETERS-->\n<para>\n%g;
3426
3427             # If there is a blank line, finish the paragraph and start another.
3428             $src_doc = &ConvertBlankLines ($src_doc, $symbol);
3429
3430             if ($symbol =~ m/$TMPL_DIR\/.+:Long_Description/) {
3431                 # FIXME: should we check for empty $tmpl_doc ?
3432                 $SymbolDocs{$symbol} = "<para>\n$src_doc</para>\n$tmpl_doc"
3433             } elsif ($symbol =~ m/$TMPL_DIR\/.+:.+/) {
3434                 # For the title/summary/see also section docs we don't want to
3435                 # add any <para> tags.
3436                 $SymbolDocs{$symbol} = "$src_doc"
3437             } else {
3438                 $SymbolDocs{$symbol} = "<para>\n$src_doc</para>\n$tmpl_doc";
3439             }
3440
3441             # merge parameters
3442             if ($symbol =~ m/.*::.*/) {
3443                 # For signals we prefer the param names from the source docs,
3444                 # since the ones from the templates are likely to contain the
3445                 # artificial argn names which are generated by gtkdoc-scangobj.
3446                 $SymbolParams{$symbol} = $SourceSymbolParams{$symbol};
3447                 # FIXME: we need to check for empty docs here as well!
3448             } else {
3449                 # The templates contain the definitive parameter names and order,
3450                 # so we will not change that. We only override the actual text.
3451                 my $tmpl_params = $SymbolParams{$symbol};
3452                 if (!defined ($tmpl_params)) {
3453                     #print "No merge needed for $symbol\n";
3454                     $SymbolParams{$symbol} = $SourceSymbolParams{$symbol};
3455                 } else {
3456                     my $params = $SourceSymbolParams{$symbol};
3457                     my $j;
3458                     for ($j = 0; $j <= $#$tmpl_params; $j += 2) {
3459                         my $tmpl_param_name = $$tmpl_params[$j];
3460
3461                         # Allow '...' as the Varargs parameter.
3462                         if ($tmpl_param_name eq "...") {
3463                           $tmpl_param_name = "Varargs";
3464                         }
3465
3466                         # Try to find the param in the source comment documentation.
3467                         my $found = 0;
3468                         my $k;
3469                         for ($k = 0; $k <= $#$params; $k += 2) {
3470                             my $param_name = $$params[$k];
3471                             my $param_desc = $$params[$k + 1];
3472
3473                             # We accept changes in case, since the Gnome source docs
3474                             # contain a lot of these.
3475                             if ("\L$param_name" eq "\L$tmpl_param_name") {
3476                                 $found = 1;
3477
3478                                 # Override the description.
3479                                 $$tmpl_params[$j + 1] = $param_desc ;
3480
3481                                 # Set the name to "" to mark it as used.
3482                                 $$params[$k] = "";
3483                                 last;
3484                             }
3485                         }
3486
3487                         # If it looks like the parameters are there, but not
3488                         # in the right place, try to explain a bit better.
3489                         if ((!$found) && ($src_doc =~ m/\@$tmpl_param_name:/)) {
3490                             print <<EOF;
3491          Parameters must start on the line immediately after the function
3492          or macro name.
3493 EOF
3494                         }
3495                     }
3496
3497                     # Now we output a warning if parameters have been described which
3498                     # do not exist.
3499                     for ($j = 0; $j <= $#$params; $j += 2) {
3500                         my $param_name = $$params[$j];
3501                         if ($param_name) {
3502                             # the template builder cannot detect if a macro returns
3503                             # a result or not
3504                             if(($type eq "MACRO") && ($param_name eq "Returns")) {
3505                                 next;
3506                             }
3507                             print <<EOF;
3508 WARNING: $item described in source code comment block but does not exist -
3509          $type: $symbol $item: $param_name.
3510 EOF
3511                         }
3512                     }
3513                 }
3514             }
3515         } else {
3516             if ($have_tmpl_docs) {
3517                 $AllDocumentedSymbols{$symbol} = 1;
3518             }
3519             else {
3520                 #print "... undocumented\n";
3521             }
3522         }
3523         # if this symbol is documented, check if docs are complete
3524         $tmpl_doc = $SymbolDocs{$symbol};
3525         $tmpl_doc = defined ($tmpl_doc) ? $tmpl_doc : "";
3526         $tmpl_doc =~ s/<\/?[a-z]+>//g;
3527         $tmpl_doc =~ s/\s//g;
3528         if ($tmpl_doc ne "") {
3529             my $tmpl_params = $SymbolParams{$symbol};
3530             if (defined ($tmpl_params)) {
3531                 my $type = $DeclarationTypes {$symbol};
3532
3533                 my $item = "Parameter";
3534                 if (defined ($type)) {
3535                     if ($type eq 'STRUCT') {
3536                         $item = "Field";
3537                     } elsif ($type eq 'ENUM') {
3538                         $item = "Value";
3539                     } elsif ($type eq 'UNION') {
3540                         $item = "Field";
3541                     }
3542                 } else {
3543                     $type="SIGNAL";
3544                 }
3545
3546                 my $j;
3547                 for ($j = 0; $j <= $#$tmpl_params; $j += 2) {
3548                     # Output a warning if the parameter is empty and
3549                     # remember for stats.
3550                     my $tmpl_param_name = $$tmpl_params[$j];
3551                     my $tmpl_param_desc = $$tmpl_params[$j + 1];
3552                     if ($tmpl_param_desc !~ m/\S/) {
3553                         if (exists ($AllIncompleteSymbols{$symbol})) {
3554                             $AllIncompleteSymbols{$symbol}.=", ".$tmpl_param_name;
3555                         } else {
3556                             $AllIncompleteSymbols{$symbol}=$tmpl_param_name;
3557                         }
3558 #                        print <<EOF;
3559 #WARNING: $item description missing in source code comment block -
3560 # $type: $symbol $item: $tmpl_param_name.
3561 #EOF
3562                     }
3563                 }
3564             }
3565         }
3566    }
3567 }
3568
3569 sub IsEmptyDoc {
3570     my ($doc) = @_;
3571
3572     if ($doc =~ /^\s*<para>\s*(FIXME)?\s*<\/para>\s*$/) {
3573         return 1;
3574     } else {
3575         return 0;
3576     }
3577 }
3578
3579
3580 # This converts blank lines to "</para><para>", but only outside CDATA and
3581 # <programlisting> tags.
3582 sub ConvertBlankLines {
3583     return &ModifyXMLElements ($_[0], $_[1],
3584                                "<!\\[CDATA\\[|<programlisting[^>]*>|\\|\\[",
3585                                \&ConvertBlankLinesEndTag,
3586                                \&ConvertBlankLinesCallback);
3587 }
3588
3589
3590 sub ConvertBlankLinesEndTag {
3591   if ($_[0] eq "<!\[CDATA\[") {
3592     return "]]>";
3593   } elsif ($_[0] eq "|[") {
3594     return "]\\|";
3595   } else {
3596     return "</programlisting>";
3597   }
3598 }
3599
3600 sub ConvertBlankLinesCallback {
3601   my ($text, $symbol, $tag) = @_;
3602
3603   # If we're not in CDATA or a <programlisting> we convert blank lines so
3604   # they start a new <para>.
3605   if ($tag eq "") {
3606     $text =~ s%\n{2,}%\n</para>\n<para>\n%g;
3607   }
3608
3609   return $text;
3610 }
3611
3612
3613 #############################################################################
3614 # LIBRARY FUNCTIONS -   These functions are used in both gtkdoc-mkdb and
3615 #                       gtkdoc-mktmpl and should eventually be moved to a
3616 #                       separate library.
3617 #############################################################################
3618
3619 #############################################################################
3620 # Function    : ReadDeclarationsFile
3621 # Description : This reads in a file containing the function/macro/enum etc.
3622 #               declarations.
3623 #
3624 #               Note that in some cases there are several declarations with
3625 #               the same name, e.g. for conditional macros. In this case we
3626 #               set a flag in the %DeclarationConditional hash so the
3627 #               declaration is not shown in the docs.
3628 #
3629 #               If a macro and a function have the same name, e.g. for
3630 #               gtk_object_ref, the function declaration takes precedence.
3631 #
3632 #               Some opaque structs are just declared with 'typedef struct
3633 #               _name name;' in which case the declaration may be empty.
3634 #               The structure may have been found later in the header, so
3635 #               that overrides the empty declaration.
3636 #
3637 # Arguments   : $file - the declarations file to read
3638 #               $override - if declarations in this file should override
3639 #                       any current declaration.
3640 #############################################################################
3641
3642 sub ReadDeclarationsFile {
3643     my ($file, $override) = @_;
3644
3645     if ($override == 0) {
3646         %Declarations = ();
3647         %DeclarationTypes = ();
3648         %DeclarationConditional = ();
3649         %DeclarationOutput = ();
3650     }
3651
3652     open (INPUT, $file)
3653         || die "Can't open $file";
3654     my $declaration_type = "";
3655     my $declaration_name;
3656     my $declaration;
3657     my $is_deprecated = 0;
3658     while (<INPUT>) {
3659         if (!$declaration_type) {
3660             if (m/^<([^>]+)>/) {
3661                 $declaration_type = $1;
3662                 $declaration_name = "";
3663 #               print "Found declaration: $declaration_type\n";
3664                 $declaration = "";
3665             }
3666         } else {
3667             if (m%^<NAME>(.*)</NAME>%) {
3668                 $declaration_name = $1;
3669             } elsif (m%^<DEPRECATED/>%) {
3670                 $is_deprecated = 1;
3671             } elsif (m%^</$declaration_type>%) {
3672 #               print "Found end of declaration: $declaration_name\n";
3673                 # Check that the declaration has a name
3674                 if ($declaration_name eq "") {
3675                     print "ERROR: $declaration_type has no name $file:$.\n";
3676                 }
3677
3678                 # If the declaration is an empty typedef struct _XXX XXX
3679                 # set the flag to indicate the struct has a typedef.
3680                 if ($declaration_type eq 'STRUCT'
3681                     && $declaration =~ m/^\s*$/) {
3682 #                   print "Struct has typedef: $declaration_name\n";
3683                     $StructHasTypedef{$declaration_name} = 1;
3684                 }
3685
3686                 # Check if the symbol is already defined.
3687                 if (defined ($Declarations{$declaration_name})
3688                     && $override == 0) {
3689                     # Function declarations take precedence.
3690                     if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') {
3691                         # Ignore it.
3692                     } elsif ($declaration_type eq 'FUNCTION') {
3693                         if ($is_deprecated) {
3694                             $Deprecated{$declaration_name} = "";
3695                         }
3696                         $Declarations{$declaration_name} = $declaration;
3697                         $DeclarationTypes{$declaration_name} = $declaration_type;
3698                     } elsif ($DeclarationTypes{$declaration_name}
3699                               eq $declaration_type) {
3700                         # If the existing declaration is empty, or is just a
3701                         # forward declaration of a struct, override it.
3702                         if ($declaration_type eq 'STRUCT') {
3703                             if ($Declarations{$declaration_name} =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
3704                                 if ($is_deprecated) {
3705                                     $Deprecated{$declaration_name} = "";
3706                                 }
3707                                 $Declarations{$declaration_name} = $declaration;
3708                             } elsif ($declaration =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
3709                                 # Ignore an empty or forward declaration.
3710                             } else {
3711                                 print "WARNING: Structure has multiple definitions: $declaration_name\n";
3712                             }
3713
3714                         } else {
3715                             # set flag in %DeclarationConditional hash for
3716                             # multiply defined macros/typedefs.
3717                             $DeclarationConditional{$declaration_name} = 1;
3718                         }
3719                     } else {
3720                         print "ERROR: $declaration_name has multiple definitions\n";
3721                     }
3722                 } else {
3723                     if ($is_deprecated) {
3724                         $Deprecated{$declaration_name} = "";
3725                     }
3726                     $Declarations{$declaration_name} = $declaration;
3727                     $DeclarationTypes{$declaration_name} = $declaration_type;
3728                 }
3729
3730                 $declaration_type = "";
3731                 $is_deprecated = 0;
3732             } else {
3733                 $declaration .= $_;
3734             }
3735         }
3736     }
3737     close (INPUT);
3738 }
3739
3740
3741 #############################################################################
3742 # Function    : ReadSignalsFile
3743 # Description : This reads in an existing file which contains information on
3744 #               all GTK signals. It creates the arrays @SignalNames and
3745 #               @SignalPrototypes containing info on the signals. The first
3746 #               line of the SignalPrototype is the return type of the signal
3747 #               handler. The remaining lines are the parameters passed to it.
3748 #               The last parameter, "gpointer user_data" is always the same
3749 #               so is not included.
3750 # Arguments   : $file - the file containing the signal handler prototype
3751 #                       information.
3752 #############################################################################
3753
3754 sub ReadSignalsFile {
3755     my ($file) = @_;
3756
3757     my $in_signal = 0;
3758     my $signal_object;
3759     my $signal_name;
3760     my $signal_returns;
3761     my $signal_flags;
3762     my $signal_prototype;
3763
3764     # Reset the signal info.
3765     @SignalObjects = ();
3766     @SignalNames = ();
3767     @SignalReturns = ();
3768     @SignalFlags = ();
3769     @SignalPrototypes = ();
3770
3771     if (! -f $file) {
3772         return;
3773     }
3774     if (!open (INPUT, $file)) {
3775         warn "Can't open $file - skipping signals\n";
3776         return;
3777     }
3778     while (<INPUT>) {
3779         if (!$in_signal) {
3780             if (m/^<SIGNAL>/) {
3781                 $in_signal = 1;
3782                 $signal_object = "";
3783                 $signal_name = "";
3784                 $signal_returns = "";
3785                 $signal_prototype = "";
3786             }
3787         } else {
3788             if (m/^<NAME>(.*)<\/NAME>/) {
3789                 $signal_name = $1;
3790                 if ($signal_name =~ m/^(.*)::(.*)$/) {
3791                     $signal_object = $1;
3792                     ($signal_name = $2) =~ s/_/-/g;
3793 #                   print "Found signal: $signal_name\n";
3794                 } else {
3795                     print "Invalid signal name: $signal_name\n";
3796                 }
3797             } elsif (m/^<RETURNS>(.*)<\/RETURNS>/) {
3798                 $signal_returns = $1;
3799             } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
3800                 $signal_flags = $1;
3801             } elsif (m%^</SIGNAL>%) {
3802 #               print "Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}";
3803                 push (@SignalObjects, $signal_object);
3804                 push (@SignalNames, $signal_name);
3805                 push (@SignalReturns, $signal_returns);
3806                 push (@SignalFlags, $signal_flags);
3807                 push (@SignalPrototypes, $signal_prototype);
3808                 $in_signal = 0;
3809             } else {
3810                 $signal_prototype .= $_;
3811             }
3812         }
3813     }
3814     close (INPUT);
3815 }
3816
3817
3818 #############################################################################
3819 # Function    : ReadTemplateFile
3820 # Description : This reads in the manually-edited documentation file
3821 #               corresponding to the file currently being created, so we can
3822 #               insert the documentation at the appropriate places.
3823 #               It outputs %SymbolTypes, %SymbolDocs and %SymbolParams, which
3824 #               is a hash of arrays.
3825 #               NOTE: This function is duplicated in gtkdoc-mkdb (but
3826 #               slightly different).
3827 # Arguments   : $docsfile - the template file to read in.
3828 #               $skip_unused_params - 1 if the unused parameters should be
3829 #                       skipped.
3830 #############################################################################
3831
3832 sub ReadTemplateFile {
3833     my ($docsfile, $skip_unused_params) = @_;
3834
3835     my $template = "$docsfile.sgml";
3836 #    print "Reading $template\n";
3837     if (! -f $template) {
3838 #       print "File doesn't exist: $template\n";
3839         return;
3840     }
3841
3842     my $current_type = "";      # Type of symbol being read.
3843     my $current_symbol = "";    # Name of symbol being read.
3844     my $symbol_doc = "";                # Description of symbol being read.
3845     my @params;                 # Parameter names and descriptions of current
3846                                 #   function/macro/function typedef.
3847     my $current_param = -1;     # Index of parameter currently being read.
3848                                 #   Note that the param array contains pairs
3849                                 #   of param name & description.
3850     my $in_unused_params = 0;   # True if we are reading in the unused params.
3851     my $in_deprecated = 0;
3852     my $in_since = 0;
3853     my $in_stability = 0;
3854
3855     open (DOCS, "$template")
3856         || die "Can't open file $template: $!";
3857     while (<DOCS>) {
3858         if (m/^<!-- ##### ([A-Z_]+) (\S+) ##### -->/) {
3859             my $type = $1;
3860             my $symbol = $2;
3861             if ($symbol eq "Title"
3862                 || $symbol eq "Short_Description"
3863                 || $symbol eq "Long_Description"
3864                 || $symbol eq "See_Also"
3865                 || $symbol eq "Stability_Level"
3866                 || $symbol eq "Include") {
3867
3868                 $symbol = $docsfile . ":" . $symbol;
3869             }
3870
3871 #           print "Found symbol: $symbol\n";
3872
3873             # Store previous symbol, but remove any trailing blank lines.
3874             if ($current_symbol ne "") {
3875                 $symbol_doc =~ s/\s+$//;
3876                 $SymbolTypes{$current_symbol} = $current_type;
3877                 $SymbolDocs{$current_symbol} = $symbol_doc;
3878
3879                 # Check that the stability level is valid.
3880                 if ($StabilityLevel{$current_symbol}) {
3881                     $StabilityLevel{$current_symbol} = &ParseStabilityLevel($StabilityLevel{$current_symbol}, "Stability level for $current_symbol");
3882                 }
3883
3884                 if ($current_param >= 0) {
3885                     $SymbolParams{$current_symbol} = [ @params ];
3886                 } else {
3887                     # Delete any existing params in case we are overriding a
3888                     # previously read template.
3889                     delete $SymbolParams{$current_symbol};
3890                 }
3891             }
3892             $current_type = $type;
3893             $current_symbol = $symbol;
3894             $current_param = -1;
3895             $in_unused_params = 0;
3896             $in_deprecated = 0;
3897             $in_since = 0;
3898             $in_stability = 0;
3899             $symbol_doc = "";
3900             @params = ();
3901
3902         } elsif (m/^<!-- # Unused Parameters # -->/) {
3903 #           print "DEBUG: Found unused parameters\n";
3904             $in_unused_params = 1;
3905             next;
3906
3907         } elsif ($in_unused_params && $skip_unused_params) {
3908             # When outputting the DocBook we skip unused parameters.
3909 #           print "DEBUG: Skipping unused param: $_";
3910             next;
3911
3912         } else {
3913             # Check if param found. Need to handle "..." and "format...".
3914             if (s/^\@([\w\.]+):\040?//) {
3915                 my $param_name = $1;
3916                 # Allow variations of 'Returns'
3917                 if ($param_name =~ m/^[Rr]eturns?$/) {
3918                     $param_name = "Returns";
3919                 }
3920 #               print "Found param for symbol $current_symbol : '$param_name'= '$_'\n";
3921
3922                 if ($param_name eq "Deprecated") {
3923                     $in_deprecated = 1;
3924                     $Deprecated{$current_symbol} = $_;
3925                 } elsif ($param_name eq "Since") {
3926                     $in_since = 1;
3927                     $Since{$current_symbol} = $_;
3928                 } elsif ($param_name eq "Stability") {
3929                     $in_stability = 1;
3930                     $StabilityLevel{$current_symbol} = $_;
3931                 } else {
3932                     push (@params, $param_name);
3933                     push (@params, $_);
3934                     $current_param += 2;
3935                 }
3936             } else {
3937                 if ($in_deprecated) {
3938                     $Deprecated{$current_symbol} .= $_;
3939                 } elsif ($in_since) {
3940                     $Since{$current_symbol} .= $_;
3941                 } elsif ($in_stability) {
3942                     $StabilityLevel{$current_symbol} .= $_;
3943                 } elsif ($current_param >= 0) {
3944                     $params[$current_param] .= $_;
3945                 } else {
3946                     $symbol_doc .= $_;
3947                 }
3948             }
3949         }
3950     }
3951
3952     # Remember to finish the current symbol doccs.
3953     if ($current_symbol ne "") {
3954
3955         $symbol_doc =~ s/\s+$//;
3956         $SymbolTypes{$current_symbol} = $current_type;
3957         $SymbolDocs{$current_symbol} = $symbol_doc;
3958
3959         # Check that the stability level is valid.
3960         if ($StabilityLevel{$current_symbol}) {
3961             $StabilityLevel{$current_symbol} = &ParseStabilityLevel($StabilityLevel{$current_symbol}, "Stability level for $current_symbol");
3962         }
3963
3964         if ($current_param >= 0) {
3965             $SymbolParams{$current_symbol} = [ @params ];
3966         } else {
3967             # Delete any existing params in case we are overriding a
3968             # previously read template.
3969             delete $SymbolParams{$current_symbol};
3970         }
3971     }
3972
3973     close (DOCS);
3974 }
3975
3976
3977 #############################################################################
3978 # Function    : ReadObjectHierarchy
3979 # Description : This reads in the $MODULE-hierarchy.txt file containing all
3980 #               the GtkObject subclasses described in this module (and their
3981 #               ancestors).
3982 #               It places them in the @Objects array, and places their level
3983 #               in the widget hierarchy in the @ObjectLevels array, at the
3984 #               same index. GtkObject, the root object, has a level of 1.
3985 #
3986 #               FIXME: the version in gtkdoc-mkdb also generates tree_index.sgml
3987 #               as it goes along, this should be split out into a separate
3988 #               function.
3989 #
3990 # Arguments   : none
3991 #############################################################################
3992
3993 sub ReadObjectHierarchy {
3994     @Objects = ();
3995     @ObjectLevels = ();
3996
3997     if (! -f $OBJECT_TREE_FILE) {
3998         return;
3999     }
4000     if (!open (INPUT, $OBJECT_TREE_FILE)) {
4001         warn "Can't open $OBJECT_TREE_FILE - skipping object tree\n";
4002         return;
4003     }
4004
4005     my $old_tree_index = "$SGML_OUTPUT_DIR/tree_index.sgml";
4006     my $new_tree_index = "$SGML_OUTPUT_DIR/tree_index.new";
4007     my $tree_header = $doctype_header;
4008     $tree_header =~ s/<!DOCTYPE \w+/<!DOCTYPE screen/;
4009
4010     open (OUTPUT, ">$new_tree_index")
4011         || die "Can't create $new_tree_index";
4012     print (OUTPUT "$tree_header<screen>\n");
4013
4014     # Only emit objects if they are supposed to be documented, or if
4015     # they have documented children. To implement this, we maintain a
4016     # stack of pending objects which will be emitted if a documented
4017     # child turns up.
4018     my @pending_objects = ();
4019     my @pending_levels = ();
4020     while (<INPUT>) {
4021         if (m/\S+/) {
4022             my $object = $&;
4023             my $level = (length($`)) / 2 + 1;
4024             my $xref = "";
4025
4026             while (($#pending_levels >= 0) && ($pending_levels[$#pending_levels] >= $level)) {
4027                 my $pobject = pop(@pending_objects);
4028                 my $plevel = pop(@pending_levels);
4029             }
4030
4031             push (@pending_objects, $object);
4032             push (@pending_levels, $level);
4033
4034             if (exists($KnownSymbols{$object}) && $KnownSymbols{$object} == 1) {
4035                 while ($#pending_levels >= 0) {
4036                     $object = shift @pending_objects;
4037                     $level = shift @pending_levels;
4038                     $xref = &MakeXRef ($object);
4039
4040                     print (OUTPUT ' ' x ($level * 4), "$xref\n");
4041                     push (@Objects, $object);
4042                     push (@ObjectLevels, $level);
4043                 }
4044             }
4045         }
4046     }
4047     print (OUTPUT "</screen>\n");
4048
4049     close (INPUT);
4050     close (OUTPUT);
4051
4052     &UpdateFileIfChanged ($old_tree_index, $new_tree_index, 0);
4053
4054     &OutputObjectList;
4055 }
4056
4057 #############################################################################
4058 # Function    : ReadInterfaces
4059 # Description : This reads in the $MODULE.interfaces file.
4060 #
4061 # Arguments   : none
4062 #############################################################################
4063
4064 sub ReadInterfaces {
4065     %Interfaces = ();
4066
4067     if (! -f $INTERFACES_FILE) {
4068         return;
4069     }
4070     if (!open (INPUT, $INTERFACES_FILE)) {
4071         warn "Can't open $INTERFACES_FILE - skipping interfaces\n";
4072         return;
4073     }
4074
4075     while (<INPUT>) {
4076        chomp;
4077        my ($object, @ifaces) = split;
4078        if (exists($KnownSymbols{$object}) && $KnownSymbols{$object} == 1) {
4079            my @knownIfaces = ();
4080
4081            # filter out private interfaces, but leave foreign interfaces
4082            foreach my $iface (@ifaces) {
4083                if (!exists($KnownSymbols{$iface}) || $KnownSymbols{$iface} == 1) {
4084                    push (@knownIfaces, $iface);
4085                }
4086              }
4087
4088            $Interfaces{$object} = join(' ', @knownIfaces);
4089        }
4090     }
4091     close (INPUT);
4092 }
4093
4094 #############################################################################
4095 # Function    : ReadPrerequisites
4096 # Description : This reads in the $MODULE.prerequisites file.
4097 #
4098 # Arguments   : none
4099 #############################################################################
4100
4101 sub ReadPrerequisites {
4102     %Prerequisites = ();
4103
4104     if (! -f $PREREQUISITES_FILE) {
4105         return;
4106     }
4107     if (!open (INPUT, $PREREQUISITES_FILE)) {
4108         warn "Can't open $PREREQUISITES_FILE - skipping prerequisites\n";
4109         return;
4110     }
4111
4112     while (<INPUT>) {
4113        chomp;
4114        my ($iface, @prereqs) = split;
4115        if (exists($KnownSymbols{$iface}) && $KnownSymbols{$iface} == 1) {
4116            my @knownPrereqs = ();
4117
4118            # filter out private prerequisites, but leave foreign prerequisites
4119            foreach my $prereq (@prereqs) {
4120                if (!exists($KnownSymbols{$prereq}) || $KnownSymbols{$prereq} == 1) {
4121                   push (@knownPrereqs, $prereq);
4122                }
4123            }
4124
4125            $Prerequisites{$iface} = join(' ', @knownPrereqs);
4126        }
4127     }
4128     close (INPUT);
4129 }
4130
4131 #############################################################################
4132 # Function    : ReadArgsFile
4133 # Description : This reads in an existing file which contains information on
4134 #               all GTK args. It creates the arrays @ArgObjects, @ArgNames,
4135 #               @ArgTypes, @ArgFlags, @ArgNicks and @ArgBlurbs containing info
4136 #               on the args.
4137 # Arguments   : $file - the file containing the arg information.
4138 #############################################################################
4139
4140 sub ReadArgsFile {
4141     my ($file) = @_;
4142
4143     my $in_arg = 0;
4144     my $arg_object;
4145     my $arg_name;
4146     my $arg_type;
4147     my $arg_flags;
4148     my $arg_nick;
4149     my $arg_blurb;
4150     my $arg_default;
4151     my $arg_range;
4152
4153     # Reset the args info.
4154     @ArgObjects = ();
4155     @ArgNames = ();
4156     @ArgTypes = ();
4157     @ArgFlags = ();
4158     @ArgNicks = ();
4159     @ArgBlurbs = ();
4160     @ArgDefaults = ();
4161     @ArgRanges = ();
4162
4163     if (! -f $file) {
4164         return;
4165     }
4166     if (!open (INPUT, $file)) {
4167         warn "Can't open $file - skipping args\n";
4168         return;
4169     }
4170     while (<INPUT>) {
4171         if (!$in_arg) {
4172             if (m/^<ARG>/) {
4173                 $in_arg = 1;
4174                 $arg_object = "";
4175                 $arg_name = "";
4176                 $arg_type = "";
4177                 $arg_flags = "";
4178                 $arg_nick = "";
4179                 $arg_blurb = "";
4180                 $arg_default = "";
4181                 $arg_range = "";
4182             }
4183         } else {
4184             if (m/^<NAME>(.*)<\/NAME>/) {
4185                 $arg_name = $1;
4186                 if ($arg_name =~ m/^(.*)::(.*)$/) {
4187                     $arg_object = $1;
4188                     ($arg_name = $2) =~ s/_/-/g;
4189 #                   print "Found arg: $arg_name\n";
4190                 } else {
4191                     print "Invalid arg name: $arg_name\n";
4192                 }
4193             } elsif (m/^<TYPE>(.*)<\/TYPE>/) {
4194                 $arg_type = $1;
4195             } elsif (m/^<RANGE>(.*)<\/RANGE>/) {
4196                 $arg_range = $1;
4197             } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
4198                 $arg_flags = $1;
4199             } elsif (m/^<NICK>(.*)<\/NICK>/) {
4200                 $arg_nick = $1;
4201             } elsif (m/^<BLURB>(.*)<\/BLURB>/) {
4202                 $arg_blurb = $1;
4203                 if ($arg_blurb eq "(null)") {
4204                   $arg_blurb = "";
4205                   print <<EOF;
4206 WARNING: Property ${arg_object}:${arg_name} has no documentation.
4207 EOF
4208                 }
4209             } elsif (m/^<DEFAULT>(.*)<\/DEFAULT>/) {
4210                 $arg_default = $1;
4211             } elsif (m%^</ARG>%) {
4212 #               print "Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n";
4213                 push (@ArgObjects, $arg_object);
4214                 push (@ArgNames, $arg_name);
4215                 push (@ArgTypes, $arg_type);
4216                 push (@ArgRanges, $arg_range);
4217                 push (@ArgFlags, $arg_flags);
4218                 push (@ArgNicks, $arg_nick);
4219                 push (@ArgBlurbs, $arg_blurb);
4220                 push (@ArgDefaults, $arg_default);
4221                 $in_arg = 0;
4222             }
4223         }
4224     }
4225     close (INPUT);
4226 }
4227
4228
4229 #############################################################################
4230 # Function    : CheckIsObject
4231 # Description : Returns 1 if the given name is a GtkObject or a subclass.
4232 #               It uses the global @Objects array.
4233 #               Note that the @Objects array only contains classes in the
4234 #               current module and their ancestors - not all GTK classes.
4235 # Arguments   : $name - the name to check.
4236 #############################################################################
4237
4238 sub CheckIsObject {
4239     my ($name) = @_;
4240
4241     my $object;
4242     foreach $object (@Objects) {
4243         if ($object eq $name) {
4244             return 1;
4245         }
4246     }
4247     return 0;
4248 }
4249
4250
4251 #############################################################################
4252 # Function    : MakeReturnField
4253 # Description : Pads a string to $RETURN_TYPE_FIELD_WIDTH.
4254 # Arguments   : $str - the string to pad.
4255 #############################################################################
4256
4257 sub MakeReturnField {
4258     my ($str) = @_;
4259
4260     return $str . (' ' x ($RETURN_TYPE_FIELD_WIDTH - length ($str)));
4261 }
4262