HTML static macros : Java Glossary


HTML static macros
A technique for generating website HTML (Hypertext Markup Language) using various computer programs before you upload it to the website. A vanilla HTTP (Hypertext Transfer Protocol) server then delivers the contents to visitors on the web. This is how the web pages at are created and served.

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 Example Macro Expansions
Advantages of HTML Static Macros Availability of the HTML Static Macro Tools
Disadvantages of HTML Static Macros Website Philosophy
Canadian Mind Products HTML Static Macro Tools Links
Third Party HTML Static Macro Tools

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 labelled 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 Mouse1. 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.

You can, of course, combine both schemes, perhaps using different servers. You handle the bread and butter items with HTML macros and use JSP for the tricky stuff that really needs it. This simplifies your JSP side.

Canadian Mind Products HTML Static Macro Tools

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

Canadian Mind Products Tools For HTML Static Macros
Tool Function
Amper Amper just tidies web pages converting & to &amp; intelligently. I do this for high level compliance with W3C (World Wide Web Consortium) standards demanded by the HTML Validator. I have already released Amper for general distribution.
Splitter Used to split a big HTML file into smaller pieces. I embed commands in the big file telling it which pieces of it are to go where, then let Splitter do the work. It is much faster and more accurate than trying to select huge blocks of text in an editor. You don’t accidentally lose or duplicate text. I have already released Splitter for general distribution. Keeping files small makes the site more responsive.
MacroExpander This is the guts of the system and the most complicated. You need to write custom macros to generate headers and footers of various sorts in Java. Your macro gets passed the parameters and it returns a String containing the HTML. Your macro is free to use what ever tools it wants to do that. The MacroExpander searches for embedded macros in the text and calls your code to expand them. The macro expansion code is written in ordinary Java. That gives you the power to do anything Java can to expand your macro, including even things like reading files, checking a database, finding out the time, checking if files exist, reading files, sending off a transaction to JSP… This not some impoverished ad-hoc macro language. You have the full power of Java at your command, same as in JSP.

With the latest version, it takes about 20 seconds to expand the macros and compact the results to remove excess white space in 4200 files, leaving the files unchanged if the macros expanded the same way as last time. I do this prior to every upload.

Check out my website. You will see <! macro XXXX all over the website with the <generated> … </generated> expansion. You can see from the examples what sorts of things are possible. Some of my macros you would use too, others you might modify, others would be useless to you. You would need to write your own before you could generate your own website. Here is what the source code for a simple macro looks like. It takes a birthdate and generates

Compactor Removes excess white space from generated HTML files. This makes them faster to upload and download.
Qf: quick Find Builds indexes for the various glossaries, with master and letter index pages. Builds the files for the Go Applet to do quick lookups on the glossaries.
SeeSort At the bottom of most pages is the links see also section. It sorts the items alphabetically and removes duplicates. It also builds missing href links by looking up words in the glossary index.
Untouch Redates files back the way they were if they have not really changed. The macroexpander and the compactor don’t write out a new file if it would be same as last time. However, it is still possible to disturb the files, say with an HTML reformat, in ways that don’t really change anything. Untouch undoes nugatory changes. It mainly helps avoid needless file uploading.
PriceList Instead of using macros, I generate the price list/download pages from a CSV file with the PriceList Program. I did a similar one that generated multilevel catalogs sorted in various orders all cross linked for a client.
The Replicator Allows clients to keep a mirror copy of the entire website for local browsing, when is down, busy, or the link to it is unavailable, or simply to avoid connect charges. The mirror copy is automatically kept up to date with just the changes.
publish.bat After I make a series of changes, I just run a bat file called publish.bat that runs these utilities in order and uploads the changed files to my server.

Third Party HTML Static Macro Tools

Third Party Tools For HTML Static Macros
Tool Function
SlickEdit This is an ordinary text editor I use for composing the content. It does HTML syntax highlighting and it can tidy HTML to indent it to make it easier to read. The Compactor squeezes it back down again. You might use DreamWeaver for as your editor. You don’t need anything special. Any tool for editing HTML will do. The macros look like comments to the editor.
TopStyle CSS style sheet editor and CSS Validator. It also checks I have not used any invalid classes in my HTML markup.
HTMLValidator Check that HTML is well formed. You must check after expansion to make sure both the original HTML and the generated HTML meld properly.
Xenu Link checker. Makes sure that links both internal and external point to a valid URL (Uniform Resource Locator). Also tells you about orphan files, files and images that nothing points to. You may be able to delete these if they are obsolete, or you may need to hook them in with a reference somewhere so they become accessible.
NetLoad Automated FTP (File Transfer Protocol) upload of just the changed files to the website. The product is buggy and no longer supported. Eventually I will write a replacement. Every FTP program I have tried is fatally flawed when it comes to reliably uploading files unattended.

Example Macro Expansions

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

If you do a view source on those pages, you can see both the macro and the expansion.

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 email feedback to Roedy Green or Canadian Mind Products. 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.

This page is posted
on the web at:

Optional Replicator mirror
on local hard disk J:

Please the feedback from other visitors, or your own feedback about the site.
Contact Roedy. Please feel free to link to this page without explicit permission.

Your face IP:[]
You are visitor number