Index: gtkdoc-mkdb.in
===================================================================
--- gtkdoc-mkdb.in	(revision 452)
+++ gtkdoc-mkdb.in	(working copy)
@@ -41,6 +42,7 @@
 my $MODULE;
 my $TMPL_DIR;
 my $SGML_OUTPUT_DIR;
+my $MASTER_DIR;
 my @SOURCE_DIRS;
 my $SOURCE_SUFFIXES = "";
 my $IGNORE_FILES = "";
@@ -59,6 +61,7 @@
 	      'source-suffixes' => \$SOURCE_SUFFIXES,
 	      'ignore-files' => \$IGNORE_FILES,
 	      'output-dir' => \$SGML_OUTPUT_DIR,
+	      'master-dir' => \$MASTER_DIR,
 	      'tmpl-dir' => \$TMPL_DIR,
 	      'version' => \$PRINT_VERSION,
 	      'help' => \$PRINT_HELP,
@@ -69,7 +72,12 @@
 	      'default-stability' => \$DEFAULT_STABILITY,
 	      'default-includes' => \$DEFAULT_INCLUDES,
 	      'output-format' => \$OUTPUT_FORMAT);
-GetOptions(\%optctl, "module=s", "source-dir:s", "source-suffixes:s", "ignore-files:s", "output-dir:s", "tmpl-dir:s", "version", "outputallsymbols", "expand-content-files:s", "main-sgml-file:s", "extra-db-files:s", "help", "sgml-mode", "default-stability:s", "default-includes:s", "output-format:s");
+GetOptions(\%optctl, "module=s", "source-dir=s", "source-suffixes:s",
+		     "ignore-files:s", "output-dir=s", "tmpl-dir=s", "version",
+		     "outputallsymbols", "expand-content-files:s",
+		     "main-sgml-file=s", "extra-db-files:s", "help",
+		     "sgml-mode", "default-stability:s", "default-includes:s",
+		     "output-format=s", "master-dir=s");
 
 if ($PRINT_VERSION) {
     print "@VERSION@\n";
@@ -94,6 +102,7 @@
     print "\n                       May be used more than once for multiple directories";
     print "\n--output-dir=DIRNAME   Directory to put the generated DocBook files in";
     print "\n--tmpl-dir=DIRNAME     Directory in which template files may be found";
+    print "\n--master-dir=DIRNAME   Directory with non-generated files (for VPATH builds)";
     print "\n--main-sgml-file=FILE  File containing the toplevel DocBook file.";
     print "\n--expand-content-files=FILES Extra DocBook files to expand abbreviations in.";
     print "\n--output-format=FORMAT The format to use for the generated docbook, XML or SGML.";
@@ -106,8 +115,18 @@
     exit 0;
 }
 
+# All the files are written in subdirectories beneath ROOT_DIR.
+# Files considered human-maintained (not normally written) are looked for and
+# created in MASTER_DIR.
+my $ROOT_DIR = ".";
+
 if (!$MAIN_SGML_FILE) {
-    $MAIN_SGML_FILE="${MODULE}-docs.sgml";
+    if ($MASTER_DIR) {
+	$MAIN_SGML_FILE="$MASTER_DIR/$MODULE-docs.sgml";
+    }
+    else {
+	$MAIN_SGML_FILE="$ROOT_DIR/$MODULE-docs.sgml";
+    }
 }
 
 my ($empty_element_end, $doctype_header);
@@ -142,9 +161,6 @@
     $empty_element_end = ">";
 }
 
-my $ROOT_DIR = ".";
-
-# All the files are written in subdirectories beneath here.
 $TMPL_DIR = $TMPL_DIR ? $TMPL_DIR : "$ROOT_DIR/tmpl";
 
 # This is where we put all the DocBook output.
@@ -165,6 +181,20 @@
 # The file containing Arg information.
 my $ARGS_FILE = "$ROOT_DIR/$MODULE.args";
 
