Eitan Suez's Blog

May 2004 Archives

Cascading Style Sheets Have Taken Root

There's nothing more satisfying than to see a good plant flourish. I believe CSS to be a "good plant." And it's really satisfying to see that it's taken root on the web so very well. I'm sure we all recall a time when browser support was not as good, making publishers hesitant to employ the technology on "production" sites.

Visiting various web sites, blogs, and wikis over the last couple of years, I've been delighted to see the variety in styles and the beauty of CSS shine through. The w3c web site's own look has improved nicely over that time period. I think one site deserving mention is Atlassian's (atlassian.com) and their beautiful issue management web application, JIRA. But the cat is out of the bag and there is no lack of clear and clean content on many other sites besides. What's exciting is that many of these sites are one-man sites, people's personal place on the web. Having a beautiful site no longer requires an ant army to maintain.

But it's not just about looks. I'm getting a little ahead of myself here, but I'd wager that it's the refactoring power of CSS that is enabling more and cleaner content than we've had in the past. The days are numbered for HTML hacks such as nested tables, 1-pixel GIFs, image-bloated pages, needless repetition of style application with <font> tags, all contributing to unmaintainable and buggy content (not to mention slow-loading pages and internet pipe clogging).

The reason I am writing about CSS on java.net is that I believe CSS is not just a tool for graphic designers. It is a core refactoring tool for content publishers (whether static or dynamic). CSS is not just about styling, it's deeper than that.

The exercise of comparing page sizes before and after applying CSS is a worthwhile one. A significant percentage of a page's markup can be weeded out and thrown in the trash. This is mainly due to duplicate and extraneous markup such as "font" tags and one-column nested tables that are used to simulate the CSS box model (margins, border, and padding). Analogous to a refactored program, the end product is content that is clearer, easier to understand, and easier to maintain.

I have personally gone through such an exercise on a relatively small site (my local JUG site) and was surprised to find out that the content of the site shrinked by approximately 25%. In my view, this is significant, because I've actually added content to the site since I began maintaining it.

Using CSS effectively involves more than just applying styles. The content must be structured in a special way. I haven't been able to articulate this up until now: the content becomes more semantic. We cannot change the html markup language but it has become flexible enough such that content publishers can now get around the issue of semantic content by applying "class" and "id" attributes to tags. What publishers end up doing is tagging a div with an id such as "sidebar." As far as I'm concerned, this is equivalent to having a <sidebar> tag. Suddenly combining markup with css stylesheets becomes a task more akin to writing content using a specialized markup language such as docbook. The difference of course is that the rules are completely informal; they're invented by the content developer.

Allow me to discuss another example, to better illustrate what I mean. When I developed the web client for my open source javadoc tool (ashkelon) in 2002, I ended up with class attributes having the names of java modifiers (static, public, abstract, etc..).

To give you an idea, here's a snippet of the one stylesheet that drives the entire application:

..
.static { font-weight: bold; }
.abstract { font-style: italic; } 
.deprecated { text-decoration: line-through; }
..

Likewise for programming elements:

..
.ordinaryClass { color: blue; }
.interface { color: green; font-style: italic; }
.exception { color: red; }
..

Here's an example of the html markup:

    <span class="interface">java.util.List</span>

Here's another example:

    <span class="method public deprecated">getBytes(int, int, byte[], int)</span>

In the latter example, you'll notice that styles can be applied in an additive manner by simply listing them all (of course, you could end up requiring the user agent to apply cascade rules to determine which of two or more conflicting styles apply). The method signature ends up showing up with a line through it because it's deprecated.

You get the picture. So what you end up with is something similar to an informal markup language for javadocs. In fact, on my task list for this particular project is the definition of an xml schema for javadocs (for the java language, really). With such a schema, the markup becomes formal and xsl stylesheets can then be applied to transform the content based on the semantics of the markup itself, similar to the way docbook works today for publishing books and articles.

One last point: once a page has been made more semantic, more than just styles can be applied to the content. It can be more easily parsed and introspected by tools used for other purposes, such as automated testing.

So, CSS is a good plant. Looked at from the perspective I discuss above, it's enabled many informal markup languages to sprout, often without their authors (myself included) realizing it.

Excited about javadocs.org

The recent news article on Pete Freitag launching javadocs.org (see http://today.java.net/pub/n/javadocs.orglaunch) was of particular interest to me. I must confess, these types of tools strike a chord with me (more on this shortly). It's hard to gauge the general feeling out there in terms of the level of interest in such tools. There seem to be two camps of developers out there. My friend Erik for example has access to all the information he needs directly from within his IDE of choice (IDEA) and never feels the need to resort to javadocs. I on the other hand "grew up" on javadocs, so to speak. And so I resort to them all the time. I can also see javadocs being useful when you don't want to load an API into your IDE and just need a glance at a package, a method listing, or method signature.

Using only my personal javadoc habits as reference, I discovered that while coding, I performed "lookups" all too frequently (it's true though that IDEs have come a long way towards reducing the need for that). The process was aggravating because I'd have to visit a different [local] URL depending on which API I wanted to consult. I quickly got into the habit of setting up my box such that my personal "home page" consisted of a aggregation of links to various APIs. I assume others have done that too. It's always convenient when not on your own box, to reference APIs directly online at java.sun.com. It's also nice to be able to google on a fully-qualified class name and get to the online javadoc page (isn't it nice that google has become a verb).

So, from here, javadocs.org is [imho] the perfect and logical next step. My impression is that this effort is generating interest and that use of javadocs.org will grow. I particularly like the community aspect of such a site. We are, after all, a java community. We share thoughts, often by sharing APIs. I also concur with Pete that this idea is not necessarily unique to javadocs, but could be applied equally effectively to assist us with the myriad of technologies we do battle with each day: css, html, and dozens of other markup languages.

For a long time I've felt the need for a javadoc system that spans APIs. I was fortunate to have acted on this need by developing such a system myself a few years ago. So I took the next step from the powerful but simple mechanism of parsing source code to produce html 3.2 static content: a full-featured web application using an mvc framework, servlets and JSPs, JSTL, a back-end database, and a totally redesigned front-end utilizing CSS and DHTML ad-nauseum, though i'd prefer to say ad-perfection. To support such a system I built a custom doclet to populate my database with the information that javadoc parsed on my behalf.

I use the system daily as I code and am very happy with what I've got. I particularly like the ability to add a feature or change some aspect of the system whenever it suits me. Ok, to be honest, what I like the most is no longer having to look at a monochromatic version of javadocs (I made sure to color-code all programming element types and style all modifiers; javadocs are so much easier to read that way).

I was fortunate to meet and get to know James Duncan Davidson on the excellent "No Fluff, Just Stuff" tours. James helped me come to the excellent decision to open-source my work (intent here is not to try to exploit my position to advertise my work, but I did realize that readers might be curious as to what specifically I'm talking about, so, with apologies, here's the url: http://ashkelon.sourceforge.net/). And so I've been able to share the fruits of my labor with others in our community. And it's a great feeling.

After reading this blog entry: http://jroller.com/page/pawnxing/20040512#searchable_javadocs_sweet on an internal Sun effort at something similar to javadocs.org, I was saddened to discover that such nice work was eventually canned.

So, where am I going with this? To Pete Freitag and javadocs.org: this is a great idea! You've done a good thing, a service to our community; thank you! I look forward to discovering how this system will evolve and grow over the coming months and years.

This work is licensed under a Creative Commons License.