Help:简易时间线语法

维基百科使用手册

简易时间线的特性就是从wiki文本中产生一个嵌入式图像。这个图像可以是一维的图表(水平或垂直),或者是二维的图表。名为“简易时间线”即表示可以用水平或垂直的方向作为时间刻度,用另一个方向来表示其它参数,但也可能是其他不同的形式。简易时间线的语法並不支持簡繁轉換

参见简易时间线简易时间线索引

简介

只要脚本介于两个专用标签之间就可以产生图像时间线:

<timeline>
腳本
</timeline>

简易时间线就会被调用生成一个PNG格式图像和一个链接映射(可选项)。

注意:即使“简易时间线”的创造是为了简单方便,但是制作一个复杂的时间线表依然不是一件轻松的事情。一个简单的时间线可以花费半个小时来完成(如果有一个合适的例子用来作为基础可以节省更多时间)大型的时间线可能要花费几个小时来创作并且修改。然而,对于现有无论多复杂的时间线进行增加或者更正都是直接快捷的,甚至是对于没有接触过这些语法的使用者。

若有问题请联络简易时间线的作者

可支持字型

Unicode有少許支援,现在只可以使用FreeSans.ttf字型。此字型目前還不支援其它字型。(效果如下)

建議使用預定義的五種字號:XS=超小、S=小(默認)、M=中、L=大、XL=超大。

This documentation is originally a wikified version of the original EasyTimeline documentation.

可用命令

脚本命令定义:

下述命令是必选的:ImageSize(图像尺寸)、PlotArea(图形区)、Period(时段)和TimeAxis(时间轴)。下述命令至少要选一个:PlotData(图形数据)和/或 TextData(文字数据),它们都可以重复多次。所有其它命令都是可选的。

大小写:命令及其属性都能接受大写、小写以及混合拼写。请在使用时保持一致以利于维持可读性,例如对于命令使用混合拼写,而所有属性使用小写。

一般语法规则

脚本可包含命令和注释。每个命令都有一个或多个属性。

命令

命令应该从行首开始。 有些命令带有多行的数据和/或选项。 这些另外的行应该以至少一个空格或完整的空行开始。(下面示范相关的数据行)

根据命令的类型,它可表示为以下的多种形式之一:

命令 = 属性(或多个属性)

DateFormat = dd/mm/yyyy

命令 名字 = 属性(或多个属性)

Color Jp = value:red legend:Japan

命令 =
  属性(或多个属性)
  属性(或多个属性)
  等等……

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

注释

可用单行和多行注释:

  • # 号后文字就是一行注释
  • 介于#><#之间的文字也是注释。用这种方式标记,可使用多行来书写注释。

例如:

Dateformat = dd/mm/yyyy # European date format
Period = from:01/09/1939 till:02/09/1945 #> 该图表将表现二战的
  整个历史。 <#

属性

当有许多属性指定到同一个命令时,它们可以用成对的 '名称:数值'来表示。 当有许多数值指定到同一个属性时,它们必须放入圆括号中。

例如:

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

参数和数据项

大部分命令只接受在同一行指定的属性。

数据块: 有一些命令、像是BarDataPlotDataTextDataColors认为一个数据块是由一个或多个数据行组成。数据行应该以一个或多个空格开始,遇到以非空字符开始的行就认为数据块已结束(例外:应忽略空行,它们可能用来对同一个块中相关的数据行进行分组)。

数据块内的属性按照概念可分成参数数据项。数据块可同时包含参数和数据项。

数据项:在数据行属性中,textfromtillat仅在它们所出现的行起作用。

参数:在数据行属性中,像是colorfontsize,根据上下文的不同会有不同的含义。如果它们出现在没有数据项的行中,它们将为后面的数据行设定新的默认属性。如果它们出现的行中同时也有数据项,那么它们只能在此行起作用,取代前面设定的默认属性。

例如:

# 在该例子中将分别画出红蓝两条系列,
# 但在每一系列中将有一段使用绿色描绘以标示战争时期。

