HTML static macros : Java Glossary

The alternative is to use Servlets/JSP/PHP/CGI/SSI etc. and dynamically generate the web page on the server each time someone requests a page.

How It Works

The basic idea is you write a computer program to generate HTML, that looks just as if you had composed it by hand, then you upload it. The server just delivers fully-prepared HTML pages. It does no dynamic content generation.

I use two different techniques to statically generate the HTML for my website:

1. The prices/downloads pages are generated by a program called PriceList that reads a CSV (Comma-Separated Value) file about each product. It goes out and finds out on its own if the download zip, precis, screenshot, icon, pad etc. are available and then adjusts the HTML it generates.
2. If you examine the source code for these pages you will see code of the form:

   <!-- macro Xxxxxxx xxxxxxx -->

   which are used to generate a lot of the boilerplate, such as headers, footers, book referrals, references to the JRE (Java Runtime Environment) and JDK (Java Development Kit), international currency references, lists of browsers etc. I invented my own macro generator where the macros are written in Java.

   Most of the site is done by embedding magic comments in the HTML markup that are later expanded my macros written in Java. For example, if you look the top of this page you will see

   <!-- example of a macro to generate a page header for the Java glossary -->
   <!-- macro JglossHead "HTML static macros" -->

   The MacroExpander converts that to:

   You can see signs of Java’s cleverness in the expansion. The expansion is not simply included boilerplate. It generated a URL-encoded Google search string, for example and it inserted the name of the file, which was not passed an a parameter. It also inserted the file last change date. It built and labeled links to related pages. It figured out how many ../ it needed to access the images directory from this page.

   The big advantage is if I want to change that header, I change the program that generates it and the next time I regenerate the website, all the headers will be automatically changed.

Advantages of HTML Static Macros

1. You need only a simple HTML server

   You can use free websites on bundled webspace that comes with your Internet access. You don’t need to run complicated software such as Tomcat and MySQL remotely on a server.

2. Faster Response

   The server does no computation, just delivers pre-composed pages. These means you can get away with a smaller server, or pump more pages per hour than you could with JSP (Java Server Pages) through any given server hardware. By having the pages completely prepared ahead of time, your customers get faster response.

3. Caching is much more efficient

   With JSP, every page you generate on-the-fly appears to the universe to be a brand new creation, even if it is identical to one produced a few seconds earlier. With static macros, pages maintain the same date until they actually change. The efficiency applies to many levels for caching within the server, out on the Internet and in browsers. This means faster response time for your clients and the ability handle more requests per hour with the same server. Google likes my statically-generated site, ranking it highly and spidering it often, possibly because the page date does not change unless the page really has changed.

4. Less fragile

   You create your web pages in batch mode offline. If anything goes wrong, you fix the problem and run it again. Your customers are totally unaffected. If you make an error with JSP, your website is out of commission until you fix the problem. You can proofread, validate and link check every page before any customer ever sees it, before you upload it. There is thus much less potential for embarrassing yourself with a programming error. Further, your server software is a simple HTTP server, much less likely to fail than the complex software used for dynamic page creation.

5. Off-line browsing

   You can distribute a mirror of your entire website on CD (Compact Disc) or via the Replicator for offline viewing without Internet access or connection charges. You can’t do that with dynamically generated content.

6. Programming is much simpler

   HTML macros don’t require any knowledge of server-side coding or GUIs (Graphic User Interfaces). All you need to know is beginner’s Java batch command-line programming.

7. Load splitting is much easier

   If you website gets too big for one server, you can fairly easily split it in two and serve half from one and half from the other. If you outgrow your JSP server, you pretty well have to get a bigger, more expensive one. Using two cheap or free ones is not an option.

8. Mirroring

   It is easy to set up multiple mirror sites. They don’t need any special administration the way JSP sites do. You just upload the files and away you go.

9. No JavaScript

   I consider JavaScript an abomination. It is a terrible security risk. It is flaky. It is non-standard. It is Mickey Mouse¹. With HTML static macros, you can put much of the cleverness you want into your static macros rather than into run time JavaScripts. If you want, you can still use JavaScript, same as ever. It is fully compatible. Avoiding JavaScript makes your content accessible to a wider range of browsers. Since I usually avoid JavaScript on my own website, my pages lack pizzazz aka silliness. There are no kittycat cursors, exploding menus, buttons you have to chase to click etc. I have done that deliberately to create a slightly old-fashioned, less-corporate look. I wanted to avoid shouting sales. I also avoid XML because it is so grossly inefficient, but again, there is no incompatibility between XML (extensible Markup Language) and static macros.

