EasyTimeline - Generate graphical timelines from a simple script

3. Script Syntax

1. Introduction    2. Procedure    4. Download    5. Acknowledgements   6. Revision history

3a. Available Commands    3b. General Syntax Rules    3c. Command Reference    3d. Input Rules    3e. Clickable Maps    3f. Trouble shooting

Note: even with a intuitive syntax (which I certainly hope this is), the formal description become rather terse. I suggest you start to play with one of the examples provided at Introduction, and return to this page for detailed inspection later.

3a. Available Commands

The script commands define:

Mandatory/optional commands

Only three of these commands are mandatory:

At least one of the following commands is required. Either or both can occur multiple times:

All other commands are optional

Case

Commands and their attributes can be specified in lower, upper or mixed case.

Please try to be consistent in applying case as this will further readability, e.g. use mixed case for all commands and lowercase for all attributes. See for an example the listing on page Introduction.


3b. General syntax rules

A script can contain
commands and comments. Each command is followed by one or more attributes. Some attributes are optional, some are required.

Commands

Commands should start on the first position of a line. Some commands can be followed by multiple lines of data and/or options. These extra lines should start with at least one space or be completely empty (the latter is useful for visually grouping related data lines).

Commands have the one of the following forms, depending on the type of command:

  1. command = attribute(s)

    example:
    DateFormat = dd/mm/yyyy

  2. command name = attribute(s)

    example:
    Color Jp = value:red legend:Japan

  3. command =
       attribute(s)
       attribute(s)
       etc.

    example:
    PlotData =
      fontsize:XS width:20
      bar:Japan from:start till:19/02/1945 color:JT
      bar:Japan from:19/02/1945 till:14/03/1945 color:AI

Comments

Single and multi line comments can be specified:
  • Text following the hash sign # will be regarded as single line comment
  • Text between #> and <# will also be regarded as comment. Comments can span multiple lines, when tagged this way.
examples: (green is comment)
Dateformat = dd/mm/yyyy # European date format

Period = from:01/09/1939 till:02/09/1945 #> this chart will show
the complete duration of World War II <#

Attributes

When several attributes can be specified for a certain command, they are notated as 'name:value' pairs. When several values can be specified for one attribute they have to be enclosed between brackets.

examples:
AlignBars = justify

Color SB = value:rgb(0.8,0,0.7) legend:Sea_Battles

Parameters vs Data Items

Most commands only accept parameters that are specified on the same line.

Some commands, like BarData, PlotData, TextData, Colors expect a data block consisting of one or more data lines. Data lines should start with one or more spaces. A data block is considered complete when a line starting with a non-space is encountered (exception: empty lines are ignored, they may be used to group related data lines within a block)

Attributes can be divided in parameters and data items. Data lines can contain parameters and data items intermingled.

In data lines attributes text, from, till and at (data items) always apply only to the line in which they occur.

Other attributes, like color and fontsize (parameters), have different implications depending on the context. If these parameters occur on a line without data items, they set new defaults for the data lines that follow. If they appear on a line mixed with data items they apply only to that line, thus overruling a default that was previously set.

Example
In this example two sets of bars are drawn, in red and blue respectively, but in each set one bar (marking war periods) will be drawn in green.

example:
PlotData =
  color:red fontsize:S                    # set defaults
  bar:USSR from:1919 till:1922 text:Lenin            # red bar
  bar:USSR from:1922 till:1953 text:Stalin           # red bar
  bar:USSR from:1939 till:1945 text:WWII color:green # green bar
  bar:USSR from:1953 till:1964 text:Krushchev        # red bar
 
  color:blue                             # change default color
  bar:US from:1913 till:1921 text:Wilson             # blue bar
  bar:US from:1917 till:1918 text:WWI color:green    # green bar
  bar:US from:1921 till:1923 text:Harding            # blue bar
#> this multiline comment ...
    does not end command PlotData <#
  bar:US from:1923 till:1929 text:Coolidge           # blue bar
TextData =                 # now PlotData is considered complete
  tabs:...etc

Special characters

#, #>, <# (hash, hash+larger, smaller+hash): see Comments
~ (tilde) in texts means: line break
^ (caret) in texts means: tab
_ (underscore) in texts means: space
$ (dollar sign) precedes any user defined constant


