JDisplay : Java Glossary

JDisplay is an Applet and back end to create the various colourised listings you see all over my website. I released the source. It consists of parsers for Java, HTML (Hypertext Markup Language), SQL (Standard Query Language), XML (extensible Markup Language) and BAT (Batch) files that decide the colours and an Applet to display and scroll the listings and a macro preprocessor to either expand small listings as HTML inline or generate an <applet invocation to an Applet to display it. If you can’t see the listings, here are things to check:

• To use JDisplay to display listings on this website, you must have  Java version 1.5 or later, preferably 1.8.0_131, installed on your machine.
• If you are using Microsoft Internet Explorer, try another browser. Seriously. Microsoft has taken great pains, over and over, to screw up Java and every other multi-platform standardisation.
• If you are using Internet Explorer 7, you must allow blocked content permission for Active X to run. This also gives permission to Java to run. Click the Information bar and then click Allow blocked content. Unfortunately, this also allows dangerous ActiveX code to run. However, you must do this in order to get access to perfectly-safe Java Applets running in a sandbox. This is part of Microsoft’s war on Java. Don’t put up with it! Use a different browser.
• Check the Java console for error messages. If you don’t know how to interpret that message, feel free to email me at   for help.
• If you still can’t get the program working click HELP for more detail.

How It Works

1. Inline

   java.exe -version

2. With an iframe

3. With an Applet

Advantages of Various Rendering Techniques

• The inline approach is used for small snippets. The colourised snippets are fully integrated into the web page. The user can copy/paste either the HTML or the rendered text. This approach does not require Java to work. Google will spider the listings.
• The iframe approach is used for mid-sized snippets. They appear in a scrolling window. This lets the user skip over the entire listing quickly even if it is many pages long. It does not require Java to work. It does require the browser to support iframes. Google will spider the listings.
• The Applet approach is used for large snippets. They appear in a scrolling Applet window. Large snippets download quickly since they are compressed binary and free of bulky HTML style markup. The rendering is handled by the same code for all platforms. HTML is rendered slightly differently by every browser. You can download the raw source code to a file by clicking a single button. Google will not spider the listings.

Under the Hood

One project on my plate is offering a free webservice to convert your listings to colourised HTML.

JDisplay, Firewalls and MIME (Multipurpose Internet Mail Extensions) Types

While you are at it, you might as well check the complete list of MIME types to make sure you are not blocking any other critical kinds of file downloads.

Improving the Look

Why Use JDisplay?

If you don’t have Java at all, you should see a button to download the listing to view in place of the listing. The problem comes when you have a malfunctioning Java. Then you won’t see anything at all.

Further, I am a Java evangelist. In particular I want to see more client-side Java computing. I think this 100% server logic talking to a browser, all the rage these days, is so sixties. So I demonstrate it where I can on my site with JDisplay, the CurrCon currency displays and the many amanuenses Applets.

Extending JDisplay

You can add your own parsers to tokenize and colourise other languages or types of structured text documents. Here are suggested steps to write your own parser:

1. Find a Tokenizer that for a language similar to what you want to do. There currently exist ones for bat, C, http (headers), html, ini, java, mft, properties, sql and plain text. Some tokenizer handle multiple extensions. On my todo list are tokenizers for CSS (partially complete), C source and ASM (Assembler) source.
2. Look in com.mindprod.jprep where the XXXTokeniser decides which file extensions to handle, XXXState is the finite state machine for parsing the code. It does not have the luxury of giving up if the text is malformed.
3. Look in com.mindprod.jtoken for the tokens. Each token represents a chunk of text that is displayed with a single CSS classes, i.e. it has the same font, size and colour, though you can get fancy displaying within token if you really want. It is a logical chunk of text that is considered a fundamental unit.
4. Glance at com.mindprod.jdisplay where you will find the code that renders your lists of token. It will not need changing.
5. You can ignore com.mindprod.htmlmacros.JDisplay, the macro generator that will expand and render your tokens three ways and insert them into HTML. It will not need any changes either.
6. Write your XXXTokeniser decides which file extensions to handle.
7. Hook up your XXXTokeniser code into com.mindprod.jprep.JPrep.prepareAllSnippetsForOneDirectory() so it will invoke your tokeniser when it encounters a file of one of the extensions it handles.
8. Write your XXXCharCategory class to categorise which characters have special meaning in the text you will process.
9. Compose new CSS styles in the style sheet, possibly separate from your main one, so it only need be include on pages that use Display. This requires you to make up your mind about fonts, colours and sizes of each token.
10. Do a mockup colourising some text in your language with your new styles. This will help you notice if you have forgotten something, or if the results are ugly or the contrasts are to garish or too subtle. The CSS classes you create will define the tokens and token names you use in your Java Token classes. It is a lot easier to play with your mockup and style sheet to experiment with colour and font schemes than with Java code.
11. Include the new colours in the Java source code for com.mindprod.jtoken.TokenPalette following the established naming convention. It would probably be safer to put your colour purpose names in a private file, or to factor them out later.
12. Associate your tokens with colour names in the Java source code for com.mindprod.jtoken.TokenColourScheme following the established naming convention, by defining colour purpose names. This sounds complicated, but if you look at the existing code, you will see this is easy but tedious. It would probably be safer to put your colour purpose names in a private file, or to factor them out later.
13. Write you various Token classes to control on the fonts, sizes colours and CSS styles of various chunks of text in your rendered text. You can use ones in the common section, but don’t use tokens from other parsers. Just clone them.

14. Work out what your finite states will be, or work them out for a subset of the entire problem. Build a giant nested case, for what you do when each character category comes in when you are in each state. Just get the framework complete, with all states and character category cases in alpha order. You could use a parser generator like JavaCC, ANTLR (Another Tool for Language Recognition) or YACC (Yet Another Compiler Compiler) to create your parser and then traverse the parse tree emitting JDisplay-style tokens to a *.ser file. I avoided that approach for thrree reasons:

    1. For some reason, I find writing state machines profoundly relaxing and satisfying. I derive immense joy from watching them work right off the bat as a whole, even when I created them thinking only about minute fraction of the problem at a time.
    2. Generated parsers tend to freak at imperfect code. They can’t even complain coherently. A lowly colouriser has no business complaining. It has to parse code fragments which are necessarily grammically incorrect according the language specs.
    3. My hand-coded parsers are wicked fast.

    But go ahead and try it that way.

15. Thinking only about one state and one character category at the time, work out what to do and what state to go into next.
16. Cannibalise freely from other finite state machines.
17. Proofread and desk check your finite state machine against some printed text.
18. Debug/single step your finite state machine so you can see it is behaving as you expected.
19. Throw all the text you can find at it, including malformed text to see if it is rendering as you expect.
20. Test out the three modes of rendering, inline, iframe and Java Applet. It is fairly easy to get the colours, fonts and sizes of the rendering done by Java and by CSS styles out of sync. This does no great harm, so long as both look ok, but I like to keep them 100% consistent.
21. Pass your code back to me for inclusion in the JDisplay packing if you are willing to share it.

Here in the mockup I am working on for the CSS parser: