Fix up doc comments not to have obvious errors that gtk-doc barfs on.

Sun Oct 29 01:27:39 2000  Owen Taylor  <otaylor@redhat.com>

	* pango/pangoft2-fontcache.c pango/pangoft2.[ch]
	pango/pangowin32.h: Fix up doc comments not to
	have obvious errors that gtk-doc barfs on. Correct
	parameter descriptions still need to be filled in.

	* configure.in pango/docs/Makefile.am: upgrade to
	have a real install rule, etc.

	* pango/docs/pango-sections.txt: Add various missing
	functions.

9 files changed, 293 insertions, 43 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 7e8074fc..b4fd8669 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,59 +1,125 @@
 ## Process this file with automake to create Makefile.in.
 
-pangoheaders = 	   	   		\
-	../pango/pango.h   		\
-	../pango/pango-attributes.h	\
-	../pango/pango-context.h	\
-	../pango/pango-coverage.h	\
-	../pango/pango-engine.h		\
-	../pango/pango-font.h       	\
-	../pango/pango-fontmap.h	\
-	../pango/pango-glyph.h	   	\
-	../pango/pango-item.h	   	\
-	../pango/pango-layout.h	   	\
-	../pango/pango-types.h	   	\
-	../pango/pangox.h	
-
-if HAVE_GTK_DOC
-
 # The name of the module.
 DOC_MODULE=pango
 
 # The top-level SGML file.
 DOC_MAIN_SGML_FILE=pango-docs.sgml
 
-SOURCE_DIR=../pango
+# The directory containing the source code
+DOC_SOURCE_DIR=$(top_srcdir)/pango
+
+# Extra options to supply to gtkdoc-fixref
+FIXXREF_OPTIONS=
+
+# Headers to ignore
+IGNORE_HFILES=			\
+	modules.h		\
+	pango-utils.h		\
+	pangoft2-private.h	\
+	pangowin32-private.h	\
+	pangox-private.h
+
+tmpl_sources =				\
+	tmpl/coverage-maps.sgml		\
+	tmpl/engines.sgml		\
+	tmpl/fonts.sgml			\
+	tmpl/freetype-fonts.sgml	\
+	tmpl/glyphs.sgml		\
+	tmpl/layout.sgml		\
+	tmpl/main.sgml			\
+	tmpl/modules.sgml		\
+	tmpl/tab-stops.sgml		\
+	tmpl/text-attributes.sgml	\
+	tmpl/win32-fonts.sgml		\
+	tmpl/x-fonts.sgml		\
+	tmpl/x-rendering.sgml
+
+
+####################################
+# Everything below here is generic #
+####################################
+
+TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
+
+EXTRA_DIST = 				\
+	$(DOC_MAIN_SGML_FILE)		\
+	$(DOC_MODULE)-decl.txt		\
+	$(DOC_MODULE)-sections.txt	\
+	$(DOC_MODULE)-overrides.txt
+
+if ENABLE_GTK_DOC
+all-local: html/index.html
+
+$(DOC_MODULE)-decl.txt: 
+	$(MAKE) scan
+
+$(tmpl_sources): $(DOC_MODULE)-decl.txt $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
+	$(MAKE) templates
+
+sgml/$(DOC_MODULE)-doc.bottom: $(tmpl_sources) $(DOC_MODULE)-decl.txt
+	$(MAKE) sgml
+
+html/index.html: sgml/$(DOC_MODULE)-doc.bottom $(DOC_MAIN_SGML_FILE)
+	$(MAKE) html
+endif
 
 scan:
-	gtkdoc-scan --module=$(DOC_MODULE) $(pangoheaders)
+	-(cd $(srcdir) \
+	&& gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" )
 
-templates: scan
-	gtkdoc-mktmpl --module=$(DOC_MODULE)
+templates: 
+	cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
 
 sgml:
-	gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(SOURCE_DIR)
+	cd $(srcdir) \
+	&& gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR)
 
 html:
-	if ! test -d html ; then mkdir html ; fi
-	-cd html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
-	cp layout.gif html
+	test -d $(srcdir)/html || mkdir $(srcdir)/html
+	-cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+	@echo '-- Fixing Crossreferences' 
+	cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
 
 clean-local:
