CVS libidn/doc/reference

[libidn-commit]

Update of /home/cvs/libidn/doc/reference
In directory dopio:/tmp/cvs-serv7804/doc/reference

Modified Files:
        Makefile.am 
Added Files:
        libidn-docs.sgml 
Removed Files:
        libidn-docs.tmpl 
Log Message:
Align GTK-DOC build infrastructure with GTK-DOC official recommendations.


--- /home/cvs/libidn/doc/reference/Makefile.am  2004/09/13 17:10:23     1.10
+++ /home/cvs/libidn/doc/reference/Makefile.am  2004/10/24 15:31:38     1.11
@@ -1,50 +1,69 @@
 ## Process this file with automake to produce Makefile.in
-# Copyright (C) 2003, 2004 Simon Josefsson.
-#
-# This file is part of GNU Libidn.
-#
-# GNU Libidn is free software; you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as
-# published by the Free Software Foundation; either version 2.1 of
-# the License, or (at your option) any later version.
-#
-# GNU Libidn 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
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public
-# License along with GNU Libidn; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-
-HIGNORE = gunibreak.h gunicomp.h gunidecomp.h idn-int.h idn-free.h
-HTML_OBJECTS = index.html c4.html libidn-tld.html libidn-pr29.html \
-       libidn-idna.html libidn-punycode.html libidn-stringprep.html
-
-EXTRA_DIST = $(PACKAGE)-docs.tmpl $(HTML_OBJECTS) $(IMAGES)
-IMAGES = home.png left.png right.png up.png
-
-scan.stamp: $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*.h
-       gtkdoc-scan --module=$(PACKAGE) --source-dir=$(top_srcdir)/lib \
-               --ignore-headers="$(HIGNORE)" && touch scan.stamp
-
-tmpl.stamp: scan.stamp
-       gtkdoc-mktmpl --module=$(PACKAGE) --output-dir=.
-
-sgml.stamp: tmpl.stamp
-       gtkdoc-mkdb --module=$(PACKAGE) --source-dir=$(top_srcdir)/lib \
-               --tmpl-dir=. --output-dir=. \
-               --main-sgml-file=$(srcdir)/$(PACKAGE)-docs.tmpl
-
-index.html: sgml.stamp
-       cp $(srcdir)/$(PACKAGE)-docs.tmpl $(PACKAGE)-docs.sgml
-       gtkdoc-mkhtml $(PACKAGE) $(PACKAGE)-docs.sgml
-       rm -f $(PACKAGE)-docs.sgml ../html.stamp
-       gtkdoc-fixxref --module-dir=. --html-dir=$(HTML_DIR)
-
-all: index.html
-
-clean-local:
-       rm -f *.bak scan.stamp tmpl.stamp sgml.stamp *.txt *.sgml \
-               $(PACKAGE)-doc.bottom $(PACKAGE)-doc.top \
-               $(HTML_OBJECTS) $(IMAGES) style.css
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# 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=libidn
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# 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=../../lib
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" 
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# 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=
+
+# 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)/lib/*.h
+CFILE_GLOB=$(top_srcdir)/lib/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES=gunibreak.h gunicomp.h gunidecomp.h idn-int.h idn-free.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=
+
+# 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. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+INCLUDES=
+GTKDOC_LIBS=
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST += 
--- /home/cvs/libidn/doc/reference/libidn-docs.sgml     2003/11/01 20:08:10     
1.2
+++ /home/cvs/libidn/doc/reference/libidn-docs.sgml     2004/10/24 15:31:38     
1.3
@@ -1,9 +1,7 @@
-<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
-<!ENTITY libidn-idna SYSTEM "sgml/idna.sgml">
-<!ENTITY libidn-stringprep SYSTEM "sgml/stringprep.sgml">
-<!ENTITY libidn-punycode SYSTEM "sgml/punycode.sgml">
-]>
-<book id="index">
+<?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";>
   <bookinfo>
     <title>GNU Libidn API Reference Manual</title>
   </bookinfo>
@@ -17,28 +15,41 @@
       (IDN) working group, used for internationalized domain names.  The
       package is available under the GNU Lesser General Public License.
     </para>
+
     <para>
-      The library contains a generic Stringprep implementation that does
-      Unicode 3.2 NFKC normalization, mapping and prohibitation of
-      characters, and bidirectional character handling.  Profiles for iSCSI,
-      Kerberos 5, Nameprep, SASL and XMPP are included.  Punycode and ASCII
-      Compatible Encoding (ACE) via IDNA are supported.
+      The library contains a generic Stringprep implementation that
+      does Unicode 3.2 NFKC normalization, mapping and prohibitation
+      of characters, and bidirectional character handling.  Profiles
+      for Nameprep, iSCSI, SASL and XMPP are included.  Punycode and
+      ASCII Compatible Encoding (ACE) via IDNA are supported.  A
+      mechanism to define Top-Level Domain (TLD) specific validation
+      tables, and to compare strings against those tables, is
+      included.  Default tables for some TLDs are also included.
     </para>
+
     <para>
-      The Stringprep API consists of two main functions, one for converting
-      data from the system's native representation into UTF-8, and one
-      function to perform the Stringprep processing.  Adding a new
-      Stringprep profile for your application within the API is
-      straightforward.  The Punycode API consists of one encoding function
-      and one decoding function.  The IDNA API consists of the ToASCII and
-      ToUnicode functions, as well as an high-level interface for converting
-      entire domain names to and from the ACE encoded form.
+      The Stringprep API consists of two main functions, one for
+      converting data from the system's native representation into
+      UTF-8, and one function to perform the Stringprep processing.
+      Adding a new Stringprep profile for your application within the
+      API is straightforward.  The Punycode API consists of one
+      encoding function and one decoding function.  The IDNA API
+      consists of the ToASCII and ToUnicode functions, as well as an
+      high-level interface for converting entire domain names to and
+      from the ACE encoded form.  The TLD API consists of one set of
+      functions to extract the TLD name from a domain string, one set
+      of functions to locate the proper TLD table to use based on the
+      TLD name, and core functions to validate a string against a TLD
+      table, and some utility wrappers to perform all the steps in one
+      call.
     </para>
+
     <para>
       The library is used by, e.g., GNU SASL and Shishi to process user
       names and passwords.  Libidn can be built into GNU Libc to enable a
       new system-wide getaddrinfo flag for IDN processing.
     </para>
+
     <para>
       Libidn is developed for the GNU/Linux system, but runs on over 20
       platforms including most major Unix platforms and Windows, and many
@@ -47,8 +58,10 @@
       C++, Emacs Lisp, Python and Java.
     </para>
 
-    &libidn-stringprep;
-    &libidn-punycode;
-    &libidn-idna;
+    <xi:include href="xml/idna.xml"/>
+    <xi:include href="xml/pr29.xml"/>
+    <xi:include href="xml/punycode.xml"/>
+    <xi:include href="xml/tld.xml"/>
+    <xi:include href="xml/stringprep.xml"/>
   </chapter>
 </book>