Glk Stylesheets: Overview

Glk Stylesheets: Overview

This is the plan for a new style and layout system for the Glk API (and thus for Glulx games). I have rewritten this document about twice a year for the past three years, but this one should be shippable. (I have discussed it with Graham and Emily -- admittedly that was six months ago, but I think we are all in accordance.)

The heart of the matter

The core idea is to render Glk output using HTML and CSS. HTML used to be the poster child for "what you get is what some hacker somewhere thought you should see", but standardization has improved dramatically in recent years. The three dominant HTML renderers (Safari/Webkit, Firefox/Gecko, and IE/IE6-is-dead-so-we're-probably-okay-now) should agree on how core HTML4/CSS2.1 documents are displayed. Newer ("HTML5") features still have compatibility issues, but at least they're everybody's compatibility issues. The IF community won't have to spend their time reinventing a wheel that giant software companies are already spinning.

This doesn't mean that a Glulx game has to include literal HTML. The Glk API will still be an API; Glulx games will still generate output using print statements and style-setting calls. Games can provide style information by including a CSS file in the Blorb package.

This plan will define a normative translation from Glk API calls to HTML structure (using a limited subset of HTML). We can then imagine three ways to build an interpreter:

• "Widget terp": The interpreter translates the Glk calls to HTML, using this translation, and passes the resulting HTML document into an OS-native HTML widget. (The game's CSS file gets linked into the HTML.) There could be one HTML widget per Glk window, or one for the entire display.
• "Browser terp": The interpreter is entirely implemented in Javascript running in a web browser (e.g., Quixe). It translates the Glk calls to HTML, and displays the result directly. (Again, linking in the game's CSS.)
• "Native terp": The interpreter implements the Glk calls using its own code, and constructs its own output, following HTML rendering rules. The interpreter will have to parse the CSS file and understand as much of the CSS as it can display. (The HTML/CSS subset should be simple enough that this isn't very difficult.)

We'll also have to consider the fourth case:

• The interpreter is old, pre-dating this plan. Backwards compatibility should be possible. (See below.)

Extended HTML features

The core Glk API will generate a limited subset of HTML. What if the game wants to go beyond this? There will be optional calls to support further cases:

• Displaying an HTML document in a box in a story window. This will look very much like the existing glk_image_draw() call, except that the displayed "image" will be HTML instead of a picture. (The HTML file and any associated resources will be packaged in the Blorb.)
• Displaying an HTML document in its own Glk window. This is analogous to a Glk graphics window, except that the pane contains HTML. (Again, the HTML is drawn from Blorb data.)
• Calling a Javascript function. This can manipulate the displayed HTML documents, and can therefore do anything at all in those boxes.
• Receiving messages from displayed HTML documents. (That is, the player taps HTML buttons or links, and these are passed back to the VM as Glk events for the game to react to.)

These features are optional in the sense that not all interpreters will provide all of them. A "native" style interpreter does not have an HTML renderer or Javascript interpreter, so these extended features will not be possible.

On the other hand, a "widget" style terp could permit Javascript calls that manipulate story and status windows directly. This would allow Undum-like special effects. A "browser" style terp could permit Javascript calls that manipulate the entire interpreter or its browser window.

The author/player balance problem

My original Glk stylesheet plan was based on the idea that both the game author and the game player have opinions about the display. I wanted the interpreter to combine their opinions in a consistent way to render the game.

Working this out has proven to be impossible, for a variety of reasons. (Nobody start cheering, or I'll cry, I warn you.)

I still hold the basic principles:

• If the game ships with a stylesheet, the normal case will be for the game to be displayed that way. But the player should have a way to opt out and prefer his own display preferences. And the game should look fine that way.
• Many games will ship without stylesheet (CSS) information, and these games should be displayed using the player's preferences (or the interpreter defaults, if the player has none). And they should look fine that way.
• Some interpreters (including all legacy interpreters) will not understand CSS at all, and will display the game according to interpreter defaults. That should be fine too.
• Player preferences and game stylesheets should use the same format (CSS). That way, a web designer can contribute a stylesheet to be used by both players and game authors. Similarly, a stylesheet from a game could be exported (or adapted) and used by a player for other games.
• Games should not have to include stylesheets to look right, and Inform's default behavior will be to not include a stylesheet. Therefore, all default stylesheets should conform to a basic set of expectations, so that a simple game can (e.g.) say "bold" and reliably get boldface.

Supporting these ideas will require a certain amount of degradation testing on the part of game authors. You will not be able to just drop in a stylesheet and be guaranteed that every player will see that stylesheet. However, you should be able to test just a couple of cases: your stylesheet, and a basic default stylesheet. (The IDE interpreters should offer the "prefer player style" option, to make this testing easy.)