+# The section organization file.
+# If it's manually written, it's in MASTER_DIR.
+my $SECTION_FILE = "$ROOT_DIR/$MODULE-sections.txt";
+if (! -e $SECTION_FILE and $MASTER_DIR) {
+    $SECTION_FILE = "$MASTER_DIR/$MODULE-sections.txt";
+}
+
+# The overrides file.
+# Typically manually written.
+my $OVERRIDES_FILE = "$ROOT_DIR/$MODULE-overrides.txt";
+if (! -e $OVERRIDES_FILE and $MASTER_DIR) {
+    $OVERRIDES_FILE = "$MASTER_DIR/$MODULE-overrides.txt";
+}
+
 # These global arrays store information on signals. Each signal has an entry
 # in each of these arrays at the same index, like a multi-dimensional array.
 my @SignalObjects;	# The GtkObject which emits the signal.
@@ -249,7 +282,7 @@
 my $SYMBOL_FIELD_WIDTH = 36;
 my $SIGNAL_FIELD_WIDTH = 16;
 
-&ReadKnownSymbols ("$ROOT_DIR/$MODULE-sections.txt");
+&ReadKnownSymbols ($SECTION_FILE);
 &ReadSignalsFile ($SIGNALS_FILE);
 &ReadArgsFile ($ARGS_FILE);
 &ReadObjectHierarchy;
@@ -257,15 +290,15 @@
 &ReadPrerequisites;
 
 &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-decl.txt", 0);
-if (-f "$ROOT_DIR/$MODULE-overrides.txt") {
-    &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-overrides.txt", 1);
+if (-f $OVERRIDES_FILE) {
+    &ReadDeclarationsFile ($OVERRIDES_FILE, 1);
 }
 
 for my $dir (@SOURCE_DIRS) {
     &ReadSourceDocumentation ($dir);
 }
 
-my $changed = &OutputSGML ("$ROOT_DIR/$MODULE-sections.txt");
+my $changed = &OutputSGML ($SECTION_FILE);
 
 # If any of the DocBook SGML files have changed, update the timestamp file (so
 # it can be used for Makefile dependencies).
Index: gtkdoc-scan.in
===================================================================
--- gtkdoc-scan.in	(revision 452)
+++ gtkdoc-scan.in	(working copy)
@@ -59,20 +60,23 @@
 my $DEPRECATED_GUARDS;
 # regexp matching decorators that should be ignored
 my $IGNORE_DECORATORS;
+my $MASTER_DIR;
 
 my %optctl = (module => \$MODULE,
 	      'source-dir' => \@SOURCE_DIRS,
 	      'ignore-headers' => \$IGNORE_HEADERS,
 	      'output-dir' => \$OUTPUT_DIR,
+	      'master-dir' => \$MASTER_DIR,
 	      'rebuild-types' => \$REBUILD_TYPES,
-              'rebuild-sections' => \$REBUILD_SECTIONS,
+	      'rebuild-sections' => \$REBUILD_SECTIONS,
 	      'version' => \$PRINT_VERSION,
 	      'help' => \$PRINT_HELP,
 	      'deprecated-guards' => \$DEPRECATED_GUARDS,
 	      'ignore-decorators' => \$IGNORE_DECORATORS);
-GetOptions(\%optctl, "module=s", "source-dir:s", "ignore-headers:s",
-	   "output-dir:s", "rebuild-types", "rebuild-sections", "version",
-	   "help", "deprecated-guards:s", "ignore-decorators:s");
+GetOptions(\%optctl, "module=s", "source-dir=s", "ignore-headers:s",
+	   "output-dir=s", "rebuild-types", "rebuild-sections", "version",
+	   "help", "deprecated-guards:s", "ignore-decorators:s",
+	   "master-dir=s");
 
 if ($PRINT_VERSION) {
     print "@VERSION@\n";
@@ -89,6 +93,7 @@
     print "\n--source-dir=DIRNAME       Directories containing the source files to scan";
     print "\n--ignore-headers=FILES     A space-separated list of header files not to scan";
     print "\n--output-dir=DIRNAME       The directory where the results are stored";
+    print "\n--master-dir=DIRNAME       Directory with non-generated files (for VPATH builds)";
     print "\n--deprecated-guards=GUARDS A |-separated list of symbols used as deprecation guards";
     print "\n--ignore-decorators=DECS   A |-separated list of addition decorators in declarations that should be ignored";
     print "\n--rebuild-sections         Rebuild (overwrite) the MODULE-sections.txt file";
@@ -112,11 +117,31 @@
 my $new_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.new";
 my $old_decl = "${OUTPUT_DIR}/$MODULE-decl.txt";
 my $new_decl = "${OUTPUT_DIR}/$MODULE-decl.new";
-my $old_types = "${OUTPUT_DIR}/$MODULE.types";
-my $new_types = "${OUTPUT_DIR}/$MODULE.types.new";
-my $sections_file = "${OUTPUT_DIR}/$MODULE-sections.txt";
 
+# With --rebuild-types, the types file assumed to be computer-generated and
+# it is read from and written to OUTPUT_DIR; without it is assumed to be
+# human-maintained and therefore reside in MASTER_DIR.  The same applies to
+# the section file.
+my ($old_types, $new_types, $sections_file);
+
+if ($REBUILD_TYPES) {
+    $old_types = "${OUTPUT_DIR}/$MODULE.types";
+    $new_types = "${OUTPUT_DIR}/$MODULE.types.new";
+}
+else {
+    $old_types = "$MASTER_DIR/$MODULE.type";
+    $old_types = "$MASTER_DIR/$MODULE.type";
+}
+
+if ($REBUILD_SECTIONS) {
+    $sections_file = "${OUTPUT_DIR}/$MODULE-sections.txt";
+}
+else {
+    $sections_file = "$MASTER_DIR/MODULE-sections.txt";
+}
+
 # If this is the very first run then we create the .types file automatically.
+# The location is decided above.
 if (! -e $sections_file && ! -e $old_types) {
     $REBUILD_TYPES = 1;
 }
@@ -160,10 +188,16 @@
 }
 
 # If there is no MODULE-overrides.txt file we create an empty one.
+# Typically it's manually written but to be on the safe side, look into
+# builddir first.
 my $overrides_file = "${OUTPUT_DIR}/$MODULE-overrides.txt";
 if (! -e $overrides_file) {
-  `touch $overrides_file`;
+    $overrides_file = "$MASTER_DIR/$MODULE-overrides.txt";
 }
+if (! -e $overrides_file) {
+    open EMPTY, ">$overrides_file";
+    close EMPTY;
+}
 
 
 
Index: gtkdoc-scangobj.in
===================================================================
--- gtkdoc-scangobj.in	(revision 452)
+++ gtkdoc-scangobj.in	(working copy)
@@ -38,6 +38,7 @@
 # name of documentation module
 my $MODULE;
 my $OUTPUT_DIR;
+my $MASTER_DIR;
 my $PRINT_VERSION;
 my $PRINT_HELP;
 my $TYPE_INIT_FUNC="g_type_init ()";
@@ -50,10 +51,13 @@
 	   'type-init-func' => \$TYPE_INIT_FUNC,
 	   'query-child-properties' => \$QUERY_CHILD_PROPERTIES,
 	   'output-dir' => \$OUTPUT_DIR,
+	   'master-dir' => \$MASTER_DIR,
 	   'version' => \$PRINT_VERSION,
 	   'help' => \$PRINT_HELP);
 	   
