More work on key-value pair docs.

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@2712 57a11ea4-9604-0410-9ed3-97b8803252fd

src/doc/design/Makefile.am

@@ -2,6 +2,7 @@
 info_TEXINFOS = gnucash-design.texinfo
 gnucash_design_TEXINFOS = concept-index.texinfo \
                           engine.texinfo \
+                          function-index.texinfo \
                           intro.texinfo \
                           register.texinfo \
                           reports.texinfo \

src/doc/design/Makefile.in

@@ -116,7 +116,7 @@ VERSION = @VERSION@
 l = @l@
 
 info_TEXINFOS = gnucash-design.texinfo
-gnucash_design_TEXINFOS = concept-index.texinfo                           engine.texinfo                           intro.texinfo                           register.texinfo                           reports.texinfo                           top-level.texinfo                           type-index.texinfo
+gnucash_design_TEXINFOS = concept-index.texinfo                           engine.texinfo                           function-index.texinfo                           intro.texinfo                           register.texinfo                           reports.texinfo                           top-level.texinfo                           type-index.texinfo
 
 mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
 CONFIG_HEADER = ../../../config.h
@@ -126,7 +126,7 @@ INFO_DEPS = gnucash-design.info
 DVIS = gnucash-design.dvi
 TEXINFOS = gnucash-design.texinfo
 DIST_COMMON =  $(gnucash_design_TEXINFOS) Makefile.am Makefile.in \
-mdate-sh stamp-vti texinfo.tex version.texi
+mdate-sh texinfo.tex
 
 
 DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST)
@@ -144,31 +144,8 @@ Makefile: $(srcdir)/Makefile.in  $(top_builddir)/config.status $(BUILT_SOURCES)
 	  && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status
 
 
-$(srcdir)/version.texi: stamp-vti
+gnucash-design.info: gnucash-design.texinfo $(gnucash_design_TEXINFOS)
-	@:
+gnucash-design.dvi: gnucash-design.texinfo $(gnucash_design_TEXINFOS)
-
-$(srcdir)/stamp-vti: gnucash-design.texinfo $(top_srcdir)/configure.in
-	@echo "@set UPDATED `$(SHELL) $(srcdir)/mdate-sh $(srcdir)/gnucash-design.texinfo`" > vti.tmp
-	@echo "@set EDITION $(VERSION)" >> vti.tmp
-	@echo "@set VERSION $(VERSION)" >> vti.tmp
-	@cmp -s vti.tmp $(srcdir)/version.texi \
-	  || (echo "Updating $(srcdir)/version.texi"; \
-	      cp vti.tmp $(srcdir)/version.texi)
-	-@rm -f vti.tmp
-	@cp $(srcdir)/version.texi $@
-
-mostlyclean-vti:
-	-rm -f vti.tmp
-
-clean-vti:
-
-distclean-vti:
-
-maintainer-clean-vti:
-	-rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi
-
-gnucash-design.info: gnucash-design.texinfo version.texi $(gnucash_design_TEXINFOS)
-gnucash-design.dvi: gnucash-design.texinfo version.texi $(gnucash_design_TEXINFOS)
 
 
 DVIPS = dvips
@@ -347,32 +324,31 @@ distclean-generic:
 	-rm -f config.cache config.log stamp-h stamp-h[0-9]*
 
 maintainer-clean-generic:
-mostlyclean-am:  mostlyclean-vti mostlyclean-aminfo mostlyclean-generic
+mostlyclean-am:  mostlyclean-aminfo mostlyclean-generic
 
 mostlyclean: mostlyclean-am
 
-clean-am:  clean-vti clean-aminfo clean-generic mostlyclean-am
+clean-am:  clean-aminfo clean-generic mostlyclean-am
 
 clean: clean-am
 
-distclean-am:  distclean-vti distclean-aminfo distclean-generic clean-am
+distclean-am:  distclean-aminfo distclean-generic clean-am
 	-rm -f libtool
 
 distclean: distclean-am
 
-maintainer-clean-am:  maintainer-clean-vti maintainer-clean-aminfo \
+maintainer-clean-am:  maintainer-clean-aminfo maintainer-clean-generic \
-		maintainer-clean-generic distclean-am
+		distclean-am
 	@echo "This command is intended for maintainers to use;"
 	@echo "it deletes files that may require special tools to rebuild."
 
 maintainer-clean: maintainer-clean-am
 
-.PHONY: mostlyclean-vti distclean-vti clean-vti maintainer-clean-vti \
+.PHONY: install-info-am uninstall-info mostlyclean-aminfo \
-install-info-am uninstall-info mostlyclean-aminfo distclean-aminfo \
+distclean-aminfo clean-aminfo maintainer-clean-aminfo tags distdir \
-clean-aminfo maintainer-clean-aminfo tags distdir info-am info dvi-am \
+info-am info dvi-am dvi check check-am installcheck-am installcheck \
-dvi check check-am installcheck-am installcheck install-exec-am \
+install-exec-am install-exec install-data-am install-data install-am \
-install-exec install-data-am install-data install-am install \
+install uninstall-am uninstall all-redirect all-am all installdirs \
-uninstall-am uninstall all-redirect all-am all installdirs \
 mostlyclean-generic distclean-generic clean-generic \
 maintainer-clean-generic clean mostlyclean distclean maintainer-clean
 

