GXml: test port of libgdata and documentation

This week has proven interminably long.  Work has surrounded two main tasks

• libgdata port: I'm porting libgdata as a test.  The patch is almost complete, but not quite.  It replaces almost all the libxml2 usage and compiles.  It's volatility means that I'm linking a diff patch rather than pushing it to a repo, as up until Thursday, I was still figuring out how to handle specific cases, or changing my mind on how I was already handling them.  




• memory: I don't have a great understanding of how to handle memory for APIs that were generated through Vala, and I need to review that.  I've learned a lot, but some of the Vala documentation is kind of out-dated, like that on transferring ownership.  Perhaps when GSoC is done I can use what I've learned and update the documentation :D


• namespace support: It isn't part of DOM Level 1 Core that we're implementing, but libgdata uses namespaces, so right now those sections are commented out or ignored.  I will try to implement something in this next week.


• verbosity: While some things are smaller/more concise using GXml, other stuff is more verbose, because libxml2 already has a compact naming "convention".   After writing "gxml_dom_..." a hundred times, I'm considering removing the "_dom_" namespace section, so GXml.Element.get_attribute () will be gxml_element_get_attribute () rather than gxml_dom_element_get_attribute ().  The Dom namespace is there to help separate future work from SAX and XPath, but enough of its classes will be used in other namespaces to justify omitting Dom to me.


• porting guide: I have a text file that outlines common mappings for things, like "how to get a property in GXml" and compares against libxml2.  I'm going to move it onto live.gnome.org when I have time to format it. 




• documentation: with a little bit of help, and a new conceptual understanding of what valadoc's options do, I can now generate documentation.  Each class and method has something written about it now, though some of it is vague, some is inaccurate (!), and some of it could do with examples.  I'll note that I'm annoyed that it complains when I use a double-space after a period. 


• sed: it is my friend.  After hand-porting lots of code for libgdata, I eventually got comfortable enough with the process to start automating it by creating a bunch of sed rules.  That sped things up greatly this past week, though it still left me to manually review and fix the things it missed, which sometimes took extra time because it became hard to see what was originally intended.  Hehe.


• Desktop Summit:









• Hooray!
  
  While I'm only a GSoC student, living in Canada, I wouldn't have been able to afford this myself, so I am incredibly grateful to the GNOME Foundation, since I am
  
  I'll actually be in Germany for about 3 weeks, as my parents are both from Germany and I have many relatives there, and have never been before. 




• I am going to sleep now.  Tomorrow is a big, terrifying day.

GXml, fewer features, more stuff

A summary in bullet points for busy days!

• git.gnome.org: GXml's development is now hosted on git.gnome.org under gxml.


• libxml2: Patching libxml2's VAPI file.  This is hand written rather than generated normally, so I've been adding bindings for functionality I want exposed for gxml.  I should clean it up and post the patch to bugzilla soon, to make sure that I'm making changes appropriately :)


• I/O: Thanks to the above VAPI work, we now have Stream and File support for I/O operations.  For future I/O work, I might add asynchronous support.


• configuration: Spent time figuring out pkg-config and how to generate a .pc file for GXml.  Turns out I just had to hand-write it.  Struggled with passing variables from WAF unless I started guessing.  Hooray!


• documentation: The amount of todos and personal notes in the source code have grown enough and most code is there, such that I started to prioritise documenting stuff this week.  I want to use valadoc, but honestly, I haven't been able to correctly generate the documentation using it yet.  I'm going to start asking for help next week :)  This has had the added bonus of revealing deviations from the spec, which have been being fixed.


• porting libgdata: I'm grateful for all the projects that volunteered their code.  Based on scope of usage, and a bit of nepotism, I'm writing patches for libgdata, a GNOME library primarily used to communicate with Google services.  I contributed to libgdata over a few months in 2009, working on PicasaWeb support, and I still use the library myself.  I asked Philip Withnall if I could just make a branch in the official repository for it, and he said sure.  I spent time this week figuring out how to include libraries compiled from Vala directly into C code (hence the pkg-config work) and have been reviewing its libxml2 usage and playing with changes to figure out what I need to do.  There are features they use that we don't support yet since they're not strictly part of the spec, like getting a string representation of an XML node structure.  I'm starting to realise that I should provide porting guidance once I'm done with this for other interested projects.


