gnome-libs/devel-docs et al (hello, and long)

[Steve Haslam <araqnid debian org>]

Hi people,

Before I start, please allow me to introduce myself- I'm a Debian
developer, and I'm the maintainer for some fundamental Gnome packages,
including orbit, gnome-libs, gnome-core, control-center and gdm. I
thought it was high time I disengaged lurk mode here and said who I
am....

Unfortunately, I'm going to start off with a bit of a moan about the
documentation section of gnome-libs... I just can't get it to make
cleanly, and once I installed the gtk-doc tools, things didn't seem to 
get any better...

Some of it may be due to me (us) having different style sheets to what 
the authors of the 'Makefile.am's intended, but basically, the
problems come down to:

gnome-dev-info.html- refers to a load of other files in the
gnome-dev-info directory, which don't get installed. I'm using
"db2html" from the cygnus-stylesheets package, and it generates 80 or
so HTML files. Is the stylesheet supposed to only generate one?  But
the dist-hook seems to imply the existence of the gnome-dev-info
directory, because it carefully uses tar to copy things. (And surely
ought to be copying $(srcdir)/gnome-dev-info anyway).

In the CVS directory, I notice that there are three .jpg files that
are referenced from gnome-dev-info.sgml. However, these aren't in the
tarball (1.0.pre10), and aren't registered with -kb in CVS (I guess
this is just fussy)... And gnome-app-helper.sgml is listed twice in
EXTRA_DIST.

Also, where/what is the gdoc tool? Do I want to package that up too?
it's referenced from the Makefile, but it's not in gtk-doc, and again
isn't in the tarball... I've found tools/gnome-doc which seems to
refer to itself as gdoc at one point, is this relevant? As far as I
can tell, it has to be made from c2man source...

The 'Makefile.am' files in gnome/ and gnomeui/ are painful. What I get
from them is:

test -d ./html || mkdir ./html
cd ./html && gtkdoc-mkhtml gnome ../gnome-docs.sgml
jade:E: cannot find "../gnome-docs.sgml"; tried "../gnome-docs.sgml", "/usr/local/share/sgml/../gnome-docs.sgml", "/usr/local/lib/sgml/../gnome-docs.sgml", "/usr/lib/sgml/../gnome-docs.sgml"
<splurge...>

And this leaves me with a gnome.html with broken anchors...

Copying in gnome-docs.sgml from CVS to devel-docs/gnome seems to
remove the first jade error message, although I still have others :

jade:../sgml/gnome-config.sgml:103:6:E: document type does not allow element "SECT2" here
jade:../sgml/gnome-config.sgml:157:6:E: document type does not allow element "SECT2" here
jade:../sgml/gnome-i18n.sgml:54:29:E: character ":" is not allowed in the value of attribute "LINKEND"
jade:../sgml/gnome-metadata.sgml:75:9:E: character ":" is not allowed in the value of attribute "LINKEND"
jade:/usr/lib/sgml/stylesheet/dsssl/gtk-doc//gtk-doc.dsl:90:7:E: reference to undefined variable "$verbatim-content-with-linenumbers$"
jade:/usr/lib/sgml/stylesheet/dsssl/gtk-doc//gtk-doc.dsl:91:7:E: reference to undefined variable "$verbatim-content$"
jade:/usr/lib/dsssl/stylesheets/docbook/html/dbverb.dsl:162:24:E: too many arguments for function
jade:/usr/lib/dsssl/stylesheets/docbook/html/dbverb.dsl:158:24:E: too many arguments for function
jade:/usr/lib/dsssl/stylesheets/docbook/html/dbsynop.dsl:136:26:E: too many arguments for function
jade:/usr/lib/dsssl/stylesheets/docbook/html/dbsynop.dsl:9:18:E: too many arguments for function

So, I thing there wants to be a script to fix up HREFs in generated
.html files that are "pulled out" of the gtkdoc-mkhtml/db2html
directories. Also, the HTML files in the generated directoies will
still reference "book1.html", so this needs to be changed too. I've
come up with a little something to do this, which I'll attach.

Also, I notice that devel-docs/gnome installs two text files in
/usr/share/gnome/html... er, is this intentional? It just seems an odd
place...

Anyway, I'll stop here and try giving it all a build. I appreciate
that documentation tends to take a lower priority that actual coding,
and I apologise if people feel I'm slagging them off because it isn't
all working for me... I'm happy to help out writing 'Makefile.am's,
scripts etc. to improve the system if that's wanted...

SRH
-- 
Steve Haslam               Debian GNU/Linux               araqnid@debian.org
gnome-libs, gnome-core, gnome-control-center, gdm, p3nfs.    what, me worry?
diff -x *~ -P -r -u ../../vanilla/devel-docs/Makefile.am /home/steve/gnome/gnome-libs/gnome-libs-1.0.9+pre10/devel-docs/Makefile.am
--- ../../vanilla/devel-docs/Makefile.am	Mon May 24 16:42:21 1999
+++ /home/steve/gnome/gnome-libs/gnome-libs-1.0.9+pre10/devel-docs/Makefile.am	Thu May 27 21:25:43 1999
@@ -5,6 +5,7 @@
 
 gnome-dev-info.html: gnome-dev-info/book1.html
 	-cp $(srcdir)/gnome-dev-info/book1.html gnome-dev-info.html
