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

[GunChleoc]

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

[GunChleoc (gunchleoc)]

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)]

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.

[kaputtnik (franku)]

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)]

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)]

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)]

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)]

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)]

> 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)]

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

[GunChleoc (gunchleoc)]

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)]

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

[GunChleoc (gunchleoc)]

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

review: Needs Resubmitting

[kaputtnik (franku)]

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.

[GunChleoc (gunchleoc)]

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)]

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)]

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.

[kaputtnik (franku)]

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)]

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 ""?

[GunChleoc (gunchleoc)]

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

[kaputtnik (franku)]

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)]

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

[GunChleoc (gunchleoc)]

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.

[kaputtnik (franku)]

Done.

[GunChleoc (gunchleoc)]

Thanks a lot for your help! :)

@bunnybot merge

=== modified file 'data/scripting/messages.lua'
--- data/scripting/messages.lua	2017-12-09 06:29:26 +0000
+++ data/scripting/messages.lua	2018-02-24 15:32:03 +0000
@@ -33,6 +33,28 @@
    player:send_message(title, body, parameters)
 end
 
+
+-- RST
+-- .. function:: send_to_all(text[, heading])
+--
+--    Sends a game status message to all players.
+--
+--    :arg text: the localized body of the message. You can use rt functions here.
+--    :type text: :class:`string`
+--    :arg heading: the localized title of the message (optional)
+--    :type heading: :class:`string`
+--
+function send_to_all(text, heading)
+   for idx,plr in ipairs(game.players) do
+      if (heading ~= nil and heading ~= "") then
+         send_message(plr, _"Status", text, {popup=true, heading=heading})
+      else
+         send_message(plr, _"Status", text, {popup=true})
+      end
+   end
+end
+
+
 -- RST
 -- .. function:: message_box(player, title, message, parameters)
 --
 
=== modified file 'data/scripting/richtext.lua'
--- data/scripting/richtext.lua	2018-02-12 10:17:22 +0000
+++ data/scripting/richtext.lua	2018-02-24 15:32:03 +0000
@@ -1,60 +1,40 @@
 -- TODO(GunChleoc): Wrap all tags and document allowed attributes when we're done
 
 -- RST
+--
+-- .. _richtext.lua:
+--
 -- richtext.lua
 -- ------------
 --
 -- Functions to simplify and unique text formatting in scenarios and help files.
--- Most of these functions are simple wrapper functions that make working with
--- widelands rich text formatting system more bearable.
+-- Most of these functions are simple wrapper functions that make working with the
+-- :ref:`widelands rich text formatting system <wlrichtext>` more bearable.
 -- Function names generally follow HTML names.
+-- We strongly recommend that you make use of these functions rather than hacking
+-- the tags manually.
+-- If you're writing a scenario, you should also have a look at
+-- :ref:`richtext_scenarios.lua`.
+--
+-- - `Blocks and Positioning`_
+-- - `Headings and Paragraphs`_
+-- - `Text Formatting`_
+-- - `Lists`_
+-- - `Images`_
+-- - `Links`_
+-- - `Text Composition`_
+-- - `Code Example`_
 
 
 -- RST