• intimidation and quality control: To be honest, having work hosted at gnome.org is pretty intimidating.  It took me a little while at first to get comfortable with committing imperfect changes frequently to my gitorious repository, but my good mentor Alberto Ruiz encouraged me to, to at least demonstrate progress as it was made.  However, previous efforts to submit patches to GNOME projects have generally gone through careful review and revision before being committed, so I've been reluctant this week to commit and push changes like documentation and libgdata toying until I was happy with it.  This won't work, though, as the week is over and because the documentation work still doesn't generate correctly and because I'm not sure whether libgdata changes I'm toying with are what I'll want to keep, code hasn't been pushed for a few days.  I do care about the quality of GNOME's code, and once GXml is sufficiently mature, I'll be much more conservative with the changes I push, but for now for the sake of transparency, I'm going to have to push things even when unready.  Sorry!


• GSoC midterm evaluations: Despite having personal issues this past month and losing productivity for a couple weeks, I've passed my midterm evaluation, indicating support and confidence from my mentor, for which I'm glad.  While life still isn't smooth yet, it is great to be trusted and allowed to continue this awesome project.   Hooray!

This post brought a day late thanks to J. K. Rowling. 

GXml 0.0.1 and Interruptions

GXml (formerly GDom) development was sidetracked for almost two weeks due to personal matters that required my attention and energy, but after discussions with my mentor, things are progressing again.



Since the last blog update, a lot has happened, some of which was reported on gnome-soc-list, and some of which in the last week.

• GXml: We decided to rebrand our effort as GXml, though we're still just implementing the DOM Level 1 Core API.  In the future, GObject SAX and XPath may be provided.


• I/O: We can read files from GInputStreams (given a patch for libxml2's bindings).  We can also save documents to paths, but not yet GOutputStreams, which will require more enhancements to the libxml2 Vala bindings.  (Patches to come.)


• website: https://live.gnome.org/XML was updated, but is now out of date again.  I will update it again this weekend including scheduling information for the rest of the summer.


• bugzilla: we have a 'gxml' bugzilla product now, which I've started to use to manage features to come.  I still need to enter more.


• building: we now use WAF as our build system.  This proved trickier than I expected, but I like how clean the result is.  


• extended coverage: more classes work more fully now, including CharacterData, Text, NodeList, and a few others, and come with fun tests.  Some classes in the API do not seem to have counterparts to wrap in libxml2 (like ProcessingInstruction and EntityReference) and we might have to forego supporting them.  


• first release: while the source code has been available in a gitorious repo since the beginning, I have wrapped up a tarball and uploaded it to my server for today: http://kosmokaryote.org/files/gxml/gxml-0.0.1.tar.bz2.  I've done this entirely so we can migrate to git.gnome.org, which wants at least one release for a new project.  I don't really recommend using it until libxml2 binding patches are available, though, so GIO can be used rather than file system paths.


• project port: my request for volunteer projects from yesterday got a good response and I'm going to look at them this weekend and then decide by Monday which I'd like to use.  Thank you for your helpful responses!


• libxml2 bindings: I'll need to submit patches for the libxml2 bindings so GXml can implement some of the features we want.  For example, I've been intent on using xmlSaveToIO to get an xmlSaveCtxtPtr, since it aligns well with GOutputStream's methods, but those two libxml2 items aren't bound yet.

Thanks for reading and have a good weekend.



Update:

I linked the wrong tarball.  It's the same contents, but the tarball should be gxml, not gdom, and be generated by distcheck, not by hand.  The link has been updated. 

Wanted: software to port to GXml

Hello GNOMEys.



GXml is pretty functional now, and it's time to start exercising it in a real-world situation.  I'm looking for a GNOMEy project which makes liberal use of an XML DOM via libxml2, and might be interested in seeing how GXml's GObject API could make life easier.



If you'd like to suggest your project, you're not under an obligation to accept the resulting patches if they don't meet your needs (though they will be irresistable), you don't need to do much work (though I might ask a few questions), you help ensure the usefulness of this Google Summer of Code project and help improve XML programming in GNOME.



Preferably, your project will be mainly in Vala or C.  GXml itself is being written in Vala.  XML use should be important to your project.



A first release, 0.0.1, will be out this week.  I had a Life Situation slow progress for two of the past weeks, but things are sailing smooth once more.  A status update comes tomorrow.



Cheerio!