format_help.lua
-------------------------------------

Functions used in the ingame help windows for formatting the text and pictures.

.. function:: image_line(image, count[, text = nil])

   Aligns the image to a row on the right side with text on the left.

   :arg image: the picture to be aligned to a row.
   :arg count: length of the picture row.
   :arg text: if given the text aligned on the left side, formatted via richtext.lua functions.
   :returns: the text on the left and a picture row on the right.


.. function:: plot_size_line(size, size_only)

   Creates a line describing space required on the map.
   Consists of a header colored text, followed by normal text and an image.

   :arg size: size key. Expected values are "mine", "port", "small, "medium", "big", "none".
   :arg size_only: size_only key. Optional bool value if size is a space requirement as well.
   :returns: header followed by normal text and image if a space is required, or empty string.


.. function:: dependencies(items[, text = nil])

   Creates a dependencies line of any length.

   :arg items: ware, worker and/or building descriptions in the correct order
               from left to right as table (set in {}).
   :arg text: comment of the image.
   :returns: a row of pictures connected by arrows.


.. function:: help_ware_amount_line(ware_description, amount)

   Displays an amount of wares with name and images

   :arg ware_description: The :class:`wl.map.WareDescription` for the ware type to be displayed
   :arg amount: The amount to show as a number
   :returns: image_line for the ware type and amount


.. function:: help_worker_experience(worker_description, becomes_description)

   Displays needed experience levels for workers

   :arg worker_description: The :class:`wl.map.WorkerDescription` for the lower-level worker
   :arg becomes_description: The :class:`wl.map.WorkerDescription` for the higher-level worker
   :returns: text describing the needed experience


.. function:: help_tool_string(tribe, toolname, no_of_workers)

   Displays tools with an intro text and images

   :arg tribe: The :class:`wl.map.TribeDescription` for the tribe that uses the tools
   :arg toolnames: e.g. {"shovel", "basket"}.
   :arg no_of_workers: the number of workers using the tools; for plural formatting.
   :returns: image_line for the tools


.. function:: help_consumed_wares_workers(tribe, building, program_name)

   Returns information for which wares and workers in which amounts are consumed by a production program.

   :arg tribe: The :class:`wl.map.TribeDescription` for the tribe that consumes the ware
   :arg building: The :class:`wl.map.BuildingDescription` for the building that runs the program
   :arg program_name: The name of the production program that the info is collected for

   :returns: A "Ware(s) consumed:" section with image_lines