--- .. function:: localize_list(items, listtype, former_textdomain)
---    :noindex:
---
---    Turns an array of string items into a localized string list with
---    appropriate concatenation.
---
---    e.g. localize_list({"foo", "bar", baz"}, "or", "widelands") will return
---    _"foo, bar or baz"
---
---    :arg items:              An array of strings
---    :arg listtype:           The type of concatenation to use.
---                             Legal values are "&", "and", "or", and ";"
---    :arg former_textdomain:  The textdomain to restore after running this function.
---    :returns: The concatenated list string, using localized concatenation operators.
---
--- Same algorithm as in src/base/i18n
-function localize_list(items, listtype, former_textdomain)
-   set_textdomain("widelands")
-   local result = ""
-   for i, item in pairs(items) do
-      if (i == 1) then
-         result = item
-      elseif (i == #items) then
-         if (listtype == "&") then
-            result = _"%1$s & %2$s":bformat(result, item)
-         elseif (listtype == "or") then
-            result = _"%1$s or %2$s":bformat(result, item)
-         elseif (listtype == ",") then
-            result = _"%1$s, %2$s":bformat(result, item)
-         else
-            result = _"%1$s and %2$s":bformat(result, item)
-      end
-      else
-         result = _"%1$s, %2$s":bformat(result, item)
-      end
-   end
-   set_textdomain(former_textdomain)
-   return result
-end
+-- Blocks and Positioning
+-- ^^^^^^^^^^^^^^^^^^^^^^
+--
+-- This section covers functions for structuring your text layout.
 
 
 -- RST
 -- .. function:: rt(text_or_attributes[, text = nil])
---    :noindex:
 --
 --    Wraps a block of text into Lua rich text.
 --    Only call this once for the whole text that gets sent to the backend.
@@ -62,14 +42,9 @@
 --    because the backend will take care of it.
 --    So, only use this function if you wish to add some attributes to the tag.
 --
---    Allowed attributes are:
---       padding, padding_r, padding_l, padding_b, padding_t: TODO(GunChleoc): Document
---       background:  a background color or image
---       debug:       add visual debug information and debug log
---       editor_mode: allow multiple blank spaces for editing
---
---    :arg attributes: the attributes for the rt tag.
---    :type attributes: :class:`string`
+--    :arg text_or_attributes: see the :ref:`rt tag's documentation <rt_tags_rt>`
+--                             for a list of attributes and their descriptions.
+--    :type text_or_attributes: :class:`string`
 --    :arg text: the text to be enclosed in rich text tags.
 --    :type text: :class:`string`
 --    :returns: the wrapped rich text.
@@ -84,31 +59,72 @@
 
 
 -- RST
--- .. function:: img(src[, attributes = nil])
---    :noindex:
---
---    Turns an image src path into an image tag for richtext.
---
---    :arg src: the file path to the image.
---    :type src: :class:`string`
---    :arg attributes: the attributes for the div tag.
---    :type attributes: :class:`string`
---
---    Allowed attributes are:
---       color:     a hex color to be applied to the image's player color mask, if it has any
---       ref:       TODO(GunChleoc): I have no idea what it does.
---
---    :returns: the img tag.
+-- .. function:: div(text_or_attributes[, text = nil])
+--
+--    Wraps a block of text into a div tag.
+--
+--    :arg text_or_attributes: see the :ref:`div tag's documentation <rt_tags_div>`
+--                             for a list of attributes and their descriptions.
+--    :type test_or_attributes: :class:`string`
+--
+--    :arg text: the text to be enclosed in div tags.
+--    :type text: :class:`string`
+--    :returns: the text wrapped in a div tag.
 
-function img(src, attributes)
-   if attributes then
-      return "<img src=" .. src .." " .. attributes .. ">"
+function div(text_or_attributes, text)
+   if text then
+      return ("<div %s>"):format(text_or_attributes) .. text .. "</div>"
    else
-      return "<img src=" .. src .. ">"
+      return ("<div>") .. text_or_attributes .. "</div>"
    end
 end
 
 
+-- RST
+-- .. function:: space(gap)
+--
+--    Adds a horizontal space
+--
+--    :arg gap: the size of the space as pixels.
+--
+--    :returns: a space tag
+
+function space(gap)
+   return "<space gap="..gap..">"
+end
+
+
+-- RST
+-- .. function:: vspace(gap)
+--
+--    Adds a vertical space
+--
+--    :arg gap: the size of the space as pixels.
+--
+--    :returns: a vspace tag
+
+function vspace(gap)
+   return "<vspace gap="..gap..">"
+end
+
+
+-- RST
+-- :ref:`Return to index<richtext.lua>`
+--
+-- Headings and Paragraphs
+-- ^^^^^^^^^^^^^^^^^^^^^^^
+--
+-- This section covers functions for defining headings and paragraphs.
+
+
+-- RST
+-- .. function:: title(font_face, text)
+--
+--    Returns a paragraph formatted as a title heading. Use this on the top of
+--    your document only.
+--
+--    :returns: A paragraph with text formatted as title.
+
 function title(font_face, text)
    return p_font("align=center", "size=38 face=".. font_face .. " color=2F9131", text)
 end
@@ -116,12 +132,11 @@
 
 -- RST
 -- .. function:: h1(text_or_color[, text = nil])
---    :noindex:
 --
 --    Returns a paragraph formatted as a big heading with a small gap after it.
---    The mnemonic comes from HTML.
 --
 --    :returns: A paragraph with text formatted as heading.
+
 function h1(text_or_color, text)
    if text then
       return p_font("", "size=18 bold=1 color=".. text_or_color, vspace(12) .. text .. vspace(1))
@@ -130,20 +145,21 @@
    end
 end
 
+
 -- RST
 -- .. function:: h2(text)
---    :noindex:
 --
 --    Like :func:`h1` but smaller.
 --
 --    :returns: A paragraph with text formatted as heading.
+
 function h2(text)
    return p_font("", "size=14 bold=1 color=D1D1D1", vspace(12) .. text .. vspace(1))
 end
 
+
 -- RST
 -- .. function:: h3(text)
---    :noindex:
 --
 --    Like :func:`h2` but smaller.
 --
@@ -153,9 +169,9 @@
    return p_font("", "size=13 color=D1D1D1", vspace(6) .. text .. vspace(1))
 end
 
+
 -- RST
 -- .. function:: h4(text)
---    :noindex:
 --
 --    Like :func:`h3` but smaller.
 --
@@ -165,16 +181,36 @@
    return p_font("", "size=12 italic=1 color=D1D1D1", text)
 end
 
+
+-- RST
+-- .. function:: inline_header(header, text)
+--
+--    Creates a line of h3 formatted text followed by normal paragraph text.
+--
+--    :arg header: text in h3 format.
+--    :arg text: text in p format.
+--    :returns: header text followed by normal text.
+
+function inline_header(header, text)
+   return
+      div("width=100%", vspace(8)) ..
+      div("width=100%", font("size=13 color=D1D1D1", header .. " ") ..
+      font("size=12", text))
+end
+
+
 -- RST
 -- .. function:: p(text_or_attributes[, text = nil])
---    :noindex:
 --
 --    Returns one paragraph with text followed by a small vertical gap. Options
 --    can be given as first argument similar to :func:`rt`.
 --
---    Allowed attributes are documented in the open_p function.
+--    :arg text_or_attributes: see the :ref:`p tag's documentation <rt_tags_p>`
+--                             for a list of attributes and their descriptions.
+--    :type text_or_attributes: :class:`string`
 --
 --    :returns: The text wrapped in <p>%s</p>
+
 function p(text_or_attributes, text)
    if text then
       return open_p(text_or_attributes) .. text .. close_p()
@@ -185,38 +221,17 @@
 
 
 -- RST
--- .. function:: p_font(text_or_attributes[, text = nil])
---
---    Returns one paragraph with text followed by a small vertical gap. Options
---    can be given as first argument similar to :func:`rt`.
---
---    Allowed p attributes are documented in the open_p function.
---
---    Allowed font attributes are are documented in the font function.
---
---    :returns: The text wrapped in <p attributes><font attributes>text</font></p>
-function p_font(p_or_font_or_attributes, text_or_font_attributes, text)
-   if text then
-      return ("<p %s>"):format(p_or_font_or_attributes) .. "<font " .. text_or_font_attributes .. ">" .. text .. close_p()
-   else
-      return "<p><font " .. p_or_font_or_attributes .. ">" .. text_or_font_attributes .. close_p()
-   end
-end
-
-
--- RST
 -- .. function:: open_p([attributes = nil])
 --
 --    Returns a paragraph open tag and default font size. Options
 --    can be given as first argument similar to :func:`rt`.
 --
---    Allowed attributes are:
---       indent:  indents the first line of the paragraph
---       align:   horizontal alignment (left, center, right)
---       valign:  vertical alignment (top, middle, bottom)
---       spacing: line spacing in pixels
+--    :arg attributes: see the :ref:`p tag's documentation <rt_tags_p>`
+--                     for a list of attributes and their descriptions.
+--    :type attributes: :class:`string`
 --
 --    :returns: <p> with added attributes and default font
+
 function open_p(attributes)
    if attributes then
       return ("<p %s>"):format(attributes) .. "<font size=12>"
@@ -232,24 +247,55 @@
 --    Closes a paragraph.
 --
 --    :returns: The closing tags for a paragraph
+
 function close_p(t)
    return vspace(6) .. "</font>" .. vspace(6)  .. "</p>"
 end
 
+
+-- RST
+-- .. function:: p_font(p_or_font_attributes, text_or_font_attributes[, text = nil])
+--
+--    Returns one paragraph with text followed by a small vertical gap. Options
+--    can be given as first argument similar to :func:`rt`.
+--
+--    :arg p_or_font_attributes: Optional paragraph or font attributes.
+--    :type p_or_font_attributes: :class:`string`
+--
+--    :arg text_or_font_attributes: Optional font attributes or the text itself.
+--    :type text_or_font_attributes: :class:`string`
+--
+--    See the :ref:`p tag's documentation <rt_tags_p>` for a list of paragraph
+--    attributes and the :ref:`font tag's documentation <rt_tags_font>` for a
+--    list of font attributes.
+--
+--    :returns: The text wrapped in <p attributes><font attributes>text</font></p>
+
+function p_font(p_or_font_attributes, text_or_font_attributes, text)
+   if text then
+      return ("<p %s>"):format(p_or_font_attributes) .. "<font " .. text_or_font_attributes .. ">" .. text .. close_p()
+   else
+      return "<p><font " .. p_or_font_attributes .. ">" .. text_or_font_attributes .. close_p()
+   end
+end
+
+-- RST
+-- :ref:`Return to index<richtext.lua>`
+--
+-- Text Formatting
+-- ^^^^^^^^^^^^^^^
+--
+-- This section covers convenience functions for text formatting.
+
+
 -- RST
 -- .. function:: font(attributes, text)
 --
---    Wraps the text in font tags.
+--    Wraps the text in font tags. See also :any:`p_font`.
 --
---    Allowed attributes are:
---       size:      the font size in pt
---       face:      sans, serif or condensed
---       color:     a hex color
---       bold:      if you add bold=1, the text will be bold
---       italic:    if you add italic=1, the text will be italic
---       underline: if you add underline=1, the text will be underlined
---       shadow:    if you add shadow=1, the text will have a shadow
---       ref:       TODO(GunChleoc): I don't know what this does.
+--    :arg attributes: see the :ref:`font tag's documentation <rt_tags_font>`
+--                     for a list of attributes and their descriptions.
+--    :type attributes: :class:`string`
 --
 --    :returns: The text wrapped in font tags with the given attributes
 
@@ -257,35 +303,61 @@
    return ("<font %s>"):format(attributes) .. text .. "</font>"
 end
 
--- RST
--- .. function:: space(gap)
---
---    Adds a horizontal space
---    :arg gap: the size of the space as pixels.
---
---    :returns: a space tag
-
-function space(gap)
-   return "<space gap="..gap..">"
-end
-
--- RST
--- .. function:: vspace(gap)
---
---    Adds a vertical space
---    :arg gap: the size of the space as pixels.
---
---    :returns: a vspace tag
-
-function vspace(gap)
-   return "<vspace gap="..gap..">"
-end
+
+-- RST
+-- .. function:: b(text)
+--
+--    This makes the text bold.
+--
+--    :arg text: the text to format
+--
+--    :returns: a font tag containing the bold text
+
+function b(text)
+   return font("bold=1", text)
+end
+
+-- RST
+-- .. function:: i(text)
+--
+--    This makes the text italic.
+--
+--    :arg text: the text to format
+--
+--    :returns: a font tag containing the italic text
+
+function i(text)
+   return font("italic=1", text)
+end
+
+-- RST
+-- .. function:: u(text)
+--
+--    This underlines the text.
+--
+--    :arg text: the text to format
+--
+--    :returns: a font tag containing the underlined text
+
+function u(text)
+   return font("underline=1", text)
+end
+
+
+-- RST
+-- :ref:`Return to index<richtext.lua>`
+--
+-- Lists
+-- ^^^^^
+--
+-- This section covers functions for defining lists.
+
 
 -- RST
 -- .. function:: dl(dt, dd)
---    :noindex:
---
--- This function imitates a HTML description list
+--
+--    This function imitates a HTML description list
+--
 --    :arg dt: "description term", will be rendered in bold.
 --    :arg dd: "description data", will be rendered normally.
 --
@@ -295,13 +367,14 @@
    return p(b(dt) .. " " .. dd)
 end
 
+
 -- RST
 -- .. function:: li(text_or_symbol[, text = nil])
 --
 --    Adds the symbol in front of the text to create a list item and
 --    wraps it in a paragraph
 --
---    :arg symbol: the item symbol for the list, e.g. "•" or "→"
+--    :arg symbol: the item symbol for the list, e.g. "•" or "→". "•" is the default.
 --    :arg text: the text of the list item
 --
 --    :returns: a p tag containing the formatted text
@@ -314,6 +387,7 @@
    end
 end
 
+
 -- RST
 -- .. function:: li_arrow(text)
 --
@@ -322,19 +396,23 @@
 --    :arg text: the text of the list item
 --
 --    :returns: li("→", text)
+
 function li_arrow(text)
    -- TODO(GunChleoc): Reverse arrow for rtl languages.
    return li("→", text)
 end
 
+
 -- RST
--- .. function li_image(imagepath, text)
+-- .. function:: li_image(imagepath, text)
 --
 --    Places a paragraph of text to the right of an image
-
+--
 --    :arg imagepath: the full path to the image file
---    :arg text_width_percent: the percentatge of space that the text will occupy
+--    :type imagepath: :class:`string`
+--
 --    :arg text: the text to be placed next to the image
+--    :type text: :class:`string`
 --
 --    :returns: the text wrapped in a paragraph and placed next to the image, the outer tag is a div.
 
@@ -347,11 +425,52 @@
       )
 end
 
+
+-- RST
+-- :ref:`Return to index<richtext.lua>`
+--
+-- Images
+-- ^^^^^^
+--
+-- This section covers functions for including images.
+
+
+-- RST
+-- .. function:: img(src[, attributes = nil])
+--
+--    Turns an image src path into an image tag for richtext. See also :any:`li_image`.
+--
+--    :arg src: the file path to the image.
+--    :type src: :class:`string`
+--    :arg attributes: see the :ref:`img tag's documentation <rt_tags_img>`
+--                     for a list of attributes and their descriptions.
+--    :type attributes: :class:`string`
+--
+--    :returns: the img tag.
+
+function img(src, attributes)
+   if attributes then
+      return "<img src=" .. src .." " .. attributes .. ">"
+   else
+      return "<img src=" .. src .. ">"
+   end
+end
+
+
+-- RST
+-- :ref:`Return to index<richtext.lua>`
+--
+-- Links
+-- ^^^^^
+--
+-- This section covers functions for including links. We can't do real links yet,
+-- so we only highlight the text for now.
+
 -- RST
 -- .. function:: a(link)
---    :noindex:
---
--- This function imitates a HTML link. We can't do real links yet, so the text just gets underlines.
+--
+--    This function imitates a HTML link. We can't do real links yet, so the text just gets underlines.
+--
 --    :arg link: the text to format
 --
 --    :returns: a font tag containing the underlined text
@@ -361,87 +480,14 @@
 end
 
 -- RST
--- .. function:: b(link)
---    :noindex:
---
--- This makes the text bold.
---    :arg link: the text to format
---
---    :returns: a font tag containing the bold text
-
-function b(text)
-   return font("bold=1", text)
-end
-
--- RST
--- .. function:: i(link)
---    :noindex:
---
--- This makes the text italic.
---    :arg link: the text to format
---
---    :returns: a font tag containing the italic text
-
-function i(text)
-   return font("italic=1", text)
-end
-
--- RST
--- .. function:: u(link)
---
--- This underlines the text.
---    :arg link: the text to format
---
---    :returns: a font tag containing the underlined text
-
-function u(text)
-   return font("underline=1", text)
-end
-
--- RST
--- .. function:: div(text_or_attributes[, text = nil])
---
---    Wraps a block of text into a div tag.
---
---    :arg attributes: the attributes for the div tag.
---    :type attributes: :class:`string`
---
---    Allowed attributes are:
---       padding, padding_r, padding_l, padding_b, padding_t: TODO(GunChleoc): Document
---       margin:     TODO(GunChleoc): Document
---       float:      TODO(GunChleoc): this does not work yet
---       margin:     inner margin for the div
---       valign:     vertical alignment
---       background: a background color or image
---       width:      the width of the div in pixels or percent
---
---    :arg text: the text to be enclosed in div tags.
---    :type text: :class:`string`
---    :returns: the text wrapped in a div tag.
-
-function div(text_or_attributes, text)
-   if text then
-      return ("<div %s>"):format(text_or_attributes) .. text .. "</div>"
-   else
-      return ("<div>") .. text_or_attributes .. "</div>"
-   end
-end
-
--- RST
--- .. function:: inline_header(t1, t2)
---
---    Creates a line of h3 formatted text followed by normal paragraph text.
---
---    :arg t1: text in h3 format.
---    :arg t2: text in p format.
---    :returns: header text followed by normal text.
-
-function inline_header(header, text)
-   return
-      div("width=100%", vspace(8)) ..
-      div("width=100%", font("size=13 color=D1D1D1", header .. " ") ..
-      font("size=12", text))
-end
+-- :ref:`Return to index<richtext.lua>`
+--
+-- Text Composition
+-- ^^^^^^^^^^^^^^^^
+--
+-- This section covers functions for text composition that help with proper markup
+-- to make the text translatable.
+
 
 -- RST
 -- .. function:: join_sentences(sentence1, sentence2)
@@ -452,9 +498,92 @@
 --    :arg sentence1: text of the first sentence
 --    :arg sentence2: text of the second sentence
 --    :returns: two concatenated sentences with a localized sentence joiner.
---
+
 function join_sentences(sentence1, sentence2)
    -- TRANSLATORS: Put 2 sentences one after the other.
    -- TRANSLATORS: Languages using Chinese script probably want to lose the blank space here.
    return pgettext("sentence_separator", "%s %s"):bformat(sentence1, sentence2)
 end
+
+
+-- RST
+-- .. function:: localize_list(items, listtype, former_textdomain)
+--
+--    Turns an array of string items into a localized string list with
+--    appropriate concatenation.
+--
+--    e.g. localize_list({"foo", "bar", "baz"}, "or", "widelands") will return
+--    _"foo, bar or baz"
+--
+--    :arg items:              An array of strings
+--    :arg listtype:           The type of concatenation to use.
+--                             Legal values are "&", "and", "or", and ";"
+--    :arg former_textdomain:  The textdomain to restore after running this function.
+--    :returns: The concatenated list string, using localized concatenation operators.
+--
+-- Same algorithm as in src/base/i18n
+
+function localize_list(items, listtype, former_textdomain)
+   set_textdomain("widelands")
+   local result = ""
+   for i, item in pairs(items) do
+      if (i == 1) then
+         result = item
+      elseif (i == #items) then
+         if (listtype == "&") then
+            result = _"%1$s & %2$s":bformat(result, item)
+         elseif (listtype == "or") then
+            result = _"%1$s or %2$s":bformat(result, item)
+         elseif (listtype == ",") then
+            result = _"%1$s, %2$s":bformat(result, item)
+         else
+            result = _"%1$s and %2$s":bformat(result, item)
+      end
+      else
+         result = _"%1$s, %2$s":bformat(result, item)
+      end
+   end
+   set_textdomain(former_textdomain)
+   return result
+end
+
+
+-- RST
+-- :ref:`Return to index<richtext.lua>`
+--
+-- .. _lua_formatting_example:
+--
+-- Code Example
+-- ^^^^^^^^^^^^
+-- Here's an example on how these functions and their attributes can be used. The double dot
+-- (``..``) is the LUA string concatenation operator. Note that this example
+-- also includes translation markup (the ``_[[Some text]]`` or ``_"Some text"`` function):
+--
+-- .. code-block:: lua
+--
+--    include "scripting/richtext.lua"
+--
+--    title = "Text Formatting",
+--    body = h1(_[[Normal header]]) ..
+--           h1("6699ff", _[[Colored header]]) ..
+--           p(_[[Normal paragraph, just with a bit more text to show how it looks like.]]) ..
+--           p("align=center", _[[A centered paragraph, just with a bit more text to show how it looks like.]]) ..
+--           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]]) ..
+--           li(_[[A list item]]) ..
+--           li(font("color=6699ff bold=1", _[[Blue and bold]])) ..
+--           li_arrow(_[[A list item with an arrow]]) ..
+--           p(_[[A more complicated paragraph with ]] ..
+--              font("color=ffffff", _[[white text ]]) ..
+--              _[[and ]] ..
+--              font("italic=1 bold=1", _[[bold italic formatted text.]])
+--           ),
+--
+--
+-- This results in the following for a campaign message box:
+--
+-- .. image:: images/wlrichtext.png
+--    :scale: 100
+--    :alt: sample rendering
+--    :align: center
+--
+-- :ref:`Return to index<richtext.lua>`
 
