widelands-dev team mailing list archive

[kaputtnik <somal@xxxxxxxx>]

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.

Diff comments:

> 
> === modified file 'data/scripting/richtext.lua'
> --- data/scripting/richtext.lua	2018-02-12 10:17:22 +0000
> +++ data/scripting/richtext.lua	2018-02-22 07:28:23 +0000
> @@ -8,53 +11,30 @@
>  -- Most of these functions are simple wrapper functions that make working with
>  -- widelands rich text formatting system more bearable.

Add the link to the widelands richtext system form below to the above?

>From my understanding you can give a link also another title using syntax: :ref:`Link title <wlrichtext>`

>  -- Function names generally follow HTML names.
> +-- We strongly recommend that you make use of these functions rather than hacking
> +-- the tags manually.
> +-- See also :ref:`wlrichtext` for an introduction to the richtext system and a code example.

A reader should not 'See also' if it is not recommended. Move the link to above and omit the sentence?

> +-- 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`_
>  
>  
>  -- 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.


-- 
https://code.launchpad.net/~widelands-dev/widelands/fh1-documentation/+merge/337545
Your team Widelands Developers is subscribed to branch lp:~widelands-dev/widelands/fh1-documentation.