PlotData =
  color:red fontsize:S                               # 默认值
  bar:USSR from:1919 till:1922 text:Lenin            # 红条
  bar:USSR from:1922 till:1953 text:Stalin           # 红条
  bar:USSR from:1939 till:1945 text:WWII color:green # 绿条
  bar:USSR from:1953 till:1964 text:Krushchev        # 红条
   
  color:blue                                         # 改变默认颜色
  bar:US from:1913 till:1921 text:Wilson             # 蓝条
  bar:US from:1917 till:1918 text:WWI color:green    # 绿条
  bar:US from:1921 till:1923 text:Harding            # 蓝条

#> 此多行注释并不终止PlotData命令,
   即使前一行并未以空格开头。<#

   bar:US from:1923 till:1929 text:Coolidge          # 蓝条

TextData =                                           # 此处PlotData命令结束
   tabs:...etc

特殊字符

  • ##><#(井号、井号+大于号、小于号+井号):参见Comments
  • ~(波浪线)在文字中:换行
  • ^在文字中:缩进
  • _(下划线)在文字中:空格
  • $(美元符号)用在任何用户自定义常量前

命令参考

每一个命令都列出了有效的属性,一些命令或属性是可选的[表示为(可选)]。

一些命令的某些属性是互斥的。(应用时再解释)

AlignBars

条块(Bar)总是以相同的距离绘制。 这个命令用来说明是否条块应该排列得尽可能分开,或者保留空白在图表的左(或上)边与第一条之间,还是保留空白在图表的右(或下)边与最后一栏之间。

early(默认)
第一条放置在图表最左(或最上)的位置('粘贴'到轴上),在最后一条与图表的右(或下)边之间留出空白。
late
early相反,最后一条尽可能地放置在图表的右(或下)边,在轴线(图表的左/上边)与第一条之间留出空白。
justify
第一条和最后一条放置得尽可能分开,图表的两边都不留空白。当只有一条存在时,justify就表示"居中"。

例如:

TimeAxis = orientation:horizontal orientation:vertical

Alignbars =

BackgroundColors

这个命令允许指定图表不同部分的背景颜色。 任何颜色id的指定在首次使用时都应该先进行定义Colors.

canvas (可选)
为全部图像指定背景颜色。
bars (可选)
为所有bars指定背景颜色。

例如:

BackgroundColors = bars:darkgrey

BackgroundColors = canvas:lightgrey bars:darkgrey

BackgroundColors = canvas:lightgrey

BarData

这是一个可选命令,它可以调整哪些条块将被显示、以何种顺序显示。如果它被省略,栏将按照它在PlotData命令中的出现的顺序进行绘制。

对于使用许多条的复合时间线,推荐使用这个命令:

  • 这将简化对显示数据的重新布置;
  • PlotData中指定的条块名字将和此列表比对,从而减少输入错误的可能。
bar
定义了条块的识别号,其他的命令(特别是PlotData)将使用该识别作为对其之引用。它也是坐标轴上显示的标签,除非设置了text属性。bar识别号不可包含空格:使用下划线代替,它们将被自动转换为空格。
text (可选)
指定显示于坐标轴上的标签,以取代条块识别号。参见text input。该文本可以包含一个内部链接(参见注释1)。
link (可选)
指定一个链接(URL)。参见注释1。坐标轴上的标签即显示为一个超链接。

注释

  1. 要么使用link属性、要么在text属性中使用内部链接,二者不能并用。

示例

BarData =
  bar:Japan
  bar:US       text:"美国"          # 将PlotData数据定位到条块“US”但显示为“美国”
  bar:China    text:[[中国]]        # “中国”标签将指向维基百科中的中国条目

以下代码产生同样的输出(只列出PlotData的改变):

bar:US        text:[[United_States]]

bar:US        text:"United States"     link:http://www.wikipedia.org/wiki/United_States

bar:United_States                      link:http://www.wikipedia.org/wiki/United_States

Colors

这个命令可用来定义颜色并用一个id(身份识别)来表示。 其它命令将用在这里指定的id来调用颜色。 这个命令可指定一个或多个的颜色定义,每一个都必须位于独立的缩进行。

id
其它命令将使用这个id来指定文本、栏或背景的颜色。
value
实际颜色定义。颜色值可用下述任一种方式表示:
  • 预定义颜色值,有32种预定义的颜色名称是公认的(参见Ploticus color page,在这里定义了这些颜色值)。
  • rgb (红,绿,蓝): 指定3个介于0(最小)和1(最大)之间的数字
  • hsv (色调,饱和度,值): 指定3个介于0和1之间的数字
  • gray (值): 指定一个介于0 (黑) 和 1 (白)