=== modified file 'data/scripting/richtext_scenarios.lua'
--- data/scripting/richtext_scenarios.lua	2018-01-04 13:45:46 +0000
+++ data/scripting/richtext_scenarios.lua	2018-02-24 15:32:03 +0000
@@ -1,12 +1,14 @@
 include "scripting/richtext.lua"
 
 -- RST
+-- .. _richtext_scenarios.lua:
+--
 -- richtext_scenarios.lua
 -- ----------------------
 --
--- Function to simplify and unique text formatting in scenarios.  Most of these
--- functions are simple wrapper functions that make working with widelands rich
--- text formatting system more bearable.
+-- Functions to simplify text formatting in scenarios and make it consistent.
+-- Most of these functions are simple wrapper functions for our :ref:`richtext system <wlrichtext>`.
+-- This file will include :ref:`richtext.lua` for you for additional formatting functions.
 
 -- RST
 -- .. function:: speech(img, clr, title, text)
@@ -36,6 +38,7 @@
    return title .. li_image(img, p(text))
 end
 
+
 -- RST
 -- .. function:: paragraphdivider()
 --
@@ -49,7 +52,6 @@
 end
 
 
-
 -- RST
 -- .. function:: objective_text(heading, body)
 --
@@ -64,13 +66,16 @@
 
 
 -- RST
