gtk-doc r597 - in trunk: . help/manual/C tests/bugs/docs tests/gobject/docs tests/gobject/docs-tmpl tests/gobject/src
- From: stefkost svn gnome org
- To: svn-commits-list gnome org
- Subject: gtk-doc r597 - in trunk: . help/manual/C tests/bugs/docs tests/gobject/docs tests/gobject/docs-tmpl tests/gobject/src
- Date: Thu, 4 Sep 2008 15:26:15 +0000 (UTC)
Author: stefkost
Date: Thu Sep 4 15:26:15 2008
New Revision: 597
URL: http://svn.gnome.org/viewvc/gtk-doc?rev=597&view=rev
Log:
* gtkdoc-mkhtml.in:
Fix comparision.
* TODO:
ideas.
* configure.in:
* gtk-doc-fo.xsl:
* gtk-doc.xsl:
* gtkdoc-common.pl.in:
* gtkdoc-mkdb.in:
* help/manual/C/gtk-doc-manual.xml:
* tests/bugs/docs/Makefile.am:
* tests/bugs/docs/tester-docs.xml:
* tests/gobject/docs-tmpl/Makefile.am:
* tests/gobject/docs-tmpl/tester-docs.xml:
* tests/gobject/docs/Makefile.am:
* tests/gobject/docs/tester-docs.xml:
* tests/gobject/src/gobject.h:
Switch to docbook 4.3 dtd. Fixes #487727.
Add --name-space option to gtkdoc-mkdb for nicer indexes. Start with a
fo wrapper for pdf output.
Added:
trunk/gtk-doc-fo.xsl
Modified:
trunk/ChangeLog
trunk/TODO
trunk/configure.in
trunk/gtk-doc.xsl
trunk/gtkdoc-common.pl.in
trunk/gtkdoc-mkdb.in
trunk/gtkdoc-mkhtml.in
trunk/help/manual/C/gtk-doc-manual.xml
trunk/tests/bugs/docs/Makefile.am
trunk/tests/bugs/docs/tester-docs.xml
trunk/tests/gobject/docs-tmpl/Makefile.am
trunk/tests/gobject/docs-tmpl/tester-docs.xml
trunk/tests/gobject/docs/Makefile.am
trunk/tests/gobject/docs/tester-docs.xml
trunk/tests/gobject/src/gobject.h
Modified: trunk/TODO
==============================================================================
--- trunk/TODO (original)
+++ trunk/TODO Thu Sep 4 15:26:15 2008
@@ -43,6 +43,7 @@
http://www.gnu.org/software/libtool/manual/automake/DESTDIR.html
= Output =
+* http://sagehill.net/docbookxsl/index.html
* multipage-html
* would be good to be able to have page titles as a concatenation of document
name and page name (gtk+:GtkWIdget)
@@ -50,11 +51,67 @@
http://bugzilla.gnome.org/show_bug.cgi?id=531572
http://bugzilla.gnome.org/show_bug.cgi?id=466535
we need more configure options in gtk-doc.m4:
- --(enable|disable)-gtk-doc-(html|pdf|man|html-single)
+ --(enable|disable)-gtk-doc-(html|pdf|man|html-single|rtf)
- html : enabled by default
- html-single : is single page html
+* validation
+ xmllint --noout --xinclude --postvalid tester-docs.xml
+ xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd
+ - fo.dtd : http://www.renderx.com/Tests/validator/fo.zip
+* single page
+ xsltproc --nonet --xinclude -o gtk-docs.html /home/ensonic/projects/gtk-doc/gtk-doc-single.xsl gtk-docs.sgml
+* pdf
+ * xmlto via passivetex
+ xmlto --skip-validation pdf tester-docs.xml
+ * fop
+ ~/download/fop-0.95beta/fop -xsl /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl -xml tester-docs.xml -pdf tester-docs.pdf
+ ~/download/fop-0.94/fop -xsl /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl -xml tester-docs.xml -pdf tester-docs.pdf
+ * xsltproc + fop
+ xsltproc --nonet --xinclude -o tester-docs.fo ../../../gtk-doc-fo.xsl tester-docs.xml
+ ~/download/fop-0.94/fop -fo tester-docs.fo -pdf tester-docs.pdf
+ * xsltproc + passivetex
+ pdflatex "&pdfxmltex" tester-docs.fo
+ xmltex tester-docs.fo
+
+ * bugs/problems/howto
+ * xmlto via passivetex
+ http://bugs.gentoo.org/show_bug.cgi?id=224937
+ http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=310148
+ - info
+ http://www.tug.org/texlive/devsrc/Master/texmf-dist/doc/xmltex/passivetex/
+ * fop
+ - download fop
+ http://mirror.eunet.fi/apache/xmlgraphics/fop/binaries/
+ http://xmlgraphics.apache.org/fop/0.94/running.html
+ export FOP_OPTS="-Dhttp.proxyHost=eswebproxy00.europe.nokia.com -Dhttp.proxyPort=8080"
+ - download offo
+ http://sourceforge.net/project/showfiles.php?group_id=116740&package_id=129569&release_id=267101
+ and copy fop-hyph.jar to fop-0.9*/lib/
+* rtf
+ ~/download/fop-0.94/fop -fo tester-docs.fo -rtf tester-docs.rtf
+ * unrtf
+ unrtf -t ps tester-docs.rtf >tester-docs.ps
+ unrtf -t latex tester-docs.rtf >tester-docs.tex
+ - bad output
+
+= Indexes =
+* http://www.w3.org/TR/2003/WD-xinclude-20031110/#syntax
+<xi:include href="index-symbols.html">
+ <xi:fallback><index /></xi:fallback>
+</xi:include>
+* index terms
+ http://sourceforge.net/tracker/index.php?func=detail&aid=1986587&group_id=21935&atid=373747
+
+* we could add smart navigation for index/glossary pages
+ (like the subsections on the doc-pages)
= Cleanup =
* can we deprecate title in the sectionfile and request people to have this in
the SECTION comment?
+= Warnings =
+* add some -Wxxx parameters to help qa work
+ - 'deprecated' deprecating 'features'
+ - 'dummy-docs' check if symbol docs are very short and repeat mainly words
+ from the symbol.
+
Modified: trunk/configure.in
==============================================================================
--- trunk/configure.in (original)
+++ trunk/configure.in Thu Sep 4 15:26:15 2008
@@ -75,8 +75,8 @@
fi
dnl check for DocBook DTD and stylesheets in the local catalog.
-JH_CHECK_XML_CATALOG([-//OASIS//DTD DocBook XML V4.1.2//EN],
- [DocBook XML DTD V4.1.2])
+JH_CHECK_XML_CATALOG([-//OASIS//DTD DocBook XML V4.3//EN],
+ [DocBook XML DTD V4.3])
JH_CHECK_XML_CATALOG([http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl],
[DocBook XSL Stylesheets])
Added: trunk/gtk-doc-fo.xsl
==============================================================================
--- (empty file)
+++ trunk/gtk-doc-fo.xsl Thu Sep 4 15:26:15 2008
@@ -0,0 +1,35 @@
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
+ xmlns:fo="http://www.w3.org/1999/XSL/Format";
+ version="1.0">
+
+ <!-- import the chunked fo stylesheet -->
+ <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
+
+ <!-- change some parameters -->
+ <xsl:attribute-set name="monospace.verbatim.properties">
+ <!--xsl:attribute name="font-family">Monospace</xsl:attribute-->
+ <xsl:attribute name="font-size">7pt</xsl:attribute>
+ <xsl:attribute name="keep-together.within-column">always</xsl:attribute>
+ </xsl:attribute-set>
+
+ <xsl:param name="shade.verbatim" select="1"/>
+
+ <xsl:attribute-set name="shade.verbatim.style">
+ <xsl:attribute name="background-color">#D0D0D0</xsl:attribute>
+ <xsl:attribute name="border-width">0.5pt</xsl:attribute>
+ <xsl:attribute name="border-style">solid</xsl:attribute>
+ <xsl:attribute name="border-color">#575757</xsl:attribute>
+ <xsl:attribute name="padding">3pt</xsl:attribute>
+ </xsl:attribute-set>
+
+ <xsl:attribute-set name="xref.properties">
+ <xsl:attribute name="color">
+ <xsl:choose>
+ <xsl:when test="self::ulink">blue</xsl:when>
+ <xsl:otherwise>inherit</xsl:otherwise>
+ </xsl:choose>
+ </xsl:attribute>
+ </xsl:attribute-set>
+
+</xsl:stylesheet>
+
Modified: trunk/gtk-doc.xsl
==============================================================================
--- trunk/gtk-doc.xsl (original)
+++ trunk/gtk-doc.xsl Thu Sep 4 15:26:15 2008
@@ -17,11 +17,12 @@
reference toc
</xsl:param>
- <xsl:param name="default.encoding" select="'UTF-8'"/>
<xsl:param name="chunker.output.encoding" select="'UTF-8'"/>
<xsl:param name="chunker.output.indent" select="'yes'"/>
<xsl:param name="chunker.output.doctype-public" select="'-//W3C//DTD HTML 4.01 Transitional//EN'"/>
<xsl:param name="chunk.fast" select="1"/>
+
+ <xsl:param name="default.encoding" select="'UTF-8'"/>
<xsl:param name="chapter.autolabel" select="0"/>
<xsl:param name="use.id.as.filename" select="1"/>
<xsl:param name="html.ext" select="'.html'"/>
Modified: trunk/gtkdoc-common.pl.in
==============================================================================
--- trunk/gtkdoc-common.pl.in (original)
+++ trunk/gtkdoc-common.pl.in Thu Sep 4 15:26:15 2008
@@ -175,7 +175,7 @@
if ($output_function_params) {
push @result, "$mod1$ptype$ptr1$mod2$ptr2$mod3 (*$pname) ($func_params)";
} else {
- push @result, "$pname ()";
+ push @result, "$pname ()";
}
@@ -196,8 +196,8 @@
#print "'$mod1' '$type' '$mod2' '$list' \n";
- $mod1 =~ s/ / /g;
- $mod2 =~ s/ / /g;
+ $mod1 =~ s/ / /g;
+ $mod2 =~ s/ / /g;
my @names = split /,/, $list;
for my $n (@names) {
@@ -212,14 +212,14 @@
my $bits = defined($4) ? " $4" : "";
if ($ptrs && $ptrs !~ m/\*$/) { $ptrs .= " "; }
- $array =~ s/ / /g;
- $bits =~ s/ / /g;
+ $array =~ s/ / /g;
+ $bits =~ s/ / /g;
push @result, $name;
if (defined $namefunc) {
$name = $namefunc->($name);
}
- push @result, "$mod1$ptype$mod2 $ptrs$name$array$bits;";
+ push @result, "$mod1$ptype$mod2 $ptrs$name$array$bits;";
#print "***** Matched line: $mod1$ptype$mod2 $ptrs$name$array$bits\n";
} else {
Modified: trunk/gtkdoc-mkdb.in
==============================================================================
--- trunk/gtkdoc-mkdb.in (original)
+++ trunk/gtkdoc-mkdb.in Thu Sep 4 15:26:15 2008
@@ -3,6 +3,7 @@
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 1998 Damon Chaplin
+# 2007,2008 Stefan Kost
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@@ -53,6 +54,7 @@
my $DEFAULT_STABILITY;
my $DEFAULT_INCLUDES;
my $OUTPUT_FORMAT;
+my $NAME_SPACE = "";
my %optctl = ('module' => \$MODULE,
'source-dir' => \ SOURCE_DIRS,
@@ -68,8 +70,13 @@
'sgml-mode' => \$SGML_MODE,
'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");
+ 'output-format' => \$OUTPUT_FORMAT,
+ 'name-space' => \$NAME_SPACE);
+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",
+ "name-space:s");
if ($PRINT_VERSION) {
print "@VERSION \n";
@@ -103,6 +110,7 @@
--default-stability=LEVEL Specify default stability Level. Valid values are
Stable, Unstable, or Private.
--default-includes=FILENAMES Specify default includes for section Synopsis
+--name-space=NS Omit namespace in index.
--version Print the version of this program
--help Print this help
EOF
@@ -139,8 +147,8 @@
} else {
$doctype_header =
"<?xml version=\"1.0\"?>\n" .
-"<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\"\n" .
-" \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\";>\n";
+"<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"\n" .
+" \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\";>\n";
}
$doctype_header =~ s/<!DOCTYPE \w+/<!DOCTYPE refentry/;
} else {
@@ -224,7 +232,7 @@
# Undeclared yet documented symbols
my %UndeclaredSymbols;
-# These global arrays store GtkObject and subclasses and the hierarchy.
+# These global arrays store GObject, subclasses and the hierarchy.
my @Objects;
my @ObjectLevels;
@@ -234,6 +242,11 @@
# holds the symbols which are mentioned in $MODULE-sections.txt
my %KnownSymbols;
+# collects index entries
+my %IndexEntriesFull;
+my %IndexEntriesSince;
+my %IndexEntriesDeprecated;
+
# Standard C preprocessor directives, which we ignore for '#' abbreviations.
my %PreProcessorDirectives;
$PreProcessorDirectives{"assert"} = 1;
@@ -284,6 +297,11 @@
# If any of the DocBook SGML files have changed, update the timestamp file (so
# it can be used for Makefile dependencies).
if ($changed || ! -e "$ROOT_DIR/sgml.stamp") {
+
+ &OutputIndexFull;
+ &OutputDeprecatedIndex;
+ &OutputSinceIndexes;
+
open (TIMESTAMP, ">$ROOT_DIR/sgml.stamp")
|| die "Can't create $ROOT_DIR/sgml.stamp: $!";
print (TIMESTAMP "timestamp");
@@ -300,11 +318,22 @@
sub OutputObjectList {
my $cols = 3;
+
+ # FIXME: use $OUTPUT_FORMAT
+ # my $old_object_index = "$SGML_OUTPUT_DIR/object_index.$OUTPUT_FORMAT";
my $old_object_index = "$SGML_OUTPUT_DIR/object_index.sgml";
my $new_object_index = "$SGML_OUTPUT_DIR/object_index.new";
open (OUTPUT, ">$new_object_index")
|| die "Can't create $new_object_index: $!";
+
+ if (lc($OUTPUT_FORMAT) eq "xml") {
+ my $header = $doctype_header;
+
+ $header =~ s/<!DOCTYPE \w+/<!DOCTYPE informaltable/;
+ print (OUTPUT "$header");
+ }
+
print (OUTPUT <<EOF);
<informaltable pgwide="1" frame="none">
<tgroup cols="$cols">
@@ -316,7 +345,7 @@
my $count = 0;
my $object;
- foreach $object (sort(@Objects)) {
+ foreach $object (sort (@Objects)) {
my $xref = &MakeXRef ($object);
if ($count % $cols == 0) { print (OUTPUT "<row>\n"); }
print (OUTPUT "<entry>$xref</entry>\n");
@@ -327,6 +356,9 @@
# emit an empty row, since empty tables are invalid
print (OUTPUT "<row><entry> </entry></row>\n");
}
+ else {
+ print (OUTPUT "</row>\n");
+ }
print (OUTPUT <<EOF);
</tbody></tgroup></informaltable>
@@ -460,6 +492,7 @@
}
if ($num_symbols > 0) {
+ # collect documents
if (lc($OUTPUT_FORMAT) eq "xml") {
$book_bottom .= " <xi:include href=\"xml/$filename.xml\"/>\n";
} else {
@@ -489,6 +522,7 @@
EOF
$signals_desc =~ s/^\n*//g;
$signals_desc =~ s/\n+$/\n/g;
+ $signals_desc =~ s/(\s|\n)+$//ms;
$signals_desc = <<EOF;
<refsect1 id="$section_id.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
@@ -509,6 +543,7 @@
EOF
$args_desc =~ s/^\n*//g;
$args_desc =~ s/\n+$/\n/g;
+ $args_desc =~ s/(\s|\n)+$//ms;
$args_desc = <<EOF;
<refsect1 id="$section_id.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
@@ -527,8 +562,9 @@
${child_args_synop}</synopsis>
</refsect1>
EOF
- $args_desc =~ s/^\n*//g;
- $args_desc =~ s/\n+$/\n/g;
+ $child_args_desc =~ s/^\n*//g;
+ $child_args_desc =~ s/\n+$/\n/g;
+ $child_args_desc =~ s/(\s|\n)+$//ms;
$args_desc .= <<EOF;
<refsect1 id="$section_id.child-property-details" role="child_property_details">
<title role="child_property_details.title">Child Property Details</title>
@@ -547,8 +583,9 @@
${style_args_synop}</synopsis>
</refsect1>
EOF
- $args_desc =~ s/^\n*//g;
- $args_desc =~ s/\n+$/\n/g;
+ $style_args_desc =~ s/^\n*//g;
+ $style_args_desc =~ s/\n+$/\n/g;
+ $style_args_desc =~ s/(\s|\n)+$//ms;
$args_desc .= <<EOF;
<refsect1 id="$section_id.style-property-details" role="style_properties_details">
<title role="style_properties_details.title">Style Property Details</title>
@@ -559,6 +596,7 @@
$hierarchy =~ s/^\n*//g;
$hierarchy =~ s/\n+$/\n/g;
+ $hierarchy =~ s/(\s|\n)+$//ms;
if ($hierarchy ne "") {
$hierarchy = <<EOF;
<refsect1 id="$section_id.object-hierarchy" role="object_hierarchy">
@@ -570,6 +608,7 @@
$interfaces =~ s/^\n*//g;
$interfaces =~ s/\n+$/\n/g;
+ $interfaces =~ s/(\s|\n)+$//ms;
if ($interfaces ne "") {
$interfaces = <<EOF;
<refsect1 id="$section_id.implemented-interfaces" role="impl_interfaces">
@@ -581,6 +620,7 @@
$implementations =~ s/^\n*//g;
$implementations =~ s/\n+$/\n/g;
+ $implementations =~ s/(\s|\n)+$//ms;
if ($implementations ne "") {
$implementations = <<EOF;
<refsect1 id="$section_id.implementations" role="implementations">
@@ -592,6 +632,7 @@
$prerequisites =~ s/^\n*//g;
$prerequisites =~ s/\n+$/\n/g;
+ $prerequisites =~ s/(\s|\n)+$//ms;
if ($prerequisites ne "") {
$prerequisites = <<EOF;
<refsect1 id="$section_id.prerequisites" role="prerequisites">
@@ -603,6 +644,7 @@
$derived =~ s/^\n*//g;
$derived =~ s/\n+$/\n/g;
+ $derived =~ s/(\s|\n)+$//ms;
if ($derived ne "") {
$derived = <<EOF;
<refsect1 id="$section_id.derived-interfaces" role="derived_interfaces">
@@ -722,6 +764,113 @@
return $changed;
}
+#############################################################################
+# Function : OutputIndex
+# Description : This writes an indexlist that can be included into the main-
+# document into an <index> tag.
+#############################################################################
+
+sub OutputIndex {
+ my ($basename, $apiindexref ) = @_;
+ my %apiindex = %{$apiindexref};
+ my $old_index = "$SGML_OUTPUT_DIR/$basename.xml";
+ my $new_index = "$SGML_OUTPUT_DIR/$basename.new";
+ my $lastletter = " ";
+ my $divopen = 0;
+ my $symbol;
+ my $short_symbol;
+
+ open (OUTPUT, ">$new_index")
+ || die "Can't create $new_index";
+
+ my $header = $doctype_header;
+ $header =~ s/<!DOCTYPE \w+/<!DOCTYPE indexdiv/;
+
+ print (OUTPUT "$header<indexdiv>\n");
+
+ #print "generate $basename index (".%apiindex." entries)\n";
+
+ # do a case insensitive sort while chopping off the prefix
+ foreach my $hash (
+ sort { $$a{kriterium} cmp $$b{kriterium} }
+ map { my $x = uc($_); $x =~ s/^$NAME_SPACE\_?(.*)/$1/i; { kriterium => $x, original => $_, short => $1 } }
+ keys %apiindex) {
+
+ $symbol = $$hash{original};
+ $short_symbol = $$hash{short};
+
+ my $xref = &MakeXRef ($symbol);
+ my $curletter = uc(substr($short_symbol,0,1));
+ my $id = $apiindex{$symbol};
+
+ #print " add symbol $symbol with $id to index\n";
+
+ if ($curletter ne $lastletter) {
+ $lastletter = $curletter;
+
+ if ($divopen == 1) {
+ print (OUTPUT "</indexdiv>\n");
+ }
+ print (OUTPUT "<indexdiv><title>$curletter</title>\n");
+ $divopen = 1;
+ }
+
+ print (OUTPUT <<EOF);
+<indexentry><primaryie linkends="$id">$xref</primaryie></indexentry>
+EOF
+ }
+
+ if ($divopen == 1) {
+ print (OUTPUT "</indexdiv>\n");
+ }
+ print (OUTPUT "</indexdiv>\n");
+ close (OUTPUT);
+
+ &UpdateFileIfChanged ($old_index, $new_index, 0);
+}
+
+
+#############################################################################
+# Function : OutputIndexFull
+# Description : This writes the full api indexlist that can be included into the
+# main document into an <index> tag.
+#############################################################################
+
+sub OutputIndexFull {
+ &OutputIndex ("api-index-full", \%IndexEntriesFull);
+}
+
+
+#############################################################################
+# Function : OutputDeprecatedIndex
+# Description : This writes the deprecated api indexlist that can be included
+# into the main document into an <index> tag.
+#############################################################################
+
+sub OutputDeprecatedIndex {
+ &OutputIndex ("api-index-deprecated", \%IndexEntriesDeprecated);
+}
+
+
+#############################################################################
+# Function : OutputSinceIndexes
+# Description : This writes the 'since' api indexlists that can be included into
+# the main document into an <index> tag.
+#############################################################################
+
+sub OutputSinceIndexes {
+ my @sinces = keys %{{ map { $_ => 1 } values %Since }};
+
+ foreach my $version (@sinces) {
+ #print "Since : [$version]\n";
+ # todo make filtered hash
+ #my %index = grep { $Since{$_} eq $version } %IndexEntriesSince;
+ my %index = map { $_ => $IndexEntriesSince{$_} } grep { $Since{$_} eq $version } keys %IndexEntriesSince;
+
+ &OutputIndex ("api-index-$version", \%index);
+ }
+}
+
#############################################################################
# Function : ReadKnownSymbols
@@ -1069,7 +1218,7 @@
# Create a table of fields and descriptions
- # FIXME: Inserting  's into the produced type declarations here would
+ # FIXME: Inserting  's into the produced type declarations here would
# improve the output in most situations ... except for function
# members of structs!
my @fields = ParseStructDeclaration($declaration, !$default_to_public,
@@ -1107,7 +1256,7 @@
if (defined $field_descr) {
$desc .= "<listitem><simpara>".&ExpandAbbreviations($symbol, $field_descr)."</simpara></listitem>\n";
} else {
- $desc .= "<listitem></listitem>\n";
+ $desc .= "<listitem><simpara /></listitem>\n";
}
$desc .= "</varlistentry>\n";
}
@@ -1501,13 +1650,13 @@
$param_name = "...";
}
$param = &ExpandAbbreviations($symbol, $param);
- $params_desc .= "<varlistentry><term><parameter>$param_name</parameter> :</term>\n<listitem><simpara>$param</simpara></listitem></varlistentry>\n";
+ $params_desc .= "<varlistentry><term><parameter>$param_name</parameter> :</term>\n<listitem><simpara>$param</simpara></listitem></varlistentry>\n";
}
}
# Signals have an implicit user_data parameter which we describe.
if ($symbol_type eq "SIGNAL") {
- $params_desc .= "<varlistentry><term><parameter>user_data</parameter> :</term>\n<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>\n";
+ $params_desc .= "<varlistentry><term><parameter>user_data</parameter> :</term>\n<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>\n";
}
# Start a table if we need one.
@@ -1523,7 +1672,7 @@
# Output the returns info last.
if ($returns) {
- $output .= "<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>$returns</simpara></listitem></varlistentry>\n";
+ $output .= "<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>$returns</simpara></listitem></varlistentry>\n";
}
# Finish the table.
@@ -1690,7 +1839,6 @@
<refnamediv>
<refname>$title</refname>
<refpurpose>$short_desc</refpurpose>
-<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>
$stability
<refsynopsisdiv id="$section_id.synopsis" role="synopsis">
@@ -1806,9 +1954,12 @@
if (lc($OUTPUT_FORMAT) eq "xml") {
print OUTPUT <<EOF;
<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index">
EOF
} else {
print OUTPUT <<EOF;
@@ -1868,6 +2019,7 @@
$id =~ s/[,\.]//g;
$id =~ s/^-*//;
$id =~ s/::/-/g;
+ $id =~ s/:/--/g;
return $id;
}
@@ -2189,20 +2341,33 @@
sub MakeIndexterms {
my ($symbol, $id) = @_;
my $terms = "";
+ my $sortas = "";
+
+ # make the index useful, by ommiting the namespace when sorting
+ if (defined($NAME_SPACE)) {
+ if ($symbol =~ m/^$NAME_SPACE\_?(.*)/i) {
+ $sortas=" sortas=\"$1\"";
+ }
+ }
if (exists $Deprecated{$symbol}) {
- $terms .= "<indexterm zone=\"$id\" role=\"deprecated\"><primary>$symbol</primary></indexterm>"
+ $terms .= "<indexterm zone=\"$id\" role=\"deprecated\"><primary$sortas>$symbol</primary></indexterm>";
+ $IndexEntriesDeprecated{$symbol}=$id;
+ $IndexEntriesFull{$symbol}=$id;
}
if (exists $Since{$symbol}) {
my $since = $Since{$symbol};
$since =~ s/^\s+//;
$since =~ s/\s+$//;
if ($since ne "") {
- $terms .= "<indexterm zone=\"$id\" role=\"$since\"><primary>$symbol</primary></indexterm>";
+ $terms .= "<indexterm zone=\"$id\" role=\"$since\"><primary$sortas>$symbol</primary></indexterm>";
}
+ $IndexEntriesSince{$symbol}=$id;
+ $IndexEntriesFull{$symbol}=$id;
}
if ($terms eq "") {
- $terms .= "<indexterm zone=\"$id\"><primary>$symbol</primary></indexterm>";
+ $terms .= "<indexterm zone=\"$id\"><primary$sortas>$symbol</primary></indexterm>";
+ $IndexEntriesFull{$symbol}=$id;
}
return $terms;
@@ -3017,7 +3182,14 @@
}
if ($since_desc) {
- $Since{$symbol} = &ConvertSGMLChars ($symbol, $since_desc);
+ ($since_desc, my @extra_lines) = split ("\n", $since_desc);
+ $since_desc =~ s/^\s+//;
+ $since_desc =~ s/\s+$//;
+ #print "Since($symbol) : [$since_desc]\n";
+ $Since{$symbol} = &ConvertSGMLChars ($symbol, $since_desc);
+ if(scalar @extra_lines) {
+ &LogWarning ($file, $., "multi-line since docs found");
+ }
}
if ($stability_desc) {
@@ -4008,13 +4180,18 @@
if ($param_name =~ m/^[Rr]eturns?$/) {
$param_name = "Returns";
}
- #print "Found param for symbol $current_symbol : '$param_name'= '$_'\n";
+
+ # strip trailing whitespaces and blank lines
+ s/\s+\n$/\n/m;
+ s/\n+$/\n/sm;
+ #print "Found param for symbol $current_symbol : '$param_name'= '$_'";
if ($param_name eq "Deprecated") {
$in_deprecated = 1;
$Deprecated{$current_symbol} = $_;
} elsif ($param_name eq "Since") {
$in_since = 1;
+ chomp;
$Since{$current_symbol} = $_;
} elsif ($param_name eq "Stability") {
$in_stability = 1;
@@ -4025,17 +4202,24 @@
$current_param += 2;
}
} else {
- if ($in_deprecated) {
- $Deprecated{$current_symbol} .= $_;
- } elsif ($in_since) {
- $Since{$current_symbol} .= $_;
- } elsif ($in_stability) {
- $StabilityLevel{$current_symbol} .= $_;
- } elsif ($current_param >= 0) {
- $params[$current_param] .= $_;
- } else {
- $symbol_doc .= $_;
- }
+ # strip trailing whitespaces and blank lines
+ s/\s+\n$/\n/m;
+ s/\n+$/\n/sm;
+
+ if (!m/^\s+$/) {
+ if ($in_deprecated) {
+ $Deprecated{$current_symbol} .= $_;
+ } elsif ($in_since) {
+ &LogWarning ($template, $., "multi-line since docs found");
+ #$Since{$current_symbol} .= $_;
+ } elsif ($in_stability) {
+ $StabilityLevel{$current_symbol} .= $_;
+ } elsif ($current_param >= 0) {
+ $params[$current_param] .= $_;
+ } else {
+ $symbol_doc .= $_;
+ }
+ }
}
}
}
@@ -4094,14 +4278,21 @@
return;
}
+ # FIXME: use $OUTPUT_FORMAT
+ # my $old_tree_index = "$SGML_OUTPUT_DIR/tree_index.$OUTPUT_FORMAT";
my $old_tree_index = "$SGML_OUTPUT_DIR/tree_index.sgml";
my $new_tree_index = "$SGML_OUTPUT_DIR/tree_index.new";
- my $tree_header = $doctype_header;
- $tree_header =~ s/<!DOCTYPE \w+/<!DOCTYPE screen/;
open (OUTPUT, ">$new_tree_index")
|| die "Can't create $new_tree_index: $!";
- print (OUTPUT "$tree_header<screen>\n");
+
+ if (lc($OUTPUT_FORMAT) eq "xml") {
+ my $tree_header = $doctype_header;
+
+ $tree_header =~ s/<!DOCTYPE \w+/<!DOCTYPE screen/;
+ print (OUTPUT "$tree_header");
+ }
+ print (OUTPUT "<screen>\n");
# Only emit objects if they are supposed to be documented, or if
# they have documented children. To implement this, we maintain a
Modified: trunk/gtkdoc-mkhtml.in
==============================================================================
--- trunk/gtkdoc-mkhtml.in (original)
+++ trunk/gtkdoc-mkhtml.in Thu Sep 4 15:26:15 2008
@@ -49,7 +49,7 @@
path_option='--directory'
fi
-if test "X$searchpath" == "X"; then
+if test "X$searchpath" = "X"; then
path_arg=
else
path_arg="$path_option $searchpath"
Modified: trunk/help/manual/C/gtk-doc-manual.xml
==============================================================================
--- trunk/help/manual/C/gtk-doc-manual.xml (original)
+++ trunk/help/manual/C/gtk-doc-manual.xml Thu Sep 4 15:26:15 2008
@@ -1340,15 +1340,20 @@
<seg>FIXME (section file, proper doc comment)</seg>
</seglistitem>
- <!-- warnings: -->
+ <!-- gtk-doc warnings: -->
<seglistitem>
<seg>Parameter described in source code comment block but does not exist</seg>
<seg>Check if the prototype in the header has different parameter names as in the source.</seg>
</seglistitem>
+ <!-- docbook warnings: -->
<seglistitem>
<seg>multiple "IDs" for constraint linkend: XYZ</seg>
<seg>Symbol XYZ appears twice in -section.txt file.</seg>
</seglistitem>
+ <seglistitem>
+ <seg>Element typename in namespace '' encountered in para, but no template matches.</seg>
+ <seg />
+ </seglistitem>
</segmentedlist>
</chapter>
Modified: trunk/tests/bugs/docs/Makefile.am
==============================================================================
--- trunk/tests/bugs/docs/Makefile.am (original)
+++ trunk/tests/bugs/docs/Makefile.am Thu Sep 4 15:26:15 2008
@@ -23,7 +23,7 @@
2>&1 | tee gtkdoc-scan.log
# Extra options to supply to gtkdoc-mkdb.
-MKDB_OPTIONS=--sgml-mode --output-format=xml 2>&1 | tee gtkdoc-mkdb.log
+MKDB_OPTIONS=--sgml-mode --name-space=bug 2>&1 | tee gtkdoc-mkdb.log
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
Modified: trunk/tests/bugs/docs/tester-docs.xml
==============================================================================
--- trunk/tests/bugs/docs/tester-docs.xml (original)
+++ trunk/tests/bugs/docs/tester-docs.xml Thu Sep 4 15:26:15 2008
@@ -1,6 +1,9 @@
<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
<bookinfo>
<title>tester Reference Manual</title>
Modified: trunk/tests/gobject/docs-tmpl/Makefile.am
==============================================================================
--- trunk/tests/gobject/docs-tmpl/Makefile.am (original)
+++ trunk/tests/gobject/docs-tmpl/Makefile.am Thu Sep 4 15:26:15 2008
@@ -21,7 +21,7 @@
SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" 2>&1 | tee gtkdoc-scan.log
# Extra options to supply to gtkdoc-mkdb.
-MKDB_OPTIONS=--sgml-mode --output-format=xml 2>&1 | tee gtkdoc-mkdb.log
+MKDB_OPTIONS=--sgml-mode --name-space=gtkdoc 2>&1 | tee gtkdoc-mkdb.log
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
Modified: trunk/tests/gobject/docs-tmpl/tester-docs.xml
==============================================================================
--- trunk/tests/gobject/docs-tmpl/tester-docs.xml (original)
+++ trunk/tests/gobject/docs-tmpl/tester-docs.xml Thu Sep 4 15:26:15 2008
@@ -1,6 +1,9 @@
<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
<bookinfo>
<title>tester Reference Manual</title>
Modified: trunk/tests/gobject/docs/Makefile.am
==============================================================================
--- trunk/tests/gobject/docs/Makefile.am (original)
+++ trunk/tests/gobject/docs/Makefile.am Thu Sep 4 15:26:15 2008
@@ -21,7 +21,7 @@
SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" 2>&1 | tee gtkdoc-scan.log
# Extra options to supply to gtkdoc-mkdb.
-MKDB_OPTIONS=--sgml-mode --output-format=xml 2>&1 | tee gtkdoc-mkdb.log
+MKDB_OPTIONS=--sgml-mode --name-space=gtkdoc 2>&1 | tee gtkdoc-mkdb.log
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
Modified: trunk/tests/gobject/docs/tester-docs.xml
==============================================================================
--- trunk/tests/gobject/docs/tester-docs.xml (original)
+++ trunk/tests/gobject/docs/tester-docs.xml Thu Sep 4 15:26:15 2008
@@ -1,7 +1,11 @@
<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY GtkdocIFace SYSTEM "xml/iface.xml">
+]>
+<book id="index">
+<!--book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"-->
<bookinfo>
<title>tester Reference Manual</title>
<releaseinfo>
@@ -22,28 +26,31 @@
<chapter id="main-api">
<title>Tests</title>
<xi:include href="xml/object.xml"/>
- <xi:include href="xml/iface.xml"/>
+ <!--xi:include href="xml/iface.xml"/-->
+ &GtkdocIFace;
</chapter>
<chapter id="object-tree">
<title>Object Hierarchy</title>
- <xi:include href="xml/tree_index.sgml" />
+ <xi:include href="xml/tree_index.sgml"/>
</chapter>
- <!--chapter id="indices"-->
- <index id="api-index">
- <title>API Index</title>
- </index>
- <index id="deprecated-api-index" role="deprecated">
- <title>Index of deprecated API</title>
- </index>
- <index id="api-index-0-1" role="0.1">
- <title>Index of new API in 0.1</title>
- </index>
- <index id="api-index-0-5" role="0.5">
- <title>Index of new API in 0.5</title>
- </index>
- <!--/chapter-->
+ <index id="api-index-full">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-deprecated" role="deprecated">
+ <title>Index of deprecated API</title>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-0-1" role="0.1">
+ <title>Index of new API in 0.1</title>
+ <xi:include href="xml/api-index-0.1.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-0-5" role="0.5">
+ <title>Index of new API in 0.5</title>
+ <xi:include href="xml/api-index-0.5.xml"><xi:fallback /></xi:include>
+ </index>
<glossary>
<glossdiv id="glossary-X"><title>X</title>
Modified: trunk/tests/gobject/src/gobject.h
==============================================================================
--- trunk/tests/gobject/src/gobject.h (original)
+++ trunk/tests/gobject/src/gobject.h Thu Sep 4 15:26:15 2008
@@ -57,7 +57,9 @@
GType gtkdoc_object_get_type(void) G_GNUC_CONST;
GtkdocObject *gtkdoc_object_new(void);
+#ifndef GTKDOC_TESTER_DISABLE_DEPRECATED
void gtkdoc_object_set_otest (GObject *self, const gchar *value);
+#endif
void gtkdoc_object_frobnicate (GObject *self, gint n);
/**
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
