Printing Dvorak decks

NAME

ddd2HTML -- Convert a Dvorak Deck Definition to a printable HTML file

SYNOPSIS

    ddd2html.pl file

DESCRIPTION

This program reads in a deck definition file and produces an HTML page that can be printed. It is meant to print the ready-to-play Dvorak games that you can find at the home of Dvorak, the card game.

GRAMMAR

The syntax of a Deck Definition file looks surprisingly like a CSS. This means in particular that a deck definition consists of a set of 'tags', followed by a list of properties for that tag in curly braces. Tags in this case are cards, or categories of cards, and the properties are used to print that card or all cards from that category.

More formally:

    file        :   record* ;
    record      :   tag '{' rule_list '}' ;
    rule_list   :   /* empty */ | rule [ ';' rule_list ]? ';'? ;
    rule        :   attribute ':' value;
    attribute   :   'name' | 'card-background-picture' | 
                    'card-background-colour' | 'title-colour' |
                    'text-background-picture' |
                    'text-background-colour' | 'text-colour' |
                    'bar-background-colour' |
                    'bar-background-picture' | 'bar-text-colour' |
                    'picture' | 'acknowledgement' | 'text' |
                    'parent' | 'count' ;

A value is anything before the end of the rule, or anything enclosed in double quotes (the character "). There is no way to specify double quotes and semicolons in one line. However, if you want to include double quotes in your card's text, you can use HTML's special entities for it, ". Specifically, any HTML you specify in the attributes that will get printed directly on the cards will be rendered.

EXAMPLE

Here's an example:

    deck {
        name: Football;

        card-background-colour: #ccffcc;
        title-colour: #000000;              /* must contrast with card-background */

        text-background-colour: #cccccc;
        text-colour: #000000;               /* must contrast with text-background */

        bar-background-colour: #666666;     /* Used in typeless cards */
        bar-text-colour: #ffffff;           /* contrast with bar-background */

        acknowledgement: "Game: Dion";
    }

For a complete example, here is a Dvorak Deck Definition for six cards of the Douglas Adams Deck; this will produce something like this printable deck, although that renders the cards slightly too big to fit on an A4 piece of paper.

CREATING DECKS

To create a new deck definition from scratch, you have to write a definition file that at least contains a record called 'deck'. It will set the default for all the different parts of the cards. Then you can create records for some categories; in a Dvorak game, these would be at least 'Action' and 'Thing'. Then you specify records for each card.

The whole idea behind the 'deck' record and the category records is that you can derive other records from it, by specifying the 'parent' field. A record inherits all properties from its parent, and then possibly overrides one or more of these properties.

An 'Action' record could look like this:

    action {
        name: Action;
        bar-background-colour: #990000;
        parent: deck;
    }

By specifying the 'name' field, we set the name for the category. Dutch Dvorak players could specify 'Actie' there. Furthermore, the colour and picture of the bar are changed. All other properties are inherited from the 'deck' record, as that is the parent of this category.

Now you can proceed to create a real card:

    header {
        name: "Header";
        text: "Can only be played in the Attack zone. Can only be played if you played a Pass in your previous turn. If the opponent cannot Save, a goal is scored.";
        parent: action;

        count: 3;
    }

This card will inherit the settings from 'action', but has its own name and text, and a count, which specifies how many of this card exist.

This card might look like this:

Header
Action
Can only be played in the Attack zone. Can only be played if you played a Pass in your previous turn. If the opponent cannot Save, a goal is scored.
Game: Dion

This is how the deck definition determined what the card looked like:

'name' in 'title-colour'. The background of the card is 'card-background-colour'.
'parent.name' using bar colours
'picture' if any.
'text', in 'text-colour', on 'text-background-colour'
'acknowledgement' in 'title-colour'

The lay-out of the card is fixed, but you can specify the colours that you want to use for the different elements. If you specify background-picture instead of background-colour for the card, the bar or the text, that will be used. You could still specify a background colour though, that can be used if the picture cannot be displayed for whatever reason.

Here's the exact meaning of all the fields

name Name of the deck, the category or the card. The deck's name is for reference only. The category's name is displayed in the bar of the cards from that category.
card-background-picture A picture that is used as a background for the cards. You can specify a default for the deck, then override it for categories or cards.
card-background-colour The background colour for the card, used if there is no background picture.
title-colour The colour that is used for the card's title and the acknowledgement. Must contrast with card-background-picture and card-background-colour.
bar-background-picture The background for the bar that displays the category of this card. The category always is the parent's name, so if the parent is 'action' the category displayed on the card will be 'Action'. You typically specify a bar-background for a category and let the cards in that category inherit that colour. If you specify a bar-background for 'deck', you can derive cards from 'deck'; they will have the name of the deck as category. Card like that can be used for special rules.
bar-background-colour
bar-text-colour The text used to print the categroy name in the bar. It must contrast with bar-background (picture/colour).
text-background-picture The picture/colour used as background for the card's text in the box on the bottom.
text-background-colour
text-colour The colour of the text on the bottom itself. This must contrast with text-background (picture/colour).
picture A picture displayed in the middle of a card. You can specify it for deck, category or for each individual card. Note that it should fit in the room left above the text.
acknowledgement Any acknowledgements for a deck or a card. Could be something like 'Game: Dion', but also 'Card idea: Albert' or 'Artwork: Vincent'.
text The card's text, in de box on the bottom. You can specify a default text for each card in a deck or category.
parent The category's or card's parent. It inherits all properties from that parent, and then overides some of them. A card's category is displayed as its parent's name.
count Only used for cards. How many of this card you need in the game. If you specify '0', the card will not be printed.

There is one special value you can use in fields, which is the character '^'. This character is replaced by the parent's value of that same field. This way you could specify the following: 

    
    deck {
        acknowledgement: "Game: Dion";
    }

    card11 {
        acknowledgement: "^; Card idea: Albert";
    }

The acknowledgement on card11 would then read "Game: Dion; Card idea: Albert". The same trick could be used to add category-specific text to each card, or e.g. to standardise titles.

RUNNING THE PROGRAM

After you created the deck definition file, you can run the program like this:

    ddd2html.pl file > file.html

Then the program will parse the deck definition file and possibly issue some error messages. If there are no errors in your deck file, an HTML page will be created displaying all your cards, with a black line around them, nine at the time on a page.

The HTML layout uses a CSS2-style called page-break-before that forces cards to be printed nine at a time on one page. This fits on A4, Letter and Legal size paper. If your browser does not support this style, your only hope is to fiddle with margins to make the tables fit exactly on one page; setting you page size to A4 might also do the trick.

You can print the cards in two different ways in Opera and Internet Explorer: with or without backgrounds. If you print them without backgrounds, the coloured bars are outlined, and no dark background colours are used. This is a bit more plain then the versions with backgrounds, but might save a lot on printer ink.

To switch on backgrounds in Opera, proceed as follows:

  1. Choose File/Print Options from the menu
  2. Check the box "Print page background"

To switch on backgrounds in Internet Explorer, do the following:

  1. Choose Tools/Internet Options from the menu
  2. Go to the "Advanced" tab
  3. Check the box "Printing/Print background colors and images"

In Netscape, there is no option to switch off background colours.

AUTHOR

Dion Nicolaas <dion@nicolaas.net>

SEE ALSO

http://www.dvorakgame.co.uk/

SHORTCOMINGS

Right now, the card layout is built into the Perl program. It should be possible to specify it as a separate entity, thus allowing multiple possible lay-outs.

It is currently not possible to derive a card from multiple categories.

Although the program structure allows as many levels as you want, the current layout only shows the parent's name as the category name. Together with the bar colour and the bar-text-colour this allows for two (or possibly three) visible layers, but not more; it is not possible to refer to a card's grandparent in the card layout.

Although the format of a Deck Definition looks like a CSS, it is a subset. Notably, it is not possible to specify the same properties for more tags, like:

    ship, computer {
        text-background-colour: #ccff66;
    }

Furthermore, it is not possible to specify tags in context (pre h1 { }), nor is there any possibility to use IDs. Also, ! important is not recognised. What all these things would mean in Deck Definitions remains to be seen.

This version of Dvorak Deck Definitions only deals with cards and how to print them. Any special rules could be written on cards with parent 'deck'; they will get a gray bar with the name of the deck on it. There is no way to specify other fields, they will be rejected by the reader.

BUGS