3c. Command Reference

For each command the valid attributes are listed. Some commands and/or attributes are optional (O).

For some commands certain attributes are mutually exclusive (will be explained where applicable).


Top AlignBars

Bars will be drawn at equal distances. Command AlignBars specifies whether the bars should be spaced as much apart as possible or some white space should be reserved between the left/top side of the chart and the first bar or between the last bar and the right/bottom side of the chart.
early
The first bar will be placed on the left-/topmost position of the chart. Some space will be reserved between the last bar and right/bottom side of the chart.
late
Opposite from early: some space between axis line (left/top side of chart) and first bar. The last bar will be placed as much to the right/bottom side of the charts as possible.
justify
First and last bar will as much apart as possible, leaving no empty space on either sides of the chart.
example:
AlignBars = late


Top BackgroundColors

canvas (O)
Specify a background color for the whole image.
The color id specified should be defined first with command Colors.
bars (O)
Specify a background color for all bars.
The color id specified should be defined first with command Colors.
examples:
BackgroundColors = bars:darkgrey
 
BackgroundColors = canvas:lightgrey bars:darkgrey
 
BackgroundColors = canvas:lightgrey


Top BarData

If specified this command determines which bars will be drawn on the chart and in which order. Otherwise bars will be drawn in order of appearance in command PlotData.

Tip: For complex timelines with many bars usage of this command is recommended:
      • It will ease reordering of the displayed data.
      • Bar names specified in PlotData can be validated against this list, thus preventing typing errors.

bar
Bar id, other commands (notably PlotData), will expect this id for reference.
This will also be the label to be shown along the axis, unless attribute text is present.
The bar id should not contain any spaces, (use underscores instead, these will be converted to spaces).
text (O)
When specified this text will be presented along the axis, instead of the bar id.
See also rules for text input.

The text may include one embedded link1 for use in clickable maps.
link (O)
Specify a web link1 (URL) for use in clickable maps. The label along the axis will be shown as a blue clickable link.

1 Either use attribute link, or an embedded link in attribute text, not both.

example:
BarData =
  bar:Japan
  bar:US       text:"United States"  # refer in PlotData to bar "US" but show "United States"
  bar:China    text:[[China]]        # label China will be shown as blue clickable link to the English Wikipedia article about China

The following lines produce the same output (only reference in PlotData changes):
  bar:US            text:[[United_States]]
  bar:US            text:"United States"  link:http://en.wikipedia.org/wiki/United_States
  bar:United_States                       link:http://en.wikipedia.org/wiki/United_States


Top Colors

With this command colors can be defined and coupled to an id (=identification tag). Other commands will refer to colors with the id specified here.
This command expects one or more color definitions, each on a separate indented line.
id
Other commands will use this id to specify text, bar or background colors.
value
Actual color definition. Colors values can be either be specified as:

  • predefined color constant, 32 predefined color names are recognized

    See Ploticus color page where all these constants are defined

  • rgb (red,green,blue), specify 3 numbers between 0 (minimal) and 1 (maximal)

  • hsv (hue, saturation, value), specify 3 numbers between 0 and 1

  • gray(value), specify a number between 0 (black) and 1 (white)
legend (O)
Specifies the text that should be displayed in the Legend for this color.
If this attribute is omitted no entry will appear in the legend at all.
See text input for rules
example:
Colors =
  id:war       value:red   legend:War Period
  id:peace     value:blue  legend:Peace Time
  id:treaty    value:rgb(0.6,0,0.6)
  id:lightgrey value:gray(0.9)
  id:darkgrey  value:gray(0.1)


Top DateFormat

This comand defines how dates, specified in other commands, should be interpreted.

Valid dateformats are:

dd/mm/yyyy
Dates are interpreted as day/month/year
Note: this format is only allowed for dates starting from 01/01/1800
mm/dd/yyyy
Dates are interpreted as month/day/year
Note: this format is only allowed for dates starting from 01/01/1800
yyyy
Only whole years are accepted
example:
DateFormat = mm/dd/yyy


Top Define

This command allows definition of text constants, i.e. shorthands for pieces of script code that occur multiple times.
Text constants should always start with a $ (dollar sign).

