Commit 14f3d4ce authored by Christian Persch's avatar Christian Persch

Modernise API docs

Use no-tmpl, move to xml, use xinclude, add indices.
parent 9afcac62
......@@ -314,12 +314,12 @@ AM_CONDITIONAL(ENABLE_PIXBUF_LOADER, test x$enable_pixbuf_loader = xyes)
##################################################
# Checks for gtk-doc and docbook-tools
##################################################
gtk_doc_installed=true
#ifdef([GTK_DOC_CHECK],[GTK_DOC_CHECK([1.0])],[gtk_doc_installed=false])
# I would have liked to conditionalize this, but
# that appears to break other things http://bugzilla.gnome.org/show_bug.cgi?id=156399
GTK_DOC_CHECK([1.0])
AM_CONDITIONAL(GTK_DOC_INSTALLED, $gtk_doc_installed)
GTK_DOC_CHECK([1.13],[--flavour no-tmpl])
AC_SUBST([GLIB_PREFIX],[$($PKG_CONFIG --variable=prefix glib-2.0)])
AC_SUBST([GTK_PREFIX],[$($PKG_CONFIG --variable=prefix gdk-pixbuf-$GTK_API_VERSION)])
AC_SUBST([CAIRO_PREFIX],[$($PKG_CONFIG --variable=prefix cairo)])
dnl ===========================================================================
dnl Do we build the miscellaenous tools provided with librsvg ?
......@@ -371,6 +371,7 @@ tests/Makefile
tests/pdiff/Makefile
tools/Makefile
doc/Makefile
doc/version.xml
])
AC_CONFIG_FILES([librsvg-${RSVG_API_VERSION}.pc:librsvg.pc.in],[],[RSVG_API_VERSION=$RSVG_API_VERSION])
......
Makefile
Makefile.in
html
sgml
xml
rsvg-decl-list.txt
rsvg-decl.txt
rsvg-undocumented.txt
rsvg-unused.txt
rsvg.args
rsvg.hierarchy
rsvg.signals
*.stamp
## Process this file with automake to produce Makefile.in
# We require automake 1.10 for $(abs_builddir)
AUTOMAKE_OPTIONS = 1.10
# The name of the module.
DOC_MODULE=rsvg
# This is a blank Makefile.am for using gtk-doc.
# Copy this to your project's API docs directory and modify the variables to
# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
# of using the various options.
# The name of the module, e.g. 'glib'.
DOC_MODULE = rsvg
# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
DOC_MODULE_VERSION = $(RSVG_API_VERSION)
# The top-level SGML file.
DOC_MAIN_SGML_FILE=rsvg-docs.sgml
# The directory containing the source code. Relative to $(srcdir)
DOC_SOURCE_DIR=..
# Extra options to pass to gtkdoc-scangobj
SCANGOBJ_OPTIONS= --nogtkinit --type-init-func="g_type_init ()"
# Extra options to supply to gtkdoc-scan
SCAN_OPTIONS=--deprecated-guards=RSVG_DISABLE_DEPRECATED
# Extra options to supply to gtkdoc-mkdb
MKDB_OPTIONS= --sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=
# Used for dependencies
HFILE_GLOB=$(top_srcdir)/*.h
CFILE_GLOB=$(top_srcdir)/*.c
# Header files to ignore when scanning
IGNORE_HFILES= \
config.h \
librsvg-features.h \
rsvg-bpath-util.h \
rsvg-css.h \
rsvg-defs.h \
rsvg-paint-server.h \
rsvg-path.h \
rsvg-private.h \
rsvg-shapes.h \
rsvg-styles.h \
rsvg-text.h \
svg-rc-style.h \
svg-style.h \
svg.h
# Images to copy into HTML directory
HTML_IMAGES=
EXTRA_HFILES=
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
content_files=
# The top-level SGML file. You can change this if you want to.
DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml
# The directory containing the source code. Relative to $(srcdir).
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting the functions and macros.
# e.g. DOC_SOURCE_DIR=../../../gtk
DOC_SOURCE_DIR = ..
# Extra options to pass to gtkdoc-scangobj. Not normally needed.
SCANGOBJ_OPTIONS = --nogtkinit --type-init-func="g_type_init ()"
# Extra options to supply to gtkdoc-scan.
# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
SCAN_OPTIONS = --deprecated-guards="RSVG_DISABLE_DEPRECATED"
# Extra options to supply to gtkdoc-mkdb.
# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
MKDB_OPTIONS = --sgml-mode --output-format=xml --name-space=rsvg
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
MKTMPL_OPTIONS =
# Extra options to supply to gtkdoc-mkhtml
# Add the builddir to the HTML path so that version.xml is found
MKHTML_OPTIONS = --path="$(abs_builddir)"
# Extra options to supply to gtkdoc-fixref. Not normally needed.
# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
FIXXREF_OPTIONS = \
--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/glib \
--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gio \
--extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/gdk \
--extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/gdk-pixbuf \
--extra-dir=$(CAIRO_PREFIX)/share/gtk-doc/html/cairo
# Used for dependencies. The docs will be rebuilt if any of these change.
# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
HFILE_GLOB = \
$(top_srcdir)/*.h \
$(top_builddir)/*.h
CFILE_GLOB = \
$(top_srcdir)/*.c \
$(top_builddir)/*.c
# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
# EXTRA_HFILES = $(top_builddir)/evdocument/ev-version.h
EXTRA_HFILES =
# Header files to ignore when scanning. Use base file name, no paths
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES = \
config.h \
rsvg-bpath-util.h \
rsvg-cairo-clip.h \
rsvg-cairo-draw.h \
rsvg-cairo-render.h \
rsvg-css.h \
rsvg-defs.h \
rsvg-filter.h \
rsvg-image.h \
rsvg-marker.h \
rsvg-mask.h \
rsvg-paint-server.h \
rsvg-path.h \
rsvg-private.h \
rsvg-shapes.h \
rsvg-structure.h \
rsvg-styles.h \
rsvg-text.h \
rsvg-xml.h
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
HTML_IMAGES =
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files = \
version.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files =
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
# Only needed if you are using gtkdoc-scangobj to dynamically query widget
# signals and properties.
# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
GTKDOC_CFLAGS = \
-I$(top_srcdir) \
-I$(top_builddir) \
$(LIBRSVG_CFLAGS) \
$(LIBGSF_CFLAGS) \
$(LIBCROCO_CFLAGS) \
$(GTK_CFLAGS) \
$(GDK_X11_CFLAGS) \
$(WARN_CFLAGS) \
$(DISABLE_DEPRECATED) \
$(AM_CFLAGS)
GTKDOC_LIBS = \
$(top_builddir)/librsvg-@RSVG_API_MAJOR_VERSION@.la \
$(LIBRSVG_LIBS) \
$(LIBGSF_LIBS) \
$(GLIB_LIBS) \
$(LIBCROCO_LIBS) \
$(GTK_LIBS)
# This includes the standard gtk-doc make rules, copied by gtkdocize.
include $(top_srcdir)/gtk-doc.make
# Other files to distribute
extra_files=
# CFLAGS and LDFLAGS for compiling scan program. Only needed
# if $(DOC_MODULE).types is non-empty.
GTKDOC_CFLAGS = -I$(top_srcdir) $(LIBRSVG_CFLAGS)
GTKDOC_LIBS = $(top_builddir)/librsvg-@RSVG_API_MAJOR_VERSION@.la $(LIBRSVG_LIBS)
if GTK_DOC_INSTALLED
include $(top_srcdir)/gtk-doc.make
CLEANFILES += rsvg-scan.*
.PHONY : dist-hook-local
# e.g. EXTRA_DIST += version.xml.in
EXTRA_DIST += \
version.xml.in
# Files not to distribute
# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
#DISTCLEANFILES +=
# Comment this out if you want your docs-status tested during 'make check'
if ENABLE_GTK_DOC
#TESTS_ENVIRONMENT = cd $(srcsrc) &&
#TESTS = $(GTKDOC_CHECK)
endif
-include $(top_srcdir)/git.mk
<?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" [
<!NOTATION PNG SYSTEM "PNG">
<!ENTITY hash "#">
<!ENTITY % local.notation.class "| PNG">
<!ENTITY RSVG SYSTEM "xml/rsvg.xml">
<!ENTITY Cairo SYSTEM "xml/rsvg-cairo.xml">
<!ENTITY GdkPixbuf SYSTEM "xml/rsvg-file-util.xml">
<!ENTITY ObjectIndex SYSTEM "xml/object_index.sgml">
<!ENTITY TreeIndex SYSTEM "xml/tree_index.sgml">
]>
<book id="index">
<bookinfo>
<title>RSVG Reference Manual</title>
</bookinfo>
<part id="rsvg">
<title>RSVG Overview</title>
<partintro>
<para>
The GNOME SVG Library (RSVG) is library for rendering SVG and SVGZ files. RSVG is released under the GNU Library General Public
License (GNU LGPL), which allows for flexible licensing of client applications.
</para>
<para>
RSVG depends on the following libraries:
<variablelist>
<varlistentry>
<term>GLib</term>
<listitem><para>
A general-purpose utility library, not specific to graphical user interfaces.
GLib provides many useful data types, macros, type conversions,
string utilities, file utilities, a main loop abstraction, and so on.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Pango</term>
<listitem><para>
A general-purpose text library. http://www.pango.org/
</para></listitem>
</varlistentry>
<varlistentry>
<term>GdkPixbuf</term>
<listitem><para>
A general-purpose image library.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Cairo</term>
<listitem><para>
Cairo is a 2D graphics library with support for multiple output devices. Cairo is designed to produce consistent output on all output media while taking advantage of display hardware acceleration when available. http://www.cairographics.org/
</para></listitem>
</varlistentry>
</variablelist>
</para>
</partintro>
</part>
<part>
<title>
Using RSVG
</title>
&RSVG;
</part>
<part>
<title>
Using RSVG with Cairo
</title>
&Cairo;
</part>
<part>
<title>
Using RSVG with GdkPixbuf
</title>
&GdkPixbuf;
</part>
<index>
&ObjectIndex;
&TreeIndex;
</index>
</book>
<?xml version="1.0" encoding="UTF-8" ?>
<!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 version SYSTEM "version.xml">
]>
<book id="librsvg">
<!--
Copyright © 2009, 2010 Christian Persch
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU General Public License, Version 2
as published by the Free Software Foundation; or (at your option) any
later version.
A copy of the license is included in the COPYING file.
-->
<bookinfo>
<title>RSVG Libary Reference Manual</title>
<releaseinfo>
For RSVG version &version;.
The latest version of this documentation can be found on-line at the
<ulink role="online-location" url="http://library.gnome.org/devel/rsvg/index.html">GNOME Library</ulink>.
</releaseinfo>
<copyright>
<year>2003</year>
<year>2004</year>
<year>2005</year>
<year>2006</year>
<year>2007</year>
<year>2008</year>
<year>2009</year>
<holder>Dom Lachowicz</holder>
</copyright>
<copyright>
<year>2010</year>
<holder>Christian Persch</holder>
</copyright>
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the <citetitle>GNU General Public Licence</citetitle>
published by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version.
You may obtain a copy of the <citetitle>GNU General Public Licence</citetitle>
from the Free Software Foundation at
<ulink type="http" url="http://www.gnu.org/licences/">GNU Licences web site</ulink>
or by writing to:
<address>
The Free Software Foundation, Inc.,
<street>51 Franklin St</street> – Fifth Floor,
<city>Boston</city>, <state>MA</state> <postcode>02110-1301</postcode>,
<country>USA</country>
</address>
</para>
</legalnotice>
</bookinfo>
<part id="rsvg">
<title>API Reference</title>
<partintro>
<para>
The GNOME SVG Library (RSVG) is library for rendering SVG and SVGZ files.
</para>
</partintro>
<xi:include href="xml/rsvg-handle.xml"/>
<xi:include href="xml/rsvg-gio.xml"/>
<xi:include href="xml/rsvg-cairo.xml"/>
<xi:include href="xml/rsvg-pixbuf.xml"/>
<xi:include href="xml/rsvg-features.xml"/>
</part>
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</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 symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-4" role="2.4">
<title>Index of new symbols in 2.4</title>
<xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-8" role="2.8">
<title>Index of new symbols in 2.8</title>
<xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-9" role="2.9">
<title>Index of new symbols in 2.9</title>
<xi:include href="xml/api-index-2.9.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-14" role="2.14">
<title>Index of new symbols in 2.14</title>
<xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-22" role="2.22">
<title>Index of new symbols in 2.22</title>
<xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-2-32" role="2.32">
<title>Index of new symbols in 2.32</title>
<xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
<appendix id="licence">
<title>Licence</title>
<para>
This library is free software; you can redistribute it and/or
modify it under the terms of the <citetitle>GNU General Public
Licence</citetitle> as published by the Free Software Foundation; either
version 2 of the Licence, or (at your option) any later version.
</para>
<para>
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
<citetitle>GNU General Public Licence</citetitle> for
more details.
</para>
<para>
You may obtain a copy of the <citetitle>GNU General Public Licence</citetitle>
from the Free Software Foundation at
<ulink type="http" url="http://www.gnu.org/licences/">GNU Licences web site</ulink>
or by writing to:
<address>
The Free Software Foundation, Inc.,
<street>51 Franklin St</street> – Fifth Floor,
<city>Boston</city>, <state>MA</state> <postcode>02110-1301</postcode>,
<country>USA</country>
</address>
</para>
</appendix>
</book>
# These are manually-edited to override or add declarations to those scanned
# from the header files.
<SECTION>
<FILE>rsvg</FILE>
<TITLE>Core API</TITLE>
<FILE>rsvg-handle</FILE>
<TITLE>RsvgHandle</TITLE>
RsvgError
RSVG_ERROR
rsvg_error_quark
RsvgHandle
RsvgHandlePrivate
RsvgHandleClass
RsvgDimensionData
RsvgPositionData
rsvg_init
rsvg_term
rsvg_set_default_dpi
rsvg_set_default_dpi_x_y
rsvg_handle_new
rsvg_handle_free
rsvg_handle_set_dpi
rsvg_handle_set_dpi_x_y
rsvg_handle_new
rsvg_handle_write
rsvg_handle_close
rsvg_handle_new_from_data
rsvg_handle_new_from_file
RsvgDimensionData
RsvgSizeFunc
rsvg_handle_set_size_callback
rsvg_handle_get_base_uri
rsvg_handle_set_base_uri
rsvg_handle_get_title
rsvg_handle_get_desc
rsvg_handle_get_dimensions
rsvg_handle_get_dimensions_sub
rsvg_handle_get_position_sub
rsvg_handle_has_sub
rsvg_handle_get_title
rsvg_handle_get_desc
rsvg_handle_get_metadata
rsvg_handle_new_from_data
rsvg_handle_new_from_file
rsvg_handle_free
RsvgSizeFunc
rsvg_handle_set_size_callback
rsvg_error_get_type
RSVG_TYPE_ERROR
<SUBSECTION Standard>
RSVG_HANDLE
RSVG_IS_HANDLE
RSVG_TYPE_HANDLE
rsvg_handle_get_type
RSVG_HANDLE_CLASS
RSVG_IS_HANDLE_CLASS
RSVG_HANDLE_GET_CLASS
</SECTION>
<SUBSECTION>
<SECTION>
<FILE>rsvg-gio</FILE>
<TITLE>Using RSVG with GIO</TITLE>
RsvgHandleFlags
rsvg_handle_set_base_gfile
rsvg_handle_read_stream_sync
rsvg_handle_new_from_gfile_sync
rsvg_handle_new_from_stream_sync
<SUBSECTION Standard>
rsvg_handle_flags_get_type
RSVG_TYPE_HANDLE_FLAGS
</SECTION>
<SECTION>
<FILE>rsvg-cairo</FILE>
<TITLE>Cairo</TITLE>
<TITLE>Using RSVG with cairo</TITLE>
rsvg_handle_render_cairo
rsvg_handle_render_cairo_sub
</SECTION>
<SECTION>
<FILE>rsvg-file-util</FILE>
<TITLE>GdkPixbuf</TITLE>
<FILE>rsvg-pixbuf</FILE>
<TITLE>Using RSVG with GdkPixbuf</TITLE>
rsvg_handle_get_pixbuf
rsvg_handle_get_pixbuf_sub
rsvg_pixbuf_from_file
......@@ -53,3 +77,19 @@ rsvg_pixbuf_from_file_at_size
rsvg_pixbuf_from_file_at_max_size
rsvg_pixbuf_from_file_at_zoom_with_max
</SECTION>
<SECTION>
<FILE>rsvg-features</FILE>
<TITLE>Version check and feature tests</TITLE>
LIBRSVG_MAJOR_VERSION
LIBRSVG_MINOR_VERSION
LIBRSVG_MICRO_VERSION
LIBRSVG_VERSION
LIBRSVG_CHECK_VERSION
LIBRSVG_HAVE_SVGZ
LIBRSVG_HAVE_CSS
LIBRSVG_CHECK_FEATURE
librsvg_version
librsvg_preinit
librsvg_postinit
</SECTION>
rsvg_error_get_type
rsvg_handle_flags_get_type
rsvg_handle_get_type
<!-- ##### SECTION Title ##### -->
Rendering SVGs with GdkPixbuf
<!-- ##### SECTION Short_Description ##### -->
<para>
How to render SVGs into GdkPixbufs, for easy use in GTK+ applications
</para>
<!-- ##### SECTION Long_Description ##### -->
<para>
GdkPixbuf is a library for image loading and manipulation. It is part of the cross-platform GTK+ widget toolkit.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### FUNCTION rsvg_handle_get_pixbuf ##### -->
<para>
</para>
@handle:
@Returns:
<!-- ##### FUNCTION rsvg_handle_get_pixbuf_sub ##### -->
<para>
</para>
@handle:
@id:
@Returns:
<!-- ##### FUNCTION rsvg_pixbuf_from_file ##### -->
<para>
</para>
@file_name:
@error:
@Returns:
<!-- ##### FUNCTION rsvg_pixbuf_from_file_at_zoom ##### -->
<para>
</para>
@file_name:
@x_zoom:
@y_zoom:
@error:
@Returns:
<!-- ##### FUNCTION rsvg_pixbuf_from_file_at_size ##### -->
<para>
</para>
@file_name:
@width:
@height:
@error:
@Returns:
<!-- ##### FUNCTION rsvg_pixbuf_from_file_at_max_size ##### -->
<para>
</para>
@file_name:
@max_width:
@max_height:
@error:
@Returns:
<!-- ##### FUNCTION rsvg_pixbuf_from_file_at_zoom_with_max ##### -->
<para>
</para>
@file_name:
@x_zoom:
@y_zoom:
@max_width:
@max_height:
@error:
@Returns:
<!-- ##### SECTION ./tmpl/rsvg-gz.sgml:Long_Description ##### -->
<para>
</para>
<!-- ##### SECTION ./tmpl/rsvg-gz.sgml:See_Also ##### -->
<para>
</para>
<!-- ##### SECTION ./tmpl/rsvg-gz.sgml:Short_Description ##### -->
<!-- ##### SECTION ./tmpl/rsvg-gz.sgml:Stability_Level ##### -->
<!-- ##### SECTION ./tmpl/rsvg-gz.sgml:Title ##### -->
Creating a SVGZ reader
<!-- ##### FUNCTION rsvg_cairo_render ##### -->
<para>
</para>
@cr:
@handle:
<!-- ##### FUNCTION rsvg_cairo_render_sub ##### -->
<para>
</para>
@cr:
@handle:
@id:
<!-- ##### FUNCTION rsvg_handle_new_from_gfile ##### -->
<para>
</para>
@file:
@flags:
@cancellable:
@error:
@Returns:
<!-- ##### FUNCTION rsvg_handle_new_from_stream ##### -->
<para>
</para>
@input_stream:
@base_file:
@flags:
@cancellable:
@error: