The Battle for Wesnoth Wiki - User contributions [en]

WML for Complete Beginners: Chapter 1/zh-Hans

2017-03-18T11:22:36Z

Vanfans: /* 基本组件：标签和属性 */

{| {{Prettytable}}
|-
!|其他语言：
[[WML_for_Complete_Beginners:_Chapter_1|English]]
[[WML_for_Complete_Beginners:_Chapter_1/zh|简体中文]]
|}

==第1章：语法==

首先让我们看看 WML 的''语法''。

对于不了解语言“语法”的朋友，可以把它看作是编写 WML 的规则。这个概念有些混乱，但是，无论您是否意识到，您在日常生活中时时刻刻都在使用语法。比如句子“我喜欢果冻和奶酪三明治”。这句话就包含语法，语法让受众能听懂句子的含义。如果您说“喜欢奶酪我和三明治果冻”，这句话也就失去了意义，因为没人听得懂。

就像英语的语法一样，WML 语法也需要字母、拼写、标点，这样才能让其他人理解您想表达什么。例如，如果您胡略语法，然后写出“一天玛丽和我有去看大象在动物园它是长”，那么大家不会明白您在写什么。但是如果您使用正确的语法：“某日，我和玛丽去动物园看到大象。它的鼻子真的很长”，这就很清楚了，因为这里用到了正确的语法。正如英国人无法理解使用错误语法写出的句子一样，韦诺之战也不会读取语法错误的脚本。

所以我们先看一下 WML 的基本语法。稍后再来介绍更复杂的 WML 语法，但是这些足够您开始学习。

===基本组件：标签和属性===

WML，就像首字母表达的那样，这是一个“[https://zh.wikipedia.org/wiki/%E7%BD%AE%E6%A0%87%E8%AF%AD%E8%A8%80 标记语言]。”这表示整个语言的语法包含两个基本元素：'''tags'''和'''attributes'''。
====标签====

:标签是由两个方括号扩起来的小写字符串，两端各一个。下面是“campaign”的标签示例：

[campaign]

:标签只能包含字母和数字和下划线“_”。请注意前面提到的，“标签是''小写''字符串”。这是 WML 语法的基本：所有标签都用小写字母。如果您使用大写字母，WML 引擎会无法理解，并且发出错误。

:和大部分标记语言一样，WML 的标签是成对出现的：一个开始标记和一个结束标记。就像一本书的封面和封底：打开一本书的封面表示开始，到达封底就意味着已经读完了这本书。同样，WML 引擎从开始标签开始。一直执行到结束标签。

:结束标签除了和开始标签一样的关键字以外，还需要在方括号后面加入一个正斜杠“/”。正斜杠表示这个标签是结束标。下面是“campaign”标签的示例：

[/campaign]

:开始标识和结束标识合起来称作'''标签集'''。标签集有两个标签：开始和结束。例如“campaign”标签集就像这个样子：

[campaign]
[/campaign]

:所以我们现在知道 WML 引擎如何判断开始和结束和书写它们时的语法。这些是 WML 标签的基本概念。之后我们再讨论更复杂的标签；现在请确保您了解这些概念。

:在进入下个章节之前，我们回顾一下这个部分提到的有关标签的内容：

::*标签是使用两个方括号括起来的小写字符串。
::*结束标签和起始标签相同，只是多了一个斜杠。
::*起始标签和结束标签一起称为“标签集”。
::*标签集只能由两个标签组成：起始和结束。

:现在我们了解了起始、结束标签，下面该了解如何使用它们。

====属性====

:属性由两部分组成：''keys''和''values''，书写格式如下：

key=value

:属性的功能是存储 WML 引擎需要的信息。属性的''key''说明存储什么样的信息，属性的''value''是存储的实际数据。等号左侧的文本作为键，右侧作为值。

:这听起来有些乱，举个实际的例子来说明：

:您想让您的朋友去杂货店买一块面包。您会直接对他说“去”吗？不会，这样他不会明白您让他做什么，您也不会有面包吃。同样，如果您只写一个标签集，等同于告诉 WML 引擎做什么，但是这还不够。如果您的朋友是个 WML 引擎，您让他去杂货店买面包，您可以给他这样的代码（''注意''：这不是真正的 WML 代码，这是教程中使用的伪代码）。

[go]
where=grocery_store
get=bread
[/go]

:标签告诉 WML 引擎做什么（类似让您的朋友“去”），但是没有属性来指定要做什么（比如告诉朋友什么时候去哪里），如果没有具体的信息，WML 引擎不会做任何事情。如果您让您的朋友“去”，他什么都不会做，因为不知道去哪里做什么。

:*'''Keys'''

::键是小写字母字符串，他告诉游戏处理的是什么信息。键是区分大小写的（虽然不能使用大写），需要正确拼写。

:*'''Values'''

::WML 的键只会处理一个类型的数据，也就是''字符串''。字符串是 ASCII 字符序列，包括键盘上的任何字符。字符串分成两类：标准和数字。

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-translatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter [FIXME HERE]). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 8 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 12 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

