Content deleted Content added
TRANSWIKI: Copied from Meta:Help:EasyTimeline syntax. |
|||
Line 1:
{{
The EasyTimeline feature produces an embedded [[Help:Images and other uploaded files|image]] from wikitext. The image can be a one-dimensional diagram (horizontally or vertically), or a two-dimensional one. The name "EasyTimeline" refers to the possibility to apply the feature with a time scale horizontally or vertically, possibly with another parameter in the other direction, but there are also various other possiblities.
See also [[EasyTimeline]], [
==Introduction==
Line 14:
EasyTimeline will then be invoked to render a PNG image and (optionally) a clickable map.
'''Disclaimer''': Even
A simple timeline may take half an hour to compose (or even less, when a suitable example is taken as a basis). Large timelines may take a few hours for composition and fine-tuning. However, adding to or correcting a timeline, no matter how complex, should be a relatively straightforward affair, even for contributors who have no expert knowledge of the syntax described here. Feel free to ask the [[user:Erik Zachte|author of EasyTimeline]] for advice.
Line 20 ⟶ 22:
==Available commands==
The script commands define:
*Overall layout: [[#
*Interpretation and presentation of dates and periods: [[#DateFormat|DateFormat]], [[#
*Events, periods and descriptive texts: [[#PlotData|PlotData]], [[#TextData|TextData]]
*How to order, divide, and name groups of events and periods: [[#BarData|BarData]], [[#Legend|Legend]], [[#
*Shorthands for pieces of script code that occur multiple times: [[#Define|Define]]
The following commands are mandatory: [[#
'''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.
----
==General syntax rules==
Line 39 ⟶ 42:
(the latter is useful for visually grouping related data lines).
Commands have
command:
'''''Command = attribute(s)'''''
<pre>
DateFormat = dd/mm/yyyy
</pre
'''''Command name = attribute(s)'''''
<pre>
Color Jp = value:red legend:Japan
</pre
'''''Command =<br/> attribute(s)<br/> attribute(s)<br/> etc.'''''
<pre>
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
</pre
===Comments===
Line 67 ⟶ 70:
<small>Examples:</small>
<pre>
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 <#
</pre
===Attributes===
Line 80 ⟶ 83:
<small>Examples:</small>
<pre>
AlignBars = justify
Color SB = value:rgb(0.8,0,0.7) legend:Sea_Battles
</pre
====Parameters vs data items====
Line 99 ⟶ 102:
<small>Example:</small>
<!-- all data start with space here to keep source formatting
but in actual usage commands should be at start of line -->
<pre>
# 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.
Line 125 ⟶ 129:
TextData = # now PlotData is considered complete
tabs:...etc
</pre
===Special characters===
Line 134 ⟶ 138:
*'''$''' (dollar sign) precedes any user defined constant
----
==Command Reference==
For each command the valid attributes are listed. Some commands and/or
Line 153 ⟶ 158:
<small>Examples:</small>
{{EasyTimeline_Examples_AlignBars}}
----
===BackgroundColors===
Line 161 ⟶ 168:
<small>Examples:</small>
<pre>
BackgroundColors = bars:darkgrey
Line 167 ⟶ 174:
BackgroundColors = canvas:lightgrey
</pre
----
===BarData===
This is an optional command which if present determines which bars will be drawn on the chart and in which order.
Line 185 ⟶ 193:
<small>Examples:</small>
<pre>
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
</pre
The following lines produce the same output (only reference in [[#PlotData|PlotData]] changes):
<pre>
bar:US text:[[United_States]]
Line 199 ⟶ 207:
bar:United_States link:http://www.wikipedia.org/wiki/United_States
</pre
----
===Colors===
This command allows colors to be defined and coupled to an id (identification tag).
Line 215 ⟶ 223:
<small>Example:</small>
<pre>
Colors =
id:war value:red legend:War Period
Line 222 ⟶ 230:
id:lightgrey value:gray(0.9)
id:darkgrey value:gray(0.1)
</pre
----
===DateFormat===
Line 238 ⟶ 247:
<small>Example:</small>
<pre>
DateFormat = mm/dd/yyy
</pre
----
===Define===
Line 249 ⟶ 260:
<small>Example:</small>
<pre>
Define $broad = width:30
Define $narrow = width:10
Define $bardefaults = $broad fontsize:S
</pre
----
===ImageSize (mandatory)===
This command defines the overall size of the final image.
Specify values in [[#Measurements|absolute measurements]].
;width : Width of final image: maximum is 1600 pixels, minimum is 25
;height : Height of final image: maximum is 1200 pixels, minimum is 25
For maximum flexibility you can let the script calculate the height or width of the image, based on the number of bars and the amount in pixels to add per bar. Specify '''height:auto''' (for horizontal time axis) or '''width:auto''' (for vertical time axis).
This is especially helpful when the number of bars in a timeline is likely to change over time again and again. Or to ensure equal distances between bars in images with many narrow bars where differences in amount of white space would soon be noticed (see for a real example [[en:Template:Vocal and instrumental pitch ranges]]). Or to make sure several related timelines always use the same distance between bars, no matter how many bars each contains (see for a real example [[en:List of popes (graphical)]]. In short it is a good idea most of the time.
;barincrement : Amount in pixels that should be added to the image size for each bar specified (mandatory and only allowed in combination with width:auto or height:auto).
<small>Examples:</small>
<pre>
ImageSize = width:800 height:600
ImageSize = width:800 height:auto barincrement:30
</pre>
----
===Legend===
Line 289 ⟶ 293:
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).
:''
;'''position''' (O) : Defines placement of the legend relative to the chart area. Specify top, bottom (default) or right.
:''
;'''columns''' (O) : Specify 1, 2, 3 or 4. When this attribute is omitted the number of columns is determined as follows:
*
*
**
**
''
;'''columnwidth''' (O) : Defines the distance between columns. You can specify an [[#Measurements|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).
;
<small>Examples:</small>
<pre>
Legend = orientation:vertical position:bottom columns:3 columnwidth:140
Line 314 ⟶ 317:
Legend = left:100 top:120 columns:3
</pre
----
===LineData===
Some timelines extend over several clearly distinct periods.
A line demarcating these periods may serve as a visual aid.
;at : Draws a line perpendicular to the time axis (default at maximal length, see also below).<br>Specify the date/year where the line should be drawn, in compliance with the specified [[#DateFormat|DateFormat]].
;color : Specify the color in which the line should drawn.
:'''Note''': The color id specified should be defined first with command [[#Colors|Colors]].
;layer : Specify front or back (default). Defines whether the line should appear in front of or behind all time segment bars.
;width : specify value between 0.1 (very thin) and 10 (very thick)
Only in rare cases the following extra attributes may be needed for full flexibility:
'''Advanced positioning options'''
You can draw lines in any direction. The following options are available:
*'''Perpendicular to the time axis''' with arbitrary start and stop points: '''at''':''date'' '''frompos''':''position '''tillpos''':''position''
*'''Parallel to the time axis''' with arbitrary start and stop points '''from''':''date'' '''till''':''date'' '''atpos''':''position''
*'''In any direction''' with arbitrary start and stop points: '''points''':(x1,y1)(x2,y2)
Attributes '''at''', '''from''' and '''till''' expect a date or year, in compliance with the specified [[#DateFormat|DateFormat]].<br>
Attributes '''frompos''', '''tillpos''', '''atpos''' expect coordinates (e.g. pixels values)
<small>Example:</small>
<timeline>
ImageSize = width:200 height:120
PlotArea = left:20 right:10 top:10 bottom:20
TimeAxis = orientation:horizontal
AlignBars = justify
Colors =
id:gray1 value:gray(0.3)
id:gray2 value:gray(0.5)
id:gray3 value:gray(0.7)
Period = from:0 till:10
ScaleMajor = unit:year increment:1 start:0
PlotData =
bar:X color:gray1 width:15
from:start till:end
bar:Y color:gray2
from:start till:end
bar:Z color:gray3
from:start till:end
LineData =
layer:front
at:1 color:yellow
at:2 color:orange layer:back
at:4 frompos:50 tillpos:105 color:green
from:5 till:8 atpos:50 color:red
points:(100,20)(170,105) color:blue width:3
</timeline>
<pre>
LineData =
layer:front # all lines in front of bars unless stated otherwise
at:1 color:yellow # perpendicular to time axis full length
at:2 color:orange layer:back # perpendicular to time axis full length but behind bars
at:4 frompos:50 tillpos:105 color:green # perpendicular to time axis, with specified start and stop points
from:5 till:8 atpos:50 color:red # parallel to time axis
points:(100,20)(170,105) color:blue width:3 # from one arbitrary absolute position to another, extra thick
</pre>
----
===Period (mandatory)===
Line 322 ⟶ 392:
<small>Example:</small>
<pre>
Period = from:01/09/1939 till:02/09/1945
</pre
----
===PlotArea (mandatory)===
;width : Specify value in absolute or relative [[#Measurements|measurements]]. ('''do not use anymore''', see below)
;height : Specify value in absolute or relative measurements. ('''do not use anymore''', see below)
;left : Margin between left side of image and left side of plot area. Specify value in absolute or relative measurements.
;top : Margin between top of image and top of plot area. Specify value in absolute or relative measurements.
;right : Margin between right side of image and right side of plot area. Specify value in absolute or relative measurements.
;bottom : Margin between bottom of image and bottom of plot area. Specify value in absolute or relative measurements.
'''width/height attributes'''
These attributes are only retained for downward compatibility. Earlier a plot area could only be defined by its total ''width'' and ''height'', and ''left'' and ''bottom'' margins. Now you can specify all four margins, and are advised to do so, and not use ''width'' and ''height'' attributes anymore. The advantage is added flexibility: when you change the overall image size, you do not need to adjust the plotarea definition as well. This is even more important when the image size is calculated automatically (see [[#ImageSize (mandatory)|ImageSize]]).
<small>Example:</small>
<pre>
PlotArea = left:40 bottom:60 top:10 right:10 # e.g. extra space to the left and below the plot area for axis labels and legend
</pre>
----
===PlotData===
Line 366 ⟶ 445:
<small>Examples:</small>
<pre>
PlotData=
bar:Japan from:start till:19/02/1945 color:JT
Line 373 ⟶ 452:
at:07/12/1941 shift:(0,-15) text:"<-- WW2 reaches Asia"
</pre
====Bar related attributes====
Line 384 ⟶ 463:
<small>Example:</small>
<pre>
BarData=
id:US text:United States
Line 399 ⟶ 478:
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
</pre
Notes:
#this line establishes a default bar width for the remainder of the data block
Line 420 ⟶ 499:
<small>Example:</small>
<pre>
PlotData=
bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:7/12 [[Pearl Harbour]]
</pre
produces the same result as:
<pre>
PlotData=
bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:"7/12 Pearl Harbour" link:http://www.wikipedia.org/wiki/Pearl_Harbour
</pre
====Marker attribute====
Line 436 ⟶ 515:
<small>Example:</small>
<pre>
PlotData=
bar:test width:15 color:red
from:1900 till:2000
at:1990 mark:(line,white)
</pre
will be shown as:
Line 460 ⟶ 539:
bar:test at:1990 mark:(line,white)
</timeline>
----
===ScaleMajor===
Line 478 ⟶ 559:
<small>Examples:</small>
<pre>
ScaleMajor = gridcolor:red start:1940
ScaleMajor = gridcolor:red unit:month increment:3 start:01/09/1939
</pre
----
===ScaleMinor===
This command defines a further subdivision of the timescale. See ScaleMajor for syntax .
<small>Example:</small>
<pre>
ScaleMajor = grid:red unit:year increment:1 start:01/01/1940
ScaleMinor = grid:blue unit:month increment:3 start:01/10/1939
</pre
----
===TextData===
Used to define a text block that can be positioned anywhere on the chart.
;text : The actual text. See also [[#Text Input|Text Input]] for rules. The text may include embedded links (see '''Notes 1 & 2''').
;pos : Defines the top-left corner of the text block in absolute or relative [[#
;link (O) : Specify a web link (see '''Note 1''') (URL) for use in clickable maps. The label along the axis will be shown as a blue clickable link.
;textcolor (O) : Defines the color of the text. The color id specified should be defined first using [[#Colors|Colors]]. When not specified, the color is black.
Line 509 ⟶ 592:
<small>Example:</small>
<pre>
TextData =
pos:(20,67) textcolor:black fontsize:S
Line 516 ⟶ 599:
text:^10^1944^1-22/7^Bretton Woods 44 nations establish
text:^^^^^IMF and World Bank
</pre
will be shown as:
<timeline>
Line 529 ⟶ 612:
pos:(20,67) textcolor:black fontsize:S
tabs:(10-right,14-left,50-left,90-left,230-left)
text:^1^1940^27/9^Germany,Italy and Japan sign <nowiki>[[Tripartite Pact]]</nowiki>
text:^10^1944^1-22/7^Bretton Woods 44 nations establish
text:^^^^^IMF and World Bank
</timeline>
----
===TimeAxis===
Line 541 ⟶ 626:
<small>Example:</small>
<pre>
TimeAxis = orientation:horizontal format:yyyy
</pre
----
==Presets==
Line 559 ⟶ 646:
<small>Example:</small>
<pre>
PlotArea = width:800 height:600 left:50 bottom:50
</pre
'''Relative measures''' may be used for specifying sizes and positions. Specify a number between 0 and 100, immediately followed by a %
Line 569 ⟶ 656:
<small>Example:</small>
<pre>
PlotArea = width:80% height:80% left:10% bottom:5%
</pre
===Text Input===
Line 583 ⟶ 670:
<small>Example: (the following are all equivalent)</small>
<pre>
BarData =
text:Japanese_mandate_since_1914 bar:Marshalls
Line 592 ⟶ 679:
BarData =
bar:Marshalls text:Japanese mandate since 1914
</pre
3 In data lines following command [[#TextData|TextData]] two characters have special meaning:
Line 599 ⟶ 686:
<small>Example showing line breaks:</small>
<pre>
TextData =
.. text:Generated for Wikipedia~Version 1.1 - 2 Januari 2004
Line 607 ⟶ 694:
# Generated for Wikipedia
# Version 1.1 - 2 Januari 2004
</pre
<small>Example showing tabs:</small>
<pre>
TextData =
tabs:(4-right,12-right,14-left,34-left)
Line 622 ⟶ 709:
# 10 1-22/7 Bretton Woods 44 nations establish
# IMF and World Bank
</pre
----
==Clickable maps==
Line 630 ⟶ 719:
Links can be specified with commands [[#BarData|BarData]], [[#PlotData|PlotData]] and [[#TextData|TextData]],
either with attribute ''link'', or as embedded links, via attribute ''text''.
You can specify one link per text segment.
===Embedded links===
Line 639 ⟶ 730:
Both type of links can be specified with commands [[#BarData|BarData]], [[#PlotData|PlotData]] and [[#TextData|TextData]] and are used for [[#clickable maps|clickable maps]].
In embedded links, internal link style is as usual, interwiki link style does not work, external link style is as usual with single brackets, but here with a pipe instead of a space
Examples:
<pre>
<nowiki>text:example [[Help:Link]] internal link</nowiki>
</pre
will be shown as:
<timeline>
Line 657 ⟶ 748:
pos:(10,10) fontsize:XL text:"example [[Help:Link]] internal link"
</timeline>
<pre>
<nowiki>text:[[Help:Link|Link]]</nowiki>
</pre
will be shown as:
<timeline>
Line 673 ⟶ 764:
</timeline>
<pre>
<nowiki>text:[http://en.wikipedia.org/wiki/Rembrandt|Rembrandt van Rijn] paints Night Watch</nowiki>
</pre
will be shown as:
<timeline>
Line 691 ⟶ 782:
Attempt to use interwiki link style:
<pre>
<nowiki>text:[[en:Main_Page]]</nowiki>
</pre
and similar with nl: and m: give:
<timeline>
Line 732 ⟶ 823:
The third one to Meta-Wikipedia works properly, except from Meta itself, the other links work like [[Main_Page]] (internal page, the prefix is ignored) or e.g. {{SERVER}}/w/Main_Page (gives File not found), depending on the URL of the referring page (e.g. different for a preview page and a diff page).
'''Special characters:'''
Blank spaces and underscores in the url should be written as %20.
The tilde character ('''~''') is normally interpreted as line break. When a tilde is part of an url write it as is two tildes.<br>
For example, link to ''www.site.com/~mysite'' as:
<pre>
<nowiki>text:[www.site.com/~~mysite|My site]</nowiki>
</pre>
The number sign ('''#''') is normally interpreted as start of comment. When a number sign is part of an url make sure the text is embedded in double quotes as follows:
<pre>
<nowiki>text:"More at [www.site.com/~~mysite#section2|My site]"</nowiki>
</pre>
Actually it may be a good idea to always put texts between double quotes.
----
==Font Support==
Line 738 ⟶ 847:
Five font tags are predefined which will render at slightly different sizes in PNG 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=eXtra Small, S=Small (default), M=Medium, L=Large, XL=eXtra
<timeline>
Line 762 ⟶ 871:
{{Template talk:Etl}}
{{H:f|langs=|enname=EasyTimeline syntax}}
[[Category:Graphical
| |||