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 </refentry>
1669 EOF
1670     close (OUTPUT);
1671
1672     return &UpdateFileIfChanged ($old_sgml_file, $new_sgml_file, 0);
1673 }
1674
1675
1676 #############################################################################
1677 # Function    : OutputExtraFile
1678 # Description : Copies an "extra" DocBook file into the output directory,
1679 #               expanding abbreviations
1680 # Arguments   : $file - the source file.
1681 #############################################################################
1682 sub OutputExtraFile {
1683     my ($file) = @_;
1684
1685     my $basename;
1686
1687     ($basename = $file) =~ s!^.*/!!;
1688
1689     my $old_sgml_file = "$SGML_OUTPUT_DIR/$basename";
1690     my $new_sgml_file = "$SGML_OUTPUT_DIR/$basename.new";
1691
1692     my $contents;
1693
1694     open(EXTRA_FILE, "<$file") || die "Can't open $file";
1695
1696     {
1697         local $/;
1698         $contents = <EXTRA_FILE>;
1699     }
1700
1701     open (OUTPUT, ">$new_sgml_file")
1702         || die "Can't create $new_sgml_file";
1703
1704     print OUTPUT &ExpandAbbreviations ("$basename file", $contents);
1705     close (OUTPUT);
1706
1707     return &UpdateFileIfChanged ($old_sgml_file, $new_sgml_file, 0);
1708 }
1709 #############################################################################
1710 # Function    : OutputBook
1711 # Description : Outputs the SGML entities that need to be included into the
1712 #               main SGML file for the module.
1713 # Arguments   : $book_top - the declarations of the entities, which are added
1714 #                 at the top of the main SGML file.
1715 #               $book_bottom - the references to the entities, which are
1716 #                 added in the main SGML file at the desired position.
1717 #############################################################################
1718
1719 sub OutputBook {
1720     my ($book_top, $book_bottom) = @_;
1721
1722     my $old_file = "$SGML_OUTPUT_DIR/$MODULE-doc.top";
1723     my $new_file = "$SGML_OUTPUT_DIR/$MODULE-doc.top.new";
1724
1725     open (OUTPUT, ">$new_file")
1726         || die "Can't create $new_file";
1727     print OUTPUT $book_top;
1728     close (OUTPUT);
1729
1730     &UpdateFileIfChanged ($old_file, $new_file, 0);
1731
1732
1733     $old_file = "$SGML_OUTPUT_DIR/$MODULE-doc.bottom";
1734     $new_file = "$SGML_OUTPUT_DIR/$MODULE-doc.bottom.new";
1735
1736     open (OUTPUT, ">$new_file")
1737         || die "Can't create $new_file";
1738     print OUTPUT $book_bottom;
1739     close (OUTPUT);
1740
1741     &UpdateFileIfChanged ($old_file, $new_file, 0);
1742
1743
1744     # If the main SGML file hasn't been created yet, we create it here.
1745     # The user can tweak it later.
1746     if ($MAIN_SGML_FILE && ! -e $MAIN_SGML_FILE) {
1747       open (OUTPUT, ">$MAIN_SGML_FILE")
1748         || die "Can't create $MAIN_SGML_FILE";
1749
1750       if (lc($OUTPUT_FORMAT) eq "xml") {
1751           print OUTPUT <<EOF;
1752 <?xml version="1.0"?>
1753 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
1754                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
1755 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
1756 EOF
1757       } else {
1758         print OUTPUT <<EOF;
1759 <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
1760 EOF
1761         print OUTPUT $book_top;
1762         print OUTPUT <<EOF;
1763 ]>
1764 <book id="index">
1765 EOF
1766       }
1767
1768 print OUTPUT <<EOF;
1769   <bookinfo>
1770     <title>$MODULE Reference Manual</title>
1771     <releaseinfo>
1772       for $MODULE [VERSION]
1773       The latest version of this documentation can be found on-line at
1774       <ulink role="online-location" url="http://[SERVER]/$MODULE/index.html">http://[SERVER]/$MODULE/</ulink>.
1775     </releaseinfo>
1776   </bookinfo>
1777
1778   <chapter>
1779     <title>[Insert title here]</title>
1780 EOF
1781       print OUTPUT $book_bottom;
1782
1783       print OUTPUT <<EOF;
1784   </chapter>
1785 </book>
1786 EOF
1787
1788       close (OUTPUT);
1789     }
1790 }
1791
1792
1793 #############################################################################
1794 # Function    : CreateValidSGMLID
1795 # Description : Creates a valid SGML 'id' from the given string.
1796 #               NOTE: SGML ids are case-insensitive, so we have a few special
1797 #                     cases to avoid clashes of ids.
1798 # Arguments   : $id - the string to be converted into a valid SGML id.
1799 #############################################################################
1800
1801 sub CreateValidSGMLID {
1802     my ($id) = $_[0];
1803
1804     # Append ":CAPS" to all all-caps identifiers
1805
1806     # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
1807     if ($id eq "_") { return "gettext-macro"; }
1808
1809     if ($id !~ /[a-z]/) { $id .= ":CAPS" };
1810
1811     $id =~ s/[_ ]/-/g;
1812     $id =~ s/[,\.]//g;
1813     $id =~ s/^-*//;
1814     $id =~ s/::/-/g;
1815
1816     return $id;
1817 }
1818
1819
1820 #############################################################################
1821 # Function    : CreateValidSGML
1822 # Description : This turns any chars which are used in SGML into entities,
1823 #               e.g. '<' into '&lt;'
1824 # Arguments   : $text - the text to turn into proper SGML.
1825 #############################################################################
1826
1827 sub CreateValidSGML {
1828     my ($text) = @_;
1829     $text =~ s/&/&amp;/g;       # Do this first, or the others get messed up.
1830     $text =~ s/</&lt;/g;
1831     $text =~ s/>/&gt;/g;
1832     return $text;
1833 }
1834
1835 #############################################################################
1836 # Function    : ConvertSGMLChars
1837 # Description : This is used for text in source code comment blocks, to turn
1838 #               chars which are used in SGML into entities, e.g. '<' into
1839 #               '&lt;'. Depending on $SGML_MODE, this is done
1840 #               unconditionally or only if the character doesn't seem to be
1841 #               part of an SGML construct (tag or entity reference).
1842 # Arguments   : $text - the text to turn into proper SGML.
1843 #############################################################################
1844
1845 sub ConvertSGMLChars {
1846     my ($symbol, $text) = @_;
1847
1848     if ($SGML_MODE) {
1849         # For the SGML mode only convert to entities outside CDATA sections.
1850         return &ModifyXMLElements ($text, $symbol,
1851                                    "<!\\[CDATA\\[|<programlisting[^>]*>",
1852                                    \&ConvertSGMLCharsEndTag,
1853                                    \&ConvertSGMLCharsCallback);
1854     } else {
1855         # For the simple non-sgml mode, convert to entities everywhere.
1856         $text =~ s/&/&amp;/g;   # Do this first, or the others get messed up.
1857         $text =~ s/</&lt;/g;
1858         $text =~ s/>/&gt;/g;
1859         return $text;
1860     }
1861 }
1862
1863
1864 sub ConvertSGMLCharsEndTag {
1865   if ($_[0] eq "<!\[CDATA\[") {
1866     return "]]>";
1867   } else {
1868     return "</programlisting>";
1869   }
1870 }
1871
1872 sub ConvertSGMLCharsCallback {
1873   my ($text, $symbol, $tag) = @_;
1874
1875   if ($tag =~ m/^<programlisting/) {
1876     # We can handle <programlisting> specially here.
1877     return &ModifyXMLElements ($text, $symbol,
1878                                "<!\\[CDATA\\[",
1879                                \&ConvertSGMLCharsEndTag,
1880                                \&ConvertSGMLCharsCallback2);
1881   } elsif ($tag eq "") {
1882     # If we're not in CDATA convert to entities.
1883     $text =~ s/&(?![a-zA-Z#]+;)/&amp;/g;        # Do this first, or the others get messed up.
1884     $text =~ s/<(?![a-zA-Z\/!])/&lt;/g;
1885     $text =~ s/(?<![a-zA-Z0-9"'\/-])>/&gt;/g;
1886
1887     # Handle "#include <xxxxx>"
1888     $text =~ s/#include(\s+)<([^>]+)>/#include$1&lt;$2&gt;/g;
1889   }
1890
1891   return $text;
1892 }
1893
1894 sub ConvertSGMLCharsCallback2 {
1895   my ($text, $symbol, $tag) = @_;
1896
1897   # If we're not in CDATA convert to entities.
1898   # We could handle <programlisting> differently, though I'm not sure it helps.
1899   if ($tag eq "") {
1900     $text =~ s/&(?![a-zA-Z#]+;)/&amp;/g;        # Do this first, or the others get messed up.
1901 #    $text =~ s/&/&amp;/g;      # Do this first, or the others get messed up.
1902     $text =~ s/<(?![a-zA-Z\/!])/&lt;/g;
1903     $text =~ s/(?<![a-zA-Z0-9"'\/-])>/&gt;/g;
1904
1905     # Handle "#include <xxxxx>"
1906     $text =~ s/#include(\s+)<([^>]+)>/#include$1&lt;$2&gt;/g;
1907   }
1908
1909   return $text;
1910 }
1911
1912
1913 #############################################################################
1914 # Function    : ExpandAbbreviations
1915 # Description : This turns the abbreviations function(), macro(), @param,
1916 #               %constant, and #symbol into appropriate DocBook markup.
1917 #               CDATA sections and <programlisting> parts are skipped.
1918 # Arguments   : $symbol - the symbol being documented, for error messages.
1919 #               $text - the text to expand.
1920 #############################################################################
1921
1922 sub ExpandAbbreviations {
1923   my ($symbol, $text) = @_;
1924
1925   # Convert "|[" and "]|" into the start and end of program listing examples.
1926   $text =~ s%\|\[%<informalexample><programlisting>%g;
1927   $text =~ s%\]\|%</programlisting></informalexample>%g;
1928
1929   return &ModifyXMLElements ($text, $symbol,
1930                              "<!\\[CDATA\\[|<programlisting[^>]*>",
1931                              \&ExpandAbbreviationsEndTag,
1932                              \&ExpandAbbreviationsCallback);
1933 }
1934
1935
1936 # Returns the end tag corresponding to the given start tag.
1937 sub ExpandAbbreviationsEndTag {
1938   if ($_[0] eq "<!\[CDATA\[") {
1939     return "]]>";
1940   } else {
1941     return "</programlisting>";
1942   }
1943 }
1944
1945 # Called inside or outside each CDATA or <programlisting> section.
1946 sub ExpandAbbreviationsCallback {
1947   my ($text, $symbol, $tag) = @_;
1948
1949   if ($tag =~ m/^<programlisting/) {
1950     # Handle any embedded CDATA sections.
1951     return &ModifyXMLElements ($text, $symbol,
1952                                "<!\\[CDATA\\[",
1953                                \&ExpandAbbreviationsEndTag,
1954                                \&ExpandAbbreviationsCallback2);
1955   } elsif ($tag eq "") {
1956     # We are outside any CDATA or <programlisting> sections, so we expand
1957     # any gtk-doc abbreviations.
1958
1959     # Convert 'function()' or 'macro()'
1960     $text =~ s/(\w+)\s*\(\)/&MakeXRef($1, &tagify($1 . "()", "function"));/eg;
1961
1962     # Convert '@param'
1963     $text =~ s/\@(\w+((\.|->)\w+)*)/<parameter>$1<\/parameter>/g;
1964
1965     # Convert '%constant'. Also allow negative numbers, e.g. %-1.
1966     $text =~ s/\%(-?\w+)/&MakeXRef($1, &tagify($1, "literal"));/eg;
1967
1968     # Convert '#symbol'
1969     $text =~ s/#([\w\-:]+)/&MakeHashXRef($1, "type");/eg;
1970   }
1971
1972   return $text;
1973 }
1974
1975 # This is called inside a <programlisting>
1976 sub ExpandAbbreviationsCallback2 {
1977   my ($text, $symbol, $tag) = @_;
1978
1979   if ($tag eq "") {
1980     # We are inside a <programlisting> but outside any CDATA sections,
1981     # so we expand any gtk-doc abbreviations.
1982     $text =~ s/#(\w+)/&MakeHashXRef($1, "");/eg;
1983   }
1984
1985   return $text;
1986 }
1987
1988 sub MakeHashXRef {
1989     my ($symbol, $tag) = @_;;
1990     my $text = $symbol;
1991
1992     # Check for things like '#include', '#define', and skip them.
1993     if ($PreProcessorDirectives{$symbol}) {
1994       return "#$symbol";
1995     }
1996
1997     # Get rid of any special '-struct' suffix.
1998     $text =~ s/-struct$//;
1999
2000     # If the symbol is in the form "Object::signal", then change the symbol to
2001     # "Object-signal" and use "signal" as the text.
2002     if ($symbol =~ s/::/-/) {
2003       $text = "\"$'\"";
2004     }
2005
2006     # If the symbol is in the form "Object:property", then change the symbol to
2007     # "Object--property" and use "property" as the text.
2008     if ($symbol =~ s/:/--/) {
2009       $text = "\"$'\"";
2010     }
2011
2012     if ($tag ne "") {
2013       $text = tagify ($text, $tag);
2014     }
2015
2016     return &MakeXRef($symbol, $text);
2017 }
2018
2019
2020 #############################################################################
2021 # Function    : ModifyXMLElements
2022 # Description : Looks for given XML element tags within the text, and calls
2023 #               the callback on pieces of text inside & outside those elements.
2024 #               Used for special handling of text inside things like CDATA
2025 #               and <programlisting>.
2026 # Arguments   : $text - the text.
2027 #               $symbol - the symbol currently being documented (only used for
2028 #                      error messages).
2029 #               $start_tag_regexp - the regular expression to match start tags.
2030 #                      e.g. "<!\\[CDATA\\[|<programlisting[^>]*>" to match
2031 #                      CDATA sections or programlisting elements.
2032 #               $end_tag_func - function which is passed the matched start tag
2033 #                      and should return the appropriate end tag string.
2034 #               $callback - callback called with each part of the text. It is
2035 #                      called with a piece of text, the symbol being
2036 #                      documented, and the matched start tag or "" if the text
2037 #                      is outside the XML elements being matched.
2038 #############################################################################
2039 sub ModifyXMLElements {
2040     my ($text, $symbol, $start_tag_regexp, $end_tag_func, $callback) = @_;
2041     my ($before_tag, $start_tag, $end_tag_regexp, $end_tag);
2042     my $result = "";
2043
2044     while ($text =~ m/$start_tag_regexp/s) {
2045       $before_tag = $`;
2046       $start_tag = $&;
2047       $text = $';
2048
2049       $result .= &$callback ($before_tag, $symbol, "");
2050       $result .= $start_tag;
2051
2052       $end_tag_regexp = &$end_tag_func ($start_tag);
2053
2054       if ($text =~ m/$end_tag_regexp/s) {
2055         $before_tag = $`;
2056         $end_tag = $&;
2057         $text = $';
2058
2059         $result .= &$callback ($before_tag, $symbol, $start_tag);
2060         $result .= $end_tag;
2061       } else {
2062         print "WARNING: Can't find tag end: $end_tag_regexp in docs for: $symbol\n";
2063         # Just assume it is all inside the tag.
2064         $result .= &$callback ($text, $symbol, $start_tag);
2065         $text = "";
2066       }
2067     }
2068
2069     # Handle any remaining text outside the tags.
2070     $result .= &$callback ($text, $symbol, "");
2071
2072     return $result;
2073 }
2074
2075 sub noop {
2076   return $_[0];
2077 }
2078
2079 # Adds a tag around some text.
2080 # e.g tagify("Text", "literal") => "<literal>Text</literal>".
2081 sub tagify {
2082    my ($text, $elem) = @_;
2083    return "<" . $elem . ">" . $text . "</" . $elem . ">";
2084 }
2085
2086
2087 #############################################################################
2088 # Function    : MakeXRef
2089 # Description : This returns a cross-reference link to the given symbol.
2090 #               Though it doesn't try to do this for a few standard C types
2091 #               that it knows won't be in the documentation.
2092 # Arguments   : $symbol - the symbol to try to create a XRef to.
2093 #               $text - text text to put inside the XRef, defaults to $symbol
2094 #############################################################################
2095
2096 sub MakeXRef {
2097     my ($symbol, $text) = ($_[0], $_[1]);
2098     if (!defined($text)) {
2099         $text = $symbol;
2100
2101         # Get rid of special '-struct' suffix.
2102         $text =~ s/-struct$//;
2103     }
2104
2105     #print "Getting type link for $symbol -> $text\n";
2106
2107     my $symbol_id = &CreateValidSGMLID ($symbol);
2108     return "<link linkend=\"$symbol_id\">$text</link>";
2109 }
2110
2111
2112 #############################################################################
2113 # Function    : MakeIndexterms
2114 # Description : This returns a indexterm elements for the given symbol
2115 # Arguments   : $symbol - the symbol to create indexterms for
2116 #############################################################################
2117
2118 sub MakeIndexterms {
2119   my ($symbol) = $_[0];
2120   my $terms =  "";
2121
2122   if (exists $Deprecated{$symbol}) {
2123       $terms .= "<indexterm role=\"deprecated\"><primary>$symbol</primary></indexterm>"
2124   }
2125   if (exists $Since{$symbol}) {
2126      my $since = $Since{$symbol};
2127      $since =~ s/^\s+//;
2128      $since =~ s/\s+$//;
2129      if ($since ne "") {
2130          $terms .= "<indexterm role=\"$since\"><primary>$symbol</primary></indexterm>";
2131      }
2132   }
2133   if ($terms eq "") {
2134      $terms .= "<indexterm><primary>$symbol</primary></indexterm>";
2135   }
2136
2137   return $terms;
2138  }
2139
2140 #############################################################################
2141 # Function    : MakeDeprecationNote
2142 # Description : This returns a deprecation warning for the given symbol.
2143 # Arguments   : $symbol - the symbol to try to create a warning for.
2144 #############################################################################
2145
2146 sub MakeDeprecationNote {
2147     my ($symbol) = $_[0];
2148     my $desc = "";
2149     my $note = "";
2150     if (exists $Deprecated{$symbol}) {
2151         $desc .= "<warning>";
2152
2153         if ($Deprecated{$symbol} =~ /^\s*([0-9\.]+)\s*:/) {
2154                 $desc .= "<para><literal>$symbol</literal> has been deprecated since version $1 and should not be used in newly-written code.";
2155         } else {
2156                 $desc .= "<para><literal>$symbol</literal> is deprecated and should not be used in newly-written code.";
2157         }
2158         if ($Deprecated{$symbol} ne "") {
2159             $note = &ExpandAbbreviations($symbol, $Deprecated{$symbol});
2160             $note =~ s/^\s*([0-9\.]+)\s*:\s*//;
2161             $note =~ s/^\s+//;
2162             $note =~ s/\s+$//;
2163             $note =~ s%\n{2,}%\n</para>\n<para>\n%g;
2164             $desc .= " " . $note;
2165         }
2166         $desc .= "</para></warning>\n";
2167     }
2168     return $desc;
2169 }
2170
2171 #############################################################################
2172 # Function    : MakeConditionDescription
2173 # Description : This returns a sumary of conditions for the given symbol.
2174 # Arguments   : $symbol - the symbol to try to create the sumary.
2175 #############################################################################
2176
2177 sub MakeConditionDescription {
2178     my ($symbol) = $_[0];
2179     my $desc = "";
2180
2181     if (exists $Deprecated{$symbol}) {
2182         if ($desc ne "") {
2183             $desc .= "|";
2184         }
2185
2186         if ($Deprecated{$symbol} =~ /^\s*(.*?)\s*$/) {
2187                 $desc .= "deprecated:$1";
2188         } else {
2189                 $desc .= "deprecated";
2190         }
2191     }
2192
2193     if (exists $Since{$symbol}) {
2194         if ($desc ne "") {
2195             $desc .= "|";
2196         }
2197
2198         if ($Since{$symbol} =~ /^\s*(.*?)\s*$/) {
2199                 $desc .= "since:$1";
2200         } else {
2201                 $desc .= "since";
2202         }
2203     }
2204
2205     if (exists $StabilityLevel{$symbol}) {
2206         if ($desc ne "") {
2207             $desc .= "|";
2208         }
2209         $desc .= "stability:".$StabilityLevel{$symbol};
2210     }
2211
2212     if ($desc ne "") {
2213         $desc=" condition=\"".$desc."\"";
2214         #print "condition for '$symbol' = '$desc'\n";
2215     }
2216     return $desc;
2217 }
2218
2219 #############################################################################
2220 # Function    : GetHierarchy
2221 # Description : Returns the DocBook output describing the ancestors and
2222 #               immediate children of a GObject subclass. It uses the
2223 #               global @Objects and @ObjectLevels arrays to walk the tree.
2224 # Arguments   : $object - the GtkObject subclass.
2225 #############################################################################
2226
2227 sub GetHierarchy {
2228     my ($object) = @_;
2229
2230     # Find object in the objects array.
2231     my $found = 0;
2232     my @children = ();
2233     my $i;
2234     my $level;
2235     my $j;
2236     for ($i = 0; $i < @Objects; $i++) {
2237         if ($found) {
2238             if ($ObjectLevels[$i] <= $level) {
2239             last;
2240         }
2241             elsif ($ObjectLevels[$i] == $level + 1) {
2242                 push (@children, $Objects[$i]);
2243             }
2244         }
2245         elsif ($Objects[$i] eq $object) {
2246             $found = 1;
2247             $j = $i;
2248             $level = $ObjectLevels[$i];
2249         }
2250     }
2251     if (!$found) {
2252         return "";
2253     }
2254
2255     # Walk up the hierarchy, pushing ancestors onto the ancestors array.
2256     my @ancestors = ();
2257     push (@ancestors, $object);
2258 #    print "Level: $level\n";
2259     while ($level > 1) {
2260         $j--;
2261         if ($ObjectLevels[$j] < $level) {
2262             push (@ancestors, $Objects[$j]);
2263             $level = $ObjectLevels[$j];
2264 #           print "Level: $level\n";
2265         }
2266     }
2267
2268     # Output the ancestors list, indented and with links.
2269     my $hierarchy = "<synopsis>\n\n";
2270     $level = 0;
2271     for ($i = $#ancestors; $i >= 0; $i--) {
2272         my $link_text;
2273         # Don't add a link to the current widget, i.e. when i == 0.
2274         if ($i > 0) {
2275             my $ancestor_id = &CreateValidSGMLID ($ancestors[$i]);
2276             $link_text = "<link linkend=\"$ancestor_id\">$ancestors[$i]</link>";
2277         } else {
2278             $link_text = "$ancestors[$i]";
2279         }
2280         if ($level == 0) {
2281             $hierarchy .= "  $link_text\n";
2282         } else {
2283 #           $hierarchy .= ' ' x ($level * 6 - 3) . "|\n";
2284             $hierarchy .= ' ' x ($level * 6 - 3) . "+----$link_text\n";
2285         }
2286         $level++;
2287     }
2288     for ($i = 0; $i <= $#children; $i++) {
2289       my $id = &CreateValidSGMLID ($children[$i]);
2290       my $link_text = "<link linkend=\"$id\">$children[$i]</link>";
2291       $hierarchy .= ' ' x ($level * 6 - 3) . "+----$link_text\n";
2292     }
2293     $hierarchy .= "</synopsis>\n";
2294
2295     return $hierarchy;
2296 }
2297
2298
2299 #############################################################################
2300 # Function    : GetInterfaces
2301 # Description : Returns the DocBook output describing the interfaces
2302 #               implemented by a class. It uses the global %Interfaces hash.
2303 # Arguments   : $object - the GtkObject subclass.
2304 #############################################################################
2305
2306 sub GetInterfaces {
2307     my ($object) = @_;
2308     my $text = "";
2309     my $i;
2310
2311     # Find object in the objects array.
2312     if (exists($Interfaces{$object})) {
2313         my @ifaces = split(' ', $Interfaces{$object});
2314         $text = <<EOF;
2315 <para>
2316 $object implements
2317 EOF
2318         for ($i = 0; $i <= $#ifaces; $i++) {
2319             my $id = &CreateValidSGMLID ($ifaces[$i]);
2320             $text .= " <link linkend=\"$id\">$ifaces[$i]</link>";
2321             if ($i < $#ifaces - 1) {
2322                 $text .= ', ';
2323             }
2324             elsif ($i < $#ifaces) {
2325                 $text .= ' and ';
2326             }
2327             else {
2328                 $text .= '.';
2329             }
2330         }
2331         $text .= <<EOF;
2332 </para>
2333 EOF
2334     }
2335
2336     return $text;
2337 }
2338
2339 #############################################################################
2340 # Function    : GetImplementations
2341 # Description : Returns the DocBook output describing the implementations
2342 #               of an interface. It uses the global %Interfaces hash.
2343 # Arguments   : $object - the GtkObject subclass.
2344 #############################################################################
2345
2346 sub GetImplementations {
2347     my ($object) = @_;
2348     my @impls = ();
2349     my $text = "";
2350     my $i;
2351     foreach my $key (keys %Interfaces) {
2352         if ($Interfaces{$key} =~ /\b$object\b/) {
2353             push (@impls, $key);
2354         }
2355     }
2356     if ($#impls >= 0) {
2357         $text = <<EOF;
2358 <para>
2359 $object is implemented by
2360 EOF
2361         for ($i = 0; $i <= $#impls; $i++) {
2362             my $id = &CreateValidSGMLID ($impls[$i]);
2363             $text .= " <link linkend=\"$id\">$impls[$i]</link>";
2364             if ($i < $#impls - 1) {
2365                 $text .= ', ';
2366             }
2367             elsif ($i < $#impls) {
2368                 $text .= ' and ';
2369             }
2370             else {
2371                 $text .= '.';
2372             }
2373         }
2374         $text .= <<EOF;
2375 </para>
2376 EOF
2377     }
2378     return $text;
2379 }
2380
2381
2382 #############################################################################
2383 # Function    : GetPrerequisites
2384 # Description : Returns the DocBook output describing the prerequisites
2385 #               of an interface. It uses the global %Prerequisites hash.
2386 # Arguments   : $iface - the interface.
2387 #############################################################################
2388
2389 sub GetPrerequisites {
2390     my ($iface) = @_;
2391     my $text = "";
2392     my $i;
2393
2394     if (exists($Prerequisites{$iface})) {
2395         $text = <<EOF;
2396 <para>
2397 $iface requires
2398 EOF
2399         my @prereqs = split(' ', $Prerequisites{$iface});
2400         for ($i = 0; $i <= $#prereqs; $i++) {
2401             my $id = &CreateValidSGMLID ($prereqs[$i]);
2402             $text .= " <link linkend=\"$id\">$prereqs[$i]</link>";
2403             if ($i < $#prereqs - 1) {
2404                 $text .= ', ';
2405             }
2406             elsif ($i < $#prereqs) {
2407                 $text .= ' and ';
2408             }
2409             else {
2410                 $text .= '.';
2411             }
2412         }
2413         $text .= <<EOF;
2414 </para>
2415 EOF
2416     }
2417     return $text;
2418 }
2419
2420 #############################################################################
2421 # Function    : GetDerived
2422 # Description : Returns the DocBook output describing the derived interfaces
2423 #               of an interface. It uses the global %Prerequisites hash.
2424 # Arguments   : $iface - the interface.
2425 #############################################################################
2426
2427 sub GetDerived {
2428     my ($iface) = @_;
2429     my $text = "";
2430     my $i;
2431
2432     my @derived = ();
2433     foreach my $key (keys %Prerequisites) {
2434         if ($Prerequisites{$key} =~ /\b$iface\b/) {
2435             push (@derived, $key);
2436         }
2437     }
2438     if ($#derived >= 0) {
2439         $text = <<EOF;
2440 <para>
2441 $iface is required by
2442 EOF
2443         for ($i = 0; $i <= $#derived; $i++) {
2444             my $id = &CreateValidSGMLID ($derived[$i]);
2445             $text .= " <link linkend=\"$id\">$derived[$i]</link>";
2446             if ($i < $#derived - 1) {
2447                 $text .= ', ';
2448             }
2449             elsif ($i < $#derived) {
2450                 $text .= ' and ';
2451             }
2452             else {
2453                 $text .= '.';
2454             }
2455         }
2456         $text .= <<EOF;
2457 </para>
2458 EOF
2459     }
2460     return $text;
2461 }
2462
2463
2464 #############################################################################
2465 # Function    : GetSignals
2466 # Description : Returns the synopsis and detailed description DocBook output
2467 #               for the signal handlers of a given GtkObject subclass.
2468 # Arguments   : $object - the GtkObject subclass, e.g. 'GtkButton'.
2469 #############################################################################
2470
2471 sub GetSignals {
2472     my ($object) = @_;
2473     my $synop = "";
2474     my $desc = "";
2475
2476     my $i;
2477     for ($i = 0; $i <= $#SignalObjects; $i++) {
2478         if ($SignalObjects[$i] eq $object) {
2479 #           print "Found signal: $SignalNames[$i]\n";
2480             my $name = $SignalNames[$i];
2481             my $symbol = "${object}::${name}";
2482             my $id = &CreateValidSGMLID ("$object-$name");
2483
2484             my $pad = ' ' x (46 - length($name));
2485             $synop .= "  &quot;<link linkend=\"$id\">$name</link>&quot;$pad ";
2486
2487             $desc .= "<refsect2><title><anchor id=\"$id\"${empty_element_end}The <literal>&quot;$name&quot;</literal> signal</title>\n";
2488             $desc .= MakeIndexterms($symbol);
2489             $desc .= "<programlisting>";
2490
2491             $SignalReturns[$i] =~ m/\s*(const\s+)?(\w+)\s*(\**)/;
2492             my $type_modifier = defined($1) ? $1 : "";
2493             my $type = $2;
2494             my $pointer = $3;
2495             my $xref = &MakeXRef ($type);
2496
2497             my $ret_type_len = length ($type_modifier) + length ($pointer)
2498                 + length ($type);
2499             my $ret_type_output = "$type_modifier$xref$pointer"
2500                 . (' ' x ($RETURN_TYPE_FIELD_WIDTH - $ret_type_len));
2501
2502             $desc  .= "${ret_type_output}user_function " . &MakeReturnField("") . " (";
2503
2504             my $sourceparams = $SourceSymbolParams{$symbol};
2505             my @params = split ("\n", $SignalPrototypes[$i]);
2506             my $j;
2507             my $l;
2508             my $type_len = length("gpointer");
2509             my $name_len = length("user_data");
2510             # do two passes, the first one is to calculate padding
2511             for ($l = 0; $l < 2; $l++) {
2512                 for ($j = 0; $j <= $#params; $j++) {
2513                     # allow alphanumerics, '_', '[' & ']' in param names
2514                     if ($params[$j] =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$/) {
2515                         $type = $1;
2516                         $pointer = $2;
2517                         if (defined($sourceparams)) {
2518                             $name = $$sourceparams[2 * $j];
2519                         }
2520                         else {
2521                             $name = $3;
2522                         }
2523                         if (!defined($name)) {
2524                             $name = "arg$j";
2525                         }
2526                         if ($l == 0) {
2527                             if (length($type) + length($pointer) > $type_len) {
2528                                 $type_len = length($type) + length($pointer);
2529                             }
2530                             if (length($name) > $name_len) {
2531                                 $name_len = length($name);
2532                             }
2533                         }
2534                         else {
2535                             $xref = &MakeXRef ($type);
2536                             $pad = ' ' x ($type_len - length($type) - length($pointer));
2537                             $desc .= "$xref$pad $pointer$name,\n";
2538                             $desc .= (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH));
2539                         }
2540                      } else {
2541                          print "###Can't parse arg: $params[$j]\nArgs:$SignalPrototypes[$i]\n";
2542                      }
2543                 }
2544             }
2545             $xref = &MakeXRef ("gpointer");
2546             $pad = ' ' x ($type_len - length("gpointer"));
2547             $desc  .= "$xref$pad user_data)";
2548
2549             my $flags = $SignalFlags[$i];
2550             my $flags_string = "";
2551
2552             if (defined ($flags)) {
2553               if ($flags =~ m/f/) {
2554                 $flags_string = "Run First";
2555               }
2556               elsif ($flags =~ m/l/) {
2557                 $flags_string = "Run Last";
2558               }
2559               elsif ($flags =~ m/c/) {
2560                 $flags_string = "Cleanup";
2561               }
2562               if ($flags =~ m/r/) {
2563                 if ($flags_string) { $flags_string .= " / "; }
2564                 $flags_string .= "No Recursion";
2565               }
2566               if ($flags =~ m/d/) {
2567                 if ($flags_string) { $flags_string .= " / "; }
2568                 $flags_string .= "Has Details";
2569               }
2570               if ($flags =~ m/a/) {
2571                 if ($flags_string) { $flags_string .= " / "; }
2572                 $flags_string .= "Action";
2573               }
2574               if ($flags =~ m/h/) {
2575                 if ($flags_string) { $flags_string .= " / "; }
2576                 $flags_string .= "No Hooks";
2577               }
2578             }
2579
2580             if ($flags_string)
2581               {
2582                 $synop .= ": $flags_string\n";
2583
2584                 $pad = ' ' x (5 + $name_len - length("user_data"));
2585                 $desc  .= "$pad : $flags_string</programlisting>\n";
2586               }
2587             else
2588               {
2589                 $synop .= "\n";
2590                 $desc  .= "</programlisting>\n";
2591               }
2592
2593             my $parameters = &OutputParamDescriptions ("SIGNAL", $symbol);
2594             my $parameters_output = 0;
2595
2596             $AllSymbols{$symbol} = 1;
2597             if (defined ($SymbolDocs{$symbol})) {
2598                 my $symbol_docs = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
2599
2600                 # Try to insert the parameter table at the author's desired
2601                 # position. Otherwise we need to tag it onto the end.
2602                 if ($symbol_docs =~ s/<!--PARAMETERS-->/$parameters/) {
2603                   $parameters_output = 1;
2604                 }
2605                 $desc .= $symbol_docs;
2606
2607                 if (!IsEmptyDoc($SymbolDocs{$symbol})) {
2608                     $AllDocumentedSymbols{$symbol} = 1;
2609                 }
2610             }
2611
2612             if ($parameters_output == 0) {
2613                 $desc .= $parameters;
2614               }
2615
2616             if (exists $Since{$symbol}) {
2617               $desc .= "<para>Since $Since{$symbol}</para>";
2618             }
2619             if (exists $StabilityLevel{$symbol}) {
2620               $desc .= "<para>Stability Level: $StabilityLevel{$symbol}</para>";
2621             }
2622             $desc .= "</refsect2>";
2623         }
2624     }
2625     return ($synop, $desc);
2626 }
2627
2628
2629 #############################################################################
2630 # Function    : GetArgs
2631 # Description : Returns the synopsis and detailed description DocBook output
2632 #               for the Args of a given GtkObject subclass.
2633 # Arguments   : $object - the GtkObject subclass, e.g. 'GtkButton'.
2634 #############################################################################
2635
2636 sub GetArgs {
2637     my ($object) = @_;
2638     my $synop = "";
2639     my $desc = "";
2640     my $child_synop = "";
2641     my $child_desc = "";
2642     my $style_synop = "";
2643     my $style_desc = "";
2644
2645     my $i;
2646     for ($i = 0; $i <= $#ArgObjects; $i++) {
2647         if ($ArgObjects[$i] eq $object) {
2648 #           print "Found arg: $ArgNames[$i]\n";
2649             my $name = $ArgNames[$i];
2650             # Remember only one colon so we don't clash with signals.
2651             my $symbol = "${object}:${name}";
2652             # I've used two dashes here for the same reason.
2653             my $id = &CreateValidSGMLID ("$object--$name");
2654
2655             my $type = $ArgTypes[$i];
2656             my $type_output;
2657             my $range = $ArgRanges[$i];
2658             my $range_output = CreateValidSGML($range);
2659             my $default = $ArgDefaults[$i];
2660             my $default_output = CreateValidSGML($default);
2661
2662             if ($type eq "GtkString") {
2663                 $type = "char*";
2664             }
2665             if ($type eq "GtkSignal") {
2666                 $type = "GtkSignalFunc, gpointer";
2667                 $type_output = &MakeXRef ("GtkSignalFunc") . ", "
2668                     . &MakeXRef ("gpointer");
2669             } elsif ($type =~ m/^(\w+)\*$/) {
2670                 $type_output = &MakeXRef ($1) . "*";
2671             } else {
2672                 $type_output = &MakeXRef ($type);
2673             }
2674
2675             my $flags = $ArgFlags[$i];
2676             my $flags_string = "";
2677
2678             if ($flags =~ m/r/) {
2679                 $flags_string = "Read";
2680             }
2681             if ($flags =~ m/w/) {
2682                 if ($flags_string) { $flags_string .= " / "; }
2683                 $flags_string .= "Write";
2684             }
2685             if ($flags =~ m/x/) {
2686                 if ($flags_string) { $flags_string .= " / "; }
2687                 $flags_string .= "Construct";
2688             }
2689             if ($flags =~ m/X/) {
2690                 if ($flags_string) { $flags_string .= " / "; }
2691                 $flags_string .= "Construct Only";
2692             }
2693
2694             $AllSymbols{$symbol} = 1;
2695             my $blurb;
2696             if (defined($SymbolDocs{$symbol}) &&
2697                 !IsEmptyDoc($SymbolDocs{$symbol})) {
2698                 $blurb = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
2699                 $AllDocumentedSymbols{$symbol} = 1;
2700             }
2701             else {
2702                 if (!($ArgBlurbs[$i] eq "")) {
2703                     $AllDocumentedSymbols{$symbol} = 1;
2704                 }
2705                 $blurb = "<para>" . &CreateValidSGML ($ArgBlurbs[$i]) . "</para>";
2706             }
2707
2708             my $pad1 = " " x (24 - length ($name));
2709             my $pad2 = " " x (20 - length ($type));
2710             my $kind = "";
2711
2712             if ($flags =~ m/c/) {
2713                 $kind = "child property";
2714             }
2715             elsif ($flags =~ m/s/) {
2716                 $kind = "style property";
2717             }
2718             else {
2719                 $kind = "property";
2720             }
2721
2722             my $arg_synop = "  &quot;<link linkend=\"$id\">$name</link>&quot;$pad1 $type_output $pad2 : $flags_string\n";
2723             my $arg_desc = "<refsect2><title><anchor id=\"$id\"${empty_element_end}The <literal>&quot;$name&quot;</literal> $kind</title>\n";
2724             $arg_desc .= MakeIndexterms($symbol);
2725             $arg_desc .= "<programlisting>  &quot;$name&quot;$pad1 $type_output $pad2 : $flags_string</programlisting>\n";
2726             $arg_desc .= $blurb;
2727             if ($range ne "") {
2728                 $arg_desc .= "<para>Allowed values: $range_output</para>\n";
2729             }
2730             if ($default ne "") {
2731                 $arg_desc .= "<para>Default value: $default_output</para>\n";
2732             }
2733             if (exists $Since{$symbol}) {
2734               $arg_desc .= "<para>Since $Since{$symbol}</para>\n";
2735             }
2736             if (exists $StabilityLevel{$symbol}) {
2737               $arg_desc .= "<para>Stability Level $StabilityLevel{$symbol}</para>\n";
2738             }
2739             $arg_desc .= "</refsect2>\n";
2740
2741             if ($flags =~ m/c/) {
2742                 $child_synop .= $arg_synop;
2743                 $child_desc .= $arg_desc;
2744             }
2745             elsif ($flags =~ m/s/) {
2746                 $style_synop .= $arg_synop;
2747                 $style_desc .= $arg_desc;
2748             }
2749             else {
2750                 $synop .= $arg_synop;
2751                 $desc .= $arg_desc;
2752             }
2753         }
2754     }
2755     return ($synop, $child_synop, $style_synop, $desc, $child_desc, $style_desc);
2756 }
2757
2758
2759 #############################################################################
2760 # Function    : ReadSourceDocumentation
2761 # Description : This reads in the documentation embedded in comment blocks
2762 #               in the source code (for Gnome).
2763 #
2764 #               Parameter descriptions override any in the template files.
2765 #               Function descriptions are placed before any description from
2766 #               the template files.
2767 #
2768 #               It recursively descends the source directory looking for .c
2769 #               files and scans them looking for specially-formatted comment
2770 #               blocks.
2771 #
2772 # Arguments   : $source_dir - the directory to scan.
2773 #############m###############################################################
2774
2775 sub ReadSourceDocumentation {
2776     my ($source_dir) = @_;
2777     my ($file, $dir, @suffix_list, $suffix);
2778 #    print "Scanning source directory: $source_dir\n";
2779
2780     # This array holds any subdirectories found.
2781     my (@subdirs) = ();
2782
2783     @suffix_list = split (/,/, $SOURCE_SUFFIXES);
2784
2785     opendir (SRCDIR, $source_dir)
2786         || die "Can't open source directory $source_dir: $!";
2787
2788     foreach $file (readdir (SRCDIR)) {
2789       if ($file =~ /^\./) {
2790         next;
2791       } elsif (-d "$source_dir/$file") {
2792         push (@subdirs, $file);
2793       } elsif (@suffix_list) {
2794         foreach $suffix (@suffix_list) {
2795           if ($file =~ m/\.\Q${suffix}\E$/) {
2796             &ScanSourceFile ("$source_dir/$file");
2797           }
2798         }
2799       } elsif ($file =~ m/\.[ch]$/) {
2800         &ScanSourceFile ("$source_dir/$file");
2801       }
2802     }
2803     closedir (SRCDIR);
2804
2805     # Now recursively scan the subdirectories.
2806     foreach $dir (@subdirs) {
2807         next if ($IGNORE_FILES =~ m/(\s|^)\Q${dir}\E(\s|$)/);
2808         &ReadSourceDocumentation ("$source_dir/$dir");
2809     }
2810 }
2811
2812
2813 #############################################################################
2814 # Function    : ScanSourceFile
2815 # Description : Scans one source file looking for specially-formatted comment
2816 #               blocks. Later &MergeSourceDocumentation is used to merge any
2817 #               documentation found with the documentation already read in
2818 #               from the template files.
2819 #
2820 # Arguments   : $file - the file to scan.
2821 #############################################################################
2822
2823 sub ScanSourceFile {
2824     my ($file) = @_;
2825     my $basename;
2826
2827     if ($file =~ m/^.*[\/\\]([^\/\\]*)$/) {
2828         $basename = $1;
2829     } else {
2830         print "WARNING: Can't find basename of file $file\n";
2831         $basename = $file;
2832     }
2833
2834     # Check if the basename is in the list of files to ignore.
2835     if ($IGNORE_FILES =~ m/(\s|^)\Q${basename}\E(\s|$)/) {
2836         return;
2837     }
2838
2839     #print "DEBUG: Scanning $file\n";
2840
2841     open (SRCFILE, $file)
2842         || die "Can't open $file: $!";
2843     my $in_comment_block = 0;
2844     my $symbol;
2845     my ($in_description, $in_return, $in_since, $in_stability, $in_deprecated);
2846     my ($description, $return_desc, $return_start, $return_style);
2847     my ($since_desc, $stability_desc, $deprecated_desc);
2848     my $current_param;
2849     my $ignore_broken_returns;
2850     my @params;
2851     while (<SRCFILE>) {
2852         # Look for the start of a comment block.
2853         if (!$in_comment_block) {
2854             if (m%^\s*/\*.*\*/%) {
2855                 #one-line comment - not gtkdoc
2856             } elsif (m%^\s*/\*\*\s%) {
2857 #             print "Found comment block start\n";
2858
2859                 $in_comment_block = 1;
2860
2861                 # Reset all the symbol data.
2862                 $symbol = "";
2863                 $in_description = 0;
2864                 $in_return = 0;
2865                 $in_since = 0;
2866                 $in_deprecated = 0;
2867                 $in_stability = 0;
2868                 $description = "";
2869                 $return_desc = "";
2870                 $return_style = "";
2871                 $since_desc = "";
2872                 $deprecated_desc = "";
2873                 $stability_desc = "";
2874                 $current_param = -1;
2875                 $ignore_broken_returns = 0;
2876                 @params = ();
2877             }
2878             next;
2879         }
2880
2881         # We're in a comment block. Check if we've found the end of it.
2882         if (m%^\s*\*+/%) {
2883             if (!$symbol) {
2884                 print <<EOF;
2885 WARNING: Symbol name not found at the start of the comment block.
2886  $file line $.
2887 EOF
2888             } else {
2889                 # Add the return value description onto the end of the params.
2890                 if ($return_desc) {
2891                     push (@params, "Returns");
2892                     push (@params, $return_desc);
2893                     if ($return_style eq 'broken') {
2894                         print <<EOF;
2895 WARNING: Free-form return value description in $symbol.
2896          Use `Returns:' to avoid ambiguities.
2897 EOF
2898                     }
2899                 }
2900                 # Convert special SGML characters
2901                 $description = &ConvertSGMLChars ($symbol, $description);
2902                 my $k;
2903                 for ($k = 1; $k <= $#params; $k += 2) {
2904                     $params[$k] = &ConvertSGMLChars ($symbol, $params[$k]);
2905                 }
2906
2907                 # Handle Section docs
2908                 if ($symbol =~ m/SECTION:\s*(.*)/) {
2909                     my $real_symbol=$1;
2910                     my $k;
2911
2912                     #print "SECTION DOCS found in source for : '$real_symbol'\n";
2913                     $ignore_broken_returns = 1;
2914                     for ($k = 0; $k <= $#params; $k += 2) {
2915                         #print "   '".$params[$k]."'\n";
2916                         $params[$k] = "\L$params[$k]";
2917                         if ($params[$k] eq "short_description") {
2918                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Short_Description"}=$params[$k+1];
2919                         } elsif ($params[$k] eq "see_also") {
2920                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:See_Also"}=$params[$k+1];
2921                         } elsif ($params[$k] eq "title") {
2922                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Title"}=$params[$k+1];
2923                         } elsif ($params[$k] eq "stability") {
2924                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Stability_Level"}=$params[$k+1];
2925                         } elsif ($params[$k] eq "section_id") {
2926                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Section_Id"}=$params[$k+1];
2927                         } elsif ($params[$k] eq "include") {
2928                             $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Include"}=$params[$k+1];
2929                         }
2930                     }
2931                     $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Long_Description"}=$description;
2932                     #$SourceSymbolTypes{$symbol} = "SECTION";
2933                 } else {
2934                     #print "SYMBOL DOCS found in source for : '$symbol' ",length($description), "\n";
2935                     $SourceSymbolDocs{$symbol} = $description;
2936                     $SourceSymbolParams{$symbol} = [ @params ];
2937                     # FIXME $SourceSymbolTypes{$symbol} = "STRUCT,SIGNAL,ARG,FUNCTION,MACRO";
2938                     #if (defined $DeclarationTypes{$symbol}) {
2939                     #    $SourceSymbolTypes{$symbol} = $DeclarationTypes{$symbol}
2940                     #}
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                          # don't warn for signals and properties
2957                          #if ($symbol !~ m/::?(.*)/) {
2958                          if (defined $DeclarationTypes{$symbol}) {
2959                              print <<EOF;
2960 WARNING: $symbol is deprecated in the inline comments
2961          but no deprecation guards were found around the declaration.
2962          (See the --deprecated-guards option for gtkdoc-scan.)
2963 EOF
2964                          }
2965                     }
2966                     $Deprecated{$symbol} = &ConvertSGMLChars ($symbol, $deprecated_desc);
2967                 }
2968             }
2969
2970             $in_comment_block = 0;
2971             next;
2972         }
2973
2974         # Get rid of ' * ' at start of every line in the comment block.
2975         s%^\s*\*\s?%%;
2976         # But make sure we don't get rid of the newline at the end.
2977         if (!$_) {
2978             $_ = "\n";
2979         }
2980 #       print "DEBUG: scanning :$_";
2981
2982         # If we haven't found the symbol name yet, look for it.
2983         if (!$symbol) {
2984             if (m%^\s*(SECTION:\s*\S+)%) {
2985                 $symbol = $1;
2986                 #print "SECTION DOCS found in source for : '$symbol'\n";
2987                 $ignore_broken_returns = 1;
2988             } elsif (m%^\s*([\w:-]*\w)\s*:?%) {
2989                 $symbol = $1;
2990                 #print "SYMBOL DOCS found in source for : '$symbol'\n";
2991             }
2992             next;
2993         }
2994
2995         # If we're in the return value description, add it to the end.
2996         if ($in_return) {
2997             # If we find another valid returns line, we assume that the first
2998             # one was really part of the description.
2999             if (m/^\s*(returns:|return\s+value:)/i) {
3000                 if ($return_style eq 'broken') {
3001                     $description .= $return_start . $return_desc;
3002                 }
3003                 $return_start = $1;
3004                 if ($return_style eq 'sane') {
3005                     print <<EOF
3006 WARNING: Multiple Returns for $symbol
3007 EOF
3008                 }
3009                 $return_style = 'sane';
3010                 $ignore_broken_returns = 1;
3011                 $return_desc = $';
3012             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3013                 $description .= $return_start . $return_desc;
3014                 $return_start = $1;
3015                 $return_style = 'broken';
3016                 $return_desc = $';
3017             } elsif (m%^\s*since:%i) {
3018                 $since_desc = $';
3019                 $in_since = 1;
3020                 $in_return = 0;
3021             } elsif (m%^\s*stability:%i) {
3022                 $stability_desc = $';
3023                 $in_stability = 1;
3024                 $in_return = 0;
3025             } elsif (m%^\s*deprecated:%i) {
3026                 $deprecated_desc = $';
3027                 $in_deprecated = 1;
3028                 $in_return = 0;
3029             } else {
3030                 $return_desc .= $_;
3031             }
3032             next;
3033         }
3034
3035         if ($in_since) {
3036             if (m/^\s*(returns:|return\s+value:)/i) {
3037                 if ($return_style eq 'broken') {
3038                     $description .= $return_start . $return_desc;
3039                 }
3040                 $return_start = $1;
3041                 if ($return_style eq 'sane') {
3042                     print <<EOF
3043 WARNING: Multiple Returns for $symbol
3044 EOF
3045                 }
3046                 $return_style = 'sane';
3047                 $ignore_broken_returns = 1;
3048                 $return_desc = $';
3049                 $in_return = 1;
3050                 $in_since = 0;
3051             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3052                 $return_start = $1;
3053                 $return_style = 'broken';
3054                 $return_desc = $';
3055                 $in_return = 1;
3056                 $in_since = 0;
3057             } elsif (m%^\s*deprecated:%i) {
3058                 $deprecated_desc = $';
3059                 $in_deprecated = 1;
3060                 $in_since = 0;
3061             } elsif (m%^\s*stability:%i) {
3062                 $stability_desc = $';
3063                 $in_stability = 1;
3064                 $in_since = 0;
3065             } else {
3066                 $since_desc .= $_;
3067             }
3068             next;
3069         }
3070
3071         if ($in_stability) {
3072             if (m/^\s*(returns:|return\s+value:)/i) {
3073                 if ($return_style eq 'broken') {
3074                     $description .= $return_start . $return_desc;
3075                 }
3076                 $return_start = $1;
3077                 if ($return_style eq 'sane') {
3078                     print <<EOF
3079 WARNING: Multiple Returns for $symbol
3080 EOF
3081                 }
3082                 $return_style = 'sane';
3083                 $ignore_broken_returns = 1;
3084                 $return_desc = $';
3085                 $in_return = 1;
3086                 $in_stability = 0;
3087             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3088                 $return_start = $1;
3089                 $return_style = 'broken';
3090                 $return_desc = $';
3091                 $in_return = 1;
3092                 $in_stability = 0;
3093             } elsif (m%^\s*deprecated:%i) {
3094                 $deprecated_desc = $';
3095                 $in_deprecated = 1;
3096                 $in_stability = 0;
3097             } elsif (m%^\s*since:%i) {
3098                 $since_desc = $';
3099                 $in_since = 1;
3100                 $in_stability = 0;
3101             } else {
3102                 $stability_desc .= $_;
3103             }
3104             next;
3105         }
3106
3107         if ($in_deprecated) {
3108             if (m/^\s*(returns:|return\s+value:)/i) {
3109                 if ($return_style eq 'broken') {
3110                     $description .= $return_start . $return_desc;
3111                 }
3112                 $return_start = $1;
3113                 if ($return_style eq 'sane') {
3114                     print <<EOF
3115 WARNING: Multiple Returns for $symbol
3116 EOF
3117                 }
3118                 $return_style = 'sane';
3119                 $ignore_broken_returns = 1;
3120                 $return_desc = $';
3121                 $in_return = 1;
3122                 $in_deprecated = 0;
3123             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3124                 $return_start = $1;
3125                 $return_style = 'broken';
3126                 $return_desc = $';
3127                 $in_return = 1;
3128                 $in_deprecated = 0;
3129             } elsif (m%^\s*since:%i) {
3130                 $since_desc = $';
3131                 $in_since = 1;
3132                 $in_deprecated = 0;
3133             } elsif (m%^\s*stability:%i) {
3134                 $stability_desc = $';
3135                 $in_stability = 1;
3136                 $in_deprecated = 0;
3137             } else {
3138                 $deprecated_desc .= $_;
3139             }
3140             next;
3141         }
3142
3143         # If we're in the description part, check for the 'Returns:' line.
3144         # If that isn't found, add the text to the end.
3145         if ($in_description) {
3146             # Get rid of 'Description:'
3147             s%^\s*Description:%%;
3148
3149             if (m/^\s*(returns:|return\s+value:)/i) {
3150                 if ($return_style eq 'broken') {
3151                     $description .= $return_start . $return_desc;
3152                 }
3153                 $return_start = $1;
3154                 if ($return_style eq 'sane') {
3155                     print <<EOF
3156 WARNING: Multiple Returns for $symbol
3157 EOF
3158                 }
3159                 $return_style = 'sane';
3160                 $ignore_broken_returns = 1;
3161                 $return_desc = $';
3162                 $in_return = 1;
3163                 next;
3164             } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) {
3165                 $return_start = $1;
3166                 $return_style = 'broken';
3167                 $return_desc = $';
3168                 $in_return = 1;
3169                 next;
3170             } elsif (m%^\s*since:%i) {
3171                 $since_desc = $';
3172                 $in_since = 1;
3173                 next;
3174             } elsif (m%^\s*deprecated:%i) {
3175                 $deprecated_desc = $';
3176                 $in_deprecated = 1;
3177                 next;
3178             } elsif (m%^\s*stability:%i) {
3179                 $stability_desc = $';
3180                 $in_stability = 1;
3181                 next;
3182             }
3183
3184             $description .= $_;
3185             next;
3186         }
3187
3188         # We must be in the parameters. Check for the empty line below them.
3189         if (m%^\s*$%) {
3190             $in_description = 1;
3191             next;
3192         }
3193
3194         # Look for a parameter name.
3195         if (m%^\s*@(\S+)\s*:%) {
3196             my $param_name = $1;
3197             #print "Found parameter: $param_name\n";
3198             # Allow '...' as the Varargs parameter.
3199             if ($param_name eq "...") {
3200                 $param_name = "Varargs";
3201             }
3202             if ("\L$param_name" eq "returns") {
3203                 $return_style = 'sane';
3204                 $ignore_broken_returns = 1;
3205             }
3206             push (@params, $param_name);
3207             push (@params, $');
3208             $current_param += 2;
3209             next;
3210         }
3211
3212         # We must be in the middle of a parameter description, so add it on
3213         # to the last element in @params.
3214         if ($current_param == -1) {
3215             print <<EOF
3216 ERROR parsing comment block file : parameter expected -
3217  $file:$.
3218 EOF
3219         } else {
3220             $params[$#params] .= $_;
3221         }
3222     }
3223     close (SRCFILE);
3224 }
3225
3226 #############################################################################
3227 # Function    : OutputMissingDocumentation
3228 # Description : Outputs report of documentation coverage to a file
3229 #
3230 # Arguments   : none
3231 #############################################################################
3232
3233 sub OutputMissingDocumentation {
3234      my $n_documented = 0;
3235      my $n_incomplete = 0;
3236      my $total = 0;
3237      my $symbol;
3238      my $percent;
3239      my $msg;
3240      my $buffer = "";
3241      my $buffer_deprecated = "";
3242      my $buffer_descriptions = "";
3243
3244      open (UNDOCUMENTED, ">$ROOT_DIR/$MODULE-undocumented.txt")
3245           || die "Can't create $ROOT_DIR/$MODULE-undocumented.txt";
3246
3247      foreach $symbol (sort (keys (%AllSymbols))) {
3248           if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include)/) {
3249               $total++;
3250               if (exists ($AllDocumentedSymbols{$symbol})) {
3251                   $n_documented++;
3252                   if (exists ($AllIncompleteSymbols{$symbol})) {
3253                       $n_incomplete++;
3254                       $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
3255                   }
3256               } elsif (exists $Deprecated{$symbol}) {
3257                   if (exists ($AllIncompleteSymbols{$symbol})) {
3258                       $n_incomplete++;
3259                       $buffer_deprecated .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
3260                   } else {
3261                       $buffer_deprecated .= $symbol . "\n";
3262                   }
3263               } else {
3264                   if (exists ($AllIncompleteSymbols{$symbol})) {
3265                       $n_incomplete++;
3266                       $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
3267                   } else {
3268                       $buffer .= $symbol . "\n";
3269                   }
3270               }
3271           } elsif ($symbol =~ /:(Long_Description|Short_Description)/) {
3272               $total++;
3273               #my $len1=(exists($SymbolDocs{$symbol}))?length($SymbolDocs{$symbol}):-1;
3274               #my $len2=(exists($AllDocumentedSymbols{$symbol}))?length($AllDocumentedSymbols{$symbol}):-1;
3275               #print "%%%% $symbol : $len1,$len2\n";
3276               if (((exists ($SymbolDocs{$symbol})) && (length ($SymbolDocs{$symbol}) > 0))
3277               || ((exists ($AllDocumentedSymbols{$symbol})) && (length ($AllDocumentedSymbols{$symbol}) > 0))) {
3278                   $n_documented++;
3279               } else {
3280                   $symbol =~ m/^.*\/(.*)$/;
3281                   $buffer_descriptions .= $1 . "\n";
3282               }
3283           }
3284      }
3285
3286      $buffer .= "\n" . $buffer_deprecated . "\n" . $buffer_descriptions;
3287
3288      if ($total == 0) {
3289           $percent = 100;
3290      } else {
3291           $percent = ($n_documented / $total) * 100.0;
3292      }
3293
3294      printf UNDOCUMENTED "%.0f%% symbol docs coverage.\n", $percent;
3295      print UNDOCUMENTED "$n_documented symbols documented.\n";
3296      print UNDOCUMENTED "$n_incomplete symbols incomplete.\n";
3297      print UNDOCUMENTED ($total - $n_documented) . " not documented.\n\n\n";
3298
3299      print UNDOCUMENTED $buffer;
3300
3301      close (UNDOCUMENTED);
3302
3303      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);
3304 }
3305
3306
3307 #############################################################################
3308 # Function    : OutputUndeclaredSymbols
3309 # Description : Outputs symbols that are undeclared yet documented to a file
3310 #
3311 # Arguments   : none
3312 #############################################################################
3313
3314 sub OutputUndeclaredSymbols {
3315     open(UNDECLARED, ">$ROOT_DIR/$MODULE-undeclared.txt")
3316         || die "Can't create $ROOT_DIR/$MODULE-undeclared.txt";
3317
3318     if (%UndeclaredSymbols) {
3319         print UNDECLARED (join("\n", sort keys %UndeclaredSymbols));
3320         print UNDECLARED "\n";
3321         print "See $MODULE-undeclared.txt for the list of undeclared symbols.\n"
3322     }
3323     close(UNDECLARED);
3324 }
3325
3326
3327 #############################################################################
3328 # Function    : OutputAllSymbols
3329 # Description : Outputs list of all symbols to a file
3330 #
3331 # Arguments   : none
3332 #############################################################################
3333
3334 sub OutputAllSymbols {
3335      my $n_documented = 0;
3336      my $total = 0;
3337      my $symbol;
3338      my $percent;
3339      my $msg;
3340
3341      open (SYMBOLS, ">$ROOT_DIR/$MODULE-symbols.txt")
3342           || die "Can't create $ROOT_DIR/$MODULE-symbols.txt";
3343
3344      foreach $symbol (sort (keys (%AllSymbols))) {
3345           print SYMBOLS $symbol . "\n"
3346      }
3347
3348      close (SYMBOLS);
3349 }
3350
3351
3352 #############################################################################
3353 # Function    : MergeSourceDocumentation
3354 # Description : This merges documentation read from a source file into the
3355 #               documentation read in from a template file.
3356 #
3357 #               Parameter descriptions override any in the template files.
3358 #               Function descriptions are placed before any description from
3359 #               the template files.
3360 #
3361 # Arguments   : none
3362 #############################################################################
3363
3364 sub MergeSourceDocumentation {
3365     my $symbol;
3366     my @Symbols;
3367
3368     if (scalar %SymbolDocs) {
3369         @Symbols=keys (%SymbolDocs);
3370     }
3371     else {
3372         @Symbols=keys (%SourceSymbolDocs);
3373     }
3374     foreach $symbol (@Symbols) {
3375         $AllSymbols{$symbol} = 1;
3376
3377         my $have_tmpl_docs = 0;
3378
3379         ## See if the symbol is documented out-of-line
3380         my $tmpl_doc = $SymbolDocs{$symbol};
3381         $tmpl_doc = defined ($tmpl_doc) ? $tmpl_doc : "";
3382         $tmpl_doc =~ s/<\/?[a-z]+>//g;
3383         $tmpl_doc =~ s/\s//g;
3384         if ($tmpl_doc ne "") {
3385             $have_tmpl_docs = 1;
3386         }
3387
3388         #print "merging $symbol\n";
3389
3390         if (exists ($SourceSymbolDocs{$symbol})) {
3391             my $src_doc = $SourceSymbolDocs{$symbol};
3392             my $tmpl_doc = $SymbolDocs{$symbol};
3393             my $type = $DeclarationTypes {$symbol};
3394
3395             #print "... from source\n";
3396
3397             my $item = "Parameter";
3398             if (defined ($type)) {
3399                 if ($type eq 'STRUCT') {
3400                     $item = "Field";
3401                 } elsif ($type eq 'ENUM') {
3402                     $item = "Value";
3403                 } elsif ($type eq 'UNION') {
3404                     $item = "Field";
3405                 }
3406             } else {
3407                 $type="SIGNAL";
3408             }
3409
3410             $tmpl_doc = defined ($tmpl_doc) ? $tmpl_doc : "";
3411             $src_doc =~ s/^\s+//;
3412             $src_doc =~ s/\s+$//;
3413
3414             # Don't output warnings for overridden titles as titles are
3415             # automatically generated in the -sections.txt file so are often
3416             # overridden.
3417             if ($have_tmpl_docs && $symbol !~ m/:Title$/) {
3418                     print <<EOF;
3419 WARNING: Documentation in template file for $symbol being overridden by inline comments
3420 EOF
3421             }
3422
3423             if ($src_doc ne "") {
3424                  $AllDocumentedSymbols{$symbol} = 1;
3425             }
3426
3427             # Convert <!--PARAMETERS--> with any blank lines around it to
3428             # a </para> followed by <!--PARAMETERS--> followed by <para>.
3429             $src_doc =~ s%\n+\s*<!--PARAMETERS-->\s*\n+%\n</para>\n<!--PARAMETERS-->\n<para>\n%g;
3430
3431             # If there is a blank line, finish the paragraph and start another.
3432             $src_doc = &ConvertBlankLines ($src_doc, $symbol);
3433
3434             if ($symbol =~ m/$TMPL_DIR\/.+:Long_Description/) {
3435                 # FIXME: should we check for empty $tmpl_doc ?
3436                 $SymbolDocs{$symbol} = "<para>\n$src_doc</para>\n$tmpl_doc"
3437             } elsif ($symbol =~ m/$TMPL_DIR\/.+:.+/) {
3438                 # For the title/summary/see also section docs we don't want to
3439                 # add any <para> tags.
3440                 $SymbolDocs{$symbol} = "$src_doc"
3441             } else {
3442                 $SymbolDocs{$symbol} = "<para>\n$src_doc</para>\n$tmpl_doc";
3443             }
3444
3445             # merge parameters
3446             if ($symbol =~ m/.*::.*/) {
3447                 # For signals we prefer the param names from the source docs,
3448                 # since the ones from the templates are likely to contain the
3449                 # artificial argn names which are generated by gtkdoc-scangobj.
3450                 $SymbolParams{$symbol} = $SourceSymbolParams{$symbol};
3451                 # FIXME: we need to check for empty docs here as well!
3452             } else {
3453                 # The templates contain the definitive parameter names and order,
3454                 # so we will not change that. We only override the actual text.
3455                 my $tmpl_params = $SymbolParams{$symbol};
3456                 if (!defined ($tmpl_params)) {
3457                     #print "No merge needed for $symbol\n";
3458                     $SymbolParams{$symbol} = $SourceSymbolParams{$symbol};
3459                 } else {
3460                     my $params = $SourceSymbolParams{$symbol};
3461                     my $j;
3462                     for ($j = 0; $j <= $#$tmpl_params; $j += 2) {
3463                         my $tmpl_param_name = $$tmpl_params[$j];
3464
3465                         # Allow '...' as the Varargs parameter.
3466                         if ($tmpl_param_name eq "...") {
3467                           $tmpl_param_name = "Varargs";
3468                         }
3469
3470                         # Try to find the param in the source comment documentation.
3471                         my $found = 0;
3472                         my $k;
3473                         for ($k = 0; $k <= $#$params; $k += 2) {
3474                             my $param_name = $$params[$k];
3475                             my $param_desc = $$params[$k + 1];
3476
3477                             # We accept changes in case, since the Gnome source docs
3478                             # contain a lot of these.
3479                             if ("\L$param_name" eq "\L$tmpl_param_name") {
3480                                 $found = 1;
3481
3482                                 # Override the description.
3483                                 $$tmpl_params[$j + 1] = $param_desc ;
3484
3485                                 # Set the name to "" to mark it as used.
3486                                 $$params[$k] = "";
3487                                 last;
3488                             }
3489                         }
3490
3491                         # If it looks like the parameters are there, but not
3492                         # in the right place, try to explain a bit better.
3493                         if ((!$found) && ($src_doc =~ m/\@$tmpl_param_name:/)) {
3494                             print <<EOF;
3495          Parameters for $symbol must start on the line immediately after the function
3496          or macro name.
3497 EOF
3498                         }
3499                     }
3500
3501                     # Now we output a warning if parameters have been described which
3502                     # do not exist.
3503                     for ($j = 0; $j <= $#$params; $j += 2) {
3504                         my $param_name = $$params[$j];
3505                         if ($param_name) {
3506                             # the template builder cannot detect if a macro returns
3507                             # a result or not
3508                             if(($type eq "MACRO") && ($param_name eq "Returns")) {
3509                                 next;
3510                             }
3511                             print <<EOF;
3512 WARNING: $item described in source code comment block but does not exist -
3513          $type: $symbol $item: $param_name.
3514 EOF
3515                         }
3516                     }
3517                 }
3518             }
3519         } else {
3520             if ($have_tmpl_docs) {
3521                 $AllDocumentedSymbols{$symbol} = 1;
3522             }
3523             else {
3524                 #print "... undocumented\n";
3525             }
3526         }
3527         # if this symbol is documented, check if docs are complete
3528         $tmpl_doc = $SymbolDocs{$symbol};
3529         $tmpl_doc = defined ($tmpl_doc) ? $tmpl_doc : "";
3530         $tmpl_doc =~ s/<\/?[a-z]+>//g;
3531         $tmpl_doc =~ s/\s//g;
3532         if ($tmpl_doc ne "") {
3533             my $tmpl_params = $SymbolParams{$symbol};
3534             if (defined ($tmpl_params)) {
3535                 my $type = $DeclarationTypes {$symbol};
3536
3537                 my $item = "Parameter";
3538                 if (defined ($type)) {
3539                     if ($type eq 'STRUCT') {
3540                         $item = "Field";
3541                     } elsif ($type eq 'ENUM') {
3542                         $item = "Value";
3543                     } elsif ($type eq 'UNION') {
3544                         $item = "Field";
3545                     }
3546                 } else {
3547                     $type="SIGNAL";
3548                 }
3549
3550                 my $j;
3551                 for ($j = 0; $j <= $#$tmpl_params; $j += 2) {
3552                     # Output a warning if the parameter is empty and
3553                     # remember for stats.
3554                     my $tmpl_param_name = $$tmpl_params[$j];
3555                     my $tmpl_param_desc = $$tmpl_params[$j + 1];
3556                     if ($tmpl_param_desc !~ m/\S/) {
3557                         if (exists ($AllIncompleteSymbols{$symbol})) {
3558                             $AllIncompleteSymbols{$symbol}.=", ".$tmpl_param_name;
3559                         } else {
3560                             $AllIncompleteSymbols{$symbol}=$tmpl_param_name;
3561                         }
3562 #                        print <<EOF;
3563 #WARNING: $item description missing in source code comment block -
3564 # $type: $symbol $item: $tmpl_param_name.
3565 #EOF
3566                     }
3567                 }
3568             }
3569         }
3570    }
3571 }
3572
3573 sub IsEmptyDoc {
3574     my ($doc) = @_;
3575
3576     if ($doc =~ /^\s*<para>\s*(FIXME)?\s*<\/para>\s*$/) {
3577         return 1;
3578     } else {
3579         return 0;
3580     }
3581 }
3582
3583
3584 # This converts blank lines to "</para><para>", but only outside CDATA and
3585 # <programlisting> tags.
3586 sub ConvertBlankLines {
3587     return &ModifyXMLElements ($_[0], $_[1],
3588                                "<!\\[CDATA\\[|<programlisting[^>]*>|\\|\\[",
3589                                \&ConvertBlankLinesEndTag,
3590                                \&ConvertBlankLinesCallback);
3591 }
3592
3593
3594 sub ConvertBlankLinesEndTag {
3595   if ($_[0] eq "<!\[CDATA\[") {
3596     return "]]>";
3597   } elsif ($_[0] eq "|[") {
3598     return "]\\|";
3599   } else {
3600     return "</programlisting>";
3601   }
3602 }
3603
3604 sub ConvertBlankLinesCallback {
3605   my ($text, $symbol, $tag) = @_;
3606
3607   # If we're not in CDATA or a <programlisting> we convert blank lines so
3608   # they start a new <para>.
3609   if ($tag eq "") {
3610     $text =~ s%\n{2,}%\n</para>\n<para>\n%g;
3611   }
3612
3613   return $text;
3614 }
3615
3616
3617 #############################################################################
3618 # LIBRARY FUNCTIONS -   These functions are used in both gtkdoc-mkdb and
3619 #                       gtkdoc-mktmpl and should eventually be moved to a
3620 #                       separate library.
3621 #############################################################################
3622
3623 #############################################################################
3624 # Function    : ReadDeclarationsFile
3625 # Description : This reads in a file containing the function/macro/enum etc.
3626 #               declarations.
3627 #
3628 #               Note that in some cases there are several declarations with
3629 #               the same name, e.g. for conditional macros. In this case we
3630 #               set a flag in the %DeclarationConditional hash so the
3631 #               declaration is not shown in the docs.
3632 #
3633 #               If a macro and a function have the same name, e.g. for
3634 #               gtk_object_ref, the function declaration takes precedence.
3635 #
3636 #               Some opaque structs are just declared with 'typedef struct
3637 #               _name name;' in which case the declaration may be empty.
3638 #               The structure may have been found later in the header, so
3639 #               that overrides the empty declaration.
3640 #
3641 # Arguments   : $file - the declarations file to read
3642 #               $override - if declarations in this file should override
3643 #                       any current declaration.
3644 #############################################################################
3645
3646 sub ReadDeclarationsFile {
3647     my ($file, $override) = @_;
3648
3649     if ($override == 0) {
3650         %Declarations = ();
3651         %DeclarationTypes = ();
3652         %DeclarationConditional = ();
3653         %DeclarationOutput = ();
3654     }
3655
3656     open (INPUT, $file)
3657         || die "Can't open $file";
3658     my $declaration_type = "";
3659     my $declaration_name;
3660     my $declaration;
3661     my $is_deprecated = 0;
3662     while (<INPUT>) {
3663         if (!$declaration_type) {
3664             if (m/^<([^>]+)>/) {
3665                 $declaration_type = $1;
3666                 $declaration_name = "";
3667 #               print "Found declaration: $declaration_type\n";
3668                 $declaration = "";
3669             }
3670         } else {
3671             if (m%^<NAME>(.*)</NAME>%) {
3672                 $declaration_name = $1;
3673             } elsif (m%^<DEPRECATED/>%) {
3674                 $is_deprecated = 1;
3675             } elsif (m%^</$declaration_type>%) {
3676 #               print "Found end of declaration: $declaration_name\n";
3677                 # Check that the declaration has a name
3678                 if ($declaration_name eq "") {
3679                     print "ERROR: $declaration_type has no name $file:$.\n";
3680                 }
3681
3682                 # If the declaration is an empty typedef struct _XXX XXX
3683                 # set the flag to indicate the struct has a typedef.
3684                 if ($declaration_type eq 'STRUCT'
3685                     && $declaration =~ m/^\s*$/) {
3686 #                   print "Struct has typedef: $declaration_name\n";
3687                     $StructHasTypedef{$declaration_name} = 1;
3688                 }
3689
3690                 # Check if the symbol is already defined.
3691                 if (defined ($Declarations{$declaration_name})
3692                     && $override == 0) {
3693                     # Function declarations take precedence.
3694                     if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') {
3695                         # Ignore it.
3696                     } elsif ($declaration_type eq 'FUNCTION') {
3697                         if ($is_deprecated) {
3698                             $Deprecated{$declaration_name} = "";
3699                         }
3700                         $Declarations{$declaration_name} = $declaration;
3701                         $DeclarationTypes{$declaration_name} = $declaration_type;
3702                     } elsif ($DeclarationTypes{$declaration_name}
3703                               eq $declaration_type) {
3704                         # If the existing declaration is empty, or is just a
3705                         # forward declaration of a struct, override it.
3706                         if ($declaration_type eq 'STRUCT') {
3707                             if ($Declarations{$declaration_name} =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
3708                                 if ($is_deprecated) {
3709                                     $Deprecated{$declaration_name} = "";
3710                                 }
3711                                 $Declarations{$declaration_name} = $declaration;
3712                             } elsif ($declaration =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
3713                                 # Ignore an empty or forward declaration.
3714                             } else {
3715                                 print "WARNING: Structure has multiple definitions: $declaration_name\n";
3716                             }
3717
3718                         } else {
3719                             # set flag in %DeclarationConditional hash for
3720                             # multiply defined macros/typedefs.
3721                             $DeclarationConditional{$declaration_name} = 1;
3722                         }
3723                     } else {
3724                         print "ERROR: $declaration_name has multiple definitions\n";
3725                     }
3726                 } else {
3727                     if ($is_deprecated) {
3728                         $Deprecated{$declaration_name} = "";
3729                     }
3730                     $Declarations{$declaration_name} = $declaration;
3731                     $DeclarationTypes{$declaration_name} = $declaration_type;
3732                 }
3733
3734                 $declaration_type = "";
3735                 $is_deprecated = 0;
3736             } else {
3737                 $declaration .= $_;
3738             }
3739         }
3740     }
3741     close (INPUT);
3742 }
3743
3744
3745 #############################################################################
3746 # Function    : ReadSignalsFile
3747 # Description : This reads in an existing file which contains information on
3748 #               all GTK signals. It creates the arrays @SignalNames and
3749 #               @SignalPrototypes containing info on the signals. The first
3750 #               line of the SignalPrototype is the return type of the signal
3751 #               handler. The remaining lines are the parameters passed to it.
3752 #               The last parameter, "gpointer user_data" is always the same
3753 #               so is not included.
3754 # Arguments   : $file - the file containing the signal handler prototype
3755 #                       information.
3756 #############################################################################
3757
3758 sub ReadSignalsFile {
3759     my ($file) = @_;
3760
3761     my $in_signal = 0;
3762     my $signal_object;
3763     my $signal_name;
3764     my $signal_returns;
3765     my $signal_flags;
3766     my $signal_prototype;
3767
3768     # Reset the signal info.
3769     @SignalObjects = ();
3770     @SignalNames = ();
3771     @SignalReturns = ();
3772     @SignalFlags = ();
3773     @SignalPrototypes = ();
3774
3775     if (! -f $file) {
3776         return;
3777     }
3778     if (!open (INPUT, $file)) {
3779         warn "Can't open $file - skipping signals\n";
3780         return;
3781     }
3782     while (<INPUT>) {
3783         if (!$in_signal) {
3784             if (m/^<SIGNAL>/) {
3785                 $in_signal = 1;
3786                 $signal_object = "";
3787                 $signal_name = "";
3788                 $signal_returns = "";
3789                 $signal_prototype = "";
3790             }
3791         } else {
3792             if (m/^<NAME>(.*)<\/NAME>/) {
3793                 $signal_name = $1;
3794                 if ($signal_name =~ m/^(.*)::(.*)$/) {
3795                     $signal_object = $1;
3796                     ($signal_name = $2) =~ s/_/-/g;
3797 #                   print "Found signal: $signal_name\n";
3798                 } else {
3799                     print "Invalid signal name: $signal_name\n";
3800                 }
3801             } elsif (m/^<RETURNS>(.*)<\/RETURNS>/) {
3802                 $signal_returns = $1;
3803             } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
3804                 $signal_flags = $1;
3805             } elsif (m%^</SIGNAL>%) {
3806 #               print "Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}";
3807                 push (@SignalObjects, $signal_object);
3808                 push (@SignalNames, $signal_name);
3809                 push (@SignalReturns, $signal_returns);
3810                 push (@SignalFlags, $signal_flags);
3811                 push (@SignalPrototypes, $signal_prototype);
3812                 $in_signal = 0;
3813             } else {
3814                 $signal_prototype .= $_;
3815             }
3816         }
3817     }
3818     close (INPUT);
3819 }
3820
3821
3822 #############################################################################
3823 # Function    : ReadTemplateFile
3824 # Description : This reads in the manually-edited documentation file
3825 #               corresponding to the file currently being created, so we can
3826 #               insert the documentation at the appropriate places.
3827 #               It outputs %SymbolTypes, %SymbolDocs and %SymbolParams, which
3828 #               is a hash of arrays.
3829 #               NOTE: This function is duplicated in gtkdoc-mkdb (but
3830 #               slightly different).
3831 # Arguments   : $docsfile - the template file to read in.
3832 #               $skip_unused_params - 1 if the unused parameters should be
3833 #                       skipped.
3834 #############################################################################
3835
3836 sub ReadTemplateFile {
3837     my ($docsfile, $skip_unused_params) = @_;
3838
3839     my $template = "$docsfile.sgml";
3840 #    print "Reading $template\n";
3841     if (! -f $template) {
3842 #       print "File doesn't exist: $template\n";
3843         return;
3844     }
3845
3846     my $current_type = "";      # Type of symbol being read.
3847     my $current_symbol = "";    # Name of symbol being read.
3848     my $symbol_doc = "";                # Description of symbol being read.
3849     my @params;                 # Parameter names and descriptions of current
3850                                 #   function/macro/function typedef.
3851     my $current_param = -1;     # Index of parameter currently being read.
3852                                 #   Note that the param array contains pairs
3853                                 #   of param name & description.
3854     my $in_unused_params = 0;   # True if we are reading in the unused params.
3855     my $in_deprecated = 0;
3856     my $in_since = 0;
3857     my $in_stability = 0;
3858
3859     open (DOCS, "$template")
3860         || die "Can't open file $template: $!";
3861     while (<DOCS>) {
3862         if (m/^<!-- ##### ([A-Z_]+) (\S+) ##### -->/) {
3863             my $type = $1;
3864             my $symbol = $2;
3865             if ($symbol eq "Title"
3866                 || $symbol eq "Short_Description"
3867                 || $symbol eq "Long_Description"
3868                 || $symbol eq "See_Also"
3869                 || $symbol eq "Stability_Level"
3870                 || $symbol eq "Include") {
3871
3872                 $symbol = $docsfile . ":" . $symbol;
3873             }
3874
3875 #           print "Found symbol: $symbol\n";
3876
3877             # Store previous symbol, but remove any trailing blank lines.
3878             if ($current_symbol ne "") {
3879                 $symbol_doc =~ s/\s+$//;
3880                 $SymbolTypes{$current_symbol} = $current_type;
3881                 $SymbolDocs{$current_symbol} = $symbol_doc;
3882
3883                 # Check that the stability level is valid.
3884                 if ($StabilityLevel{$current_symbol}) {
3885                     $StabilityLevel{$current_symbol} = &ParseStabilityLevel($StabilityLevel{$current_symbol}, "Stability level for $current_symbol");
3886                 }
3887
3888                 if ($current_param >= 0) {
3889                     $SymbolParams{$current_symbol} = [ @params ];
3890                 } else {
3891                     # Delete any existing params in case we are overriding a
3892                     # previously read template.
3893                     delete $SymbolParams{$current_symbol};
3894                 }
3895             }
3896             $current_type = $type;
3897             $current_symbol = $symbol;
3898             $current_param = -1;
3899             $in_unused_params = 0;
3900             $in_deprecated = 0;
3901             $in_since = 0;
3902             $in_stability = 0;
3903             $symbol_doc = "";
3904             @params = ();
3905
3906         } elsif (m/^<!-- # Unused Parameters # -->/) {
3907 #           print "DEBUG: Found unused parameters\n";
3908             $in_unused_params = 1;
3909             next;
3910
3911         } elsif ($in_unused_params && $skip_unused_params) {
3912             # When outputting the DocBook we skip unused parameters.
3913 #           print "DEBUG: Skipping unused param: $_";
3914             next;
3915
3916         } else {
3917             # Check if param found. Need to handle "..." and "format...".
3918             if (s/^\@([\w\.]+):\040?//) {
3919                 my $param_name = $1;
3920                 # Allow variations of 'Returns'
3921                 if ($param_name =~ m/^[Rr]eturns?$/) {
3922                     $param_name = "Returns";
3923                 }
3924 #               print "Found param for symbol $current_symbol : '$param_name'= '$_'\n";
3925
3926                 if ($param_name eq "Deprecated") {
3927                     $in_deprecated = 1;
3928                     $Deprecated{$current_symbol} = $_;
3929                 } elsif ($param_name eq "Since") {
3930                     $in_since = 1;
3931                     $Since{$current_symbol} = $_;
3932                 } elsif ($param_name eq "Stability") {
3933                     $in_stability = 1;
3934                     $StabilityLevel{$current_symbol} = $_;
3935                 } else {
3936                     push (@params, $param_name);
3937                     push (@params, $_);
3938                     $current_param += 2;
3939                 }
3940             } else {
3941                 if ($in_deprecated) {
3942                     $Deprecated{$current_symbol} .= $_;
3943                 } elsif ($in_since) {
3944                     $Since{$current_symbol} .= $_;
3945                 } elsif ($in_stability) {
3946                     $StabilityLevel{$current_symbol} .= $_;
3947                 } elsif ($current_param >= 0) {
3948                     $params[$current_param] .= $_;
3949                 } else {
3950                     $symbol_doc .= $_;
3951                 }
3952             }
3953         }
3954     }
3955
3956     # Remember to finish the current symbol doccs.
3957     if ($current_symbol ne "") {
3958
3959         $symbol_doc =~ s/\s+$//;
3960         $SymbolTypes{$current_symbol} = $current_type;
3961         $SymbolDocs{$current_symbol} = $symbol_doc;
3962
3963         # Check that the stability level is valid.
3964         if ($StabilityLevel{$current_symbol}) {
3965             $StabilityLevel{$current_symbol} = &ParseStabilityLevel($StabilityLevel{$current_symbol}, "Stability level for $current_symbol");
3966         }
3967
3968         if ($current_param >= 0) {
3969             $SymbolParams{$current_symbol} = [ @params ];
3970         } else {
3971             # Delete any existing params in case we are overriding a
3972             # previously read template.
3973             delete $SymbolParams{$current_symbol};
3974         }
3975     }
3976
3977     close (DOCS);
3978 }
3979
3980
3981 #############################################################################
3982 # Function    : ReadObjectHierarchy
3983 # Description : This reads in the $MODULE-hierarchy.txt file containing all
3984 #               the GtkObject subclasses described in this module (and their
3985 #               ancestors).
3986 #               It places them in the @Objects array, and places their level
3987 #               in the widget hierarchy in the @ObjectLevels array, at the
3988 #               same index. GtkObject, the root object, has a level of 1.
3989 #
3990 #               FIXME: the version in gtkdoc-mkdb also generates tree_index.sgml
3991 #               as it goes along, this should be split out into a separate
3992 #               function.
3993 #
3994 # Arguments   : none
3995 #############################################################################
3996
3997 sub ReadObjectHierarchy {
3998     @Objects = ();
3999     @ObjectLevels = ();
4000
4001     if (! -f $OBJECT_TREE_FILE) {
4002         return;
4003     }
4004     if (!open (INPUT, $OBJECT_TREE_FILE)) {
4005         warn "Can't open $OBJECT_TREE_FILE - skipping object tree\n";
4006         return;
4007     }
4008
4009     my $old_tree_index = "$SGML_OUTPUT_DIR/tree_index.sgml";
4010     my $new_tree_index = "$SGML_OUTPUT_DIR/tree_index.new";
4011     my $tree_header = $doctype_header;
4012     $tree_header =~ s/<!DOCTYPE \w+/<!DOCTYPE screen/;
4013
4014     open (OUTPUT, ">$new_tree_index")
4015         || die "Can't create $new_tree_index";
4016     print (OUTPUT "$tree_header<screen>\n");
4017
4018     # Only emit objects if they are supposed to be documented, or if
4019     # they have documented children. To implement this, we maintain a
4020     # stack of pending objects which will be emitted if a documented
4021     # child turns up.
4022     my @pending_objects = ();
4023     my @pending_levels = ();
4024     while (<INPUT>) {
4025         if (m/\S+/) {
4026             my $object = $&;
4027             my $level = (length($`)) / 2 + 1;
4028             my $xref = "";
4029
4030             while (($#pending_levels >= 0) && ($pending_levels[$#pending_levels] >= $level)) {
4031                 my $pobject = pop(@pending_objects);
4032                 my $plevel = pop(@pending_levels);
4033             }
4034
4035             push (@pending_objects, $object);
4036             push (@pending_levels, $level);
4037
4038             if (exists($KnownSymbols{$object}) && $KnownSymbols{$object} == 1) {
4039                 while ($#pending_levels >= 0) {
4040                     $object = shift @pending_objects;
4041                     $level = shift @pending_levels;
4042                     $xref = &MakeXRef ($object);
4043
4044                     print (OUTPUT ' ' x ($level * 4), "$xref\n");
4045                     push (@Objects, $object);
4046                     push (@ObjectLevels, $level);
4047                 }
4048             }
4049         }
4050     }
4051     print (OUTPUT "</screen>\n");
4052
4053     close (INPUT);
4054     close (OUTPUT);
4055
4056     &UpdateFileIfChanged ($old_tree_index, $new_tree_index, 0);
4057
4058     &OutputObjectList;
4059 }
4060
4061 #############################################################################
4062 # Function    : ReadInterfaces
4063 # Description : This reads in the $MODULE.interfaces file.
4064 #
4065 # Arguments   : none
4066 #############################################################################
4067
4068 sub ReadInterfaces {
4069     %Interfaces = ();
4070
4071     if (! -f $INTERFACES_FILE) {
4072         return;
4073     }
4074     if (!open (INPUT, $INTERFACES_FILE)) {
4075         warn "Can't open $INTERFACES_FILE - skipping interfaces\n";
4076         return;
4077     }
4078
4079     while (<INPUT>) {
4080        chomp;
4081        my ($object, @ifaces) = split;
4082        if (exists($KnownSymbols{$object}) && $KnownSymbols{$object} == 1) {
4083            my @knownIfaces = ();
4084
4085            # filter out private interfaces, but leave foreign interfaces
4086            foreach my $iface (@ifaces) {
4087                if (!exists($KnownSymbols{$iface}) || $KnownSymbols{$iface} == 1) {
4088                    push (@knownIfaces, $iface);
4089                }
4090              }
4091
4092            $Interfaces{$object} = join(' ', @knownIfaces);
4093        }
4094     }
4095     close (INPUT);
4096 }
4097
4098 #############################################################################
4099 # Function    : ReadPrerequisites
4100 # Description : This reads in the $MODULE.prerequisites file.
4101 #
4102 # Arguments   : none
4103 #############################################################################
4104
4105 sub ReadPrerequisites {
4106     %Prerequisites = ();
4107
4108     if (! -f $PREREQUISITES_FILE) {
4109         return;
4110     }
4111     if (!open (INPUT, $PREREQUISITES_FILE)) {
4112         warn "Can't open $PREREQUISITES_FILE - skipping prerequisites\n";
4113         return;
4114     }
4115
4116     while (<INPUT>) {
4117        chomp;
4118        my ($iface, @prereqs) = split;
4119        if (exists($KnownSymbols{$iface}) && $KnownSymbols{$iface} == 1) {
4120            my @knownPrereqs = ();
4121
4122            # filter out private prerequisites, but leave foreign prerequisites
4123            foreach my $prereq (@prereqs) {
4124                if (!exists($KnownSymbols{$prereq}) || $KnownSymbols{$prereq} == 1) {
4125                   push (@knownPrereqs, $prereq);
4126                }
4127            }
4128
4129            $Prerequisites{$iface} = join(' ', @knownPrereqs);
4130        }
4131     }
4132     close (INPUT);
4133 }
4134
4135 #############################################################################
4136 # Function    : ReadArgsFile
4137 # Description : This reads in an existing file which contains information on
4138 #               all GTK args. It creates the arrays @ArgObjects, @ArgNames,
4139 #               @ArgTypes, @ArgFlags, @ArgNicks and @ArgBlurbs containing info
4140 #               on the args.
4141 # Arguments   : $file - the file containing the arg information.
4142 #############################################################################
4143
4144 sub ReadArgsFile {
4145     my ($file) = @_;
4146
4147     my $in_arg = 0;
4148     my $arg_object;
4149     my $arg_name;
4150     my $arg_type;
4151     my $arg_flags;
4152     my $arg_nick;
4153     my $arg_blurb;
4154     my $arg_default;
4155     my $arg_range;
4156
4157     # Reset the args info.
4158     @ArgObjects = ();
4159     @ArgNames = ();
4160     @ArgTypes = ();
4161     @ArgFlags = ();
4162     @ArgNicks = ();
4163     @ArgBlurbs = ();
4164     @ArgDefaults = ();
4165     @ArgRanges = ();
4166
4167     if (! -f $file) {
4168         return;
4169     }
4170     if (!open (INPUT, $file)) {
4171         warn "Can't open $file - skipping args\n";
4172         return;
4173     }
4174     while (<INPUT>) {
4175         if (!$in_arg) {
4176             if (m/^<ARG>/) {
4177                 $in_arg = 1;
4178                 $arg_object = "";
4179                 $arg_name = "";
4180                 $arg_type = "";
4181                 $arg_flags = "";
4182                 $arg_nick = "";
4183                 $arg_blurb = "";
4184                 $arg_default = "";
4185                 $arg_range = "";
4186             }
4187         } else {
4188             if (m/^<NAME>(.*)<\/NAME>/) {
4189                 $arg_name = $1;
4190                 if ($arg_name =~ m/^(.*)::(.*)$/) {
4191                     $arg_object = $1;
4192                     ($arg_name = $2) =~ s/_/-/g;
4193 #                   print "Found arg: $arg_name\n";
4194                 } else {
4195                     print "Invalid arg name: $arg_name\n";
4196                 }
4197             } elsif (m/^<TYPE>(.*)<\/TYPE>/) {
4198                 $arg_type = $1;
4199             } elsif (m/^<RANGE>(.*)<\/RANGE>/) {
4200                 $arg_range = $1;
4201             } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
4202                 $arg_flags = $1;
4203             } elsif (m/^<NICK>(.*)<\/NICK>/) {
4204                 $arg_nick = $1;
4205             } elsif (m/^<BLURB>(.*)<\/BLURB>/) {
4206                 $arg_blurb = $1;
4207                 if ($arg_blurb eq "(null)") {
4208                   $arg_blurb = "";
4209                   print <<EOF;
4210 WARNING: Property ${arg_object}:${arg_name} has no documentation.
4211 EOF
4212                 }
4213             } elsif (m/^<DEFAULT>(.*)<\/DEFAULT>/) {
4214                 $arg_default = $1;
4215             } elsif (m%^</ARG>%) {
4216 #               print "Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n";
4217                 push (@ArgObjects, $arg_object);
4218                 push (@ArgNames, $arg_name);
4219                 push (@ArgTypes, $arg_type);
4220                 push (@ArgRanges, $arg_range);
4221                 push (@ArgFlags, $arg_flags);
4222                 push (@ArgNicks, $arg_nick);
4223                 push (@ArgBlurbs, $arg_blurb);
4224                 push (@ArgDefaults, $arg_default);
4225                 $in_arg = 0;
4226             }
4227         }
4228     }
4229     close (INPUT);
4230 }
4231
4232
4233 #############################################################################
4234 # Function    : CheckIsObject
4235 # Description : Returns 1 if the given name is a GtkObject or a subclass.
4236 #               It uses the global @Objects array.
4237 #               Note that the @Objects array only contains classes in the
4238 #               current module and their ancestors - not all GTK classes.
4239 # Arguments   : $name - the name to check.
4240 #############################################################################
4241
4242 sub CheckIsObject {
4243     my ($name) = @_;
4244
4245     my $object;
4246     foreach $object (@Objects) {
4247         if ($object eq $name) {
4248             return 1;
4249         }
4250     }
4251     return 0;
4252 }
4253
4254
4255 #############################################################################
4256 # Function    : MakeReturnField
4257 # Description : Pads a string to $RETURN_TYPE_FIELD_WIDTH.
4258 # Arguments   : $str - the string to pad.
4259 #############################################################################
4260
4261 sub MakeReturnField {
4262     my ($str) = @_;
4263
4264     return $str . (' ' x ($RETURN_TYPE_FIELD_WIDTH - length ($str)));
4265 }
4266