--- Append an objective text with a header to a dialog box in a nice fashion.
--- For displaying objectives with an extra title when an advisor is talking
+-- .. function:: new_objectives(...)
+--
+--    Append an objective text with a header to a dialog box in a nice fashion.
+--    For displaying objectives with an extra title when an advisor is talking
 --
 --    Provides nice formatting for objective texts.
---    the following arguments will be parsed:
---    number: the number of objectives described in the body
---    body: the objective text, e.g. created with function objective_text(heading, body)
+--    The following arguments will be parsed:
+--
+--       - number: the number of objectives described in the body
+--       - body: the objective text, e.g. created with function objective_text(heading, body)
 --
 --    :returns: a rich text object that contains the formatted
 --       objective text & title.
 
=== modified file 'doc/sphinx/extract_rst.py'
--- doc/sphinx/extract_rst.py	2017-11-05 09:30:44 +0000
+++ doc/sphinx/extract_rst.py	2018-02-24 15:32:03 +0000
@@ -14,6 +14,7 @@
 # Meaning: (src_file, file_name_to_generate_rst)
 cpp_pairs = (
     ('src/ai/ai_hints.cc', 'autogen_ai_hints.rst'),
+    ('src/graphic/text/rt_parse.cc', 'autogen_rt_tags.rst'),
     ('src/scripting/lua_root.cc', 'autogen_wl.rst'),
     ('src/scripting/lua_bases.cc', 'autogen_wl_bases.rst'),
     ('src/scripting/lua_editor.cc', 'autogen_wl_editor.rst'),
 
=== renamed file 'doc/sphinx/source/images/fancymsg.png' => 'doc/sphinx/source/images/wlrichtext.png'
 Binary 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
=== modified file 'doc/sphinx/source/wlrichtext.rst'
--- doc/sphinx/source/wlrichtext.rst	2016-01-28 05:24:34 +0000
+++ doc/sphinx/source/wlrichtext.rst	2018-02-24 15:32:03 +0000
@@ -1,126 +1,71 @@
+.. _wlrichtext:
+
 The Widelands Rich Text System
 ==============================
 
-All texts that can be displayed to the user can be formatted to be layouted
+All texts that can be displayed to the user can be marked up to be laid out
 and nicely formatted. This allows for changing of font sizes, weights, colors
 and for the embedding of images. This documents how to format a string to be
 recognized as rich text and which attributes are understood.
 
 The Widelands rich text language is inspired by HTML and therefore uses a
-syntax very similar to it. A rich text is started with ``<rt>`` and ended with
-``</rt>``. A rich text can have an image associated with it, this image is
-then displayed next to the text.
-
-Inside the rich text, each paragraph is enclosed by ``<p>`` and ``</p>``. You
-give font attributes to this tag to change the appearance of the text
-displayed inside.
-
-Reference
----------
-
-``<rt>``
-^^^^^^^^
-
-Starts or ends a rich text. Must be the first tag to appear in the string.
-A full example would be::
-
-   <rt image=map:khanktrukh.png><p line-spacing=3 font-size=12>Hello<br>World</p></rt>
-
-This would instruct widelands to use the image of Khankruth that comes with
-the map, left align it. To the right of it there would be two lines of text.
-The first line being ``Hello`` and the second being ``World``. They would be
-displayed with a font-size of 12 points and a line-spacing of 3 points.
-
-Valid attributes for ``<rt>`` are:
-
-image
-   The name of a image to use, can be prefixed with ``map:`` which instructs
-   widelands to load the image from the ``pics/`` directory inside the map of
-   this scenario.
-
-image-align
-   ``right``, ``center`` or ``left``. Defines were the image is displayed.
-
-text-align
-   ``right``, ``center`` or ``left``. Defines were the text is displayed.
-
-
-``<p>``
-^^^^^^^^
-
-A text paragraph inside a rich text. This gives control over which font is
-used for rendering and how it should be formatted.
-
-Valid attributes for ``<p>`` are:
-
-font-size
-   The font size to use in points. 10 points is the default. Use 12 points for
-   mission texts.
-
-font-face
-   Font face style of the font to use. The valid fonts are ``sans``, ``serif``,
-   and ``condensed``.
-
-font-color
-   The color of this font as a RGB hex tuple. That means 000000 is completely
-   black while ff0000 is completely red. Default color is a bright yellow
-   (ffff00).
-
-font-weight
-   ``normal`` or ``bold``. Note that not everything is supported by all fonts.
-   Do not use with ``font-style=italic`` at the same time; double formatting is
-   typographically bad.
-
-font-style
-   ``normal`` or ``italic``. Note that not everything is supported by all fonts.
-   Do not use with ``font-weight=bold`` at the same time; double formatting is
-   typographically bad.
-
-font-decoration
-   ``normal`` or ``underline``. Note that not everything is supported by all fonts.
-   Do not use with ``font-weight=bold`` or ``font-style=italic`` at the same time;
-   double formatting is typographically bad.
-
-line-spacing
-   Line spacing in points. Default is 0.
-
-``<br>``
-^^^^^^^^
-
-This inserts a line break into the text. The line break character (``\n``) is
-ignored inside a rich text.
-
-Real world Lua example
-----------------------
-
-Here is a small example of a fancy message send to the user via the
-:meth:`wl.game.Player.send_message` method:
+syntax very similar to it. To tell our rendering system to go into richtext mode,
+start your text with ``<rt>`` and end it with ``</rt>``.
+
+.. toctree::
+   :maxdepth: 2
+
+   General Markup Functions <autogen_auxiliary_richtext.rst>
+   Scenario Markup Functions <autogen_auxiliary_richtext_scenarios.rst>
+   Richtext Tags, their Attributes and Restrictions <autogen_rt_tags.rst>
+
+
+Code Example
+------------
+
+Here is a simplified version of a fancy message displayed to the user:
 
 .. code-block:: lua
 
-   wl.Game().players[1]:send_message(
-      "Hi",
-      "<rt image=images/logos/wl-ico-128.png image-align=center></rt>" ..
-      "<rt text-align=center>" ..
-      "<p font-weight=bold font-decoration=underline font-style=italic font-size=24>" ..
-         "YOU so rock dude!" ..
-      "</p></rt>" ..
-      "<rt><p>No. I really mean this.<br><br>Seriously.</p></rt>",
-      { popup = true }
-   )
-
-The title of the message mustn't be a rich text, the body (which is just one
-string, it has been separated for easier reading and concatenated Lua-style
-via the ``..`` operator) is one: the first rich text includes a centered image
-and no text. The second is the text ``YOU so rock dude!`` in italic, bold and
-underlined. Then a simple text follows in four lines -- two of them being
-empty. The message popups the message window when it is received.
-
-The complete message rendered looks like this on my system:
-
-.. image:: images/fancymsg.png
-   :scale: 100
-   :alt: sample rendering
-   :align: center
-
-
+   body =
+      "<rt>                                     -- This is richtext
+         <p>                                    -- Start a paragraph
+            <font size=18 bold=1 color=D1D1D1>  -- Set font size and color
+               Big font to create a header
+            </font>
+         </p>
+         <p>
+            <font size=12>
+               Normal paragraph, just with a bit more text to show how it looks like.
+            </font>
+         </p>
+         -- The following content should be spread across a full line
+         <div width=100%>
+            <div>
+               <p>
+                  <font size=12>
+                  <img src=images/wui/menus/menu_toggle_menu.png>
+                  </font>
+               </p>
+            </div>
+            <div width=*>                       -- Fill up the remaining space
+               <p>
+                  <font size=12>
+                     Another normal paragraph
+                  </font>
+               </p>
+            </div>
+         </div>
+         ...
+      </rt>"
+
+This is quite a lot of hacking, so we have :ref:`Lua convenience functions <richtext.lua>`
+set up. We recommend that you always use those while scripting in Lua, which will
+also give us consistency in style throughout Widelands.
+Using the convenience functions will also result in cleaner code when
+including translation markup (the ``_[[Some text]]`` or ``_"Some text"`` function).
+
+A code example how to use the convenience functions and their attributes is given in the
+documentation for the :ref:`richtext convenience functions <lua_formatting_example>`.
+
+:ref:`Return to index<richtext.lua>`
 
