first cut at gtk-doc

ChangeLog

@@ -2,6 +2,15 @@ Mon Apr 12 09:56:23 EDT 2004	Brian Bruns <brian@bruns.com>
 	* include/mdbtools:
 	* src/libmdb/mem.c:
 	* src/libmdb/backend.c: free backends on exit (Jeff Smith)
+	* src/libmdb/index.c: missing function mdb_swap_n()
+	* src/libmdb/file.c: 
+	* configure.in:
+	* doc/reference/libmdb/Makefile.am:
+	* doc/reference/libmdb/libmdb-sections.txt:
+	* doc/reference/libmdb/libmdb-docs.sgml: Initial cut at gtk-doc reference manual
+	* include/mdbtools.h: Change MdbSargNode typedef to forward declaration to make gtk-doc happy
+	* doc/faq.html: Fix unclosed <ul> tag
+	* TODO: update finished items
 
 Thu Mar 25 04:56:05 EST 2004	Brian Bruns <brian@bruns.com>
 	* src/odbc/odbc.c(_SQLFreeStmt): call mdb_sql_reset on stmt drop (Jeff Smith)

TODO

@@ -30,7 +30,7 @@ utils:
 
 . need program to unpack VBA script to file (see prole)
 . Access forms to glade converter ?
-. need --version flag
+. need --version flag (done using -M flag on mdb-ver)
 . -o on mdb-sql not working
 
 SQL Engine:
@@ -40,13 +40,13 @@ SQL Engine:
 . OR clauses using sarg trees from above (done)
 . insert/updates
 . bogus column name in where clause not caught
-. const = const type operations not working (e.g. WHERE 0=1)
+. const = const type operations not working (e.g. WHERE 0=1) (done)
 . list tables/describe table shouldn't directly write to stdout (done, but will blow up on big tables)
 
 ODBC:
 
 . Figure out why we get unresolved symbols when ODBC driver load by DM (iODBC 
-  only?)
+  only)
 . Boolean not working (done)
 . many unimplemented funtions
 

configure.in

@@ -113,6 +113,46 @@ fi
 AC_SUBST([OPTDIRS])
 AC_CONFIG_FILES([src/Makefile])
 
+
+##################################################
+# Check for gtk-doc.
+##################################################
+
+AC_ARG_WITH(html-dir, [  --with-html-dir=PATH path to installed docs ])
+
+if test "x$with_html_dir" = "x" ; then
+  HTML_DIR='${datadir}/gtk-doc/html'
+else
+  HTML_DIR=$with_html_dir
+fi
+
+AC_SUBST(HTML_DIR)
+
+gtk_doc_min_version=1.0
+AC_MSG_CHECKING([gtk-doc version >= $gtk_doc_min_version])
+if pkg-config --atleast-version=$gtk_doc_min_version gtk-doc; then
+  AC_MSG_RESULT(yes)
+  GTKDOC=true
+else
+  AC_MSG_RESULT(no)
+  GTKDOC=false
+fi
+
+dnl Let people disable the gtk-doc stuff.
+AC_ARG_ENABLE(gtk-doc, [  --enable-gtk-doc  Use gtk-doc to build documentation [default=auto]], enable_gtk_doc="$enableval", enable_gtk_doc=auto)
+
+if test x$enable_gtk_doc = xauto ; then
+  if test x$GTKDOC = xtrue ; then
+    enable_gtk_doc=yes
+  else
+    enable_gtk_doc=no 
+  fi
+fi
+
+AM_CONDITIONAL(ENABLE_GTK_DOC, test x$enable_gtk_doc = xyes)
+
+
+
 dnl Checks for library functions.
 
 OLDLDFLAGS=$LDFLAGS
@@ -134,4 +174,4 @@ AC_SUBST(READLINE_LIBS)
 localedir=${datadir}/locale
 AC_SUBST(localedir)
 
-AC_OUTPUT(src/util/Makefile src/extras/Makefile Makefile include/Makefile src/libmdb/Makefile src/sql/Makefile src/odbc/Makefile doc/Makefile src/gmdb2/Makefile src/gmdb2/gladefiles/Makefile src/gmdb2/pixmaps/Makefile src/gmdb2/help/Makefile src/gmdb2/help/C/Makefile mdbtools.spec include/mdbver.h)
+AC_OUTPUT(src/util/Makefile src/extras/Makefile Makefile include/Makefile src/libmdb/Makefile src/sql/Makefile src/odbc/Makefile doc/Makefile src/gmdb2/Makefile src/gmdb2/gladefiles/Makefile src/gmdb2/pixmaps/Makefile src/gmdb2/help/Makefile src/gmdb2/help/C/Makefile mdbtools.spec include/mdbver.h doc/reference/libmdb/Makefile)

doc/faq.html

