Kohsuke Kawaguchi's Blog

Introducing HTMLMacro

Writing a serious, consistent, nice-looking documents in HTML is hard. CSS improves the situation a bit, but it's still very painful. For example, suppose if you are writing a release note like this, and you want to do:

1. Generate the navigation bar in multiple pages
2. Have the same footer for all documents

If you can do the equivalent of JSP tag files (which lets you define your own tag, which will expand to HTML fragment), these would be really easy to do. That got me started to write a tool called HTMLMacro.

This is the tool I use to generate JAXB release notes and unofficial JAXB user guide.

It's basically just a thin wrapper around Jelly, but it let you define your own tags as well as use any Jelly tags --- such as a for loop, variable, XSLT transformation, RDBMS query, you name it.

The interesting thing about this tool is that it really starts to feel like Lisp macro (except you use angle brackets), and you'll quickly find out that HTML is very suitable for DSL (domain specific language), perhaps not too surprisingly.

I hope you'll find this useful, and I'll try to convince other teams in my group to use this for their docs.

Comments

• What I usually do is create my own XML format for the data, usually only a few clear tags are needed to mark up the data. Then I create an XSLT stylesheet to generate the XHTML. Works like a charm.

  Posted by: tobega on June 08, 2006 at 12:12 AM

• 
  Yes, I knew someone would bring up XSLT! In fact I've done a fair amount of XSLT+my XML format in the past (all the release notes of JAXB RI 1.0.x has been generated from XSLT, although "my XML format" was really just HTML+few tags) But there are a few reasons why Jelly works better than XSLT.

  
  Firstly, with XSLT + my own XML format approach, your XML format needs to define tags for everything that you'd need for your whole document set. Jelly, OTOH, lets you define a tag locally, if it's only needed in a particular file. This is handy just for the same reason local variables are handy (compared to global variables.)

  
  Secondly, Jelly allows you to tap into the power of Java very easily. For example, in the JAXB RI release notes, we wanted to list all samples with their descriptions. In Jelly, I can very easily enumerate directories in the file system to do this. This isn't so easy to do with XSLT. Another example would be a tag that would do syntax-coloring of Java code. It's almost hopeless for XSLT to do this kind of things.

  
  Finally, HTMLMacro lets you write HTML, not XML. You don't need to close every <li> tag, you don't need to do <br /> instead of <br>, and you don't have to quote every single attribute (thanks to NekoHTML --- talk about another "power of Java".) I found this much easier for documents that I type manually.
  

  Posted by: kohsuke on June 08, 2006 at 12:52 AM

• Ah, I missed the RDBMS query and directory listings, but you can have java code as a Source for your transform. Or you can plug in XSLT extensions written in Java.
  If you don't want to close your tags, why do you accept a programming language that you have to put a ";" at the end of each statement? And, in case you missed it, html is xml in the current version, i.e. xhtml.
  If your own XML tag set was just HTML+ a few tags you really haven't understood the whole separation of data and presentation thing.
  Still, to each his own and I think it is good that invention proceeds in many directions, sometimes one strikes gold.

  Posted by: tobega on June 08, 2006 at 07:28 AM

• You're proud of the fact you can produce broken xhtml? ;)
  XSLT isn't a bad technology for transformations, but I've noticed it can hairy as it gets more complex and arbitrary.

  Having the HTML rendered with JSP allows us to sneak in those annoying "can you just get this live?" requests from our business, which frankly, is really practical. People undervalue the simplicity and power of JSP I think, it can be very graceful and simple if you layout your frontend code well.

  Posted by: ilazarte on June 08, 2006 at 08:33 AM

• HTML isn't (and never was) meant as a programming language. It's purely designed for presentation and nothing else.
  It's bad enough that you've abused (x)HTML for something it isn't, but then going ahead and breaking the language definition because of a misguided idea is even worse.
  Close tags were ALWAYS a requirement of html, it was just laziness of html writers that caused browser creators to be extremely lax in their enforcing of the standard.

  Posted by: jwenting on June 09, 2006 at 12:43 AM

• 
  jwenting, in your reasoning then any template engine like JSP or Velocity would be a bad idea? I don't think many people would dispute the practical benefits of those technology.

  
  I also don't think close tags were a requirement in HTML (certainly in XHTML.) You need to look no further than <br> and <img>.

  Posted by: kohsuke on June 09, 2006 at 09:48 AM

This work is licensed under a Creative Commons License.