At long last, I have managed to create an ebuild for the repodoc web service and its sample client. This should help all interested Gentoo devs in installing it and giving us feedback. If your overlay is located at /usr/local/portage, you must first build the Manifest: ebuild /usr/local/portage/www-apps/repodoc-web-0.0.1_alpha.ebuild digest’. After that, emerge repodoc-web’ should do the trick.

But that’s not all. As the post-install instructions say, you must do two more things before you can start using the service.

1. Change the first 2 define lines in validate/index.php:
   define(‘HTDOCS’, ‘/path/to/htdocs’);
   define(‘REPODOC’, ‘/path/to/repodoc/executable’);Please note that the service will work well only with the latest GIT checkout of repodoc from Ferdy’s repository. The repodoc-0.0.1_beta ebuild will still work, although the output may not be as predicted as there are module changes between the ebuild and GIT versions.
2. You need to create the /.repodoc directory and assign its ownership to the web server (usually ‘apache’ or ‘nobody’). This step could not be included in the ebuild because of access violations. This is strictly a repodoc requirement and not related to the web-service. The repodoc team and myself will be working on a solution for this soon.

Once you’ve done these two steps, you may access the client at http://localhost/repodoc-web. Select a GuideXML file and click on Validate to get a tabulated result of the validation.

Now, I’d like to point out that the system is far from perfect. There are two basic issues that I need to tackle:

1. Eliminating the modify define lines’ step since webapp.eclass knows the location of htdocs. Also repodoc is usually at /usr/bin/repodoc, but this is not entirely true if you’re not using the ebuild and just the GIT version.
2. Error Handling for non GuideXML files. Trying to validate a non GuideXML file will result in a non-helpful error message. Proper handling is necessary here.

Well, of course these aren’t the only flaws, so I’d love to hear about what you have to say about everything!

Building the ebuild was quite tricky, considering this is the first one I’ve made. The webapp and depend.php eclasses made things a little easier. The webapp eclass was nicely documented, and looking at other ebuilds like phpmyadmin or tikiwiki also helped quite a bit.

On other news, I was frantically trying to finalize on a particular AJAX toolkit. After further discussion with Stuart, who very kindly let me make the choice, it looks like we’ll go with Dojo. Although I’m not entirely sure yet. I’ve seen better eye-candy with Echo2, another Java based toolkit. Also, GWT is out because of licensing problems. Apparently, the license states that:

“you may not distribute Google Web Toolkit Development Tools or any services or software associated with or derived from them, or modify, copy, license, or create derivative works from Google Web Toolkit Development Tools, unless you obtain Google’s written permission in advance.”

Quite a day, I’m still undecided on the toolkit, but atleast I can sleep with the comfort of having written my first ebuild. Go Gentoo!

So, I’ve been pondering over how exactly the editor is going to be implemented. I’ve decided not to use any of the existing web-based WYSIWYG editors, but rather use one of the AJAX toolkits out there to build the whole application. I’ve narrowed it down to 3 choices, and here they are, in order of my preference:

1) Google Web Toolkit - Yep, it’s a Google product, so it should be quite fun to use! They have the good old swing-type widget concept here, so the main editor would consist of a custom widget that I will extend from the basic textarea. Yeah, if you notice, I will have to code in Java, which is not a problem for me at all. Before you arrive at any wrong conclusions, I would like to make it clear that GWT uses Java classes only as a base to generate code. The end-result is pure JavaScript + XHTML that can work with any server-side language (which in our case, is PHP). The advantages I see here are: support for a wide variety of browsers, a good solution for the triple-b (Browser Back Button) problem, and a robust framework to lean on.

2) Yahoo UI Library – Ok, so I mentioned Google, it would be unfair not to mention the competition. The Yahoo UI library is damn stable and widely used (it’s not in “beta” like most of Google’s products!). Rich widget library, although building a custom editor widget here would be much tougher. Great effects, cool CSS and design patterns to go along. Pretty much everything to get the editor up and running.

3) Dojo – I don’t know why, but this reminds me of Django. Well Dojo uses the Moxie editor, which is to be modified to handle GuideXML instead of plain HTML. One thing that caught my eye here was the persistent storage functionality, that would allows users to temporarily save the document they are editing, on the server. I’m not sure we want that feature in the editor, but even otherwise, this toolkit is quite interesting.

