Merge lp:~widelands-dev/widelands/fh1-documentation into lp:widelands

Proposed by GunChleoc on 2018-02-12
Status: Merged
Merged at revision: 8606
Proposed branch: lp:~widelands-dev/widelands/fh1-documentation
Merge into: lp:widelands
Diff against target: 1414 lines (+698/-391)
6 files modified
data/scripting/messages.lua (+22/-0)
data/scripting/richtext.lua (+355/-226)
data/scripting/richtext_scenarios.lua (+14/-9)
doc/sphinx/extract_rst.py (+1/-0)
doc/sphinx/source/wlrichtext.rst (+60/-115)
src/graphic/text/rt_parse.cc (+246/-41)
To merge this branch: bzr merge lp:~widelands-dev/widelands/fh1-documentation
Reviewer Review Type Date Requested Status
GunChleoc Resubmit on 2018-02-22
Review via email: mp+337545@code.launchpad.net

Commit message

Documented tag constraints for new font renderer and updated the main articles.

To post a comment you must log in.
GunChleoc (gunchleoc) wrote :

The send_to_all function change is from https://code.launchpad.net/~widelands-dev/widelands/fh1-maps-multiplayer/+merge/337506, so that branch needs to be merged first.

bunnybot (widelandsofficial) wrote :

Continuous integration builds have changed state:

Travis build 3168. State: passed. Details: https://travis-ci.org/widelands/widelands/builds/340441956.
Appveyor build 2975. State: failed. Details: https://ci.appveyor.com/project/widelands-dev/widelands/build/_widelands_dev_widelands_fh1_documentation-2975.

8429. By kaputtnik on 2018-02-12

RST cleanups

kaputtnik (franku) wrote :

Took the freedom to adjust the RST parts. Mainly:

- make lists of allowed attributes a bulleted list (i think this was intended)
- fixed some args
- fixed indentation to have it consistent over the pages
- added the function definition of new_objectives() in richtext_scenarios.lua
- added some links in the text

For the allowed attributes it would be nice to have a description how to use them. Something like

Attributes have to be applied as a string in form of "attribute1=value1 attribute2=value2": E.g. font("color=ff0000 italic=1", text)

Don't know were to put such an example though.

bunnybot (widelandsofficial) wrote :

Continuous integration builds have changed state:

Travis build 3173. State: passed. Details: https://travis-ci.org/widelands/widelands/builds/340643220.
Appveyor build 2980. State: success. Details: https://ci.appveyor.com/project/widelands-dev/widelands/build/_widelands_dev_widelands_fh1_documentation-2980.

GunChleoc (gunchleoc) wrote :

Hm, we now have the allowed attributes documented in 2 places. The reason that I documented them in the C++ code is to be close to the code, so that we won't forget to update the documentation when they change. We can pretty much guarantee that updating the documentation in richtext.lua will be forgotten eventually.

kaputtnik (franku) wrote :

I didn't add any documenation ;)

Double documentation is not good. What about having the richtext documentation in the cpp file and parse it like we have for src/scripting/lua_bases.cpp? -> https://bazaar.launchpad.net/~widelands-dev/widelands/trunk/view/head:/doc/sphinx/extract_rst.py#L18

The real problem is that we have two different document generators with different syntax: doxygen and sphinx. So making documentation for one of them means it does not work with the other one. I'ts also bad for devolpers, because they have to use two different syntaxes for the source code documentation. Sphinx is also capable to document c++ code, imho: http://www.sphinx-doc.org/en/stable/domains.html#id2 In the long term run there should only be one source code documentation generator, imho.

GunChleoc (gunchleoc) wrote :

But you did add some, in this commit: https://bazaar.launchpad.net/~widelands-dev/widelands/fh1-documentation/revision/8429

It would be better to link to the allowed attributes documentation in src/graphic/text/rt_parse.cc and not duplicate the documentation in the Lua file.

I also still need to rewrite the main Richtext document https://wl.widelands.org/docs/wl/wlrichtext/ and link everything together in a tree.

kaputtnik (franku) wrote :

> But you did add some

Ok, i correct my self: I did not add any documentation which were in two places:

> Hm, we now have the allowed attributes documented in 2 places.

The allowed attributes were already at 2 places in the documentation, before i edited the RST comments. My fault that i didn't mention this. But please don't make me feel guilty for things i haven't done :-)

GunChleoc (gunchleoc) wrote :

Sorry, I'm seeing it now, you just edited them. Duh.

8430. By GunChleoc on 2018-02-21

Rewrite main Richtext article.

8431. By GunChleoc on 2018-02-21

Merged trunk.

8432. By GunChleoc on 2018-02-21

Example hookup of attributes documentation.

GunChleoc (gunchleoc) wrote :

I have now rewritten the main article and added a table of contents to it. I have also hooked up the attributes documentation for 2 tags. Before I continue with those, what do you think?

I also think that I should reorganize the richtext.lua script so that we can divide the documentation into logical sections for easier reading.

kaputtnik (franku) wrote :

I think this is good now. For the first time it is confusing that we have functions and the '<>' tags when switching between the pages. It's unclear where one has landet after clicking the link to attributes. Maybe write it in another way?

Instead:
attributes (string) – the attributes for the img tag.

Something like:
attributes (string) – see the rt-tags documentation for the attributes #attributes is the link

8433. By GunChleoc on 2018-02-22

Added links to tags for their attribute descriptions.

8434. By GunChleoc on 2018-02-22

Grouped functions into sections and added more cross-file links.

8435. By GunChleoc on 2018-02-22

Merged trunk.

GunChleoc (gunchleoc) wrote :

Should be done now. I have also reorganized the document into sections.

review: Resubmit
kaputtnik (franku) wrote :

Good work :-)

The grouping into headers is nice. A user can find the things he needs much better. There is one exception though: The rt tags documentation contain too much headers, imho. E.g for <rt> there are headers 'Attributes', 'Padding', 'Background Color' and 'Global Formatting Controls'. While the subheaders are a bit smaller it's nevertheless confusing. I think it would be better to have all attributes in one list. The attributes names are quite self explaining, imho. Same goes for the <div> tag. Just like it is for the <p> tag: One header 'Attributes' and a list of all attributes.

I miss an example how to use the attributes.

I am unsure about tags with no attributes or no subtags. I think we could omit the headers if there are no entries in it. A reader can imho understand if there is nothing documented, there are no attributes or subtags possible.

Added also two diff comments.

8436. By GunChleoc on 2018-02-23

Added code example directly to richtext.lua.

8437. By GunChleoc on 2018-02-23

Removed some subheaders from rt_parse.cc documentation.

8438. By GunChleoc on 2018-02-23

Reordered the functions in rt_parse.cc and linked back to the main documentation.

GunChleoc (gunchleoc) wrote :

All done.

For code examples, I just linked back to the main code example. Is this OK for now? Some of the attributes are still a bit WIP.

kaputtnik (franku) wrote :

I think this is better :-)

Maybe i have not explained enough about the code example for the attributes. The reason why i am so stubborn for a related code example is that it took me some time to fiddle out how to use them. E.g. it was unclear how to use values for an attribute.

I would suggest to change the code example in richtext.lua to something like:

-- h1(_[[Header]]) ..
-- p(_[[A Paragraph]]) ..
-- p(_[[A Paragraph with ]] .. font("color=ff0000", _[[red text ]]) .. _[[and ]] .. font("italic=1", _[[italic formatted text.]])) ..
-- and so on