legend (可选)
指定图例中对于使用该种颜色的项目的文字说明,如果该属性被忽略,图例中则不显示任何文本。参见Text Input以获得详细规则。

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)

DateFormat

这个命令定义了在其它命令中出现的日期应该如何解释。

有效的日期格式:

dd/mm/yyyy
日期解释为 日/月/年
注意: 这种格式只允许用于01/01/1800以后的日期
mm/dd/yyyy
日期解释为 月/日/年
注意: 这种格式只允许用于01/01/1800以后的日期
yyyy
这种格式使用从 -9999 到 +9999的整数

例如:

DateFormat = mm/dd/yyy

Define

这一个命令允许定义本文常数,例如,为在多个时间段出现的部分脚本代码定义速记。本文常数应该总是以一个$(美元符号)开始。

例如:

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

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 defined by TimeAxis).

at
Specify the date/year where the line should be drawn, in compliance with the specified DateFormat.
color
Specify the color in which the line should drawn.
Note: The color id specified should be defined first with command Colors.

Example:

LineData=
  at:start      color:red
  at:end        color:red
  at:07/12/1941 color:red

ImageSize (必选)

This command defines the overall size of the final image. Specify values in absolute measurements.

width
Width of final image: maximum is 1600 pixels
height
Height of final image: maximum is 1200 pixels

Example:

ImageSize = width:800 height:600

Legend

A legend will only be 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 :
    • Position right : All entries will be in one column
    • Position top or bottom : The number of columns depends on the number of entries to be shown:
      1-5 entries: 1 column, 6-10 entries: 2 columns, 11 or more entries: 3 columns.

Tip: 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:horizontal position:bottom

Legend = left:100 top:120 columns:3

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 TextData.
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

PlotArea (必选)

width
以绝对或相对测量来指定数值。
height
以绝对或相对测量来指定数值。
left
图像左边和图形区左边的空白余量。以绝对或相对测量来指定数值。
bottom
图像底边和图形区底边的空白余量。以绝对或相对测量来指定数值。

例如:

PlotArea = width:640 height:420 left:160 bottom:120

PlotArea = width:80% height:70% left:20% bottom:20%

PlotData

用于定义栏 (用符号表示时间周期), 并且在栏后的特定位置上加入文字。

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.

图形区有许多的属性,其中有些时互斥的。这些属性可被分为以下几种:

  • 位置属性
  • 栏相关属性
  • 文字属性
  • 标记属性

位置属性

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. Use date/year format as specified in DateFormat or specify start or end which refers to time frame defined by command Period.
NB: This attribute can not be combined with attributes from or till.
from
Specifies at which date/year a bar should start. Use date/year format as specified in DateFormat or specify start which refers to time frame defined by command Period.
NB: This attribute should be used in combination with attribute till and can not be combined with attribute at.
till
Specifies at which date/year a bar should end. Use date/year format as specified in DateFormat or specify end which refers to time frame defined by command Period.
NB: This attribute should be used in combination with attribute from and can not be combined with attribute at.
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
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
指定栏应该被绘制的颜色。
The color id specified should be defined first with command Colors.
width
Specifies the width of the bar in absolute or relative measurements.

例如:

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

Notes:

  1. this line establishes a default bar width for the remainder of the data block
  2. this line specifies a bar to be drawn and a text to placed on it at the same time
  3. bar US will be drawn before bar SB, even when specified after it, because command BarData determines the sequence
  4. bar Midway will be rejected because it is not declared with command BarData
  5. the last line will not result in a bar being plotted, it merely specifies on which bar the text should be placed

文字属性

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 links (see Notes 1 & 2) for use in clickable maps.
textcolor (O)
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 Font Support for more details.
align (O)
Specify center (default), left or right.
link (O)
Specify a web link (see Note 1) (URL) for use in clickable maps. The text will be shown as a blue clickable link.

Notes

  1. Either use attribute link, or an embedded link in attribute text, not both.
  2. On 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://www.wikipedia.org/wiki/Pearl_Harbour

标记属性