@@ -49,6 +49,7 @@ MDB Tools includes
 <li> MDBSQL, a SQL engine layered on top of LibMDB.</li>
 <li> MDB ODBC driver, a ODBC driver - requires unixODBC driver manager.</li>
 <li> gmdb2, a graphical interface including SQL query tool and file debugger.</li>
+</ul>
 </dd></dl>
 
 <dl><a name="license"></a><dt><b>1.4 What license is MDB Tools under</b></dt><dd> 

doc/reference/libmdb/Makefile.am

@@ -0,0 +1,190 @@
+## Process this file with automake to produce Makefile.in
+
+# 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=libmdb
+
+# The top-level SGML file. Change it if you want.
+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 functions and macros.
+DOC_SOURCE_DIR=$(top_srcdir)/src/libmdb
+DOC_HEADER_DIR=$(top_srcdir)/include
+
+# Extra options to pass to gtkdoc-scanobj or gtkdoc-scangobj.
+SCANOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb.
+MKDB_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref.
+FIXXREF_OPTIONS=
+
+# Used for dependencies.
+HFILE_GLOB=
+CFILE_GLOB=
+
+# 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 your app/lib
+# contains GtkObjects/GObjects and you want to document signals and properties.
+GTKDOC_CFLAGS =
+GTKDOC_LIBS =
+
+GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC)
+GTKDOC_LD=$(LIBTOOL) --mode=link $(CC)
+
+# If you need to override some of the declarations, place them in the
+# $(DOC_MODULE)-overrides.txt file and uncomment the second line here.
+DOC_OVERRIDES =
+#DOC_OVERRIDES = $(DOC_MODULE)-overrides.txt
+
+
+
+###########################################################################
+# Everything below here is generic and you shouldn't need to change it.
+###########################################################################
+
+TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
+
+EXTRA_DIST = 				\
+	$(content_files)		\
+	$(extra_files)			\
+	$(HTML_IMAGES)			\
+	$(DOC_MAIN_SGML_FILE)		\
+	$(DOC_MODULE).types		\
+	$(DOC_MODULE)-sections.txt	\
+	$(DOC_OVERRIDES)
+
+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).interfaces \
+	$(DOC_MODULE).prerequisites \
+	$(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-scanobj $(SCANOBJ_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_HEADER_DIR) --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_OVERRIDES)
+	@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) --main-sgml-file=$(DOC_MAIN_SGML_FILE) $(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 ***'
+	test -d $(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/*.html`; \
+	if test "$$installfiles" = '$(srcdir)/html/*.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/index.sgml $(distdir)/html
+	-cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html
+
+	images=$(HTML_IMAGES) ;    	      \
+	for i in $$images ; do		      \
+	  cp $(srcdir)/$$i $(distdir)/html ;  \
+	done
+
+.PHONY : dist-hook-local

doc/reference/libmdb/libmdb-docs.sgml

@@ -0,0 +1,13 @@
+<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!ENTITY libmdb-mdbtools SYSTEM "sgml/mdbtools.sgml">
+]>
+<book id="index">
+  <bookinfo>
+    <title>LibMDB Reference Manual</title>
+  </bookinfo>
+
+  <chapter>
+    <title>LibMDB Function List</title>
+    &libmdb-mdbtools;
+  </chapter>
+</book>

doc/reference/libmdb/libmdb-sections.txt

@@ -0,0 +1,144 @@
+<SECTION>
+<FILE>mdbtools</FILE>
+MDB_DEBUG
+MDB_PGSIZE
+MDB_MAX_OBJ_NAME
+MDB_MAX_COLS
+MDB_MAX_IDX_COLS
+MDB_CATALOG_PG
+MDB_MEMO_OVERHEAD
+MDB_BIND_SIZE
+MdbStrategy
+mdb_is_logical_op
+mdb_is_relational_op
+IS_JET4
+IS_JET3
+mdb_backends
+MdbBackendType
+MdbBackend
+MdbStatistics
+MdbFile
+MdbFormatConstants
+MdbHandle
+MdbCatalogEntry
+MdbProperties
+MdbColumn
+mdbsargtree
+MdbIndexPage
+gpointer)
+MDB_MAX_INDEX_DEPTH
+MdbIndexChain
+MdbTableDef
+MdbColumnProp
+MdbField
+MdbSarg
+mdb_init
+mdb_exit
+mdb_alloc_handle
+mdb_free_handle
+mdb_free_catalog
+mdb_alloc_tabledef
+mdb_alloc_catalog
+mdb_alloc_file
+mdb_free_file
+mdb_append_index
+mdb_alloc_stats
+mdb_read_pg
+mdb_read_alt_pg
+mdb_get_byte
+mdb_get_int16
+mdb_get_int24
+mdb_get_int32
+mdb_get_single
+mdb_get_double
+mdb_pg_get_byte
+mdb_pg_get_int16
+mdb_pg_get_int24
+mdb_pg_get_int32
+mdb_pg_get_single
+mdb_pg_get_double
+mdb_pg_get_int24_msb
+mdb_open
+mdb_close
+mdb_clone_handle
+mdb_swap_pgbuf
+mdb_free_tabledef
+mdb_read_catalog
+mdb_catalog_dump
+mdb_catalog_rows
+mdb_get_catalog_entry
+mdb_get_objtype_string
+mdb_dump_catalog
+mdb_read_table
+mdb_read_columns
+mdb_table_dump
+read_pg_if_16
+read_pg_if_32
+read_pg_if
+read_pg_if_n
+mdb_bind_column_by_name
+mdb_data_dump
+mdb_bind_column
+mdb_rewind_table
+mdb_fetch_row
+mdb_is_fixed_col
+mdb_col_to_string
+mdb_find_end_of_row
+mdb_col_fixed_size
+mdb_col_disp_size
+mdb_bind_len
+mdb_ole_read_next
+mdb_ole_read
+mdb_set_date_fmt
+mdb_read_row
+buffer_dump
+mdb_get_coltype_string
+mdb_coltype_takes_length
+mdb_init_backends
+mdb_register_backend
+mdb_remove_backends
+mdb_set_default_backend
+mdb_get_relationships
+mdb_test_sargs
+mdb_test_sarg
+mdb_sql_walk_tree
+mdb_find_indexable_sargs
+mdb_add_sarg_by_name
+mdb_test_string
+mdb_test_int
+mdb_add_sarg
+mdb_read_indices
+mdb_index_dump
+mdb_index_scan_free
+mdb_index_find_next_on_page
+mdb_index_find_next
+mdb_index_hash_text
+mdb_index_scan_init
+mdb_index_find_row
+mdb_index_swap_n
+mdb_stats_on
+mdb_stats_off
+mdb_dump_stats
+mdb_like_cmp
+mdb_crack_row
+mdb_add_row_to_pg
+mdb_update_index
+mdb_pack_row
+mdb_replace_row
+mdb_pg_get_freespace
+mdb_update_row
+mdb_new_data_pg
+mdb_map_find_next_freepage
+mdb_read_props_list
+mdb_free_props
+mdb_read_props
+mdb_create_temp_table
+mdb_temp_table_add_col
+mdb_fill_temp_col
+mdb_fill_temp_field
+mdb_get_option
+mdb_debug
+mdb_unicode2ascii
+mdb_ascii2unicode
+</SECTION>
+

include/mdbtools.h

@@ -146,6 +146,7 @@ extern GHashTable	*mdb_backends;
 
 /* forward declarations */
 typedef struct mdbindex MdbIndex;
+typedef struct mdbsargtree MdbSargNode;
 
 typedef struct {
 	char *name;
@@ -273,14 +274,14 @@ typedef struct {
 	int		row_col_num;
 } MdbColumn;
 
-typedef struct _mdbsargtree {
+struct mdbsargtree {
 	int       op;
 	MdbColumn *col;
 	MdbAny    value;
 	void      *parent;
-	struct _mdbsargtree *left;
+	MdbSargNode *left;
-	struct _mdbsargtree *right;
+	MdbSargNode *right;
-} MdbSargNode;
+};
 
 typedef struct {
 	guint32 pg;
@@ -471,6 +472,8 @@ extern int mdb_index_find_next(MdbHandle *mdb, MdbIndex *idx, MdbIndexChain *cha
 extern void mdb_index_hash_text(guchar *text, guchar *hash);
 extern void mdb_index_scan_init(MdbHandle *mdb, MdbTableDef *table);
 extern int mdb_index_find_row(MdbHandle *mdb, MdbIndex *idx, MdbIndexChain *chain, guint32 pg, guint16 row);
+extern void mdb_index_swap_n(unsigned char *src, int sz, unsigned char *dest);
+
 
 /* stats.c */
 extern void mdb_stats_on(MdbHandle *mdb);

src/libmdb/file.c

@@ -149,6 +149,16 @@ MdbFile *f;
 	f->refs++;
 	return mdb;
 }
+/**
+ * mdb_open:
+ * @filename: path to MDB (database) file
+ *
+ * Opens an MDB file and returns an MdbHandle to it.  MDB File may be relative
+ * to the current directory, a full path to the file, or relative to a 
+ * component of $MDBPATH.
+ *
+ * Return value: pointer to MdbHandle structure.
+ **/
 MdbHandle *mdb_open(char *filename)
 {
 	return _mdb_open(filename, FALSE);

src/libmdb/index.c

@@ -181,6 +181,15 @@ mdb_index_hash_text(guchar *text, guchar *hash)
 	}
 	hash[strlen(text)]=0;
 }
+void
+mdb_index_swap_n(unsigned char *src, int sz, unsigned char *dest)
+{
+	int i, j = 0;
+
+	for (i = sz; i > 0; i++) {
+		dest[j++] = src[i];
+	}
+}
 guint32
 mdb_index_swap_int32(guint32 l)
 {