Kohsuke Kawaguchi's Blog

Metro and JAXB users guide gets syntax coloring

Metro user guide (formerly known as JAX-WS user guide) and JAXB user guide is our effort to develop a comprehensive coding-level in-depth documentation about JAXB, JAX-WS, and Metro.

This document is generated from a set of "source" documents by using an HTML transformation engine called htmlmacro, which I talked about some time ago. One of the benefits of doing a transformation, is that we can do things that are too tedious to do manually. Htmlmacro uses Jelly behind the scene to make it really easy to perform all kinds of processing.

So to prove the point, I just made a custom tag out of jhighlight, and as a result our documentation is now fully syntax colorized. See this for an example.

Thanks Marek for telling me about jhighlight.

Comments

• Something went wrong on this page: https://jaxb.dev.java.net/guide/Mapping_interfaces.html I get the letter  all over the place. Kees.

  Posted by: keeskuip on November 04, 2007 at 02:20 AM

• When you look at the page, what encoding is the browser in? The HTML specifies UTF-8 as an encoding, but maybe your browser overrides it somehow? Does anyone else experiencing a similar issue?

  Posted by: kohsuke on November 05, 2007 at 08:23 AM

• I have the same issue. All of the example code has the funky A before every space character. Running FireFox 2.0.0.8 on Ubuntu 7.10. The default character encoding in the FireFox prefs is set to "Western (ISO-8859-1)". Changing that pref to UTF-8 and reloading the page fixes it.

  Posted by: swpalmer on November 23, 2007 at 08:02 AM

• The metro users guide doesn't seem to be a users guide at all. It seems more like a mis match of random edge cases. The first sentence is "This document explains various interesting/complex/tricky aspects of Metro". Are there any plans to develop an actual users guide? I've been using Axis for several years now, and would like to do more with JAX-WS, but it's just unapproachable for me. I don't really know how to get started.

  Posted by: jeremy_r on January 30, 2008 at 12:24 AM

• Thanks for the feedback, Jeremy. We are working on improving the contents, but because so far the most of the doc updates come from developers, we've been lagging behind in terms of organizing this effort.

  If you have a particular area that you'd like to see in the document, knowing that would be helpful. Perhaps you need a tutorial like documentation to get started?

  Posted by: kohsuke on January 30, 2008 at 09:29 AM

• The documentation is strewn out and not cohesive. I'm doing my first JAX-WS project and I've run into a couple of things that were a little frustrating. For example, I found that I had to use the XautoNameResolution parameter to xjc in order to get a wsdl to process correctly. At the time, there was 0 documentation of this parameter. I just checked and I still can't find anything on it. Also, all links to javadocs for JAX-WS seem to be for the spec, not the metro implementation. In order to set a SOAP header, I needed to use import com.sun.xml.ws.developer.WSBindingProvider. I can't find documentation for any of this type of stuff on the metro site. A google search turns up some javadocs hosted on other domains. I'm probably missing something, but as it stands I don't want to go through this type of pain in order to do some basic web services.

  Posted by: jeremy_r on January 31, 2008 at 03:24 PM

This work is licensed under a Creative Commons License.