mark
Places a marker in a bar at the specified position. Specify as mark:(symbol, color). The only value for symbol supported to date is line. The color id specified should be defined first with command Colors. When not specified color black will be assumed.

Example:

PlotData=
  bar:test width:15 color:red
  from:1900 till:2000
  at:1990 mark:(line,white)

will be shown as:

ScaleMajor

This command divides the timeline into smaller periods, either

  • Graphically, through thin vertical or horizontal lines in the chart
  • Textually, through stubs in the time axis, 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:

ScaleMajor = gridcolor:red start:1940

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

ScaleMinor

This command defines a further subdivision of the timescale. See ScaleMajor for syntax .

Example:

ScaleMajor = grid:red  unit:year  increment:1 start:01/01/1940
ScaleMinor = grid:blue unit:month increment:3 start:01/10/1939

TextData

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 links (see Notes 1 & 2).
pos
Defines the top-left corner of the text block in absolute or relative measurements. Define as pos:(x,y).
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. When not specified, the color is black.
fontsize (O)
Specify a point size between 6 and 30, or (preferably) one of tags XS, S (default), M, L or XL (see Font Support for more details).
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
  • an is the alignment for the text segment (specify center, left or 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 font size currently in use.

Notes:

  1. Either use attribute link, or an embedded link in attribute text, not both.
  2. On PNG images only one clickable link will be shown per text segment (text with tabs (^) constitutes several segments).

Example:

TextData =
  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 [[Tripartite Pact]]
  text:^10^1944^1-22/7^Bretton Woods 44 nations establish
  text:^^^^^IMF and World Bank

will be shown as:

Tripartite Pact

TimeAxis

Defines 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.
Currently only format yyyy (default) is supported. More formats may follow.
orientation (O)
Specify hor[izontal] (default) or ver[tical].

Example:

TimeAxis = orientation:horizontal format:yyyy

Presets

At the moment two presets are available:

  • Preset = TimeVertical_OneBar_UnitYear
  • Preset = TimeHorizontal_AutoPlaceBars_UnitYear

Not clear if whether there is documentation about them.

输入规则

尺寸和位置比例

Absolute measures may be used for specifying sizes, positions and position shifts, measured in pixels.

Example:

PlotArea = width:800 height:600 left:50 bottom:50

Relative measures may be 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.

The first coordinate is horizontal from left to right, the second is vertically upward.

Example:

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

文字输入

Text input is subject to a few rules:

1 No unicode is allowed yet. See also font support.

2 When text should contain spaces, either specify these by using underscores or place the text between double quotes.

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: (the following are all equivalent)

BarData =
  text:Japanese_mandate_since_1914 bar:Marshalls

BarData =
  text:"Japanese mandate since 1914" bar:Marshalls

BarData =
  bar:Marshalls text:Japanese mandate since 1914

3 In data lines following command TextData two characters have special meaning:

~ (tilde) means line break
^ (caret) means tab

Example showing line breaks:

TextData =
  .. text:Generated for Wikipedia~Version 1.1 - 2 Januari 2004

# will be shown as:
#
#  Generated for Wikipedia
#  Version 1.1 - 2 Januari 2004

Example showing tabs:

TextData =
  tabs:(4-right,12-right,14-left,34-left)
  text:^1^1940^27/9^Berlin Ger,It,Jap 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 Berlin Ger,It,Jap sign Tripartite Pact
#     10  1-22/7 Bretton Woods 44 nations establish
#                                    IMF and World Bank

可点击的图

Both output formats available in MediaWiki, i.e. 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.

嵌入式链接

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 attribute link.

Both type of links can be specified with commands BarData, PlotData and TextData and are used for 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. Blank spaces and underscores in the url should be written as %20.

Examples:

  text:example [[Help:Link]] internal link

will be shown as:

Help:Link
  text:[[Help:Link|Link]]

will be shown as:

Help:Link
  text:[http://en.wikipedia.org/wiki/Rembrandt|Rembrandt van Rijn] paints Night Watch

will be shown as:

en.wikipedia.org/..

Attempt to use interwiki link style:

  text:[[en:Main_Page]]
and similar with nl: and m: give:
m:Main Page

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. //zh.wikipedia.org/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).

EasyTimeline code with a template parameter is not allowed