+	perl -w fix_hrefs gnome-dev-info
 
 gnome-dev-info/book1.html: gnome-dev-info.sgml libgnomeui.sgml libgnome.sgml
 	-(cd $(srcdir); db2html gnome-dev-info.sgml) > /dev/null
diff -x *~ -P -r -u ../../vanilla/devel-docs/fix_hrefs /home/steve/gnome/gnome-libs/gnome-libs-1.0.9+pre10/devel-docs/fix_hrefs
--- ../../vanilla/devel-docs/fix_hrefs	Thu Jan  1 01:00:00 1970
+++ /home/steve/gnome/gnome-libs/gnome-libs-1.0.9+pre10/devel-docs/fix_hrefs	Thu May 27 21:25:34 1999
@@ -0,0 +1,51 @@
+#!/usr/bin/perl -w
+
+require 5;
+use strict;
+
+my $modulename = shift;
+
+fixtoplevel($modulename, "$modulename.html");
+my $subdir = $modulename;
+if (! -d $subdir) {
+  $subdir = "html";
+  if (! -d $subdir) {
+    die "Can't find a \"$modulename\" or a \"html\" subdirectory\n";
+  }
+}
+fixsublevels($modulename, glob "$subdir/*.html");
+
+sub fixtoplevel {
+  my $modulename = shift;
+  my $htmlfile = shift;
+  
+  open(IN, $htmlfile) || die "Can't read $htmlfile: $!\n";
+  unlink $htmlfile;
+  open(OUT, ">$htmlfile") || die "Can't write $htmlfile: $!\n";
+  
+  while (<IN>) {
+    s{^href=\"([^/]+\.(html|jpg|png))\"}{href=\"$modulename/$1\"}i;
+    print OUT;
+  }
+  close IN;
+  close OUT;
+}
+
+sub fixsublevels {
+  my $modulename = shift;
+  my @htmlfiles = @_;
+  
+  my $htmlfile;
+  foreach $htmlfile (@htmlfiles) {
+    open(IN, $htmlfile) || die "Can't read $htmlfile: $!\n";
+    unlink $htmlfile;
+    open(OUT, ">$htmlfile") || die "Can't write $htmlfile: $!\n";
+  
+    while (<IN>) {
+      s{^href=\"book1.html\"}{href=\"../$modulename.html\"}i;
+      print OUT;
+    }
+    close IN;
+    close OUT;
+  }
+}
diff -x *~ -P -r -u ../../vanilla/devel-docs/gnome/Makefile.am /home/steve/gnome/gnome-libs/gnome-libs-1.0.9+pre10/devel-docs/gnome/Makefile.am
--- ../../vanilla/devel-docs/gnome/Makefile.am	Mon May 24 16:42:21 1999
+++ /home/steve/gnome/gnome-libs/gnome-libs-1.0.9+pre10/devel-docs/gnome/Makefile.am	Thu May 27 21:29:38 1999
@@ -47,6 +47,7 @@
 if HAVE_GTK_DOC
 gnome.html: html/book1.html
 	-cd $(srcdir) && cp html/book1.html gnome.html
+	perl -w ../fix_hrefs gnome
 else
 gnome.html:
 endif
@@ -95,7 +96,7 @@
 	  echo '-- Installing $(srcdir)/html/index.sgml' ; \
 	  $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR); \
 	  echo '-- Fixing Crossreferences' ; \
-	  gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR) || true; \
+	  gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(DESTDIR)$(HTML_DIR) || true; \
 	fi)
 
 dist-hook:
diff -x *~ -P -r -u ../../vanilla/devel-docs/gnomeui/Makefile.am /home/steve/gnome/gnome-libs/gnome-libs-1.0.9+pre10/devel-docs/gnomeui/Makefile.am
--- ../../vanilla/devel-docs/gnomeui/Makefile.am	Mon May 24 16:42:22 1999
+++ /home/steve/gnome/gnome-libs/gnome-libs-1.0.9+pre10/devel-docs/gnomeui/Makefile.am	Thu May 27 21:29:48 1999
@@ -106,6 +106,7 @@
 if HAVE_GTK_DOC
 gnomeui.html: html/book1.html
 	-cd $(srcdir) && cp html/book1.html gnomeui.html
+	perl -w ../fix_hrefs gnomeui
 else
 gnomeui.html:
 endif
@@ -152,7 +153,7 @@
 	  echo '-- Installing $(srcdir)/html/index.sgml' ; \
 	  $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR); \
 	  echo '-- Fixing Crossreferences' ; \
-	  gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR)|| true; \
+	  gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(DESTDIR)$(HTML_DIR)|| true; \
 	fi)
 
 dist-hook:

PGP signature