-	rm -f *~ *.bak *.hierarchy *.signals *.args *-unused.txt
+	rm -f *~ *.bak *.signals *-unused.txt
 
 maintainer-clean-local: clean
-	rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt 
+	cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
 
-.PHONY: scan sgml html templates 
+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
 
-EXTRA_DIST=pango-sections.txt pango-docs.sgml layout.fig layout.eps layout.fig
-
-dist-hook:
+dist-hook: dist-check-gtkdoc
 	mkdir $(distdir)/tmpl
-	cp -p $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
-	mkdir $(distdir)/TEXT
-	for i in $(srcdir)/TEXT/* ; do 			\
-	  test -f $$i && cp -p $$i $(distdir)/TEXT ;	\
-        done
+	mkdir $(distdir)/sgml
+	mkdir $(distdir)/html
+	-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
+	-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
+	-cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml
+	-cp $(srcdir)/html/index.sgml $(distdir)/html
+	-cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html
+
+.PHONY : html sgml templates scan
diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
index a95ba085..6fb0cd0b 100644
--- a/docs/pango-docs.sgml
+++ b/docs/pango-docs.sgml
@@ -9,7 +9,7 @@
 <!entity x-fonts SYSTEM "sgml/x-fonts.sgml">
 <!entity x-rendering SYSTEM "sgml/x-rendering.sgml">
 ]>
-<book>
+<book id="index">
   <bookinfo>
     <title>Pango Reference Manual</title>
   </bookinfo>
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index c8d4ee62..a863276c 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -36,6 +36,7 @@ PANGO_IS_CONTEXT_CLASS
 PANGO_CONTEXT_GET_CLASS
 <SUBSECTION>
 pango_break
+pango_get_log_attrs
 PangoLogAttr
 <SUBSECTION>
 pango_shape
@@ -80,6 +81,8 @@ pango_coverage_copy
 pango_coverage_get
 pango_coverage_max
 pango_coverage_set
+pango_coverage_to_bytes
+pango_coverage_from_bytes
 </SECTION>
 
 <SECTION>
@@ -138,6 +141,7 @@ PangoAttrString
 PangoAttrColor
 PangoAttrInt
 PangoAttrFontDesc
+PangoAttrShape
 pango_attr_type_register
 pango_attribute_copy
 pango_attribute_compare
@@ -155,6 +159,7 @@ pango_attr_foreground_new
 pango_attr_background_new
 pango_attr_strikethrough_new
 pango_attr_underline_new
+pango_attr_shape_new
 PangoUnderline
 pango_attr_rise_new
 <SUBSECTION>
@@ -166,6 +171,7 @@ pango_attr_list_copy
 pango_attr_list_insert
 pango_attr_list_insert_before
 pango_attr_list_change
+pango_attr_list_splice
 pango_attr_list_get_iterator
 PangoAttrIterator
 pango_attr_iterator_copy
@@ -177,6 +183,23 @@ pango_attr_iterator_destroy
 </SECTION>
 
 <SECTION>
+<TITLE>Tab Stops</TITLE>
+<FILE>tab-stops</FILE>
+PangoTabArray
+PangoTabAlign
+pango_tab_array_new
+pango_tab_array_new_with_positions
+pango_tab_array_copy
+pango_tab_array_free
+pango_tab_array_get_size
+pango_tab_array_resize
+pango_tab_array_set_tab
+pango_tab_array_get_tab
+pango_tab_array_get_tabs
+pango_tab_array_get_positions_in_pixels
+</SECTION>
+
+<SECTION>
 <TITLE>Layout Objects</TITLE>
 <FILE>layout</FILE>
 PangoLayout
@@ -198,6 +221,8 @@ pango_layout_set_justify
 pango_layout_get_justify
 pango_layout_set_alignment
 pango_layout_get_alignment
+pango_layout_get_tabs
+pango_layout_set_tabs
 PangoAlignment
 
 pango_layout_get_log_attrs
@@ -255,6 +280,16 @@ script_engine_unload
 </SECTION>
 
 <SECTION>
+<TITLE>Modules</TITLE>
+<FILE>modules</FILE>
+PangoMap
+PangoMapEntry
+pango_find_map
+pango_map_get_entry
+pango_map_get_engine
+</SECTION>
+
+<SECTION>
 <TITLE>X Rendering</TITLE>
 <FILE>x-rendering</FILE>
 PANGO_RENDER_TYPE_X
@@ -288,3 +323,67 @@ pango_x_font_cache_free
 pango_x_font_cache_load
 pango_x_font_cache_unload
 </SECTION>
+
+<SECTION>
+<TITLE>Win32 Fonts and Rendering</TITLE>
+<FILE>win32-fonts</FILE>
+PANGO_RENDER_TYPE_WIN32
+pango_win32_get_context
+pango_win32_load_font
+pango_win32_render
+pango_win32_render_layout_line
+pango_win32_render_layout
+PangoWin32UnicodeSubrange
+pango_win32_unicode_classify
+PangoWin32Subfont
+PANGO_WIN32_MAKE_GLYPH
+PANGO_WIN32_GLYPH_SUBFONT
+PANGO_WIN32_GLYPH_INDEX
+pango_win32_list_subfonts
+pango_win32_has_glyph
+pango_win32_get_unknown_glyph
+PangoWin32FontCache
+pango_win32_font_cache_new
+pango_win32_font_cache_free
+pango_win32_font_cache_load
+pango_win32_font_cache_unload
+pango_win32_font_map_for_display
+pango_win32_shutdown_display
+pango_win32_font_map_get_font_cache
+pango_win32_font_subfont_logfont
+pango_win32_fontmap_dump
+
+<SUBSECTION Private>
+STRICT
+</SECTION>
+
+<SECTION>
+<TITLE>FreeType Fonts and Rendering</TITLE>
+<FILE>freetype-fonts</FILE>
+PANGO_RENDER_TYPE_FT2
+pango_ft2_get_context
+pango_ft2_load_font
+pango_ft2_render
+pango_ft2_render_layout_line
+pango_ft2_render_layout
+PangoFT2Subfont
+PANGO_FT2_MAKE_GLYPH
+PANGO_FT2_GLYPH_SUBFONT
+PANGO_FT2_GLYPH_INDEX
+pango_ft2_n_subfonts
+pango_ft2_has_glyph
+pango_ft2_get_unknown_glyph
+pango_ft2_font_get_kerning
+PangoFT2FontCache
+pango_ft2_font_cache_new
+pango_ft2_font_cache_free
+pango_ft2_font_cache_load
+pango_ft2_font_cache_unload
+pango_ft2_font_map_for_display
+pango_ft2_shutdown_display
+pango_ft2_font_map_get_font_cache
+pango_ft2_font_subfont_open_args
+pango_ft2_fontmap_dump
+<SUBSECTION Private>
+STRICT
+</SECTION>
diff --git a/docs/tmpl/coverage-maps.sgml b/docs/tmpl/coverage-maps.sgml
index 1793ab8d..8cde2ac9 100644
--- a/docs/tmpl/coverage-maps.sgml
+++ b/docs/tmpl/coverage-maps.sgml
@@ -104,3 +104,23 @@ point to #PangoCoverageLevel. It is an opaque structure with no public fields.
 @level: 
 
 
+<!-- ##### FUNCTION pango_coverage_to_bytes ##### -->
+<para>
+
+</para>
+
+@coverage: 
+@bytes: 
+@n_bytes: 
+
+
+<!-- ##### FUNCTION pango_coverage_from_bytes ##### -->
+<para>
+
+</para>
+
+@bytes: 
+@n_bytes: 
+@Returns: 
+
+
diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml
index 01007dd2..502286ad 100644
--- a/docs/tmpl/fonts.sgml
+++ b/docs/tmpl/fonts.sgml
@@ -48,8 +48,12 @@ An enumeration specifying the weight (boldness) of a font. This is a numerical
 value ranging from 100 to 900, but there are two predefined values:
 </para>
 
+@PANGO_WEIGHT_ULTRALIGHT: 
+@PANGO_WEIGHT_LIGHT: 
 @PANGO_WEIGHT_NORMAL: the default weight (= 400)
 @PANGO_WEIGHT_BOLD: the bold weight (= 700)
+@PANGO_WEIGHT_ULTRABOLD: 
+@PANGO_WEIGHT_HEAVY: 
 
 <!-- ##### ENUM PangoVariant ##### -->
 <para>
diff --git a/docs/tmpl/layout.sgml b/docs/tmpl/layout.sgml
index f4b0fdc0..9ca78964 100644
--- a/docs/tmpl/layout.sgml
+++ b/docs/tmpl/layout.sgml
@@ -192,6 +192,24 @@ fields.
 @Returns: 
 
 
+<!-- ##### FUNCTION pango_layout_get_tabs ##### -->
+<para>
+
+</para>
+
+@layout: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_layout_set_tabs ##### -->
+<para>
+
+</para>
+
+@layout: 
+@tabs: 
+
+
 <!-- ##### ENUM PangoAlignment ##### -->
 <para>
 describes how to align the lines of a #PangoLayout within the
diff --git a/docs/tmpl/main.sgml b/docs/tmpl/main.sgml
index a3458d59..a8f37c15 100644
--- a/docs/tmpl/main.sgml
+++ b/docs/tmpl/main.sgml
@@ -328,6 +328,18 @@ for text.
 @attrs: 
 
 
+<!-- ##### FUNCTION pango_get_log_attrs ##### -->
+<para>
+
+</para>
+
+@text: 
+@length: 
+@level: 
+@language: 
+@log_attrs: 
+
+
 <!-- ##### STRUCT PangoLogAttr ##### -->
 <para>
 The #PangoLogAttr structure stores information
diff --git a/docs/tmpl/pango-unused.sgml b/docs/tmpl/pango-unused.sgml
index 14e3d1d4..60f815a4 100644
--- a/docs/tmpl/pango-unused.sgml
+++ b/docs/tmpl/pango-unused.sgml
@@ -353,13 +353,6 @@ the X Window system.
 @trailing: 
 @x_pos: >>>>>>> 1.8
 
-<!-- ##### TYPEDEF PangoGlyphIndex ##### -->
-<para>
-The #PangoGlyphIndex type is an integral type used to store glyph
-indices.
-</para>
-
-
 <!-- ##### FUNCTION pango_x_glyph_extents ##### -->
 <para>
 
@@ -375,6 +368,13 @@ indices.
 @logical_ascent: 
 @logical_descent: 
 
+<!-- ##### TYPEDEF PangoGlyphIndex ##### -->
+<para>
+The #PangoGlyphIndex type is an integral type used to store glyph
+indices.
+</para>
+
+
 <!-- ##### SECTION ./tmpl/pango-x.sgml:See_Also ##### -->
 <para>
 
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
index d274d388..0bf3ea3b 100644
--- a/docs/tmpl/text-attributes.sgml
+++ b/docs/tmpl/text-attributes.sgml
@@ -40,6 +40,7 @@ attribute is listed in parentheses after the description.
 @PANGO_ATTR_UNDERLINE: whether the text has an underline (#PangoAttrInt)
 @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through (#PangoAttrInt)
 @PANGO_ATTR_RISE: baseline displacement (#PangoAttrInt)
+@PANGO_ATTR_SHAPE: 
 
 <!-- ##### STRUCT PangoAttrClass ##### -->
 <para>
@@ -106,6 +107,15 @@ sets all aspects of the font description at once.
 @attr: the common portion of the attribute
 @desc: the font description which is the value of this attribute
 
+<!-- ##### STRUCT PangoAttrShape ##### -->
+<para>
+
+</para>
+
+@attr: 
+@ink_rect: 
+@logical_rect: 
+
 <!-- ##### FUNCTION pango_attr_type_register ##### -->
 <para>
 
@@ -254,6 +264,16 @@ sets all aspects of the font description at once.
 @Returns: 
 
 
+<!-- ##### FUNCTION pango_attr_shape_new ##### -->
+<para>
+
+</para>
+
+@ink_rect: 
+@logical_rect: 
+@Returns: 
+
+
 <!-- ##### ENUM PangoUnderline ##### -->
 <para>
 the #PangoUnderline enumeration is used to specify
@@ -356,6 +376,17 @@ for more than one paragraph of text.
 @attr: 
 
 
+<!-- ##### FUNCTION pango_attr_list_splice ##### -->
+<para>
+
+</para>
+
+@list: 
+@other: 
+@pos: 
+@len: 
+
+
 <!-- ##### FUNCTION pango_attr_list_get_iterator ##### -->
 <para>