diff options
author | Dom Lachowicz <doml@src.gnome.org> | 2003-02-01 21:17:28 +0000 |
---|---|---|
committer | Dom Lachowicz <doml@src.gnome.org> | 2003-02-01 21:17:28 +0000 |
commit | ac670d2ddf87dc023ec59226b1dd3b569a8bc374 (patch) | |
tree | 92d84bc41f19a96df90a218c0e75b0c24d00e4b0 | |
parent | 8cf44348b19aafff4c892c5627f59610c34290da (diff) | |
download | librsvg-ac670d2ddf87dc023ec59226b1dd3b569a8bc374.tar.gz |
start of gtk-doc documentation stuff
-rw-r--r-- | Makefile.am | 2 | ||||
-rw-r--r-- | configure.in | 56 | ||||
-rw-r--r-- | doc/Makefile.am | 175 | ||||
-rw-r--r-- | doc/rsvg-docs.sgml | 78 | ||||
-rw-r--r-- | doc/rsvg-overrides.txt | 2 | ||||
-rw-r--r-- | doc/rsvg-sections.txt | 37 | ||||
-rw-r--r-- | doc/rsvg.types | 0 | ||||
-rw-r--r-- | doc/tmpl/rsvg-file-util.sgml | 141 | ||||
-rw-r--r-- | doc/tmpl/rsvg-gz.sgml | 24 | ||||
-rw-r--r-- | doc/tmpl/rsvg-unused.sgml | 0 | ||||
-rw-r--r-- | doc/tmpl/rsvg.sgml | 109 |
11 files changed, 623 insertions, 1 deletions
diff --git a/Makefile.am b/Makefile.am index fd3be8b9..f59b8eae 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ -SUBDIRS = . gtk-engine gdk-pixbuf-loader +SUBDIRS = . gtk-engine gdk-pixbuf-loader doc bin_PROGRAMS = rsvg diff --git a/configure.in b/configure.in index c3336551..fc80f8c7 100644 --- a/configure.in +++ b/configure.in @@ -181,6 +181,61 @@ fi AM_CONDITIONAL(ENABLE_PIXBUF_LOADER, test x$enable_pixbuf_loader = xyes) +################################################## +# Checks for gtk-doc and docbook-tools +################################################## + +AC_ARG_WITH(html-dir, [ --with-html-dir=PATH path to installed docs ]) + +if test "x$with_html_dir" = "x" ; then + HTML_DIR='${datadir}/doc/librsvg/html' +else + HTML_DIR=$with_html_dir +fi + +AC_SUBST(HTML_DIR) + +AC_CHECK_PROG(GTKDOC, gtkdoc-mkdb, true, false) + +gtk_doc_min_version=0.9 +if $GTKDOC ; then + gtk_doc_version=`gtkdoc-mkdb --version` + AC_MSG_CHECKING([gtk-doc version ($gtk_doc_version) >= $gtk_doc_min_version]) + + IFS="${IFS= }"; gtk_save_IFS="$IFS"; IFS="." + set $gtk_doc_version + for min in $gtk_doc_min_version ; do + cur=$1; shift + if test -z $min ; then break; fi + if test -z $cur ; then GTKDOC=false; break; fi + if test $cur -gt $min ; then break ; fi + if test $cur -lt $min ; then GTKDOC=false; break ; fi + done + IFS="$gtk_save_IFS" + + if $GTKDOC ; then + AC_MSG_RESULT(yes) + else + AC_MSG_RESULT(no) + fi +fi + +AC_CHECK_PROG(DB2HTML, db2html, true, false) +AM_CONDITIONAL(HAVE_DOCBOOK, $DB2HTML) + +dnl Make people enable the gtk-doc stuff explicitely. +AC_ARG_ENABLE(gtk-doc, [ --disable-gtk-doc use gtk-doc to build documentation [default=yes]], enable_gtk_doc="$enableval", enable_gtk_doc=yes) + +if test x$enable_gtk_doc = xyes ; then + if test x$GTKDOC != xtrue ; then + enable_gtk_doc=no + fi +fi + +dnl NOTE: We need to use a separate automake conditional for this +dnl to make this work with the tarballs. +AM_CONDITIONAL(ENABLE_GTK_DOC, test x$enable_gtk_doc = xyes) + dnl =========================================================================== AC_OUTPUT([ @@ -188,6 +243,7 @@ librsvg.spec librsvg-features.h Makefile librsvg-2.0.pc +doc/Makefile gtk-engine/Makefile gtk-engine/examples/Makefile gtk-engine/examples/bubble/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 00000000..68a3b0ed --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,175 @@ +## Process this file with automake to produce Makefile.in + +# 'borrowed' from gtk-2.0/docs/reference/gtk + +# The name of the module. +DOC_MODULE=rsvg + +# 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=--type-init-func="g_type_init ()" + +# Extra options to supply to gtkdoc-scan +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb +MKDB_OPTIONS=--sgml-mode + +# 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= + +# Images to copy into HTML directory +HTML_IMAGES = + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE) +content_files = + +# 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 = $(LIBRSVG_LIBS) + +#################################### +# Everything below here is generic # +#################################### + +# We set GPATH here; this gives us semantics for GNU make +# which are more like other make's VPATH, when it comes to +# whether a source that is a target of one rule is then +# searched for in VPATH/GPATH. +# +GPATH = $(srcdir) + +TARGET_DIR=$(HTML_DIR) + +EXTRA_DIST = \ + $(content_files) \ + $(extra_files) \ + $(HTML_IMAGES) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE).types \ + $(DOC_MODULE)-sections.txt \ + $(DOC_MODULE)-overrides.txt + +DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \ + $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp + +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).signals + +if ENABLE_GTK_DOC +all-local: html-build.stamp + +#### scan #### + +scan-build.stamp: $(HFILE_GLOB) + @echo '*** Scanning header files ***' + if grep -l '^..*$$' $(srcdir)/$(DOC_MODULE).types > /dev/null ; then \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) --output-dir=$(srcdir) ; \ + else \ + cd $(srcdir) ; \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi + cd $(srcdir) && \ + gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES) + touch scan-build.stamp + +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): scan-build.stamp + @true + +#### templates #### + +tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt + @echo '*** Rebuilding template files ***' + cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) + touch tmpl-build.stamp + +tmpl.stamp: tmpl-build.stamp + @true + +#### sgml #### + +sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml + @echo '*** Building SGML ***' + cd $(srcdir) && \ + gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS) + touch sgml-build.stamp + +sgml.stamp: sgml-build.stamp + @true + +#### html #### + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) + @echo '*** Building HTML ***' + rm -rf $(srcdir)/html + mkdir $(srcdir)/html + cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html ) + @echo '-- Fixing Crossreferences' + cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + touch html-build.stamp +endif + +############## + +clean-local: + rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) + +maintainer-clean-local: clean + cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + +install-data-local: + $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR) + (installfiles=`echo $(srcdir)/html/*`; \ + if test "$$installfiles" = '$(srcdir)/html/*'; \ + then echo '-- Nothing to install' ; \ + else \ + for i in $$installfiles; do \ + echo '-- Installing '$$i ; \ + $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \ + done; \ + echo '-- Installing $(srcdir)/html/index.sgml' ; \ + $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR); \ + fi) + +# +# Require gtk-doc when making dist +# +if ENABLE_GTK_DOC +dist-check-gtkdoc: +else +dist-check-gtkdoc: + @echo "*** gtk-doc must be installed and enabled in order to make dist" + @false +endif + +dist-hook: dist-check-gtkdoc dist-hook-local + mkdir $(distdir)/tmpl + mkdir $(distdir)/sgml + mkdir $(distdir)/html + -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl + -cp $(srcdir)/sgml/*.sgml $(distdir)/sgml + -cp $(srcdir)/html/* $(distdir)/html + +.PHONY : dist-hook-local diff --git a/doc/rsvg-docs.sgml b/doc/rsvg-docs.sgml new file mode 100644 index 00000000..231598f6 --- /dev/null +++ b/doc/rsvg-docs.sgml @@ -0,0 +1,78 @@ +<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +<!notation PNG system "PNG"> +<!entity % local.notation.class "| PNG"> + +<!entity hash "#"> +<!entity percent "%"> +<!entity RSVG SYSTEM "sgml/rsvg.sgml"> +<!entity SVGZ SYSTEM "sgml/rsvg-gz.sgml"> +<!entity Utilities SYSTEM "sgml/rsvg-file-util.sgml"> +<!entity ObjectIndex SYSTEM "sgml/object_index.sgml"> +<!entity TreeIndex SYSTEM "sgml/tree_index.sgml"> +]> + +<book id="index"> + <bookinfo> + <title>RSVG Reference Manual</title> + </bookinfo> + + <part id="gsf"> + <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 General Public +License (GNU GPL), which allows for flexible licensing of client applications. + </para> + <para> +RSVG depends on the following libraries: +<variablelist> + +<varlistentry> +<listitem><term>GLib</term><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> + +<listitem><term>Pango</term><para> +A general-purpose text library. http://www.pango.org +</para></listitem> + +<listitem><term>GdkPixbuf</term><para> +A general-purpose image library. +</para></listitem> + +</varlistentry> +</variablelist> +</para> +</partintro> + +<reference> +<title> +rsvg +</title> +&RSVG; +</reference> + +<reference> +<title> +Handling Gzipped SVG +</title> +&SVGZ; +</reference> + + +<reference> +<title> +Utility and Convenience Functions +</title> +&Utilities; +</reference> + +</part> + +<index> +&ObjectIndex; +&TreeIndex; +</index> +</book> diff --git a/doc/rsvg-overrides.txt b/doc/rsvg-overrides.txt new file mode 100644 index 00000000..13f485f1 --- /dev/null +++ b/doc/rsvg-overrides.txt @@ -0,0 +1,2 @@ +# These are manually-edited to override or add declarations to those scanned +# from the header files. diff --git a/doc/rsvg-sections.txt b/doc/rsvg-sections.txt new file mode 100644 index 00000000..5ab816a2 --- /dev/null +++ b/doc/rsvg-sections.txt @@ -0,0 +1,37 @@ +<SECTION> +<FILE>rsvg</FILE> +<TITLE>Core API</TITLE> +rsvg_error_quark +RsvgSizeFunc +rsvg_set_default_dpi +rsvg_handle_new +rsvg_handle_set_dpi +rsvg_handle_set_size_callback +rsvg_handle_write +rsvg_handle_close +rsvg_handle_get_pixbuf +rsvg_handle_free +</SECTION> + +<SECTION> +<FILE>rsvg-gz</FILE> +<TITLE>Creating a SVGZ reader</TITLE> +rsvg_handle_new_gz +</SECTION> + +<SECTION> +<FILE>rsvg-file-util</FILE> +<TITLE>Utility/Convenience Functions</TITLE> +rsvg_pixbuf_from_file +rsvg_pixbuf_from_file_at_zoom +rsvg_pixbuf_from_file_at_size +rsvg_pixbuf_from_file_at_max_size +rsvg_pixbuf_from_file_at_zoom_with_max +rsvg_pixbuf_from_file_ex +rsvg_pixbuf_from_file_at_zoom_ex +rsvg_pixbuf_from_file_at_size_ex +rsvg_pixbuf_from_file_at_max_size_ex +rsvg_pixbuf_from_file_at_zoom_with_max_ex +</SECTION> + + diff --git a/doc/rsvg.types b/doc/rsvg.types new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/doc/rsvg.types diff --git a/doc/tmpl/rsvg-file-util.sgml b/doc/tmpl/rsvg-file-util.sgml new file mode 100644 index 00000000..9a4f002a --- /dev/null +++ b/doc/tmpl/rsvg-file-util.sgml @@ -0,0 +1,141 @@ +<!-- ##### SECTION Title ##### --> +Utility/Convenience Functions + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### 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: + + +<!-- ##### FUNCTION rsvg_pixbuf_from_file_ex ##### --> +<para> + +</para> + +@handle: +@file_name: +@error: +@Returns: + + +<!-- ##### FUNCTION rsvg_pixbuf_from_file_at_zoom_ex ##### --> +<para> + +</para> + +@handle: +@file_name: +@x_zoom: +@y_zoom: +@error: +@Returns: + + +<!-- ##### FUNCTION rsvg_pixbuf_from_file_at_size_ex ##### --> +<para> + +</para> + +@handle: +@file_name: +@width: +@height: +@error: +@Returns: + + +<!-- ##### FUNCTION rsvg_pixbuf_from_file_at_max_size_ex ##### --> +<para> + +</para> + +@handle: +@file_name: +@max_width: +@max_height: +@error: +@Returns: + + +<!-- ##### FUNCTION rsvg_pixbuf_from_file_at_zoom_with_max_ex ##### --> +<para> + +</para> + +@handle: +@file_name: +@x_zoom: +@y_zoom: +@max_width: +@max_height: +@error: +@Returns: + + diff --git a/doc/tmpl/rsvg-gz.sgml b/doc/tmpl/rsvg-gz.sgml new file mode 100644 index 00000000..f7379658 --- /dev/null +++ b/doc/tmpl/rsvg-gz.sgml @@ -0,0 +1,24 @@ +<!-- ##### SECTION Title ##### --> +Creating a SVGZ reader + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### FUNCTION rsvg_handle_new_gz ##### --> +<para> + +</para> + +@Returns: + + diff --git a/doc/tmpl/rsvg-unused.sgml b/doc/tmpl/rsvg-unused.sgml new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/doc/tmpl/rsvg-unused.sgml diff --git a/doc/tmpl/rsvg.sgml b/doc/tmpl/rsvg.sgml new file mode 100644 index 00000000..322c7f52 --- /dev/null +++ b/doc/tmpl/rsvg.sgml @@ -0,0 +1,109 @@ +<!-- ##### SECTION Title ##### --> +Core API + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### FUNCTION rsvg_error_quark ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### USER_FUNCTION RsvgSizeFunc ##### --> +<para> + +</para> + +@width: +@height: +@user_data: + + +<!-- ##### FUNCTION rsvg_set_default_dpi ##### --> +<para> + +</para> + +@dpi: + + +<!-- ##### FUNCTION rsvg_handle_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION rsvg_handle_set_dpi ##### --> +<para> + +</para> + +@handle: +@dpi: + + +<!-- ##### FUNCTION rsvg_handle_set_size_callback ##### --> +<para> + +</para> + +@handle: +@size_func: +@user_data: +@user_data_destroy: + + +<!-- ##### FUNCTION rsvg_handle_write ##### --> +<para> + +</para> + +@handle: +@buf: +@count: +@error: +@Returns: + + +<!-- ##### FUNCTION rsvg_handle_close ##### --> +<para> + +</para> + +@handle: +@error: +@Returns: + + +<!-- ##### FUNCTION rsvg_handle_get_pixbuf ##### --> +<para> + +</para> + +@handle: +@Returns: + + +<!-- ##### FUNCTION rsvg_handle_free ##### --> +<para> + +</para> + +@handle: + + |