example:
Define $broad       = width:30
Define $narrow      = width:10
Define $bardefaults = $broad fontsize:S


Top DrawLines

Some timelines extend over several clearly distinct periods. A line demarcating these periods may serve as a visual aid.

Lines specified here will be drawn over the whole width/length of the chart (depending on the orientation of TimeAxis).

at
Specify date/year where the line should be drawn, in compliance with specified DateFormat..
color
Specify color in which the line should drawn.

Note: The color id specified should be defined first with command Colors.

example: (used here)
DrawLines=
  at:start      color:red
  at:end        color:red
  at:07/12/1941 color:red


Top ImageSize

width
Width of final image.
Specify value in absolute measurements.
height
Height of final image.
See value in absolute measurements.

Maximum image size is 1600 x 1200 pixels (run EasyTimeline with option -b to bypass this size check)
Note: the image will automatically be enlarged when long texts extend outside the defined image area, even when the texts that fall outsize the plot area are not displayed.
example:
ImageSize = width:800 height:600


Top Legend

A legend will be only shown when this command is present.
There are several ways to define the appearance and position of the legend.
Some attributes are mutually exclusive (see below).
orientation (O)
Specify hor[izontal] or ver[tical] (default).

Restriction: orientation = 'horizontal' and position = 'right' are mutually exclusive
position (O)
Defines placement of the legend relative to the chart area. Specify top, bottom (default) or right.

Restriction: orientation = 'horizontal' and position = 'right' are mutually exclusive
columns (O)
Specify 1, 2, 3 or 4.

When this attribute is omitted the number of columns is determined as follows:

orientation = 'horizontal'
Attribute columns does not apply here. All entries will be on the same line.
orientation = 'vertical' and position is 'right'
All entries will be in one column
orientation = 'vertical' and position is 'top' or 'bottom'
The number of columns depends on the number of entries to be shown: 1-5: 1 column, 6-10: 2 columns, 11 or more: 3 columns.

Tip: to avoid confusion you may consider omitting the following parameters at first, and only add them when defaults settings are not satisfactory.

columnwidth (O)
Defines the distance between columns
You can specify an absolute distance or a relative distance (as percentage of the page width).

Restriction: this parameter is ignored when columns = 1 is defined or implied.
left (O)
Defines the distance between the left side of the legend and the left side of the page.
You can specify an absolute distance or a relative distance (as percentage of the page width).
top (O)
Defines the distance between the top of the legend and the bottom of the page.
You can specify an absolute distance or a relative distance (as percentage of the page height).
examples:
Legend = orientation:vertical position:bottom columns:3 columnwidth:140
 
Legend = orientation:horiontal position:bottom
 
Legend = left:100 top:120 columns:3


Top MajorScale

This command divides the timeline into smaller periods, either
  • Graphically, through thin vertical or horizontal lines in the chart
  • Textually, through stubs in the timeaxis, below or to the left of the chart
  • Both graphically and textually

Note: the orientation of the lines and/or placement of the stubs depends on the orientation of the TimeAxis

gridcolor (O)
Defines the color for the grid lines. When this attribute is omitted no grid lines will be drawn.

Note: The color id specified should be defined first with command Colors.

unit (O)
Specifies the unit by which the grid spacing is incremented.
Specify day, month or year (default).

Note: When DateFormat yyyy is specified, only unit year is allowed.

increment (O)
Specifies the numbers of units by which the grid spacing is incremented. Default is 1.
start (O)
Specifies where the first grid line and/or stub should be displayed. Defaults to start of defined Period

examples:
MajorScale = gridcolor:red start:1940

MajorScale = gridcolor:red unit:month increment:3 start:01/09/1939


Top MinorScale

This command defines a further subdivision of the timescale.

See for syntax MajorScale

example:
MajorScale = grid:red  unit:year  increment:1 start:01/01/1940
MinorScale = grid:blue unit:month increment:3 start:01/10/1939


Top Period

Defines the time period that will be displayed in the chart.
Both parameters are mandatory. Specify dates in compliance with specified DateFormat.
from
Timeline starts here. The specified value can be referenced as start in commands like PlotData and PlotText.
till
Time ends here. The specified value can be referenced as end in other commands.
example:
Period = from:01/09/1939 till:02/09/1945