No idea if this code will ever work :-D But hopefully it shows what kind of code example i miss. I could add such an example with a related image, if you don't want to do the additional work to create such an image. May i could test then also if i have understand all the things ;)

I have found some misspelling, will do a complete proof reading this weekend.

GunChleoc (gunchleoc) wrote :

Thanks!

Maybe it would indeed be best if you created the examples - I am too close to this, so you know better what is needed here.

8439. By kaputtnik on 2018-02-23

changed code example in richtext.lua

kaputtnik (franku) wrote :

Changed the code example and the resulting image. I have tried also to explain in short what the '..' are used for. While a first reader may does not know what my explanation means exactly, one can search the web for the keyword.

Feel free to rephrase :-)

kaputtnik (franku) wrote :

Ah forgotten: Not directly related to this branch but a question about the translation makro '_' and the use of brackets for strings instead of double quotation marks:

Does the _ only work with '_[[some text]]' and not with _"some text"?

The doc for _ (https://wl.widelands.org/docs/wl/autogen_globals/#_) says _"some text" can also be used.

Why are then all strings in the campaign files enclosed with brackets? Is there a benefit of using [[ ]] in comparison with using ""?

8440. By GunChleoc on 2018-02-24

Changed code example in main article to match.

8441. By GunChleoc on 2018-02-24

Spellchecking and some text tweaks.

8442. By GunChleoc on 2018-02-24

Merged trunk.

GunChleoc (gunchleoc) wrote :

Thanks for the image! I have also changed the code example in the main article to match. The red is a bit glaring, maybe we can have different color, just toned down a bit? I also fixed a spelling error in the text contained in the image, so it needs rerendering anyway.

It doesn't matter whether we use "" or [[]] in Lua. [[]] is for multiline strings that will ignore newlines, but using those would make for weird strings presented to translators. https://www.lua.org/manual/5.3/manual.html#3.1

8443. By kaputtnik on 2018-02-24

new image for code example; use blue and white instead of red

8444. By kaputtnik on 2018-02-24

use only one code example and link it from wlrichtext

kaputtnik (franku) wrote :

Thanks for explanation.

I have used now blue and white instead of red and completed the example. In r8443 i have changed both code examples accordingly. In r8444 i have removed the code example from wlrichtext and linked the example in richtext.lua. Feel free to revert this change, but one example is better for maintenance, imho.

kaputtnik (franku) wrote :

Did now some proof reading, see inline comments.

What i stumbled over is a mixed use of uppercase/lowercase after hyphen/colon. Eg. for the two text composition functions we have:

In join_sentence() its lowercase:
:arg sentence1: text of the first sentence

In localize lists its uppercase:
:arg items: An array of strings

8445. By GunChleoc on 2018-02-24

More proofreading.

GunChleoc (gunchleoc) wrote :

Thanks for proofreading :)

I'm not font of the blue either, can you please try something like 6699ff? The problem wasn't the hue, but the saturation.

8446. By kaputtnik on 2018-02-24

use baby blue as color

kaputtnik (franku) wrote :

Done.

GunChleoc (gunchleoc) wrote :

Thanks a lot for your help! :)