=== modified file 'src/graphic/text/rt_parse.cc'
--- src/graphic/text/rt_parse.cc	2017-12-09 06:29:26 +0000
+++ src/graphic/text/rt_parse.cc	2018-02-24 15:32:03 +0000
@@ -171,11 +171,64 @@
 	}
 }
 
+/* RST
+.. _rt_tags:
+
+The Richtext Tags
+=================
+
+- :ref:`rt_tags_rt`
+- :ref:`rt_tags_div`
+- :ref:`rt_tags_br`
+- :ref:`rt_tags_space`
+- :ref:`rt_tags_vspace`
+- :ref:`rt_tags_p`
+- :ref:`rt_tags_font`
+- :ref:`rt_tags_img`
+
+For an introduction to our richtext system including a code example, see :ref:`wlrichtext`.
+
+*/
+
 /*
  * Class Parser
  */
 Parser::Parser() {
-	{  // rt tag
+	{
+		/* RST
+.. _rt_tags_rt:
+
+Rich Text -- <rt>
+-----------------
+
+The main wrapper that will signal to the font renderer to go into richtext mode.
+This tag surrounds your whole text, and is allowed only once.
+You can also set some options here what will affect your whole text.
+
+Attributes
+^^^^^^^^^^
+
+* **padding**: The rectangle of this tag is shrunk so leave a gap on its outside, on all four outer edges.
+* **padding_r**: Padding on the right-hand side
+* **padding_l**: Padding on the left-hand side
+* **padding_b**: Padding on the bottom
+* **padding_t**: Padding on the top
+
+* **background**: Give this tag's rectangle a background color as a hex value.
+
+* **keep_spaces**: Do now trim away trailing and double spaces. Use this where the user is editing text.
+* **db_show_spaces**: Highlight all blank spaces for debugging purposes.
+
+Sub-tags
+^^^^^^^^
+
+* :ref:`rt_tags_div`
+* :ref:`rt_tags_font`
+* :ref:`rt_tags_p`
+* :ref:`rt_tags_vspace`
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		TagConstraint tc;
 		tc.allowed_attrs.insert("padding");
 		tc.allowed_attrs.insert("padding_r");
@@ -194,30 +247,92 @@
 		tc.has_closing_tag = true;
 		tag_constraints_["rt"] = tc;
 	}
-	{  // br tag
+	{
+		/* RST
+.. _rt_tags_div:
+
+Division -- <div>
+-----------------
+
+This tag defines a rectangle and can be used as a layout control.
+
+Attributes
+^^^^^^^^^^
+
+The same attributes as :ref:`rt_tags_rt`, plus the following:
+
+* **margin**: Shrink all contents to leave a margin towards the outer edge of this tag's rectangle
+* **float**: To be implemented. Allowed values are ``left``,  ``right``
+* **valign**: Align the contents vertically. Allowed values are ``top`` (default), ``center`` or ``middle``, ``bottom``.
+* **width**: The width of this element, as a pixel amount, or as a percentage.
+  The last ``div`` in a row can be expanded automatically by using ``*``.
+
+Sub-tags
+^^^^^^^^
+
+* :ref:`rt_tags_div`
+* :ref:`rt_tags_font`
+* :ref:`rt_tags_p`
+* :ref:`rt_tags_vspace`
+
+:ref:`Return to tag index<rt_tags>`
+		*/
+		TagConstraint tc;
+		tc.allowed_attrs.insert("padding");
+		tc.allowed_attrs.insert("padding_r");
+		tc.allowed_attrs.insert("padding_l");
+		tc.allowed_attrs.insert("padding_b");
+		tc.allowed_attrs.insert("padding_t");
+		tc.allowed_attrs.insert("margin");
+		tc.allowed_attrs.insert("float");
+		tc.allowed_attrs.insert("valign");
+		tc.allowed_attrs.insert("background");
+		tc.allowed_attrs.insert("width");
+
+		tc.allowed_children.insert("p");
+		tc.allowed_children.insert("vspace");
+		tc.allowed_children.insert("font");
+		tc.allowed_children.insert("div");
+
+		tc.text_allowed = false;
+		tc.has_closing_tag = true;
+		tag_constraints_["div"] = tc;
+	}
+	{
+		/* RST
+.. _rt_tags_br:
+
+Line Break -- <br>
+------------------
+
+A single line break. Use sparingly for things like poetry stanzas.
+If you are starting a new paragraph, use :ref:`rt_tags_p` instead.
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		TagConstraint tc;
 		tc.text_allowed = false;
 		tc.has_closing_tag = false;
 		tag_constraints_["br"] = tc;
 	}
-	{  // img tag
-		TagConstraint tc;
-		tc.allowed_attrs.insert("src");
-		tc.allowed_attrs.insert("ref");
-		tc.allowed_attrs.insert("color");
-		tc.allowed_attrs.insert("width");
-		tc.text_allowed = false;
-		tc.has_closing_tag = false;
-		tag_constraints_["img"] = tc;
-	}
-	{  // vspace tag
-		TagConstraint tc;
-		tc.allowed_attrs.insert("gap");
-		tc.text_allowed = false;
-		tc.has_closing_tag = false;
-		tag_constraints_["vspace"] = tc;
-	}
-	{  // space tag
+	{
+		/* RST
+.. _rt_tags_space:
+
+Horizontal Space -- <space>
+---------------------------
+
+Inserts a horizontal gap between the previous and the following text.
+This space can be filled with a character of your choice.
+
+Attributes
+^^^^^^^^^^
+
+* **gap**: The size of the gap as a pixel amount
+* **fill**: A character to fill the gap with
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		TagConstraint tc;
 		tc.allowed_attrs.insert("gap");
 		tc.allowed_attrs.insert("fill");
@@ -225,29 +340,58 @@
 		tc.has_closing_tag = false;
 		tag_constraints_["space"] = tc;
 	}
-	{  // div tag
+	{
+		/* RST
+.. _rt_tags_vspace:
+
+Vertical Space -- <vspace>
+--------------------------
+
+Inserts a vertical gap between the previous and the following text.
+
+Attributes
+^^^^^^^^^^
+
+* **gap**: The size of the gap as a pixel amount
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		TagConstraint tc;
-		tc.allowed_attrs.insert("padding");
-		tc.allowed_attrs.insert("padding_r");
-		tc.allowed_attrs.insert("padding_l");
-		tc.allowed_attrs.insert("padding_b");
-		tc.allowed_attrs.insert("padding_t");
-		tc.allowed_attrs.insert("margin");
-		tc.allowed_attrs.insert("float");
-		tc.allowed_attrs.insert("valign");
-		tc.allowed_attrs.insert("background");
-		tc.allowed_attrs.insert("width");
-
-		tc.allowed_children.insert("p");
-		tc.allowed_children.insert("vspace");
-		tc.allowed_children.insert("font");
-		tc.allowed_children.insert("div");
-
+		tc.allowed_attrs.insert("gap");
 		tc.text_allowed = false;
-		tc.has_closing_tag = true;
-		tag_constraints_["div"] = tc;
+		tc.has_closing_tag = false;
+		tag_constraints_["vspace"] = tc;
 	}
-	{  // p tag
+	{
+		/* RST
+.. _rt_tags_p:
+
+Paragraph -- <p>
+----------------
+
+This tag encloses a text paragraph.
+
+Attributes
+^^^^^^^^^^
+
+* **indent**: Adds an indent to the first line of the paragraph
+* **align**: The horizontal alignment for the paragraph's text.
+  Allowed values are ``left`` (default), ``center`` or ``middle``, ``right``.
+* **valign**: See :ref:`rt_tags_div`
+* **spacing**: Vertical line spacing as a pixel value
+
+Sub-tags
+^^^^^^^^
+
+* :ref:`rt_tags_br`
+* :ref:`rt_tags_div`
+* :ref:`rt_tags_font`
+* :ref:`rt_tags_img`
+* :ref:`rt_tags_space`
+* :ref:`rt_tags_vspace`
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		TagConstraint tc;
 		tc.allowed_attrs.insert("indent");
 		tc.allowed_attrs.insert("align");
@@ -264,7 +408,40 @@
 		tc.has_closing_tag = true;
 		tag_constraints_["p"] = tc;
 	}
-	{  // font tag
+	{
+		/* RST
+.. _rt_tags_font:
+
+Font -- <font>
+--------------
+
+This tag defines the font style for the enclosed text.
+
+Attributes
+^^^^^^^^^^
+
+* **size**: The font size as a pixel value
+* **face**: The font face. Allowed values are ``sans`` (default), ``serif``  and ``condensed``.
+* **color**: The font color as a hex value
+* **bold**: Make the text bold
+* **italic**: Make the text italic
+* **underline**: Underline the text
+* **shadow**: Add a background shadow
+* **ref**: To be implemented
+
+Sub-tags
+^^^^^^^^
+
+* :ref:`rt_tags_br`
+* :ref:`rt_tags_div`
+* :ref:`rt_tags_font`
+* :ref:`rt_tags_img`
+* :ref:`rt_tags_p`
+* :ref:`rt_tags_space`
+* :ref:`rt_tags_vspace`
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		TagConstraint tc;
 		tc.allowed_attrs.insert("size");
 		tc.allowed_attrs.insert("face");
@@ -286,6 +463,34 @@
 		tc.has_closing_tag = true;
 		tag_constraints_["font"] = tc;
 	}
+	{
+		/* RST
+.. _rt_tags_img:
+
+Image -- <img>
+--------------
+
+Displays an image with your text.
+
+Attributes
+^^^^^^^^^^
+
+* **src**: The path to the image, relative to the ``data`` directory.
+* **ref**: To be implemented
+* **color**: Player color for the image as a hex value
+* **width**: Width of the image as a pixel amount. The corresponding height will be matched automatically.
+
+:ref:`Return to tag index<rt_tags>`
+		*/
+		TagConstraint tc;
+		tc.allowed_attrs.insert("src");
+		tc.allowed_attrs.insert("ref");
+		tc.allowed_attrs.insert("color");
+		tc.allowed_attrs.insert("width");
+		tc.text_allowed = false;
+		tc.has_closing_tag = false;
+		tag_constraints_["img"] = tc;
+	}
 }
 
 Parser::~Parser() {