10. No Speed Worry

    With HTML static macros, you have the full flexibility and optionally the speed of JET-natively-compiled Java code to generate the pages, with no RAM (Random Access Memory) or response time worries. With JSP, the user is waiting while you generate content. You cannot dawdle. You have to use resources sparingly since there may be many pages being generated at once, all with users wanting the results instantly.

11. Simpler, Safer Markup

    HTML static macros take skill to write, but almost anybody could use them to embed in HTML. They are far safer than JSP since nothing the person composing the markup can do will disturb the computer programs that do the generation. In JSP, markup and program are mixed together to some extent. The person doing the markup has to be careful not to disturb anything the programmers put in the page.

Disadvantages of HTML Static Macros

1. You can’t react to user input

   With HTML static macros, all the user can do is select links. You can’t do database lookups for example. You can, of course, direct some of this work to a different server than is prepared to deal with user input. You can use Applets or Java Web Start, of course, and they can talk to various servers.

2. You can’t collect data from the user

   With HTML static macros, you can’t register users for an email list for example, or run a webstore (though you can if some other website handles the money and database for you). You can use Applets or Java Web Start, of course, and they can talk to various servers. You can generate HTML FORMS, but you still need some sort of server side code to deal with the data the users send with them.

3. Your site is always a little out of date

   Changes are not reflected until you re-upload the changed files. This scheme would not be suitable for example to display stock prices which change rapidly. I upload changes perhaps ten times a day, so my own site is not that out of date.

4. frequent petty file uploading

   With HTML static macros, for example, if you make a tiny change to the way your page footers look, that change will be reflected in every page and you will have to upload every *.html file in the website. With JSP you would just change the program that generates that generates the footer on the fly. You would not have to upload any of the content files. Extensive use of CSS (Cascading Style Sheets) can avoid many of these minor changes in the generated pages and hence the excessive uploading. Instead of changing the generated markup, you change the CSS style sheet to get a new effect. CSS is much more powerful than it first appears. Use styles instead of icons. Then you can change the name of the image or its size or even its location and none of your markup changes.

   You get frivolous updates often like this. Let us say that file B has a macro that expands to display the size or date of file A. Every time file A changes, that expansion will change, triggering a change to file B. If file C contains a reference to the date or size of file B, you get a propagation and C too will change and before you know it, a tiny change has triggered a fission reaction dozen dependent uploads. With SSI (Server Side Includes) or JSP, the referencing file itself does not change when the referenced file changes.

Canadian Mind Products HTML Static Macro Tools

I have written a number of tools to implement HTML static macros. The tools include:

Third Party HTML Static Macro Tools

Example Macro Expansions

Here are some examples of the output of the approximately 100 macros I have written:

• book and DVD recommendations with links to a variety of bookstores
• menus with the current page highlighted
• CurrCon that generates prices that automatically change to the local currency and the daily exchanges rates. This is available for the public, which can be used manually without the macro generator.
• Quilt menus sorted by column
• references to multiple sources for Sun documentation
• JDisplay that generates Colourful CSS-ized source code listings
• Headers, footers
• nested boiler plate includes
• List of products, prices, downloads, documentation

Availability of the HTML Static Macro Tools

I wrote these tools for my own use. For the most part, they are not yet documented other than in Javadoc. Further, they do things my way. You would have to change the code to make them do things your way. Eventually I may make them configurable without modifying source so that non-technical people could use them too.

I have no far not packaged my HTML static macro tools for general distribution, except for Splitter, Amper and the Replicator. I did not want to get into trying to support the suite for non-programmers or inexperienced programmers.

However, I am willing to share them with you on an as-is basis. Email me at . The MacroExpander, Qf, SeeSort, Compactor and Untouch are not documented other than in Javadoc. Compactor and Untouch could be fairly easily be prepared for general distribution. I’m not sure of the general applicability of Qf and SeeSort. That leaves the big mother MacroExpander. The catch there is you have to write code to customise it to your own use. It is just a starting point. It would be a beast to document.

Perhaps I could write macros to your specifications or act as a paid consultant.

Website Philosophy

HTML static macros fit well with my website design philosophy. I aim for functionality rather than gee whiz. The site looks a little on pedestrian side (that was deliberate), but I have incorporated many suggestions to make it less frustrating to navigate. A local university uses my website to teach the principles of good web design. They like my automatically generated you are here feature. Google tends to rank me high. This is because my pages tend to be small and stick to a single topic. I don’t do anything consciously to try to manipulate the rankings. Also many people have links into my glossaries for their own quick reference. Google notices this and ups my ranks.