Top PlotArea

width
Specify value in absolute or relative measurements.
height
Specify value in absolute or relative measurements.
left
Margin between left side of image and left side of plotarea.
Specify value in absolute or relative measurements.
bottom
Margin between bottom of image and bottom of plotarea.
Specify value in absolute or relative measurements.
examples:
PlotArea = width:640 height:420 left:160 bottom:120
 
PlotArea = width:80% height:70% left:20% bottom:20%


Top PlotData

Command PlotData is used to define bars (symbolizing a time period), and add texts next to these bars on a specific position.

For texts which are not related to a certain period or date/year or which require extensive formatting use command TextData.

Attributes text, at, from and till always apply only to the line on which they occur. All other attributes, when not combined with one these four, act as default for the remainder of the command block or until a new default is specified, and may be overruled for a single line. See Parameters vs Data Items for more info and an example.

PlotData accepts a lot of attributes, some of which are mutually exclusive. These attributes can be grouped as follows:

Positional attributes
at
Specifies at which date/year a text should be positioned. Depending on attribute align the text either starts, ends or is centered at this position.

Note: This attribute can not be combined with attributes from or till.

Use data/year format as specified in DateFormat or specify start or end which refers to time frame defined by command Period.

from
Specifies at which date/year a bar should start.

Note: This attribute should be used in combination with attribute till and can not be combined with attribute at.

Use data/year format as specified in DateFormat or specify start which refers to time frame defined by command Period.

till
Specifies at which date/year a bar should end.

Note: This attribute should be used in combination with attribute from and can not be combined with attribute at.

Use data/year format as specified in DateFormat or specify end which refers to time frame defined by command Period.

shift
Specifies a horizontal and vertical displacement in absolute measurements for a text. This allows:
  • Texts to be shifted to avoid overlaps
  • Placement of text beside a bar, instead of on top of it.
examples:
PlotData=
  bar:Japan from:start      till:19/02/1945 color:JT
  bar:Japan from:19/02/1945 till:14/03/1945 color:AI
  bar:Japan from:02/09/1945 till:end        color:AO
  at:07/12/1941 shift(0,-15) text:"<-- WW2 reaches Asia"

Bar related attributes
bar
Specifies to which bar all other attributes apply.

When command BarData has not been used, bars will be drawn in the order in which they occur in any PlotData data block. The id specified here will also be the text presented along the axis, next to the bar.

When command BarData has been used, bars will presented in the order specified there, also the bar id specified here will be validated against that list. Also the text presented along the axis will depend on the definition in BarData.

color
Specifies the color is which the bar should be drawn.

The color id specified should be defined first with command Colors.

width
Specifies the width of the bar in absolute or relative measurements.
example:
BarData=
  id:US text:United States
  id:SB text:Sea Battles

Colors=
  id:US value:blue legend:United_States
  id:SB value:rgb(0.8,0,0.7) legend:Sea_Battles

PlotData=
  width=0.3 # see note 1
  bar:SB from:07/08/1942 till:09/02/1943 text:Guadalcanal color:SB # see note 2
  bar:US from:start till:end color:US # see note 3
  bar:Midway from:start till:end color:US # see note 4
  bar:US at:07/12/1941 text:7/12 Pearl Harbour # see note 5

----
Note 1: this line establishes a default bar width for the remainder of the data block
Note 2: this line specifies a bar to be drawn and a text to placed on it at the same time
Note 3: bar US will be drawn before bar SB, even when specified after it, because command BarData determines the sequence
Note 4: bar Midway will be rejected because it is not declared with command BarData
Note 5: the last line will not result in a bar being plotted, it merely specifies on which bar the text should be placed
Text attributes
text
Defines a text that should be plotted on or near a bar. The anchor position can be defined either explicitly with attribute at, or implicitly with attributes from and till. In the latter case the text will be positioned in the middle of the defined bar segment. See also text input for rules

The text may include embedded links1, 2 for use in clickable maps.
textcolor (O)
Obviously defines the color of the text.

The color id specified should be defined first with command Colors. When not specified color black will be assumed.

