widelands-dev team mailing list archive

[GunChleoc <fios@xxxxxxxxxxxxxxxxxxx>]

GunChleoc has proposed merging lp:~widelands-dev/widelands/fh1-documentation into lp:widelands.

Commit message:
Updated documentation for new font renderer

Requested reviews:
  Widelands Developers (widelands-dev)

For more details, see:
https://code.launchpad.net/~widelands-dev/widelands/fh1-documentation/+merge/337545
-- 
Your team Widelands Developers is requested to review the proposed merge of lp:~widelands-dev/widelands/fh1-documentation into lp:widelands.

=== modified file 'data/scripting/messages.lua'
--- data/scripting/messages.lua	2017-12-09 06:29:26 +0000
+++ data/scripting/messages.lua	2018-02-12 10:29:06 +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-01-16 19:46:20 +0000
+++ data/scripting/richtext.lua	2018-02-12 10:29:06 +0000
@@ -12,7 +12,6 @@
 
 -- RST
 -- .. function:: localize_list(items, listtype, former_textdomain)
---    :noindex:
 --
 --    Turns an array of string items into a localized string list with
 --    appropriate concatenation.
@@ -54,7 +53,6 @@
 
 -- 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.
@@ -85,7 +83,6 @@
 
 -- RST
 -- .. function:: img(src[, attributes = nil])
---    :noindex:
 --
 --    Turns an image src path into an image tag for richtext.
 --
@@ -116,7 +113,6 @@
 
 -- 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.
@@ -132,7 +128,6 @@
 
 -- RST
 -- .. function:: h2(text)
---    :noindex:
 --
 --    Like :func:`h1` but smaller.
 --
@@ -143,7 +138,6 @@
 
 -- RST
 -- .. function:: h3(text)
---    :noindex:
 --
 --    Like :func:`h2` but smaller.
 --
@@ -155,7 +149,6 @@
 
 -- RST
 -- .. function:: h4(text)
---    :noindex:
 --
 --    Like :func:`h3` but smaller.
 --
@@ -167,7 +160,6 @@
 
 -- 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`.
@@ -283,7 +275,6 @@
 
 -- RST
 -- .. function:: dl(dt, dd)
---    :noindex:
 --
 -- This function imitates a HTML description list
 --    :arg dt: "description term", will be rendered in bold.
@@ -349,7 +340,6 @@
 
 -- RST
 -- .. function:: a(link)
---    :noindex:
 --
 -- 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
@@ -362,7 +352,6 @@
 
 -- RST
 -- .. function:: b(link)
---    :noindex:
 --
 -- This makes the text bold.
 --    :arg link: the text to format
@@ -375,7 +364,6 @@
 
 -- RST
 -- .. function:: i(link)
---    :noindex:
 --
 -- This makes the text italic.
 --    :arg link: the text to format

=== 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-12 10:29:06 +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'),

=== modified file 'doc/sphinx/source/lua_index.rst'
--- doc/sphinx/source/lua_index.rst	2012-06-20 09:07:10 +0000
+++ doc/sphinx/source/lua_index.rst	2018-02-12 10:29:06 +0000
@@ -10,5 +10,6 @@
    tutorial
    reference
    roadmap
+   autogen_rt_tags
    wlrichtext
    implementation

=== 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-12 10:29:06 +0000
@@ -171,11 +171,71 @@
 	}
 }
 
+/* RST
+.. _rt_tags:
+
+The Richtext Tags
+=================
+
+- :ref:`rt_tags_br`
+- :ref:`rt_tags_div`
+- :ref:`rt_tags_font`
+- :ref:`rt_tags_img`
+- :ref:`rt_tags_p`
+- :ref:`rt_tags_rt`
+- :ref:`rt_tags_space`
+- :ref:`rt_tags_vspace`
+
+*/
+
 /*
  * 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
+"""""""
+
+* **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 color
+""""""""""""""""
+
+* **background**: Give this tag's rectangle a background color as a hex value.
+
+Global Formatting Controls
+""""""""""""""""""""""""""
+
+* **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.
+
+Subtags
+^^^^^^^
+
+* :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,13 +254,57 @@
 		tc.has_closing_tag = true;
 		tag_constraints_["rt"] = tc;
 	}
-	{  // br tag
+	{
+		/* 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.
+
+Attributes
+^^^^^^^^^^
+
+None
+
+Subtags
+^^^^^^^
+
+None
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		TagConstraint tc;
 		tc.text_allowed = false;
 		tc.has_closing_tag = false;
 		tag_constraints_["br"] = tc;
 	}
-	{  // img tag
+	{
+		/* 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**: Playercolor for the image as a hex value
+* **width**: Width of the image as a pixel amount. The corresponding height will be matched automatically.
+
+Subtags
+^^^^^^^
+
+None
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		TagConstraint tc;
 		tc.allowed_attrs.insert("src");
 		tc.allowed_attrs.insert("ref");
@@ -210,14 +314,56 @@
 		tc.has_closing_tag = false;
 		tag_constraints_["img"] = tc;
 	}
-	{  // vspace 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
+
+Subtags
+^^^^^^^
+
+None
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		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
+
+Subtags
+^^^^^^^
+
+None
+
+:ref:`Return to tag index<rt_tags>`
+		*/
 		TagConstraint tc;
 		tc.allowed_attrs.insert("gap");
 		tc.allowed_attrs.insert("fill");
@@ -225,7 +371,47 @@
 		tc.has_closing_tag = false;
 		tag_constraints_["space"] = tc;
 	}
-	{  // div tag
+	{
+		/* RST
+.. _rt_tags_div:
+
+Division -- <div>
+-----------------
+
+This tag defines a rectangle and an be used as a layouting control.
+
+Attributes
+^^^^^^^^^^
+
+Padding
+"""""""
+
+See :ref:`rt_tags_rt`
+
+Background color
+""""""""""""""""
+
+See :ref:`rt_tags_rt`
+
+Margins and placement
+"""""""""""""""""""""
+
+* **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`` = ``middle``, ``bottom``.
+* **width**: The width of this element, as a pixel amount, or as a precentage.
+  The last ``div`` in a row can be expanded automatically by using ``*``.
+
+Subtags
+^^^^^^^
+
+* :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");
@@ -247,7 +433,36 @@
 		tc.has_closing_tag = true;
 		tag_constraints_["div"] = 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`` = ``middle``, ``right``.
+* **valign**: See :ref:`rt_tags_div`
+* **spacing**: Vertical line spacing as a pixel value
+
+Subtags
+^^^^^^^
+
+* :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 +479,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
+
+Subtags
+^^^^^^^
+
+* :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");