Created attachment 21432 [details] [review]
proposed docs edits patch

Applied and committed, docs regenerated.  For your future reference, 
should be able to just cd doc, make rebuild, make web (but then 
again, I'm not sure I fully understand it either :-)

I'd done the "make rebuild", didn't try "make web". But when I did it
just now, I ended up with broken docs, much missing content, and I
haven't had/taken the time to understand why.

William -
I checked out your changes and see that the build problems that made
me unwilling to check in myself happened to you when you rebuilt the docs:

doc/html/index.html lost all its text (it's just an empty formatted file)
doc/html/libxml-tree.html doesn't reflect the changes I made to the
comments.

This suggests that whatever is going wrong when I do the build, also
is going wrong when you do the build.

John -
  Ok, I'll go into it tomorrow (it's midnight now) and let you know 
what I did wrong.

I spent quite a bit of time, and finally decided that some manual 
action is required.  I committed a new file doc/docdescr.doc which
attempts to explain the process.  Basically, the gtkdoc scripts are 
used to generate this stuff, and the sequence is
  gtkdoc-scan (generates libxml-*.txt)
  gtkdoc-mktmpl (generates templates)
  gtkdoc-mkdb (generates an xml file which controls the html gen)

At this point the output file (gnome-xml.xml) needs to be manually 
edited to put in the manual and chapter heading.  Then, continuing,
  gtkdoc-mkhtml (generates the html pages for the functions)
This last script also generates an index.html, but it doesn't have 
what we want.  So, again manually, a better version (kept in CVS) is 
substituted for the generated one (i.e. just delete the file 
generated by the script).

I don't like this whole thing, and am really afraid I missed 
something along the way (but there is practically no documentation 
that I can find to guide me), but in any event I think the web site 
should be ok once again.

Bill -

This is fabulous, thanks. I added what little additional information I
know (the man page building) and I'll use your directions to see if I
can get a handle on where the problems are occurring in my build
setup, as I still can't seem to get the docs building right (my
changes to tree.c still don't seem to be showing up in the built docs
for me).

OK, finally found (through "brute force" techniques, and in less 
than a day's work) where the *!@# problem happens.  Trouble occurs 
in gtkdoc-scan when the libxml include files are scanned.  To cater 
for that OS from the NW US, we have put in two macros (XMLPUBFUN and 
XMLCALL) which are not recognized by gtkdoc, and cause *all* of the 
public functions to be silently dropped :-(.  In the longer term, we 
must either enhance the gtkdoc-scan script, or else replace steps 1-
4 with a completely different approach.  For the short term, I wrote 
a small python script to remove the macros from the include files.  
If you want to do it for yourself (and I *greatly* encourage you to 
take over as much as possible of the doc stuff), make a backup copy 
of include/libxml, then run this script in that directory:

#!/usr/bin/python -u
import glob
import string
import sys

mylist=glob.glob('./*.h')
for file in mylist:
  curfile = open(file,'r')
  tempfile = []
  for line in curfile.readlines():
      line = string.replace(line,'XMLPUBFUN ','')
      line = string.replace(line,'XMLCALL','')
      tempfile.append(line)
  curfile.close()
  curfile = open(file,'w')
  for line in tempfile:
      curfile.write(line)
  curfile.close()

After that, from the doc directory, make scan, make templates, make 
xml, edit the gnome-xml.xml file to put in the right titles, make 
html, and rm html/index.html. (I told you it was messy, didn't I?)

I'll discuss further with Daniel about the longer term.

grumbles ...
gtk-doc is really getting in the way at this point.
we have code to parse header and C files, it's in python,
the gtk-doc are becoming redundant, the obvious solution
seems to simply ditch gtk-doc and regenerate everything
ourselves, which should not bee too hard since all the
hard part of parsing and data extraction is already done
by python scripts.
Actually I think all the XML and HTML generated by the
gtk-doc can be (nearly) trivially replaced by XSLT stylesheets
running on the libxml2-api.xml we generate. It has all the
data we need.

Daniel

Tested Bill's python script, followed by the recipe in docdescr.doc,
and the test change I made in the source comment in a *.c file
successfully showed up in the resulting api html file. Thanks, Bill.

A new approach (using an xslt transformation with doc/newapi.xsl) 
has now been implemented and fixes this problem.

This should be closed now,

Daniel