-GetOptions(\%optctl, "module=s", "types:s", "output-dir:s", "nogtkinit", "type-init-func:s", "query-child-properties:s", "version", "help");
+GetOptions(\%optctl, "module=s", "types:s", "output-dir=s", "nogtkinit",
+		     "type-init-func:s", "query-child-properties:s",
+		     "master-dir=s", "version", "help");
 
 if ($NO_GTK_INIT) {
   # Do nothing. This just avoids a warning.
@@ -76,6 +80,7 @@
     print "\n--query-child-properties=FUNC A function that returns a list of child";
     print "\n                      properties for a class";
     print "\n--output-dir=DIRNAME  The directory where the results are stored";
+    print "\n--master-dir=DIRNAME  Directory with non-generated files (for VPATH builds)";
     print "\n--version             Print the version of this program";
     print "\n--help                Print this help\n";
     exit 0;
@@ -83,10 +88,15 @@
 
 $OUTPUT_DIR = $OUTPUT_DIR ? $OUTPUT_DIR : ".";
 
-$TYPES_FILE = $TYPES_FILE ? $TYPES_FILE : "$OUTPUT_DIR/$MODULE.types";
+if (!$TYPES_FILE) {
+    $TYPES_FILE = "$OUTPUT_DIR/$MODULE.types";
+    if (! -e $TYPES_FILE) {
+	$TYPES_FILE = "$MASTER_DIR/$MODULE.types";
+    }
+}
 
 open (TYPES, $TYPES_FILE) || die "Cannot open $TYPES_FILE: $!\n";
-open (OUTPUT, ">$MODULE-scan.c") || die "Cannot open $MODULE-scan.c: $!\n";
+open (OUTPUT, ">$MODULE-scan.c") || die "Cannot create $MODULE-scan.c: $!\n";
 
 my $old_signals_filename = "$OUTPUT_DIR/$MODULE.signals";
 my $new_signals_filename = "$OUTPUT_DIR/$MODULE.signals.new";
Index: gtkdoc-mktmpl.in
===================================================================
--- gtkdoc-mktmpl.in	(revision 452)
+++ gtkdoc-mktmpl.in	(working copy)
@@ -62,6 +62,7 @@
 # name of documentation module
 my $MODULE;
 my $TMPL_DIR;
+my $MASTER_DIR;
 my $FLAG_CHANGES;
 my $PRINT_VERSION;
 my $PRINT_HELP;
@@ -70,10 +71,12 @@
 my %optctl = (module => \$MODULE,
 	      'flag-changes' => \$FLAG_CHANGES,
 	      'output-dir' => \$TMPL_DIR,
+	      'master-dir' => \$MASTER_DIR,
 	      'only-section-tmpl' => \$ONLY_SECTION_TMPL,
 	      'version' => \$PRINT_VERSION,
 	      'help' => \$PRINT_HELP);
-GetOptions(\%optctl, "module=s", "flag-changes!", "output-dir:s", "only-section-tmpl!", "version", "help");
+GetOptions(\%optctl, "module=s", "flag-changes!", "output-dir=s",
+                     "only-section-tmpl!", "version", "help", "master-dir=s");
 
 if ($PRINT_VERSION) {
     print "@VERSION@\n";
@@ -89,6 +92,7 @@
     print "\n--module=MODULE_NAME Name of the doc module being parsed";
     print "\n--flag-changes       If specified, changes in templates are flagged";
     print "\n--output-dir=DIRNAME The directory where the results are stored";
+    print "\n--master-dir=DIRNAME Directory with non-generated files (for VPATH builds)";
     print "\n--only-section-tmpl  Only include section information in templates";
     print "\n--version            Print the version of this program";
     print "\n--help               Print this help\n";
@@ -109,6 +113,21 @@
 # The file containing Arg information.
 my $ARGS_FILE = "$ROOT_DIR/$MODULE.args";
 
+# The section organization file.
+# If it's manually written, it's in MASTER_DIR.
+my $SECTION_FILE = "$ROOT_DIR/$MODULE-sections.txt";
+if (! -e $SECTION_FILE and $MASTER_DIR) {
+    $SECTION_FILE = "$MASTER_DIR/$MODULE-sections.txt";
+}
+
+# The overrides file.
+# Typically it's manually written but to be on the safe side, look into
+# builddir first.
+my $OVERRIDES_FILE = "$ROOT_DIR/$MODULE-overrides.txt";
+if (! -e $OVERRIDES_FILE and $MASTER_DIR) {
+    $OVERRIDES_FILE = "$MASTER_DIR/$MODULE-overrides.txt";
+}
+
 # Set the flag to indicate changes, if requested.
 my $CHANGES_FLAG = $FLAG_CHANGES ? "FIXME" : "";
 
@@ -147,14 +166,14 @@
 &ReadObjectHierarchy;
 
 &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-decl.txt", 0);
-if (-f "$ROOT_DIR/$MODULE-overrides.txt") {
-    &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-overrides.txt", 1);
+if (-f $OVERRIDES_FILE) {
+    &ReadDeclarationsFile ($OVERRIDES_FILE, 1);
 }
 &ReadExistingTemplates;
 
 my $changed = 0;
 
-if (&UpdateTemplates ("$ROOT_DIR/$MODULE-sections.txt")) {
+if (&UpdateTemplates ($SECTION_FILE)) {
   $changed = 1;
 }
 &OutputUnusedTemplates;