Other than these 3, there is also Rico and Mochikit. This is the worst part about FLOSS, there’s just too much choice! Although my scales tip heavily towards the GWT ( this being the Google Summer of Code and all ); I plead all of you to please send me your opinion of what toolkit would be the best fit for the project.

Okay, so I got together a decent client for all of you to test out the repodoc web service. It's pretty basic, just about 35 lines of code, uses the cURL and XSL extensions of PHP5, and displays a tabulated page that shows how tha validation went. I haven't concentrated too much on the eye-candy yet, I'm waiting until I decide on a nice theme for the editor itself.

Check out the client, the upload form, and a sample result file.

Meanwhile, I'm steadily moving on the ebuild, it should be done now that the client is ready. I'm also going through "AJAX Patterns and Best Practices" to see which pattern applies to the editor the best. Needless to say, if any of you have ideas, comments, suggestions or cristicisms, be sure to send them my way

Okay, instead of hanging around waiting for the infra, I thought I'd just post the source so that my mentors and the community in general, can poke around and scrutinize the script So here are the links:

The Web-Service Script
A bare-bones result file, No errors
The schema for the result file
A sample repodoc log, which is parsed by the script

All comments, suggestions, criticisms are most welcome. Hold your horses on the parseOutput() function though, it's only temporary until we fix repodoc to give a little more easier-to-parse output.

I cannot demonstrate the service yet though, because I don't have a box with PHP 5 + repodoc and the correct permissions everywhere. /me taking a break now.

Finally, some substantial progress. First thing I did today was to figure out a concrete way of developing a REST web service in PHP. Turns out that the $_SERVER global variable has all that I need to respond to HTTP GET/POST etc. requests. PHP even has a nifty function called apache_request_headers() to get all this stuff. After that, it’s merely a question of processing the request and echoing back a response. headers() is what will help in sending back the proper response codes and HTTP headers.

So this is how it’s going to work. You make a POST request to, say http://docs.gentoo.org/repodoc/validate with the XML document to be validated attached to the request, and you receive a 201 (Resource Created) response code, with a location such as http://docs.gentoo.org/repodoc/result/<someID>. Next, the client makes a GET request to that location, which will send you back an XML file with details on the validation; whether it was successful or not, and if it wasn’t, what the problems were.I’m kind of deviating from the actual REST specification a bit, the location returned by the response to a POST request should really be the URI of the resource created, which in our case is the XML file to be validated. But what I’m doing instead is to create the result of the validation at that URI. The original XML file will actually not be stored permanently on the server. And neither will the results, so the URI returned with the 201 code is not persistent. This is sort of tricky, we need to decide on the amount of time that the result will stay. I was thinking of a daily cron job that cleans up the results, but we’ll need a debate on that.

So that’s just two resources, the validate’ resource responds to POST requests, and the result/*’ resource responds to the GET requests. As simple as it can get. The only XML that the server sends back is the result file, the Schema for which I’m currently authoring. Which would help people interested in writing a client for the repodoc web service, although I’ll be writing a reference client’ once the web service is up and running.

Phew! Surprisingly, there isn’t much information available on the internet on how to build a REST service in PHP. Making a nice tutorial and putting it up on xml.com or something would be a philanthrophic thing to do

Okay so it's decided. We're going the REST way for the repodoc web service. My plan is to begin writing a schema for the XML document that the client must get in response to a validation request to the service. This should be useful for those who would want to write a client for this web service in the future.

As a matter of fact, I am also thinking of writing a sample client for the web service, just a small collection of web pages that will allow you to upload a GuideXML document and validate it. Kind of like the XHTML and CSS validation that W3C offers. That way, we won't have to wait until the actual editor is ready to play around with the service.

On another note, I filed a bug with Gentoo Infrastructure on bugzilla, as requested by Lance, who has kindly volunteered to arrange infrastructure for Gentoo SoC students. Lance has requested OSUOSL to create Xen instances for all Gentoo SoC projects that require it. OSUOSL is contemplating on opening a new Xen server to cater to all the SoC-related infrastructure requests that they've been receiving from the community.

I'll planning to install PHP 5.1.4 on the instance, in addition to recreating a Gentoo CVS structure to get repodoc up and running. It'll be really cool to work on a virtual server, I've never done that before! Looking forward to a wonderful experience on the cool new box…