src/doc/design/engine.texinfo

@@ -33,9 +33,7 @@ be created as a shared library for use by other programs.
 
 @node Key-Value Pair Frames, Sessions, Globally Unique Identifiers, Engine
 @section Key-Value Pair Frames
-@tindex kvp_frame
+@cindex Key-Value Pairs
-@tindex kvp_value
-@tindex kvp_value_t
 @tindex kvp_list
 
 The number and types of data items which are associated with the
@@ -55,10 +53,61 @@ possible types enumerated in the @code{kvp_value_t} enum which
 indicates the type of data stored in a @code{kvp_value} object.
 Possible @code{kvp_value_t} values and their meanings are:
 
+@menu
+* kvp_frame::                   
+* kvp_value::                   
+@end menu
+
+
+@node kvp_frame, kvp_value, Key-Value Pair Frames, Key-Value Pair Frames
+@subsection kvp_frame
+@tindex kvp_frame
+
+A @code{kvp_frame} is the datatype used to associate key strings with
+@code{kvp_value} objects (@pxref{kvp_value}).
+
+@deftypefun kvp_frame* kvp_frame_new (void)
+Create and initialize a new @code{kvp_frame} object and return
+a pointer to it.
+@end deftypefun
+
+@deftypefun void kvp_frame_delete(kvp_frame * @var{frame})
+Free all memory associated with @var{frame}.
+@end deftypefun
+
+@deftypefun kvp_frame* kvp_frame_copy(const kvp_frame * frame)
+Return a deep copy of @var{frame}.
+@end deftypefun
+
+@deftypefun void kvp_frame_set_slot(kvp_frame * @var{frame}, const char * @var{key}, const kvp_value * @var{value})
+Associate @var{key} with @var{value} in @var{frame}.
+@end deftypefun
+
+@deftypefun kvp_value* kvp_frame_get_slot(kvp_frame * @var{frame}, const char * @var{key})
+Return the @code{kvp_value} object associated with @var{key}
+in @var{frame} or return @code{NULL} if there is no association
+for @var{key}. The value returned is not a copy.
+@end deftypefun
+
+
+@node kvp_value,  , kvp_frame, Key-Value Pair Frames
+@subsection kvp_value
+@tindex kvp_value
+@tindex kvp_value_t
+
+The @code{kvp_value} object stores the 'value' part of a key-value
+association in a @code{kvp_frame} object.
+
+@deftypefun kvp_value_t kvp_value_get_type(const kvp_value * @var{value})
+Return the type of value stored in @var{value}.
+@end deftypefun
+
+A @code{kvp_value_t} enum must have one of the following values:
+
 @table @code
 
 @item KVP_TYPE_NONE
-Indicates the abscence of a value in a kvp_frame.
+Indicates the abscence of a value in a @code{kvp_frame}.
 
 @item KVP_TYPE_INT64
 A @code{gint64} value.
@@ -101,9 +150,8 @@ implies that the associated file is locked.
 
 @item
 Provides a search path for the file to be edited. This should simplify
-install & maintenance problems for naive users who may not have a good
+install & maintenance problems for users who may not have a good grasp
-grasp on what a file ssytem is, or where they want to keep their data
+of what a file system is, or where they want to keep their data files.
-files.
 
 @end itemize
 

src/doc/design/function-index.texinfo

@@ -0,0 +1,4 @@
+@node Function Index, Data Type Index, Reports, Top
+@unnumbered Function Index
+
+@printindex fn

src/doc/design/gnucash-design.texinfo

@@ -88,6 +88,7 @@ of the @cite{GnuCash Design Document}, version @value{VERSION}.
 * Engine::                      
 * Register::                    
 * Reports::                     
+* Function Index::              
 * Data Type Index::
 * Concept Index::
 
@@ -103,6 +104,11 @@ Engine
 * Transactions::                
 * Splits::                      
 
+Key-Value Pair Frames
+
+* kvp_frame::                   
+* kvp_value::                   
+
 Register
 
 * Cells::                       
@@ -122,6 +128,7 @@ Cells
 @include engine.texinfo
 @include register.texinfo
 @include reports.texinfo
+@include function-index.texinfo
 @include type-index.texinfo
 @include concept-index.texinfo
 

src/doc/design/reports.texinfo

@@ -1,4 +1,4 @@
-@node Reports, Data Type Index, Register, Top
+@node Reports, Function Index, Register, Top
 @chapter Reports
 
 To define a report, your report must have 

src/doc/design/type-index.texinfo

@@ -1,4 +1,4 @@
-@node Data Type Index, Concept Index, Reports, Top
+@node Data Type Index, Concept Index, Function Index, Top
 @unnumbered Date Type Index
 
 @printindex tp