fontsize (O)
Specify a point size between 6 and 30, or (preferably) one of tags XS, S (default), M, L or XL. See for more details font support.
align (O)
Specify center (default), left or right.
link (O)
Specify a web link1 (URL) for use in clickable maps. The text will be shown as a blue clickable link.

1 Either use attribute link, or an embedded link in attribute text, not both.
2 On GIF/PNG images only one clickable link will be shown per text segment (text with line breaks (~) constitutes several segments).
example:
PlotData=
   bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:7/12 [[Pearl Harbour]]
produces the same result as:
PlotData=
   bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:"7/12 Pearl Harbour" link:http://en.wikipedia.org/wiki/Pearl_Harbour

Marker attribute
mark
Places a marker in a bar at the specified position. Specify as mark:(symbol, color). Only symbol line is supported to date.

The color id specified should be defined first with command Colors. When not specified color black will be assumed.

example:
PlotData=
   bar:US at:07/12/1941 mark:(line,white)


Top TextData

Command TextData is used to define a text block that can be positioned anywhere on the chart.
text
The actual text. See also text input for rules.

The text may include embedded links1, 2 for use in clickable maps.
pos
Defines top left corner of text block in absolute or relative measurements. Define as pos:(x,y)
link (O)
Specify a web link1 (URL) for use in clickable maps. The label along the axis will be shown as a blue clickable link.

textcolor (O)
Obviously defines the color of the text.

The color id specified should be defined first with command Colors. When not specified color black will be assumed.

fontsize (O)
Specify a point size between 6 and 30, or (preferably) one of tags XS, S (default), M, L or XL. See for more details font support.
tabs (O)
Defines position and alignment for tab character: ^ (caret)

Specify multiple tab settings as tabs:(x1-a1,x2-a2,x3-a3,etc..) where
      xn is the horizontal displacement in absolute measurements from the left side of the text, and
      an is the alignment for the text segment (specify center, left of right).

lineheight (O)
Defines spacing between consecutive lines in absolute measurements. Specify a value up to 40 pixels or 0.4in. When not specified a default lineheight will be based on the fontsize currently in use.
1 Either use attribute link, or an embedded link in attribute text, not both.
2 On GIF/PNG images only one clickable link will be shown per text segment (text with tabs (^) constitutes several segments).
example:
TextData =
  pos:(50,100) textcolor:black fontsize:XS
  tabs:(4-right,12-right,14-left,34-left)
  text:^1^1940^27/9^Germany,Italy and Japan sign [[Tripartite Pact]]
  text:^10^1944^1-22/7^Bretton Woods 44 nations establish
  text:^^^^^IMF and World Bank

will be shown as:

   1    27/9 Germany,Italy and Japan sign Tripartite Pact
  10  1-22/7 Bretton Woods 44 nations establish
                                 IMF and World Bank


Top TimeAxis

This command defined the orientation of the time axis, and textual representation of stubs along that axis.
format (O)
Specify in which format dates should be presented along the time axis.
Note: this feature is incomplete. Currently only format yyyy (default) is supported. More formats will follow.
orientation (O)
Specify hor[izontal] (default) or ver[tical].
example:
TimeAxis = orientation:horizontal format:yyyy

3d. Input rules


Top Absolute Measurements

Absolute measurements are used for specifying sizes, positions and position shifts.

A two letter postfix immediately after the number defines the unit.
Postfixes are: px (for pixels), in (for inches), cm (for centimeters). A resolution of 100 pixels per inch is assumed.

When no postfix is supplied pixels are assumed. Values can have a decimal fraction.

These specifications are equivalent:

width:800
 
width:800px
 
width:8in
 
width:3.15cm
 


Top Relative Measurements

Relative measurements are used for specifying sizes and positions.

Specify a number between 0 and 100, immediately followed by a % (percentage) sign.

For horizontal measurements the percentage is related to image width, for vertical measurements to image height.

example:
PlotArea = width:80% height:80% left:10% bottom:5%


Top Text Input

Text input is subject to a few rules:


Top Font Support

No unicode is allowed yet. No font type can be specified yet.

The rendering package used (Ploticus) comes out of the box with one ASCII standard font in five sizes, at least in the Windows version. Therefore, until freetype is supported (see below), the range of font sizes for PNG images is limited to these five. EasyTimelines also produces a SVG version of the image. Here any font size is possible.

