GNOME Bugzilla – Bug 126945
tree.c API docs updates
Last modified: 2009-08-15 18:40:50 UTC
Minor edits to API docs in tree.c to: xmlNewNode xmlNewNodeEatName xmlNewChild xmlNewTextChild xmlGetLineNo xmlReplaceNode Because I don't understand Daniel's docs-building mojo, I'm attaching a diff file as a patch, as I was unsuccessful in testing the docs build and therefore unable to be sure I was getting the API doc syntax stuff right.
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