@bunnybot merge

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'data/scripting/messages.lua'
2--- data/scripting/messages.lua 2017-12-09 06:29:26 +0000
3+++ data/scripting/messages.lua 2018-02-24 15:32:03 +0000
4@@ -33,6 +33,28 @@
5 player:send_message(title, body, parameters)
6 end
7
8+
9+-- RST
10+-- .. function:: send_to_all(text[, heading])
11+--
12+-- Sends a game status message to all players.
13+--
14+-- :arg text: the localized body of the message. You can use rt functions here.
15+-- :type text: :class:`string`
16+-- :arg heading: the localized title of the message (optional)
17+-- :type heading: :class:`string`
18+--
19+function send_to_all(text, heading)
20+ for idx,plr in ipairs(game.players) do
21+ if (heading ~= nil and heading ~= "") then
22+ send_message(plr, _"Status", text, {popup=true, heading=heading})
23+ else
24+ send_message(plr, _"Status", text, {popup=true})
25+ end
26+ end
27+end
28+
29+
30 -- RST
31 -- .. function:: message_box(player, title, message, parameters)
32 --
33
34=== modified file 'data/scripting/richtext.lua'
35--- data/scripting/richtext.lua 2018-02-12 10:17:22 +0000
36+++ data/scripting/richtext.lua 2018-02-24 15:32:03 +0000
37@@ -1,60 +1,40 @@
38 -- TODO(GunChleoc): Wrap all tags and document allowed attributes when we're done
39
40 -- RST
41+--
42+-- .. _richtext.lua:
43+--
44 -- richtext.lua
45 -- ------------
46 --
47 -- Functions to simplify and unique text formatting in scenarios and help files.
48--- Most of these functions are simple wrapper functions that make working with
49--- widelands rich text formatting system more bearable.
50+-- Most of these functions are simple wrapper functions that make working with the
51+-- :ref:`widelands rich text formatting system <wlrichtext>` more bearable.
52 -- Function names generally follow HTML names.
53+-- We strongly recommend that you make use of these functions rather than hacking
54+-- the tags manually.
55+-- If you're writing a scenario, you should also have a look at
56+-- :ref:`richtext_scenarios.lua`.
57+--
58+-- - `Blocks and Positioning`_
59+-- - `Headings and Paragraphs`_
60+-- - `Text Formatting`_
61+-- - `Lists`_
62+-- - `Images`_
63+-- - `Links`_
64+-- - `Text Composition`_
65+-- - `Code Example`_
66
67
68 -- RST
69--- .. function:: localize_list(items, listtype, former_textdomain)
70--- :noindex:
71---
72--- Turns an array of string items into a localized string list with
73--- appropriate concatenation.
74---
75--- e.g. localize_list({"foo", "bar", baz"}, "or", "widelands") will return
76--- _"foo, bar or baz"
77---
78--- :arg items: An array of strings
79--- :arg listtype: The type of concatenation to use.
80--- Legal values are "&", "and", "or", and ";"
81--- :arg former_textdomain: The textdomain to restore after running this function.
82--- :returns: The concatenated list string, using localized concatenation operators.
83---
84--- Same algorithm as in src/base/i18n
85-function localize_list(items, listtype, former_textdomain)
86- set_textdomain("widelands")
87- local result = ""
88- for i, item in pairs(items) do
89- if (i == 1) then
90- result = item
91- elseif (i == #items) then
92- if (listtype == "&") then
93- result = _"%1$s & %2$s":bformat(result, item)
94- elseif (listtype == "or") then
95- result = _"%1$s or %2$s":bformat(result, item)
96- elseif (listtype == ",") then
97- result = _"%1$s, %2$s":bformat(result, item)
98- else
99- result = _"%1$s and %2$s":bformat(result, item)
100- end
101- else
102- result = _"%1$s, %2$s":bformat(result, item)
103- end
104- end
105- set_textdomain(former_textdomain)
106- return result
107-end
108+-- Blocks and Positioning
109+-- ^^^^^^^^^^^^^^^^^^^^^^
110+--
111+-- This section covers functions for structuring your text layout.
112
113
114 -- RST
115 -- .. function:: rt(text_or_attributes[, text = nil])
116--- :noindex:
117 --
118 -- Wraps a block of text into Lua rich text.
119 -- Only call this once for the whole text that gets sent to the backend.
120@@ -62,14 +42,9 @@
121 -- because the backend will take care of it.
122 -- So, only use this function if you wish to add some attributes to the tag.
123 --
124--- Allowed attributes are:
125--- padding, padding_r, padding_l, padding_b, padding_t: TODO(GunChleoc): Document
126--- background: a background color or image
127--- debug: add visual debug information and debug log
128--- editor_mode: allow multiple blank spaces for editing
129---
130--- :arg attributes: the attributes for the rt tag.
131--- :type attributes: :class:`string`
132+-- :arg text_or_attributes: see the :ref:`rt tag's documentation <rt_tags_rt>`
133+-- for a list of attributes and their descriptions.
134+-- :type text_or_attributes: :class:`string`
135 -- :arg text: the text to be enclosed in rich text tags.
136 -- :type text: :class:`string`
137 -- :returns: the wrapped rich text.
138@@ -84,31 +59,72 @@
139
140
141 -- RST
142--- .. function:: img(src[, attributes = nil])
143--- :noindex:
144---
145--- Turns an image src path into an image tag for richtext.
146---
147--- :arg src: the file path to the image.
148--- :type src: :class:`string`
149--- :arg attributes: the attributes for the div tag.
150--- :type attributes: :class:`string`
151---
152--- Allowed attributes are:
153--- color: a hex color to be applied to the image's player color mask, if it has any
154--- ref: TODO(GunChleoc): I have no idea what it does.
155---
156--- :returns: the img tag.
157+-- .. function:: div(text_or_attributes[, text = nil])
158+--
159+-- Wraps a block of text into a div tag.
160+--
161+-- :arg text_or_attributes: see the :ref:`div tag's documentation <rt_tags_div>`
162+-- for a list of attributes and their descriptions.
163+-- :type test_or_attributes: :class:`string`
164+--
165+-- :arg text: the text to be enclosed in div tags.
166+-- :type text: :class:`string`
167+-- :returns: the text wrapped in a div tag.
168
169-function img(src, attributes)
170- if attributes then
171- return "<img src=" .. src .." " .. attributes .. ">"
172+function div(text_or_attributes, text)
173+ if text then
174+ return ("<div %s>"):format(text_or_attributes) .. text .. "</div>"
175 else
176- return "<img src=" .. src .. ">"
177+ return ("<div>") .. text_or_attributes .. "</div>"
178 end
179 end
180
181
182+-- RST
183+-- .. function:: space(gap)
184+--
185+-- Adds a horizontal space
186+--
187+-- :arg gap: the size of the space as pixels.
188+--
189+-- :returns: a space tag
190+
191+function space(gap)
192+ return "<space gap="..gap..">"
193+end
194+
195+
196+-- RST
197+-- .. function:: vspace(gap)
198+--
199+-- Adds a vertical space
200+--
201+-- :arg gap: the size of the space as pixels.
202+--
203+-- :returns: a vspace tag
204+
205+function vspace(gap)
206+ return "<vspace gap="..gap..">"
207+end
208+
209+
210+-- RST
211+-- :ref:`Return to index<richtext.lua>`
212+--
213+-- Headings and Paragraphs
214+-- ^^^^^^^^^^^^^^^^^^^^^^^
215+--
216+-- This section covers functions for defining headings and paragraphs.
217+
218+
219+-- RST
220+-- .. function:: title(font_face, text)
221+--
222+-- Returns a paragraph formatted as a title heading. Use this on the top of
223+-- your document only.
224+--
225+-- :returns: A paragraph with text formatted as title.
226+
227 function title(font_face, text)
228 return p_font("align=center", "size=38 face=".. font_face .. " color=2F9131", text)
229 end
230@@ -116,12 +132,11 @@
231
232 -- RST
233 -- .. function:: h1(text_or_color[, text = nil])
234--- :noindex:
235 --
236 -- Returns a paragraph formatted as a big heading with a small gap after it.
237--- The mnemonic comes from HTML.
238 --
239 -- :returns: A paragraph with text formatted as heading.
240+
241 function h1(text_or_color, text)
242 if text then
243 return p_font("", "size=18 bold=1 color=".. text_or_color, vspace(12) .. text .. vspace(1))
244@@ -130,20 +145,21 @@
245 end
246 end
247
248+
249 -- RST
250 -- .. function:: h2(text)
251--- :noindex:
252 --
253 -- Like :func:`h1` but smaller.
254 --
255 -- :returns: A paragraph with text formatted as heading.
256+
257 function h2(text)
258 return p_font("", "size=14 bold=1 color=D1D1D1", vspace(12) .. text .. vspace(1))
259 end
260
261+
262 -- RST
263 -- .. function:: h3(text)
264--- :noindex:
265 --
266 -- Like :func:`h2` but smaller.
267 --
268@@ -153,9 +169,9 @@
269 return p_font("", "size=13 color=D1D1D1", vspace(6) .. text .. vspace(1))
270 end
271
272+
273 -- RST
274 -- .. function:: h4(text)
275--- :noindex:
276 --
277 -- Like :func:`h3` but smaller.
278 --
279@@ -165,16 +181,36 @@
280 return p_font("", "size=12 italic=1 color=D1D1D1", text)
281 end
282
283+
284+-- RST
285+-- .. function:: inline_header(header, text)
286+--
287+-- Creates a line of h3 formatted text followed by normal paragraph text.
288+--
289+-- :arg header: text in h3 format.
290+-- :arg text: text in p format.
291+-- :returns: header text followed by normal text.
292+
293+function inline_header(header, text)
294+ return
295+ div("width=100%", vspace(8)) ..
296+ div("width=100%", font("size=13 color=D1D1D1", header .. " ") ..
297+ font("size=12", text))
298+end
299+
300+
301 -- RST
302 -- .. function:: p(text_or_attributes[, text = nil])
303--- :noindex:
304 --
305 -- Returns one paragraph with text followed by a small vertical gap. Options
306 -- can be given as first argument similar to :func:`rt`.
307 --
308--- Allowed attributes are documented in the open_p function.
309+-- :arg text_or_attributes: see the :ref:`p tag's documentation <rt_tags_p>`
310+-- for a list of attributes and their descriptions.
311+-- :type text_or_attributes: :class:`string`
312 --
313 -- :returns: The text wrapped in <p>%s</p>
314+
315 function p(text_or_attributes, text)
316 if text then
317 return open_p(text_or_attributes) .. text .. close_p()
318@@ -185,38 +221,17 @@
319
320
321 -- RST
322--- .. function:: p_font(text_or_attributes[, text = nil])
323---
324--- Returns one paragraph with text followed by a small vertical gap. Options
325--- can be given as first argument similar to :func:`rt`.
326---
327--- Allowed p attributes are documented in the open_p function.
328---
329--- Allowed font attributes are are documented in the font function.
330---
331--- :returns: The text wrapped in <p attributes><font attributes>text</font></p>
332-function p_font(p_or_font_or_attributes, text_or_font_attributes, text)
333- if text then
334- return ("<p %s>"):format(p_or_font_or_attributes) .. "<font " .. text_or_font_attributes .. ">" .. text .. close_p()
335- else
336- return "<p><font " .. p_or_font_or_attributes .. ">" .. text_or_font_attributes .. close_p()
337- end
338-end
339-
340-
341--- RST
342 -- .. function:: open_p([attributes = nil])
343 --
344 -- Returns a paragraph open tag and default font size. Options
345 -- can be given as first argument similar to :func:`rt`.
346 --
347--- Allowed attributes are:
348--- indent: indents the first line of the paragraph
349--- align: horizontal alignment (left, center, right)
350--- valign: vertical alignment (top, middle, bottom)
351--- spacing: line spacing in pixels
352+-- :arg attributes: see the :ref:`p tag's documentation <rt_tags_p>`
353+-- for a list of attributes and their descriptions.
354+-- :type attributes: :class:`string`
355 --
356 -- :returns: <p> with added attributes and default font
357+
358 function open_p(attributes)
359 if attributes then
360 return ("<p %s>"):format(attributes) .. "<font size=12>"
361@@ -232,24 +247,55 @@
362 -- Closes a paragraph.
363 --
364 -- :returns: The closing tags for a paragraph
365+
366 function close_p(t)
367 return vspace(6) .. "</font>" .. vspace(6) .. "</p>"
368 end
369
370+
371+-- RST
372+-- .. function:: p_font(p_or_font_attributes, text_or_font_attributes[, text = nil])
373+--
374+-- Returns one paragraph with text followed by a small vertical gap. Options
375+-- can be given as first argument similar to :func:`rt`.
376+--
377+-- :arg p_or_font_attributes: Optional paragraph or font attributes.
378+-- :type p_or_font_attributes: :class:`string`
379+--
380+-- :arg text_or_font_attributes: Optional font attributes or the text itself.
381+-- :type text_or_font_attributes: :class:`string`
382+--
383+-- See the :ref:`p tag's documentation <rt_tags_p>` for a list of paragraph
384+-- attributes and the :ref:`font tag's documentation <rt_tags_font>` for a
385+-- list of font attributes.
386+--
387+-- :returns: The text wrapped in <p attributes><font attributes>text</font></p>
388+
389+function p_font(p_or_font_attributes, text_or_font_attributes, text)
390+ if text then
391+ return ("<p %s>"):format(p_or_font_attributes) .. "<font " .. text_or_font_attributes .. ">" .. text .. close_p()
392+ else
393+ return "<p><font " .. p_or_font_attributes .. ">" .. text_or_font_attributes .. close_p()
394+ end
395+end
396+
397+-- RST
398+-- :ref:`Return to index<richtext.lua>`
399+--
400+-- Text Formatting
401+-- ^^^^^^^^^^^^^^^
402+--
403+-- This section covers convenience functions for text formatting.
404+
405+
406 -- RST
407 -- .. function:: font(attributes, text)
408 --
409--- Wraps the text in font tags.
410+-- Wraps the text in font tags. See also :any:`p_font`.
411 --
412--- Allowed attributes are:
413--- size: the font size in pt
414--- face: sans, serif or condensed
415--- color: a hex color
416--- bold: if you add bold=1, the text will be bold
417--- italic: if you add italic=1, the text will be italic
418--- underline: if you add underline=1, the text will be underlined
419--- shadow: if you add shadow=1, the text will have a shadow
420--- ref: TODO(GunChleoc): I don't know what this does.
421+-- :arg attributes: see the :ref:`font tag's documentation <rt_tags_font>`
422+-- for a list of attributes and their descriptions.
423+-- :type attributes: :class:`string`
424 --
425 -- :returns: The text wrapped in font tags with the given attributes
426
427@@ -257,35 +303,61 @@
428 return ("<font %s>"):format(attributes) .. text .. "</font>"
429 end
430
431--- RST
432--- .. function:: space(gap)
433---
434--- Adds a horizontal space
435--- :arg gap: the size of the space as pixels.
436---
437--- :returns: a space tag
438-
439-function space(gap)
440- return "<space gap="..gap..">"
441-end
442-
443--- RST
444--- .. function:: vspace(gap)
445---
446--- Adds a vertical space
447--- :arg gap: the size of the space as pixels.
448---
449--- :returns: a vspace tag
450-
451-function vspace(gap)
452- return "<vspace gap="..gap..">"
453-end
454+
455+-- RST
456+-- .. function:: b(text)
457+--
458+-- This makes the text bold.
459+--
460+-- :arg text: the text to format
461+--
462+-- :returns: a font tag containing the bold text
463+
464+function b(text)
465+ return font("bold=1", text)
466+end
467+
468+-- RST
469+-- .. function:: i(text)
470+--
471+-- This makes the text italic.
472+--
473+-- :arg text: the text to format
474+--
475+-- :returns: a font tag containing the italic text
476+
477+function i(text)
478+ return font("italic=1", text)
479+end
480+
481+-- RST
482+-- .. function:: u(text)
483+--
484+-- This underlines the text.
485+--
486+-- :arg text: the text to format
487+--
488+-- :returns: a font tag containing the underlined text
489+
490+function u(text)
491+ return font("underline=1", text)
492+end
493+
494+
495+-- RST
496+-- :ref:`Return to index<richtext.lua>`
497+--
498+-- Lists
499+-- ^^^^^
500+--
501+-- This section covers functions for defining lists.
502+
503
504 -- RST
505 -- .. function:: dl(dt, dd)
506--- :noindex:
507---
508--- This function imitates a HTML description list
509+--
510+-- This function imitates a HTML description list
511+--
512 -- :arg dt: "description term", will be rendered in bold.
513 -- :arg dd: "description data", will be rendered normally.
514 --
515@@ -295,13 +367,14 @@
516 return p(b(dt) .. " " .. dd)
517 end
518
519+
520 -- RST
521 -- .. function:: li(text_or_symbol[, text = nil])
522 --
523 -- Adds the symbol in front of the text to create a list item and
524 -- wraps it in a paragraph
525 --
526--- :arg symbol: the item symbol for the list, e.g. "•" or "→"
527+-- :arg symbol: the item symbol for the list, e.g. "•" or "→". "•" is the default.
528 -- :arg text: the text of the list item
529 --
530 -- :returns: a p tag containing the formatted text
531@@ -314,6 +387,7 @@
532 end
533 end
534
535+
536 -- RST
537 -- .. function:: li_arrow(text)
538 --
539@@ -322,19 +396,23 @@
540 -- :arg text: the text of the list item
541 --
542 -- :returns: li("→", text)
543+
544 function li_arrow(text)
545 -- TODO(GunChleoc): Reverse arrow for rtl languages.
546 return li("→", text)
547 end
548
549+
550 -- RST
551--- .. function li_image(imagepath, text)
552+-- .. function:: li_image(imagepath, text)
553 --
554 -- Places a paragraph of text to the right of an image
555-
556+--
557 -- :arg imagepath: the full path to the image file
558--- :arg text_width_percent: the percentatge of space that the text will occupy
559+-- :type imagepath: :class:`string`
560+--
561 -- :arg text: the text to be placed next to the image
562+-- :type text: :class:`string`
563 --
564 -- :returns: the text wrapped in a paragraph and placed next to the image, the outer tag is a div.
565
566@@ -347,11 +425,52 @@
567 )
568 end
569
570+
571+-- RST
572+-- :ref:`Return to index<richtext.lua>`
573+--
574+-- Images
575+-- ^^^^^^
576+--
577+-- This section covers functions for including images.
578+
579+
580+-- RST
581+-- .. function:: img(src[, attributes = nil])
582+--
583+-- Turns an image src path into an image tag for richtext. See also :any:`li_image`.
584+--
585+-- :arg src: the file path to the image.
586+-- :type src: :class:`string`
587+-- :arg attributes: see the :ref:`img tag's documentation <rt_tags_img>`
588+-- for a list of attributes and their descriptions.
589+-- :type attributes: :class:`string`
590+--
591+-- :returns: the img tag.
592+
593+function img(src, attributes)
594+ if attributes then
595+ return "<img src=" .. src .." " .. attributes .. ">"
596+ else
597+ return "<img src=" .. src .. ">"
598+ end
599+end
600+
601+
602+-- RST
603+-- :ref:`Return to index<richtext.lua>`
604+--
605+-- Links
606+-- ^^^^^
607+--
608+-- This section covers functions for including links. We can't do real links yet,
609+-- so we only highlight the text for now.
610+
611 -- RST
612 -- .. function:: a(link)
613--- :noindex:
614---
615--- This function imitates a HTML link. We can't do real links yet, so the text just gets underlines.
616+--
617+-- This function imitates a HTML link. We can't do real links yet, so the text just gets underlines.
618+--
619 -- :arg link: the text to format
620 --
621 -- :returns: a font tag containing the underlined text
622@@ -361,87 +480,14 @@
623 end
624
625 -- RST
626--- .. function:: b(link)
627--- :noindex:
628---
629--- This makes the text bold.
630--- :arg link: the text to format
631---
632--- :returns: a font tag containing the bold text
633-
634-function b(text)
635- return font("bold=1", text)
636-end
637-
638--- RST
639--- .. function:: i(link)
640--- :noindex:
641---
642--- This makes the text italic.
643--- :arg link: the text to format
644---
645--- :returns: a font tag containing the italic text
646-
647-function i(text)
648- return font("italic=1", text)
649-end
650-
651--- RST
652--- .. function:: u(link)
653---
654--- This underlines the text.
655--- :arg link: the text to format
656---
657--- :returns: a font tag containing the underlined text
658-
659-function u(text)
660- return font("underline=1", text)
661-end
662-
663--- RST
664--- .. function:: div(text_or_attributes[, text = nil])
665---
666--- Wraps a block of text into a div tag.
667---
668--- :arg attributes: the attributes for the div tag.
669--- :type attributes: :class:`string`
670---
671--- Allowed attributes are:
672--- padding, padding_r, padding_l, padding_b, padding_t: TODO(GunChleoc): Document
673--- margin: TODO(GunChleoc): Document
674--- float: TODO(GunChleoc): this does not work yet
675--- margin: inner margin for the div
676--- valign: vertical alignment
677--- background: a background color or image
678--- width: the width of the div in pixels or percent
679---
680--- :arg text: the text to be enclosed in div tags.
681--- :type text: :class:`string`
682--- :returns: the text wrapped in a div tag.
683-
684-function div(text_or_attributes, text)
685- if text then
686- return ("<div %s>"):format(text_or_attributes) .. text .. "</div>"
687- else
688- return ("<div>") .. text_or_attributes .. "</div>"
689- end
690-end
691-
692--- RST
693--- .. function:: inline_header(t1, t2)
694---
695--- Creates a line of h3 formatted text followed by normal paragraph text.
696---
697--- :arg t1: text in h3 format.
698--- :arg t2: text in p format.
699--- :returns: header text followed by normal text.
700-
701-function inline_header(header, text)
702- return
703- div("width=100%", vspace(8)) ..
704- div("width=100%", font("size=13 color=D1D1D1", header .. " ") ..
705- font("size=12", text))
706-end
707+-- :ref:`Return to index<richtext.lua>`
708+--
709+-- Text Composition
710+-- ^^^^^^^^^^^^^^^^
711+--
712+-- This section covers functions for text composition that help with proper markup
713+-- to make the text translatable.
714+
715
716 -- RST
717 -- .. function:: join_sentences(sentence1, sentence2)
718@@ -452,9 +498,92 @@
719 -- :arg sentence1: text of the first sentence
720 -- :arg sentence2: text of the second sentence
721 -- :returns: two concatenated sentences with a localized sentence joiner.
722---
723+
724 function join_sentences(sentence1, sentence2)
725 -- TRANSLATORS: Put 2 sentences one after the other.
726 -- TRANSLATORS: Languages using Chinese script probably want to lose the blank space here.
727 return pgettext("sentence_separator", "%s %s"):bformat(sentence1, sentence2)
728 end
729+
730+
731+-- RST
732+-- .. function:: localize_list(items, listtype, former_textdomain)
733+--
734+-- Turns an array of string items into a localized string list with
735+-- appropriate concatenation.
736+--
737+-- e.g. localize_list({"foo", "bar", "baz"}, "or", "widelands") will return
738+-- _"foo, bar or baz"
739+--
740+-- :arg items: An array of strings
741+-- :arg listtype: The type of concatenation to use.
742+-- Legal values are "&", "and", "or", and ";"
743+-- :arg former_textdomain: The textdomain to restore after running this function.
744+-- :returns: The concatenated list string, using localized concatenation operators.
745+--
746+-- Same algorithm as in src/base/i18n
747+
748+function localize_list(items, listtype, former_textdomain)
749+ set_textdomain("widelands")
750+ local result = ""
751+ for i, item in pairs(items) do
752+ if (i == 1) then
753+ result = item
754+ elseif (i == #items) then
755+ if (listtype == "&") then
756+ result = _"%1$s & %2$s":bformat(result, item)
757+ elseif (listtype == "or") then
758+ result = _"%1$s or %2$s":bformat(result, item)
759+ elseif (listtype == ",") then
760+ result = _"%1$s, %2$s":bformat(result, item)
761+ else
762+ result = _"%1$s and %2$s":bformat(result, item)
763+ end
764+ else
765+ result = _"%1$s, %2$s":bformat(result, item)
766+ end
767+ end
768+ set_textdomain(former_textdomain)
769+ return result
770+end
771+
772+
773+-- RST
774+-- :ref:`Return to index<richtext.lua>`
775+--
776+-- .. _lua_formatting_example:
777+--
778+-- Code Example
779+-- ^^^^^^^^^^^^
780+-- Here's an example on how these functions and their attributes can be used. The double dot
781+-- (``..``) is the LUA string concatenation operator. Note that this example
782+-- also includes translation markup (the ``_[[Some text]]`` or ``_"Some text"`` function):
783+--
784+-- .. code-block:: lua
785+--
786+-- include "scripting/richtext.lua"
787+--
788+-- title = "Text Formatting",
789+-- body = h1(_[[Normal header]]) ..
790+-- h1("6699ff", _[[Colored header]]) ..
791+-- p(_[[Normal paragraph, just with a bit more text to show how it looks like.]]) ..
792+-- p("align=center", _[[A centered paragraph, just with a bit more text to show how it looks like.]]) ..
793+-- li_image("images/wui/menus/menu_toggle_menu.png", _[[An image with right aligned text. This is just text to show automatic line breaks and behavior in regard with images]]) ..
794+-- li(_[[A list item]]) ..
795+-- li(font("color=6699ff bold=1", _[[Blue and bold]])) ..
796+-- li_arrow(_[[A list item with an arrow]]) ..
797+-- p(_[[A more complicated paragraph with ]] ..
798+-- font("color=ffffff", _[[white text ]]) ..
799+-- _[[and ]] ..
800+-- font("italic=1 bold=1", _[[bold italic formatted text.]])
801+-- ),
802+--
803+--
804+-- This results in the following for a campaign message box:
805+--
806+-- .. image:: images/wlrichtext.png
807+-- :scale: 100
808+-- :alt: sample rendering
809+-- :align: center
810+--
811+-- :ref:`Return to index<richtext.lua>`
812
813=== modified file 'data/scripting/richtext_scenarios.lua'
814--- data/scripting/richtext_scenarios.lua 2018-01-04 13:45:46 +0000
815+++ data/scripting/richtext_scenarios.lua 2018-02-24 15:32:03 +0000
816@@ -1,12 +1,14 @@
817 include "scripting/richtext.lua"
818
819 -- RST
820+-- .. _richtext_scenarios.lua:
821+--
822 -- richtext_scenarios.lua
823 -- ----------------------
824 --
825--- Function to simplify and unique text formatting in scenarios. Most of these
826--- functions are simple wrapper functions that make working with widelands rich
827--- text formatting system more bearable.
828+-- Functions to simplify text formatting in scenarios and make it consistent.
829+-- Most of these functions are simple wrapper functions for our :ref:`richtext system <wlrichtext>`.
830+-- This file will include :ref:`richtext.lua` for you for additional formatting functions.
831
832 -- RST
833 -- .. function:: speech(img, clr, title, text)
834@@ -36,6 +38,7 @@
835 return title .. li_image(img, p(text))
836 end
837
838+
839 -- RST
840 -- .. function:: paragraphdivider()
841 --
842@@ -49,7 +52,6 @@
843 end
844
845
846-
847 -- RST
848 -- .. function:: objective_text(heading, body)
849 --
850@@ -64,13 +66,16 @@
851
852
853 -- RST
854--- Append an objective text with a header to a dialog box in a nice fashion.
855--- For displaying objectives with an extra title when an advisor is talking
856+-- .. function:: new_objectives(...)
857+--
858+-- Append an objective text with a header to a dialog box in a nice fashion.
859+-- For displaying objectives with an extra title when an advisor is talking
860 --
861 -- Provides nice formatting for objective texts.
862--- the following arguments will be parsed:
863--- number: the number of objectives described in the body
864--- body: the objective text, e.g. created with function objective_text(heading, body)
865+-- The following arguments will be parsed:
866+--
867+-- - number: the number of objectives described in the body
868+-- - body: the objective text, e.g. created with function objective_text(heading, body)
869 --
870 -- :returns: a rich text object that contains the formatted
871 -- objective text & title.
872
873=== modified file 'doc/sphinx/extract_rst.py'
874--- doc/sphinx/extract_rst.py 2017-11-05 09:30:44 +0000
875+++ doc/sphinx/extract_rst.py 2018-02-24 15:32:03 +0000
876@@ -14,6 +14,7 @@
877 # Meaning: (src_file, file_name_to_generate_rst)
878 cpp_pairs = (
879 ('src/ai/ai_hints.cc', 'autogen_ai_hints.rst'),
880+ ('src/graphic/text/rt_parse.cc', 'autogen_rt_tags.rst'),
881 ('src/scripting/lua_root.cc', 'autogen_wl.rst'),
882 ('src/scripting/lua_bases.cc', 'autogen_wl_bases.rst'),
883 ('src/scripting/lua_editor.cc', 'autogen_wl_editor.rst'),
884
885=== renamed file 'doc/sphinx/source/images/fancymsg.png' => 'doc/sphinx/source/images/wlrichtext.png'
886Binary files doc/sphinx/source/images/fancymsg.png 2012-06-20 09:07:10 +0000 and doc/sphinx/source/images/wlrichtext.png 2018-02-24 15:32:03 +0000 differ
887=== modified file 'doc/sphinx/source/wlrichtext.rst'
888--- doc/sphinx/source/wlrichtext.rst 2016-01-28 05:24:34 +0000
889+++ doc/sphinx/source/wlrichtext.rst 2018-02-24 15:32:03 +0000
890@@ -1,126 +1,71 @@
891+.. _wlrichtext:
892+
893 The Widelands Rich Text System
894 ==============================
895
896-All texts that can be displayed to the user can be formatted to be layouted
897+All texts that can be displayed to the user can be marked up to be laid out
898 and nicely formatted. This allows for changing of font sizes, weights, colors
899 and for the embedding of images. This documents how to format a string to be
900 recognized as rich text and which attributes are understood.
901
902 The Widelands rich text language is inspired by HTML and therefore uses a
903-syntax very similar to it. A rich text is started with ``<rt>`` and ended with
904-``</rt>``. A rich text can have an image associated with it, this image is
905-then displayed next to the text.
906-
907-Inside the rich text, each paragraph is enclosed by ``<p>`` and ``</p>``. You
908-give font attributes to this tag to change the appearance of the text
909-displayed inside.
910-
911-Reference
912----------
913-
914-``<rt>``
915-^^^^^^^^
916-
917-Starts or ends a rich text. Must be the first tag to appear in the string.
918-A full example would be::
919-
920- <rt image=map:khanktrukh.png><p line-spacing=3 font-size=12>Hello<br>World</p></rt>
921-
922-This would instruct widelands to use the image of Khankruth that comes with
923-the map, left align it. To the right of it there would be two lines of text.
924-The first line being ``Hello`` and the second being ``World``. They would be
925-displayed with a font-size of 12 points and a line-spacing of 3 points.
926-
927-Valid attributes for ``<rt>`` are:
928-
929-image
930- The name of a image to use, can be prefixed with ``map:`` which instructs
931- widelands to load the image from the ``pics/`` directory inside the map of
932- this scenario.
933-
934-image-align
935- ``right``, ``center`` or ``left``. Defines were the image is displayed.
936-
937-text-align
938- ``right``, ``center`` or ``left``. Defines were the text is displayed.
939-
940-
941-``<p>``
942-^^^^^^^^
943-
944-A text paragraph inside a rich text. This gives control over which font is
945-used for rendering and how it should be formatted.
946-
947-Valid attributes for ``<p>`` are:
948-
949-font-size
950- The font size to use in points. 10 points is the default. Use 12 points for
951- mission texts.
952-
953-font-face
954- Font face style of the font to use. The valid fonts are ``sans``, ``serif``,
955- and ``condensed``.
956-
957-font-color
958- The color of this font as a RGB hex tuple. That means 000000 is completely
959- black while ff0000 is completely red. Default color is a bright yellow
960- (ffff00).
961-
962-font-weight
963- ``normal`` or ``bold``. Note that not everything is supported by all fonts.
964- Do not use with ``font-style=italic`` at the same time; double formatting is
965- typographically bad.
966-
967-font-style
968- ``normal`` or ``italic``. Note that not everything is supported by all fonts.
969- Do not use with ``font-weight=bold`` at the same time; double formatting is
970- typographically bad.
971-
972-font-decoration
973- ``normal`` or ``underline``. Note that not everything is supported by all fonts.
974- Do not use with ``font-weight=bold`` or ``font-style=italic`` at the same time;
975- double formatting is typographically bad.
976-
977-line-spacing
978- Line spacing in points. Default is 0.
979-
980-``<br>``
981-^^^^^^^^
982-
983-This inserts a line break into the text. The line break character (``\n``) is
984-ignored inside a rich text.
985-
986-Real world Lua example
987-----------------------
988-
989-Here is a small example of a fancy message send to the user via the
990-:meth:`wl.game.Player.send_message` method:
991+syntax very similar to it. To tell our rendering system to go into richtext mode,
992+start your text with ``<rt>`` and end it with ``</rt>``.
993+
994+.. toctree::
995+ :maxdepth: 2
996+
997+ General Markup Functions <autogen_auxiliary_richtext.rst>
998+ Scenario Markup Functions <autogen_auxiliary_richtext_scenarios.rst>
999+ Richtext Tags, their Attributes and Restrictions <autogen_rt_tags.rst>
1000+
1001+
1002+Code Example
1003+------------
1004+
1005+Here is a simplified version of a fancy message displayed to the user:
1006
1007 .. code-block:: lua
1008
1009- wl.Game().players[1]:send_message(
1010- "Hi",
1011- "<rt image=images/logos/wl-ico-128.png image-align=center></rt>" ..
1012- "<rt text-align=center>" ..
1013- "<p font-weight=bold font-decoration=underline font-style=italic font-size=24>" ..
1014- "YOU so rock dude!" ..
1015- "</p></rt>" ..
1016- "<rt><p>No. I really mean this.<br><br>Seriously.</p></rt>",
1017- { popup = true }
1018- )
1019-
1020-The title of the message mustn't be a rich text, the body (which is just one
1021-string, it has been separated for easier reading and concatenated Lua-style
1022-via the ``..`` operator) is one: the first rich text includes a centered image
1023-and no text. The second is the text ``YOU so rock dude!`` in italic, bold and
1024-underlined. Then a simple text follows in four lines -- two of them being
1025-empty. The message popups the message window when it is received.
1026-
1027-The complete message rendered looks like this on my system:
1028-
1029-.. image:: images/fancymsg.png
1030- :scale: 100
1031- :alt: sample rendering
1032- :align: center
1033-
1034-
1035+ body =
1036+ "<rt> -- This is richtext
1037+ <p> -- Start a paragraph
1038+ <font size=18 bold=1 color=D1D1D1> -- Set font size and color
1039+ Big font to create a header
1040+ </font>
1041+ </p>
1042+ <p>
1043+ <font size=12>
1044+ Normal paragraph, just with a bit more text to show how it looks like.
1045+ </font>
1046+ </p>
1047+ -- The following content should be spread across a full line
1048+ <div width=100%>
1049+ <div>
1050+ <p>
1051+ <font size=12>
1052+ <img src=images/wui/menus/menu_toggle_menu.png>
1053+ </font>
1054+ </p>
1055+ </div>
1056+ <div width=*> -- Fill up the remaining space
1057+ <p>
1058+ <font size=12>
1059+ Another normal paragraph
1060+ </font>
1061+ </p>
1062+ </div>
1063+ </div>
1064+ ...
1065+ </rt>"
1066+
1067+This is quite a lot of hacking, so we have :ref:`Lua convenience functions <richtext.lua>`
1068+set up. We recommend that you always use those while scripting in Lua, which will
1069+also give us consistency in style throughout Widelands.
1070+Using the convenience functions will also result in cleaner code when
1071+including translation markup (the ``_[[Some text]]`` or ``_"Some text"`` function).
1072+
1073+A code example how to use the convenience functions and their attributes is given in the
1074+documentation for the :ref:`richtext convenience functions <lua_formatting_example>`.
1075+
1076+:ref:`Return to index<richtext.lua>`
1077
1078=== modified file 'src/graphic/text/rt_parse.cc'
1079--- src/graphic/text/rt_parse.cc 2017-12-09 06:29:26 +0000
1080+++ src/graphic/text/rt_parse.cc 2018-02-24 15:32:03 +0000
1081@@ -171,11 +171,64 @@
1082 }
1083 }
1084
1085+/* RST
1086+.. _rt_tags:
1087+
1088+The Richtext Tags
1089+=================
1090+
1091+- :ref:`rt_tags_rt`
1092+- :ref:`rt_tags_div`
1093+- :ref:`rt_tags_br`
1094+- :ref:`rt_tags_space`
1095+- :ref:`rt_tags_vspace`
1096+- :ref:`rt_tags_p`
1097+- :ref:`rt_tags_font`
1098+- :ref:`rt_tags_img`
1099+
1100+For an introduction to our richtext system including a code example, see :ref:`wlrichtext`.
1101+
1102+*/
1103+
1104 /*
1105 * Class Parser
1106 */
1107 Parser::Parser() {
1108- { // rt tag
1109+ {
1110+ /* RST
1111+.. _rt_tags_rt:
1112+
1113+Rich Text -- <rt>
1114+-----------------
1115+
1116+The main wrapper that will signal to the font renderer to go into richtext mode.
1117+This tag surrounds your whole text, and is allowed only once.
1118+You can also set some options here what will affect your whole text.
1119+
1120+Attributes
1121+^^^^^^^^^^
1122+
1123+* **padding**: The rectangle of this tag is shrunk so leave a gap on its outside, on all four outer edges.
1124+* **padding_r**: Padding on the right-hand side
1125+* **padding_l**: Padding on the left-hand side
1126+* **padding_b**: Padding on the bottom
1127+* **padding_t**: Padding on the top
1128+
1129+* **background**: Give this tag's rectangle a background color as a hex value.
1130+
1131+* **keep_spaces**: Do now trim away trailing and double spaces. Use this where the user is editing text.
1132+* **db_show_spaces**: Highlight all blank spaces for debugging purposes.
1133+
1134+Sub-tags
1135+^^^^^^^^
1136+
1137+* :ref:`rt_tags_div`
1138+* :ref:`rt_tags_font`
1139+* :ref:`rt_tags_p`
1140+* :ref:`rt_tags_vspace`
1141+
1142+:ref:`Return to tag index<rt_tags>`
1143+ */
1144 TagConstraint tc;
1145 tc.allowed_attrs.insert("padding");
1146 tc.allowed_attrs.insert("padding_r");
1147@@ -194,30 +247,92 @@
1148 tc.has_closing_tag = true;
1149 tag_constraints_["rt"] = tc;
1150 }
1151- { // br tag
1152+ {
1153+ /* RST
1154+.. _rt_tags_div:
1155+
1156+Division -- <div>
1157+-----------------
1158+
1159+This tag defines a rectangle and can be used as a layout control.
1160+
1161+Attributes
1162+^^^^^^^^^^
1163+
1164+The same attributes as :ref:`rt_tags_rt`, plus the following:
1165+
1166+* **margin**: Shrink all contents to leave a margin towards the outer edge of this tag's rectangle
1167+* **float**: To be implemented. Allowed values are ``left``, ``right``
1168+* **valign**: Align the contents vertically. Allowed values are ``top`` (default), ``center`` or ``middle``, ``bottom``.
1169+* **width**: The width of this element, as a pixel amount, or as a percentage.
1170+ The last ``div`` in a row can be expanded automatically by using ``*``.
1171+
1172+Sub-tags
1173+^^^^^^^^
1174+
1175+* :ref:`rt_tags_div`
1176+* :ref:`rt_tags_font`
1177+* :ref:`rt_tags_p`
1178+* :ref:`rt_tags_vspace`
1179+
1180+:ref:`Return to tag index<rt_tags>`
1181+ */
1182+ TagConstraint tc;
1183+ tc.allowed_attrs.insert("padding");
1184+ tc.allowed_attrs.insert("padding_r");
1185+ tc.allowed_attrs.insert("padding_l");
1186+ tc.allowed_attrs.insert("padding_b");
1187+ tc.allowed_attrs.insert("padding_t");
1188+ tc.allowed_attrs.insert("margin");
1189+ tc.allowed_attrs.insert("float");
1190+ tc.allowed_attrs.insert("valign");
1191+ tc.allowed_attrs.insert("background");
1192+ tc.allowed_attrs.insert("width");
1193+
1194+ tc.allowed_children.insert("p");
1195+ tc.allowed_children.insert("vspace");
1196+ tc.allowed_children.insert("font");
1197+ tc.allowed_children.insert("div");
1198+
1199+ tc.text_allowed = false;
1200+ tc.has_closing_tag = true;
1201+ tag_constraints_["div"] = tc;
1202+ }
1203+ {
1204+ /* RST
1205+.. _rt_tags_br:
1206+
1207+Line Break -- <br>
1208+------------------
1209+
1210+A single line break. Use sparingly for things like poetry stanzas.
1211+If you are starting a new paragraph, use :ref:`rt_tags_p` instead.
1212+
1213+:ref:`Return to tag index<rt_tags>`
1214+ */
1215 TagConstraint tc;
1216 tc.text_allowed = false;
1217 tc.has_closing_tag = false;
1218 tag_constraints_["br"] = tc;
1219 }
1220- { // img tag
1221- TagConstraint tc;
1222- tc.allowed_attrs.insert("src");
1223- tc.allowed_attrs.insert("ref");
1224- tc.allowed_attrs.insert("color");
1225- tc.allowed_attrs.insert("width");
1226- tc.text_allowed = false;
1227- tc.has_closing_tag = false;
1228- tag_constraints_["img"] = tc;
1229- }
1230- { // vspace tag
1231- TagConstraint tc;
1232- tc.allowed_attrs.insert("gap");
1233- tc.text_allowed = false;
1234- tc.has_closing_tag = false;
1235- tag_constraints_["vspace"] = tc;
1236- }
1237- { // space tag
1238+ {
1239+ /* RST
1240+.. _rt_tags_space:
1241+
1242+Horizontal Space -- <space>
1243+---------------------------
1244+
1245+Inserts a horizontal gap between the previous and the following text.
1246+This space can be filled with a character of your choice.
1247+
1248+Attributes
1249+^^^^^^^^^^
1250+
1251+* **gap**: The size of the gap as a pixel amount
1252+* **fill**: A character to fill the gap with
1253+
1254+:ref:`Return to tag index<rt_tags>`
1255+ */
1256 TagConstraint tc;
1257 tc.allowed_attrs.insert("gap");
1258 tc.allowed_attrs.insert("fill");
1259@@ -225,29 +340,58 @@
1260 tc.has_closing_tag = false;
1261 tag_constraints_["space"] = tc;
1262 }
1263- { // div tag
1264+ {
1265+ /* RST
1266+.. _rt_tags_vspace:
1267+
1268+Vertical Space -- <vspace>
1269+--------------------------
1270+
1271+Inserts a vertical gap between the previous and the following text.
1272+
1273+Attributes
1274+^^^^^^^^^^
1275+
1276+* **gap**: The size of the gap as a pixel amount
1277+
1278+:ref:`Return to tag index<rt_tags>`
1279+ */
1280 TagConstraint tc;
1281- tc.allowed_attrs.insert("padding");
1282- tc.allowed_attrs.insert("padding_r");
1283- tc.allowed_attrs.insert("padding_l");
1284- tc.allowed_attrs.insert("padding_b");
1285- tc.allowed_attrs.insert("padding_t");
1286- tc.allowed_attrs.insert("margin");
1287- tc.allowed_attrs.insert("float");
1288- tc.allowed_attrs.insert("valign");
1289- tc.allowed_attrs.insert("background");
1290- tc.allowed_attrs.insert("width");
1291-
1292- tc.allowed_children.insert("p");
1293- tc.allowed_children.insert("vspace");
1294- tc.allowed_children.insert("font");
1295- tc.allowed_children.insert("div");
1296-
1297+ tc.allowed_attrs.insert("gap");
1298 tc.text_allowed = false;
1299- tc.has_closing_tag = true;
1300- tag_constraints_["div"] = tc;
1301+ tc.has_closing_tag = false;
1302+ tag_constraints_["vspace"] = tc;
1303 }
1304- { // p tag
1305+ {
1306+ /* RST
1307+.. _rt_tags_p:
1308+
1309+Paragraph -- <p>
1310+----------------
1311+
1312+This tag encloses a text paragraph.
1313+
1314+Attributes
1315+^^^^^^^^^^
1316+
1317+* **indent**: Adds an indent to the first line of the paragraph
1318+* **align**: The horizontal alignment for the paragraph's text.
1319+ Allowed values are ``left`` (default), ``center`` or ``middle``, ``right``.
1320+* **valign**: See :ref:`rt_tags_div`
1321+* **spacing**: Vertical line spacing as a pixel value
1322+
1323+Sub-tags
1324+^^^^^^^^
1325+
1326+* :ref:`rt_tags_br`
1327+* :ref:`rt_tags_div`
1328+* :ref:`rt_tags_font`
1329+* :ref:`rt_tags_img`
1330+* :ref:`rt_tags_space`
1331+* :ref:`rt_tags_vspace`
1332+
1333+:ref:`Return to tag index<rt_tags>`
1334+ */
1335 TagConstraint tc;
1336 tc.allowed_attrs.insert("indent");
1337 tc.allowed_attrs.insert("align");
1338@@ -264,7 +408,40 @@
1339 tc.has_closing_tag = true;
1340 tag_constraints_["p"] = tc;
1341 }
1342- { // font tag
1343+ {
1344+ /* RST
1345+.. _rt_tags_font:
1346+
1347+Font -- <font>
1348+--------------
1349+
1350+This tag defines the font style for the enclosed text.
1351+
1352+Attributes
1353+^^^^^^^^^^
1354+
1355+* **size**: The font size as a pixel value
1356+* **face**: The font face. Allowed values are ``sans`` (default), ``serif`` and ``condensed``.
1357+* **color**: The font color as a hex value
1358+* **bold**: Make the text bold
1359+* **italic**: Make the text italic
1360+* **underline**: Underline the text
1361+* **shadow**: Add a background shadow
1362+* **ref**: To be implemented
1363+
1364+Sub-tags
1365+^^^^^^^^
1366+
1367+* :ref:`rt_tags_br`
1368+* :ref:`rt_tags_div`
1369+* :ref:`rt_tags_font`
1370+* :ref:`rt_tags_img`
1371+* :ref:`rt_tags_p`
1372+* :ref:`rt_tags_space`
1373+* :ref:`rt_tags_vspace`
1374+
1375+:ref:`Return to tag index<rt_tags>`
1376+ */
1377 TagConstraint tc;
1378 tc.allowed_attrs.insert("size");
1379 tc.allowed_attrs.insert("face");
1380@@ -286,6 +463,34 @@
1381 tc.has_closing_tag = true;
1382 tag_constraints_["font"] = tc;
1383 }
1384+ {
1385+ /* RST
1386+.. _rt_tags_img:
1387+
1388+Image -- <img>
1389+--------------
1390+
1391+Displays an image with your text.
1392+
1393+Attributes
1394+^^^^^^^^^^
1395+
1396+* **src**: The path to the image, relative to the ``data`` directory.
1397+* **ref**: To be implemented
1398+* **color**: Player color for the image as a hex value
1399+* **width**: Width of the image as a pixel amount. The corresponding height will be matched automatically.
1400+
1401+:ref:`Return to tag index<rt_tags>`
1402+ */
1403+ TagConstraint tc;
1404+ tc.allowed_attrs.insert("src");
1405+ tc.allowed_attrs.insert("ref");
1406+ tc.allowed_attrs.insert("color");
1407+ tc.allowed_attrs.insert("width");
1408+ tc.text_allowed = false;
1409+ tc.has_closing_tag = false;
1410+ tag_constraints_["img"] = tc;
1411+ }
1412 }
1413
1414 Parser::~Parser() {