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.
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.
Commands have the one of the following forms, depending on the type of command:
example:
example:
example:
examples:
Color SB = value:rgb(0.8,0,0.7) legend:Sea_Battles
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
example:
3a. Available Commands
The script commands define:
ImageSize -
PlotArea -
Colors -
BackgroundColors -
AlignBars
DateFormat -
Period -
MajorScale -
MinorScale -
TimeAxis
PlotData -
TextData
BarData -
Legend -
DrawLines
Define
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).
attribute(s)
attribute(s)
etc.
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:
examples: (green is comment)
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.
Parameters vs Data Items
Most commands only accept parameters that are specified on the same line.
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.
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
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).
Tip: For complex timelines with many bars usage of this command is recommended:
example:
The following lines produce the same output (only reference in PlotData changes):
See Ploticus color page where all these constants are defined
Valid dateformats are:
example:
Lines specified here will be drawn over the whole width/length of the chart
(depending on the orientation of TimeAxis).
Note: The color id specified should be defined first with command Colors.
When this attribute is omitted the number of columns is determined as follows:
Note: the orientation of the lines and/or placement of the stubs
depends on the orientation of the TimeAxis
Note: The color id specified should be defined first with command Colors.
Note: When DateFormat yyyy is specified, only unit year is allowed.
examples:
See for syntax MajorScale
example:
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:
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.
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.
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.
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.
The color id specified should be defined first with command Colors.
The color id specified should be defined first with command Colors.
When not specified color black will be assumed.
The color id specified should be defined first with command Colors.
When not specified color black will be assumed.
example:
The color id specified should be defined first with command Colors.
When not specified color black will be assumed.
Top AlignBars
example:
Top BackgroundColors
examples:
Top BarData
• It will ease reordering of the displayed data.
• Bar names specified in PlotData can be validated against this list, thus preventing typing errors.
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
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
This command expects one or more color definitions, each on a separate indented line.
example:
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
example:
Top Define
Text constants should always start with a $ (dollar sign).
Define $narrow = width:10
Define $bardefaults = $broad fontsize:S
Top DrawLines
example: (used here)
at:start color:red
at:end color:red
at:07/12/1941 color:red
Top ImageSize
example:
Top Legend
There are several ways to define the appearance and position of the legend.
Some attributes are mutually exclusive (see below).
examples:
Top MajorScale
Top MinorScale
MinorScale = grid:blue unit:month increment:3 start:01/10/1939
Top Period
Both parameters are mandatory. Specify dates in compliance with specified DateFormat.
example:
Top PlotArea
examples:
Top 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"
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
bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:7/12 [[Pearl Harbour]]
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
bar:US at:07/12/1941 mark:(line,white)
Top TextData
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).
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:
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:
Exception: when the text attribute is the last attribute on a line, spaces are allowed
(no confusion will arise where the text stops and the next attribute starts, that is -to be precise- when no colons occur in the text).
example:
example:
example:
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.
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:
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:
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
The following embedded link points to the article on the Dutch Wikipedia: http://nl.wikipedia.org/wiki/Rembrandt
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.