gtkdoc-mkdb.in

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