Five font tags are predefined which will render at slightly different sizes in PGN and SVG images to produce optimal readability for both platforms. It is advised to use these tags instead of numbers whenever possible. They are XS, S (default), M, L or XL, which stands for (very) small, medium and (very) large.

Please review both versions of the image for proper text placement before uploading them to Wikipedia.

If someone is familiar with gcc or another C compiler: the author of Ploticus provides instructions for recompiling Ploticus to add freetype and unicode support to the Windows version. I'd be obliged.


3e. Clickable Maps

All output formats, i.e. GIF, PNG and SVG, can contain clickable links. Texts shown in blue, and bars, may then be clicked, to surf to another web page.

Links can be specified with commands BarData, PlotData and TextData, either with attribute link, or as embedded links, via attribute text.

For SVG files no change in the web page on which they appear is needed.

For GIF and PNG files this only works when a extra piece of code, a map definition, is added to the HTML code for the page.

Therefore generation of clickable links for the latter two formats depends on an extra runtime option. Run EasyTimeline with option -m to generate a .map file which contains the map definition to be included in the HTML and to render text links blue. With extra runtime option -h a sample HTML file is generated to preview the result.

The map file will look something like this

example:
<area shape="rect" href="http://..some url .." coords="..coordinates of clickable area 1.." >
<area shape="rect" href="http://..other url.." coords="..coordinates of clickable area 2.." >
etc

Copy this block of code into the HTML file, surrounded by <map name='mapname'> and </map>
Add a reference to this clickmap in the HTML tag defining the image: <img src=... usemap='#mapname'>

full example:
<map name='map1'>
<area shape="rect" href="http://..some url .." coords="..coordinates of clickable area 1.." >
<area shape="rect" href="http://..other url.." coords="..coordinates of clickable area 2.." >
</map>

<img src=Timeline1.png usemap='#map1'>


Top Embedded Links

Embedded links are links that are (part of a) displayable text, specified with attribute text. Their counterpart are explicit links (URL only) which are defined with attrribute link.

Both type of links can be specified with commands BarData, PlotData and TextData and are used for clickable maps.

The syntax for embedded links is based on the MediaWiki syntax, which has been developed for the Wikipedia encyclopedia, but is used elsewhere too.

Text between double square brackets defines a link to a Wikipedia article. By default the link points to the English version. An article on any of the other Wikipedias can be defined by prefixing the article name with the 2 or 3 letter code for that Wikipedia. Any text following after a | (pipe) symbol, will be displayed instead of the actual article name.

Any web link (URL) can be specified between single square brackets. Again, the actual text to be displayed follows after a | (pipe) symbol.

The following three embedded links all point to the same article on the English Wikipedia: http://en.wikipedia.org/wiki/Rembrandt
text:1642 [[Rembrandt]] paints Night Watch
# will be shown as: 1642 Rembrandt paints Night Watch

text:1642 [[Rembrandt|Rembrandt van Rijn]] paints Night Watch
# will be shown as: 1642 Rembrandt van Rijn paints Night Watch

text:1642 [http://en.wikipedia.org/wiki/Rembrandt|Rembrandt van Rijn] paints Night Watch
# will be shown as: 1642 Rembrandt van Rijn paints Night Watch

The following embedded link points to the article on the Dutch Wikipedia: http://nl.wikipedia.org/wiki/Rembrandt
text:1642 [[nl:Rembrandt|Rembrandt van Rijn]] paints Night Watch
# will be shown as: 1642 Rembrandt van Rijn paints Night Watch


3f. Trouble shooting

  1. Problem: EasyTimeline generates an image that is larger than you requested with command ImageSize.

    Solution: You probably specified a long text that extends beyond the defined image boundaries. The image size is then automatically adjusted. Check your texts and modify start position, text alignment and/or font size or add line breaks within the text.


Return to 2: Procedure Copyright (C) 2004 Erik Zachte, Amsterdam, The Netherlands.
Email:erikzachte@+++.com (nospam: +++=infodisiac).

Wikipedia on your PDA  My other Wikipedia projects  Statistics for all Wikipedias

Continue to 4: Download

EasyTimeline is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2.