注意：本文翻译质量不佳

Next Chapter:
[[WML for Complete Beginners: Chapter 2]]

Return to introduction:
[[WML for Complete Beginners: Introduction]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 1/zh-Hans

2017-03-16T20:07:38Z

Vanfans: Created page with "{| {{Prettytable}} |- !|其他语言： English 简体中文 |} ==第1章：语法==..."

{| {{Prettytable}}
|-
!|其他语言：
[[WML_for_Complete_Beginners:_Chapter_1|English]]
[[WML_for_Complete_Beginners:_Chapter_1/zh|简体中文]]
|}

==第1章：语法==

首先让我们看看 WML 的''语法''。

对于不了解语言“语法”的朋友，可以把它看作是编写 WML 的规则。这个概念有些混乱，但是，无论您是否意识到，您在日常生活中时时刻刻都在使用语法。比如句子“我喜欢果冻和奶酪三明治”。这句话就包含语法，语法让受众能听懂句子的含义。如果您说“喜欢奶酪我和三明治果冻”，这句话也就失去了意义，因为没人听得懂。

就像英语的语法一样，WML 语法也需要字母、拼写、标点，这样才能让其他人理解您想表达什么。例如，如果您胡略语法，然后写出“一天玛丽和我有去看大象在动物园它是长”，那么大家不会明白您在写什么。但是如果您使用正确的语法：“某日，我和玛丽去动物园看到大象。它的鼻子真的很长”，这就很清楚了，因为这里用到了正确的语法。正如英国人无法理解使用错误语法写出的句子一样，韦诺之战也不会读取语法错误的脚本。

所以我们先看一下 WML 的基本语法。稍后再来介绍更复杂的 WML 语法，但是这些足够您开始学习。

===基本组件：标签和属性===

WML，就像首字母表达的那样，这是一个“[https://zh.wikipedia.org/wiki/%E7%BD%AE%E6%A0%87%E8%AF%AD%E8%A8%80 标记语言]。”这表示整个语言的语法包含两个基本元素：'''tags'''和'''attributes'''。
====标签====

:标签是由两个方括号扩起来的小写字符串，两端各一个。下面是“campaign”的标签示例：

[campaign]

:标签只能包含字母和数字和下划线“_”。请注意前面提到的，“标签是''小写''字符串”。这是 WML 语法的基本：所有标签都用小写字母。如果您使用大写字母，WML 引擎会无法理解，并且发出错误。

:和大部分标记语言一样，WML 的标签是成对出现的：一个开始标记和一个结束标记。就像一本书的封面和封底：打开一本书的封面表示开始，到达封底就意味着已经读完了这本书。同样，WML 引擎从开始标签开始。一直执行到结束标签。

:结束标签除了和开始标签一样的关键字以外，还需要在方括号后面加入一个正斜杠“/”。正斜杠表示这个标签是结束标。下面是“campaign”标签的示例：

[/campaign]

:The opening and closing tag together are referred to as a '''tagset'''. A tagset always contains exactly two tags: the opening tag and the closing tag. For example, the "campaign" tagset would look like this:
[campaign]
[/campaign]

:所以我们现在知道 WML 引擎如何判断开始和结束。这些是 WML 标签的基本概念。之后我们再讨论更复杂的标签；现在请确保您了解这些概念。

:在进入下个章节之前，我们回顾一下这个部分提到的有关标签的内容：

::*标签是使用两个方括号括起来的小写字符串。
::*结束标签和起始标签相同，只是多了一个斜杠。
::*起始标签和结束标签一起称为“标签集”。
::*标签集只能由两个标签组成：起始和结束。

:现在我们了解了起始、结束标签，下面该了解如何使用它们。

====属性====

:属性由两部分组成：''keys''和''values''，书写格式如下：

key=value

:属性的功能是存储 WML 引擎需要的信息。属性的''key''说明存储什么样的信息，属性的''value''是存储的实际数据。等号左侧的文本作为键，右侧作为值。

:这听起来有些乱，举个实际的例子来说明：

:您想让您的朋友去杂货店买一块面包。您会直接对他说“去”吗？不会，这样他不会明白您让他做什么，您也不会有面包吃。同样，如果您只写一个标签集，等同于告诉 WML 引擎做什么，但是这还不够。如果您的朋友是个 WML 引擎，您让他去杂货店买面包，您可以给他这样的代码（''注意''：这不是真正的 WML 代码，这是教程中使用的伪代码）。

[go]
where=grocery_store
get=bread
[/go]

:标签告诉 WML 引擎做什么（类似让您的朋友“去”），但是没有属性来指定要做什么（比如告诉朋友什么时候去哪里），如果没有具体的信息，WML 引擎不会做任何事情。如果您让您的朋友“去”，他什么都不会做，因为不知道去哪里做什么。

:*'''Keys'''

::键是小写字母字符串，他告诉游戏处理的是什么信息。键是区分大小写的（虽然不能使用大写），需要正确拼写。

:*'''Values'''

::WML 的键只会处理一个类型的数据，也就是''字符串''。字符串是 ASCII 字符序列，包括键盘上的任何字符。字符串分成两类：标准和数字。

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-translatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter [FIXME HERE]). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 8 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 12 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

注意：本文翻译质量不佳

Next Chapter:
[[WML for Complete Beginners: Chapter 2]]

Return to introduction:
[[WML for Complete Beginners: Introduction]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Chapter 1

2017-03-16T19:29:01Z

Vanfans: /* Chapter 1: Syntax */

{| {{Prettytable}}
|-
!|其他语言：
[[WML_for_Complete_Beginners:_Chapter_1|English]]
[[WML_for_Complete_Beginners:_Chapter_1/zh|简体中文]]
|}

==Chapter 1: Syntax==

First things first; let's go over the ''syntax'' of WML.

For those of you who might not know what the "syntax" of a language is, think of it as a set of rules for how WML needs to be written in order for the game to understand it. This concept may sound a bit confusing, but whether you realize it or not you have been using the concept of syntax your entire life! Think of the structure of a sentence in English: "I like jelly and cheese sandwiches." That sentence uses a certain set of rules, or ''syntax'' in order to make sense to people who hear or read it. If you said instead, "Like cheese I and sandwiches jelly", that would make no sense, and no one would understand what you were saying. Likewise, if you said "I like cheese sandwiches and jelly", that would change the entire meaning of the sentence!

Just like the syntax of the English language, WML syntax also requires proper capitalization, spelling, grammar and punctuation in order for others to understand what you're saying or writing. For example, if you decided to ignore the syntax of the English language and wrote something like this: "won day mary and i had went to seen the elefant at the zoo it's trunc was reely long", chances are people would not understand much of what you wrote. On the other hand, if you used the correct syntax and wrote: "One day Mary and I went to see the elephant at the zoo. Its trunk was really long!", people can easily understand what you wrote because it is written in the syntax they recognize and understand. Just as English-reading people would be unable to understand something were it not written in the correct English syntax, the Battle for Wesnoth game is unable to read any WML that is not written in the correct WML syntax.

So now let's go over the basics of WML syntax. Later on you will be gradually introduced to more complex WML syntax, but for now we'll just go over the basic stuff, enough to get you started.

===Basic Components: Tags and Attributes===

WML, as one can infer from the meaning of the acronym, is a "[http://en.wikipedia.org/wiki/Markup_language markup language]." This means that the syntax of the entire language consists of two fundamental elements: '''tags''' and '''attributes'''.

====Tags====
:A tag is a string of lowercase text encapsulated by two square brackets, one at either end. This is an example of a "campaign" tag:
[campaign]

:Tags can only contain alphanumeric characters (letters and numbers) and underscores "_". Notice I said earlier that "a tag is a string of ''lowercase'' text". This is a fundamental aspect of the WML syntax: all tags are always written in lowercase letters. If you try using capital letters (even just one), the WML engine won't be able to understand what tag you're trying to use and will give you an error when it tries to read the incorrect tag.

:As with most markup languages, in WML tags are always used in pairs: one opening tag and one closing tag. Think of the opening tag and the closing tag like the covers of a book: when you open the front cover, you know you're at the beginning. When you reach the back cover, you know you're done reading the book. Likewise, when the WML engine finds an opening tag, it realizes it's at the beginning of a task. When it reaches the closing tag, it realizes it has finished the task.

:Closing tags are exactly the same as opening tags except for one key component: closing tags always have a forward slash "/" immediately after the first square bracket. This forward slash tells the WML engine that this tag is a closing tag and not another opening tag. Here is an example of the closing "campaign" tag:
[/campaign]

:The opening and closing tag together are referred to as a '''tagset'''. A tagset always contains exactly two tags: the opening tag and the closing tag. For example, the "campaign" tagset would look like this:
[campaign]
[/campaign]

:So now we know how the WML engine knows where the beginning and end of a task are, and what syntax to use when writing them. These are the basics of tags in WML. Later on we'll go over the more complicated aspects of tags; for now though, make sure you understand the concepts introduced here.

:Before we move on to the next section, let's review the points we've learned in this section about tags:
::*A tag is a string of lowercase text encapsulated by two square brackets, one at either end.
::*A closing tag is exactly the same as an opening tag, except a closing tag has a forward slash immediately following the first square bracket.
::*The opening tag and the closing tag together are called a "tagset".
::*A tagset can only ever consist of exactly two tags: the opening tag and the closing tag.

:Now we know how to tell the WML engine where the beginning and the end of a task are, but what about actually making it do the task? This is where attributes come in.

====Attributes====

:Attributes consist of two principal elements: ''keys'' and ''values'', and are written like so:
key=value

:The basic function of attributes is to store information that is needed by the WML engine. The ''key'' of the attribute specifies what kind of information is stored, and the ''value'' of the attribute is the actual data that is stored. All text to the left of the equals sign "=" is considered to be the key, and all text to the right of the equals sign is considered to be the value of the key.

:This may sound rather confusing, so let's illustrate by a practical example:

:Let's say you wanted your friend to go to the grocery store and pick you up a loaf of bread. Would you just say to him, "Go"? Of course not! He wouldn't understand what you wanted him to do, which means you'd have no bread for dinner. Likewise, if you only write a tagset, that's equivalent to telling the WML engine to "do", but that's not enough. You will need to be more specific about exactly what the WML engine should do. If your friend were a human WML engine and you wanted him to go to the grocery store to get some bread, you might give him this code to read (''note'': this code isn't actually real WML, it is "pseudocode", i.e. made up code for the purpose of illustration. If I ever use pseudocode during this tutorial I will tell you that it is pseudocode before you read the example, like I am doing now.):
[go]
where=grocery_store
get=bread
[/go]

:Tags tell the WML engine what to do generally (like telling your friend to "go"), but without attributes to specify ''exactly'' what to do (like telling your friend where and when to go, and what to do when he gets there), the WML engine won't be able to do anything because you haven't given it enough specific information. If you told your friend, "Go," he'd understand that you want him to go somewhere, but he'd be unable to actually perform the task because he doesn't know ''where'' to go or what to do when he gets there.

:*'''Keys'''
::Keys are sequences of lowercase alphabetic characters that tell the game what kind of information it is dealing with when it reads the attribute. Keys are case-sensetive (i.e., you can't use capital letters) and must be spelled correctly.

:*'''Values'''

::WML keys deal with one and only one type of data, called ''strings''. A string is simply a sequence of ASCII characters that can include pretty much any character on your keyboard. Strings may be divided into two categories: Standard and Numerical.

::'''1. Standard Strings'''

::A standard string is simply a sequence of ASCII characters that is neither a numerical nor a translatable string. For example, this is a standard string:
x
::as is this:
blue

::If a standard string includes whitespaces, it must be enclosed within double quotes:
"Everything in these double quotes is a single string. This is the number one: 1. Hooray! :) We are now coming to the end of this string."

::Everything within the double quotes (including the colon and parenthesis emoticon) is considered to one long string by the game.

::Sometimes you will want to mark a standard string as translatable so that it can be translated into other languages. The only difference between a translatable sting and a non-translatable is that translatable strings are marked so that translators know that they need to translate that string, and non-translatable strings are not marked, so the translators know that they don't translate those strings.

::To mark a string as translatable, all you have to do is add an underscore before the first double quote that marks the beginning of the string. Example of a translatable string:

_ "This is a translatable string."

::If the WML engine does not find an underscore in front of the string, it will assume the string is non-translatable.

::Although not strictly necessary, it is generally considered a good practice to include a space before and after the underscore that marks a string as translatable. For instance, if we were to assign the translatable string "Hello World!" to this key, it would be considered good syntax to write
key= _ "Hello World!"
::rather than
key=_"Hello World!"
::However, the game considers both of the above strings to be equivalent, and will therefore recognize both as translatable strings. Adding whitespaces just allows for better human readability in your WML code.

::'''2. Numerical Strings'''

::Unsurprisingly, numerical strings are strings that contain only numbers, decimal points, or minus signs "-". If a string contains anything other than numbers, decimal points and/or a minus sign, the string becomes a standard string instead of a numerical one. Numerical strings can be either a single numeric character like this:
2
::a sequence of numeric characters, like this:
230001

::or floating-point values (that's just a fancy way of saying that they can contain decimal points), like these two examples:
2.6
395667.49382345

::or negative numbers, like these examples:
-49
-594.932

::For all intents and purposes, you can treat numerical strings just as you would numbers in real life. You can add, divide, and otherwise mathematically employ them in mathematical computations (we'll go over this in-depth in chapter [FIXME HERE]). Just remember that if you include any characters other than numbers, decimal points, or minus signs, the string will cease to be a numeric string and will become a standard string, which means you won't be able to use it in mathematical calculations.

::Directory paths are simply special strings that tell the game where to find a specific file or folder. Here is an example of a directory path:
{data/add-ons/my_first_campaign}
This directory path tells the game where the folder "my_first_campaign" is located.

===More About Tags===

So now you should understand the basics about tags and attributes. As I promised earlier, we will now discuss some of the more involved aspects of tags.

====Nested Tags: Parents and Children====

:A fundamental aspect of markup languages is that you can use tagsets inside other tagsets. Tagsets located inside other tagsets are called nested tagsets. In the example below, the "side" tagset is nested inside the "scenario" tagset:

[scenario]
[side]
[/side]
[/scenario]

:When referring to nested tagsets, the tagset located inside the other is called the ''child'' tagset, and the tagset that encloses the child tagset is known ast he ''parent'' tagset. To illustrate with pseudocode:

[parent]
[child]
[/child]
[/parent]

:Tagsets that are not child tagsets of any other tagsets are called ''toplevel'' tagsets. In this next example, the [scenario] tagset is a toplevel tagset, because it is not the child tagset of any other tagset. The [event] tagset is the child tagset of [scenario], because it is located inside the [scenario] tagset. The tagset [event] is also the parent tagset of the [message] tagset, because the [message] tagset is located inside the [event] tagset. That means that since [event] is the parent of [message], [message] is the child tagset of [event].

[scenario]
[event]
[message]
[/message]
[/event]
[/scenario]

====Indentation and Levels====

:You may have noticed that in the examples above, the child tagsets are indented four spaces further to the right than are their parent tagsets. Why is this? It's because proper indentation (although not technically required by the WML engine) makes you code a lot easier to read and maintain. It's like writing an outline for a school paper, where you would write something like this:

I.
A.
B.
C.
II.
A.
1.
2.
B.
C.

:Indentation makes it much easier to see whether tagset is the child or parent of other tagsets. The amount of indentation before a tagset determines in what level that tagset is located. If the tagset is a toplevel tagset (i.e. has no spaces in front of it because it is not the child of any other tagset), that tagset is located at level one. Tagsets with an indentation of four spaces in front of them are located in level 2, because they are the children of the toplevel (level 1) tagset. Tagsets that are children of level 2 tagsets are called level 3 tagsets (and are indented 8 spaces), tagsets inside level 3 tagsets are called level 4 tagsets (and are indented 12 spaces), etc. As a general rule, all the attributes of a tagset, along with any child tagsets of that tagset, are indented one level deeper than that tagset. To illustrate in pseudocode:

[toplevel_tagset]
level_2_attribute=value
[level_2_tagset]
level_3_attribute=value
[level 3 tagset]
level_4_attribute=value
[/level 3 tagset]
[/level_2_tagset]
[/toplevel_tagset]

:Indenting tagsets and attributes into levels like this makes it much easier for you (and others) to read, fix and maintain your code. It is strongly recommended that you indent exactly four spaces for each new level, although you can also use tabs instead of hitting the space key 4 times, if you'd prefer.

Next Chapter:
[[WML for Complete Beginners: Chapter 2]]

Return to introduction:
[[WML for Complete Beginners: Introduction]]

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Introduction/zh-Hans

2017-03-15T16:34:02Z

Vanfans: Created page with "{| {{Prettytable}} |- !|其他语言： English 简体中文 |} ==介绍== 各..."

{| {{Prettytable}}
|-
!|其他语言：
[[WML_for_Complete_Beginners:_Introduction|English]]
[[WML_for_Complete_Beginners:_Introduction/zh|简体中文]]
|}

==介绍==

各位！

我猜，如果您读到这里，您应该已经了解韦诺之战是什么了。如果您不知道，我建议您在阅读本教程之前先了解一下。

可能有人想知道这个教程的目的。您可能会说“[[ReferenceWML]]部分已经涵盖了 WML 的所有方面”。但是 WML 参考部分只是参考，而非教程。这个页面的目的是向初学者完整地介绍 WML 而不必在参考中查找一天。

===教程是为谁准备的===

本教程针对没有编程知识的用户。教程假定您对计算机有基本的了解和简单的操作能力，例如可以编辑文本文件，以及能够找到特定的目录。在本教程中，您会通过从零开始建立一个简单的单人战役来了解 WML。

===您需要什么工具===

对于 WML 您只需要一个基本的文本编辑器。不需要花哨的文字处理工具（应该说建议您不要使用文字处理工具）；用一个简单的程序，比如 Windows 的文本编辑器或者 Mac OS X 的 TextEdit。对于 Linux，有一个非常好的文本编辑程序 Kate，可以语法高亮显示 WML。此外，还有专门的编写 WML 的程序，您可以在这里找到[http://eclipse.wesnoth.org eclipse.wesnoth.org]

显然，您还需要安装韦诺之战。

===什么是 WML？===

WML 是“韦诺标记语言”的缩写，韦诺标记语言可以让玩家创建和修改韦诺之战的内容，而不需学习更复杂的语言，比如 Lua 和 C++。现在我要说：不要觉得一夜之间就可以学会 WML。虽然 WML 容易学习，但是要花一定的精力曲理解。

===准备开始吗？===

当您准备开始，我们就可以进入 [[WML for Complete Beginners: Chapter 1]]！

返回目录：
[[WML for Complete Beginners|WML 新手指南]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners: Introduction

2017-03-15T16:31:17Z

Vanfans:

{| {{Prettytable}}
|-
!|其他语言：
[[WML_for_Complete_Beginners:_Introduction|English]]
[[WML_for_Complete_Beginners:_Introduction/zh|简体中文]]
|}

==Introduction==

Hey there!

Now I'm guessing that, if you're reading this, you already know what The Battle for Wesnoth is. If you don't, I suggest finding out before you read this tutorial.

Some people may wonder about the purpose of this tutorial. "We already have almost every aspect of WML covered in the [[ReferenceWML]] section," these people might say. But the information contained in the WML reference section is just that: a reference. Not a tutorial. This page aims to introduce complete beginners to WML without their having to sift for days through "references" until WML finally begins to vuagely make some sort of sense.

===Who This Tutorial is For===
The specific demographic for which this tutorial is intended is users with no previous programming knowledge. This tutorial does assume that you have a certain level of competence in basic computer skills and concepts, such as opening and editing text files, and being able to follow folder paths and locate specific directories. In this tutorial you will learn the fundamentals of WML by building a short single-player campaign from the ground up.

===What Tools You Will Need===

Programming in WML requires only one tool: a basic text editor. You don't need a fancy word processor to program WML (in fact, it is recommended that you ''avoid'' using those fancy word processors); a simple program like Windows Notepad or Mac OS X TextEdit will work just fine. For Linux, there is a very nice text editing application called Kate that actually comes with syntax highlighting for WML. In addition, some very helpful people put together a program specifically designed to help you write WML, which you can find at [http://eclipse.wesnoth.org eclipse.wesnoth.org]

Obviously, you will also need The Battle for Wesnoth installed on your computer.

===So What Exactly is WML?===

WML is an acronym for the "Wesnoth Markup Language", a custom scripting language that The Battle For Wesnoth uses to allow players to create and modify content without being required to learn a much more complex language like Lua or C++. Now I'm going to say this here and now: don't think you can learn WML overnight. Although WML is relatively easy to learn, it will take a certain amount of effort, time and dedication on your part to fully understand the ins and outs of the language.

===Ready to Get Started?===

When you are ready, head on over to [[WML for Complete Beginners: Chapter 1]] and let's get started!

Return to Main Index:
[[WML for Complete Beginners]]

[[Category:WML_for_Complete_Beginners]]

WML for Complete Beginners/zh-Hans

2017-03-14T17:04:23Z

Vanfans: /* 目录 */

{| {{Prettytable}}
|-
!|其他语言：
[[WML_for_Complete_Beginners|English]]
[[WML_for_Complete_Beginners/zh|简体中文]]
|}

欢迎来到 WML 新手指南！在这里，您可以直达[[WML for Complete Beginners: Introduction|简介]]部分，或者阅读其他章节。

==注意事项：==

这套新手指南正在编写中。
小的修改不会立刻提交给读者。
-------------

TODO:

1. Add to the numbers definition that numbers can include decimal point values (and reference the fact that WML will remove any unnecessary 0's when it performs the calculations or accesses the numerical value in question).

2. Finish chapters 6-11 (Partially Complete)

-------------

=目录=

[[WML_for_Complete_Beginners:_Introduction|WML 新手指南：简介]]

[[WML_for_Complete_Beginners:_Chapter_1|WML 新手指南：第1章]]

[[WML_for_Complete_Beginners:_Chapter_2|WML 新手指南：第2章]]

[[WML_for_Complete_Beginners:_Chapter_3|WML 新手指南：第3章]]

[[WML_for_Complete_Beginners:_Chapter_4|WML 新手指南：第4章]]

[[WML_for_Complete_Beginners:_Chapter_5|WML 新手指南：第5章]]

[[WML_for_Complete_Beginners:_Chapter_6|WML 新手指南：第6章]]

[[WML_for_Complete_Beginners:_Chapter_7|WML 新手指南：第7章]]

[[WML_for_Complete_Beginners:_Chapter_8|WML 新手指南：第8章]]

[[WML_for_Complete_Beginners:_Chapter_9|WML 新手指南：第9章]]

[[WML_for_Complete_Beginners:_Chapter_10|WML 新手指南：第10章]]

[[WML_for_Complete_Beginners:_Chapter_11|WML 新手指南：第11章]]

[[WML_for_Complete_Beginners:_Conclusion]]

[[Category:WML_for_Complete_Beginners]]

2017-03-13T12:16:05Z

Vanfans:

{{Create}}

{| {{Prettytable}}
|-
!|Other languages:
[[Create|English]]
[[Create/zh-Hans|简体中文]]
|}

In order to create custom content for Wesnoth, you need to set up a folder in userdata/data/add-ons/. If you have not found your userdata directory yet, read [[EditingWesnoth]] and come back here. This page will explain the basic directory structure of an add-on and where stuff goes.

Several pages on this wiki will assume you have done so and refer to relative paths in such.

== The Main File ==

For this example, we will assume you are creating an add-on called A Simple Addon.

*Create the empty directory userdata/data/add-ons/A_Simple_Addon.

Important: Remember to use underscores in all directory and file names instead of spaces. Failure to do so will result in your content not working properly.

*Create a file called _main.cfg inside the A_Simple_Addon folder.

The _main.cfg file will instruct the game on how to load your content. Here is shown a very simple example of the file.

#textdomain wesnoth-A_Simple_Addon
[textdomain]
name="wesnoth-A_Simple_Addon"
path="data/add-ons/A_Simple_Addon/translations"
[/textdomain]

#ifdef MULTIPLAYER
[binary_path]
path=data/add-ons/A_Simple_Addon
[/binary_path]

{~add-ons/A_Simple_Addon/scenarios}
#endif

The [textdomain] WML tag specifies where the game should look for translations to the strings in the add-on. The textdomain should be the add-on's directory name prefixed with "wesnoth-", to ensure that it does not conflict with other textdomains that might be specified on a given system and is compatible with [[WesCamp]].

Note: A textdomain is only required if your add-on contains text meant to be translated. In the case of, for example, a music pack, no textdomain is needed.

All tags save for [campaign] and [textdomain] must be enclosed in an #ifdef preprocessor conditional - including those substituted through inclusion (see [[PreprocessorRef]] for more information). This is to make sure your content only loads at the correct time and does not conflict with other add-ons. In the example above, the scenarios will be loaded when you enter multiplayer mode. In a campaign, you can set up a specific flag to allow your content to only load when that campaign is played.

Note: Only code must be included from this file. You do not need to include binary content (such as sounds, images, or music). Those may be referred to simply by path relative to the one specified in [binary_path]. Also, including the units directory cannot be done by a simple path inclusion; it also must be wrapped in a [+units][/units] (the + is very important!) tag pair, as such:

[+units]
{~add-ons/A_Simple_Addon/units}
[/units]

== The Directory Structure ==

What to create next depend on what type of content you are creating. For example, campaigns or map packs will have scenarios and maps directories, while a music pack would have only music. Here we will assume you are creating a campaign or single-scenario add-on.

Create the following directories:

*userdata/data/add-ons/A_Simple_Addon/scenarios
*userdata/data/add-ons/A_Simple_Addon/maps

All map files used in scenarios go in maps (see [[BuildingMaps]]. All configuration (‘.cfg’) files for scenarios go in scenarios (see [[BuildingScenarios]]).

If you have additional custom content such as images or units, create the respective following:

*userdata/data/add-ons/A_Simple_Addon/macros
*userdata/data/add-ons/A_Simple_Addon/units
*userdata/data/add-ons/A_Simple_Addon/images
*userdata/data/add-ons/A_Simple_Addon/music
*userdata/data/add-ons/A_Simple_Addon/sounds

Important: You may name the directories containing code (such as scenarios and macros) anything you like, but the three binary content directories (images, music, and sounds) must be named as such and be relative to your [binary_path]. This is because when trying to resolve an image path, Wesnoth will look under images/, and likewise for sounds and music, in [binary_path].

If you set up a textdomain, create a translations directory, even if it remains empty. Failure to do so generates a warning in stderr. This path must be the same as specified in the [textdomain] tag.

*userdata/data/add-ons/A_Simple_Addon/translations

==See also==

* [[Create]]
* [[BinaryPathWML]]
* [[BuildingCampaignsTheCampaignFile]]
* [[WesCamp]]

[[Category:Create]]