Classes
class	help_manager
	The help implementation caches data parsed from the game_config. More...

class	topic_generator
	Generate a topic text on the fly. More...

class	text_topic_generator

class	topic_text
	The text displayed in a topic. More...

struct	topic
	A topic contains a title, an id and some text. More...

struct	section
	A section contains topics and sections along with title and ID. More...

class	has_id
	To be used as a function object to locate sections and topics with a specified ID. More...

class	title_less
	To be used as a function object when sorting topic lists on the title. More...

class	section_less
	To be used as a function object when sorting section lists on the title. More...

class	string_less

struct	parse_error
	Thrown when the help system fails to parse something. More...

struct	terrain_movement_info

class	terrain_topic_generator

class	unit_topic_generator

Typedefs
typedef std::list< section >	section_list

typedef std::list< topic >	topic_list

typedef std::pair< std::string, std::string >	trait_data

Enumerations
enum	UNIT_DESCRIPTION_TYPE { FULL_DESCRIPTION , NO_DESCRIPTION , HIDDEN_BUT_SHOW_MACROS }

Functions
std::string	get_unit_type_help_id (const unit_type &t)
	Given a unit type, find the corresponding help topic's id. More...

void	show_unit_description (const unit &u)

void	show_unit_description (const unit_type &t)

void	show_terrain_description (const terrain_type &t)

static void	show_with_toplevel (const section &toplevel_sec, const std::string &show_topic)

void	show_help (const std::string &show_topic="")
	Open the help browser. More...

bool	section_is_referenced (const std::string &section_id, const config &cfg)
	Return true if the section with id section_id is referenced from another section in the config, or the toplevel. More...

bool	topic_is_referenced (const std::string &topic_id, const config &cfg)
	Return true if the topic with id topic_id is referenced from another section in the config, or the toplevel. More...

section	parse_config_internal (const config &help_cfg, const config &section_cfg, int level=0)
	Recursive function used by parse_config. More...

section	parse_config (const config &cfg)
	Parse a help config, return the top level section. More...

std::vector< topic >	generate_topics (const bool sort_generated, const std::string &generator)

void	generate_sections (const config &help_cfg, const std::string &generator, section &sec, int level)
	Dispatch generators to their appropriate functions. More...

std::string	generate_topic_text (const std::string &generator, const config &help_cfg, const section &sec)

static std::string	time_of_day_bonus_colored (const int time_of_day_bonus)

std::vector< topic >	generate_time_of_day_topics (const bool)

std::vector< topic >	generate_weapon_special_topics (const bool sort_generated)

std::vector< topic >	generate_ability_topics (const bool sort_generated)

std::vector< topic >	generate_era_topics (const bool sort_generated, const std::string &era_id)

std::vector< topic >	generate_faction_topics (const config &era, const bool sort_generated)

std::vector< topic >	generate_trait_topics (const bool sort_generated)

std::string	make_unit_link (const std::string &type_id)
	return a hyperlink with the unit's name and pointing to the unit page return empty string if this unit is hidden. More...

std::vector< std::string >	make_unit_links_list (const std::vector< std::string > &type_id_list, bool ordered=false)
	return a list of hyperlinks to unit's pages (ordered or not) More...

void	generate_races_sections (const config &help_cfg, section &sec, int level)

void	generate_era_sections (const config &help_cfg, section &sec, int level)

void	generate_terrain_sections (section &sec, int)

void	generate_unit_sections (const config &, section &sec, int, const bool, const std::string &race)

std::vector< topic >	generate_unit_topics (const bool sort_generated, const std::string &race)

UNIT_DESCRIPTION_TYPE	description_type (const unit_type &type)
	Return the type of description that should be shown for a unit of the given kind. More...

std::string	generate_contents_links (const std::string &section_name, const config &help_cfg)

std::string	generate_contents_links (const section &sec)

const topic *	find_topic (const section &sec, const std::string &id)
	Search for the topic with the specified identifier in the section and its subsections. More...

const section *	find_section (const section &sec, const std::string &id)
	Search for the section with the specified identifier in the section and its subsections. More...

section *	find_section (section &sec, const std::string &id)

std::pair< section, section >	generate_contents ()
	Generate the help contents from the configurations given to the manager. More...

std::string	hidden_symbol (bool hidden)

bool	is_visible_id (const std::string &id)

bool	is_valid_id (const std::string &id)
	Return true if the id is valid for user defined topics and sections. More...

static void	print_trait_list (std::stringstream &ss, const std::vector< trait_data > &l)

Variables
const int	max_section_level = 15

const std::string	default_show_topic = "..introduction"

const std::string	unknown_unit_topic = ".unknown_unit"

const std::string	unit_prefix = "unit_"

const std::string	terrain_prefix = "terrain_"

const std::string	race_prefix = "race_"

const std::string	faction_prefix = "faction_"

const std::string	era_prefix = "era_"

const std::string	variation_prefix = "variation_"

const std::string	ability_prefix = "ability_"

Typedef Documentation

◆ section_list

typedef std::list<section> help::section_list

Definition at line 106 of file help_impl.hpp.

◆ topic_list

typedef std::list<topic> help::topic_list

Definition at line 107 of file help_impl.hpp.

◆ trait_data

typedef std::pair<std::string, std::string> help::trait_data

Definition at line 338 of file help_topic_generators.cpp.

Enumeration Type Documentation

◆ UNIT_DESCRIPTION_TYPE

enum help::UNIT_DESCRIPTION_TYPE

Enumerator

FULL_DESCRIPTION

NO_DESCRIPTION

Ignore this unit for documentation purposes.

HIDDEN_BUT_SHOW_MACROS

Although the unit itself is hidden, traits reachable via this unit are not hidden.

This is a bug workaround - traits are defined by WML macros, and therefore the help system has to use a place where that macro is instanciated to provide the documentation. None of the normal unit types has the "loyal" trait, but there is a hidden unit which does, purely to support the help system.

Definition at line 199 of file help_impl.hpp.

Function Documentation

◆ description_type()

UNIT_DESCRIPTION_TYPE help::description_type ( const unit_type & type )

Return the type of description that should be shown for a unit of the given kind.

This method is intended to filter out information about units that should not be shown, for example due to not being encountered.

Definition at line 1076 of file help_impl.cpp.

References game_config::debug, prefs::encountered_units(), FULL_DESCRIPTION, prefs::get(), HIDDEN_BUT_SHOW_MACROS, hotkey::is_scope_active(), NO_DESCRIPTION, and hotkey::SCOPE_EDITOR.

Referenced by generate_ability_topics(), generate_races_sections(), generate_trait_topics(), generate_unit_topics(), generate_weapon_special_topics(), make_unit_link(), and help::unit_topic_generator::operator()().

◆ find_section() [1/2]

const section * help::find_section	(	const section &	sec,
		const std::string &	id
	)

Search for the section with the specified identifier in the section and its subsections.

Return the found section or nullptr if none could be found.

Definition at line 1204 of file help_impl.cpp.

References utils::find_if(), s, and help::section::sections.

Referenced by find_section(), generate_contents(), and generate_races_sections().

◆ find_section() [2/2]

section * help::find_section	(	section &	sec,
		const std::string &	id
	)

Definition at line 1220 of file help_impl.cpp.

References find_section().

◆ find_topic()

const topic * help::find_topic	(	const section &	sec,
		const std::string &	id
	)

Search for the topic with the specified identifier in the section and its subsections.

Return the found topic, or nullptr if none could be found.

Definition at line 1188 of file help_impl.cpp.

References utils::find_if(), s, help::section::sections, t, and help::section::topics.

Referenced by generate_contents(), and gui2::dialogs::help_browser::show_topic().

◆ generate_ability_topics()

std::vector< topic > help::generate_ability_topics ( const bool sort_generated )

Definition at line 444 of file help_impl.cpp.

References _(), ability_prefix, description_type(), FULL_DESCRIPTION, markup::make_link(), markup::tag(), unit_type_data::types(), font::unicode_bullet, unit_prefix, and unit_types.

Referenced by generate_topics().

◆ generate_contents()

std::pair< section, section > help::generate_contents ( )

Generate the help contents from the configurations given to the manager.

Returns: A pair consisting of the toplevel section and any hidden sections.

Definition at line 1225 of file help_impl.cpp.

References config::add_child(), game_config_view::child_or_empty(), config::child_range(), config::clear_children(), find_section(), find_topic(), game_config_manager::game_config(), game_config_manager::get(), utils::join(), parse_config(), section_is_referenced(), and topic_is_referenced().

Referenced by help::help_manager::implementation::regenerate().

◆ generate_contents_links() [1/2]

std::string help::generate_contents_links ( const section & sec )

Definition at line 1132 of file help_impl.cpp.

References is_visible_id(), markup::make_link(), s, help::section::sections, t, help::section::topics, and font::unicode_bullet.

◆ generate_contents_links() [2/2]

std::string help::generate_contents_links	(	const std::string &	section_name,
		const config &	help_cfg
	)

Definition at line 1096 of file help_impl.cpp.

References config::find_child(), is_visible_id(), markup::make_link(), utils::quoted_split(), and font::unicode_bullet.

Referenced by generate_topic_text().

◆ generate_era_sections()

void help::generate_era_sections	(	const config &	help_cfg,
		section &	sec,
		int	level
	)

Definition at line 830 of file help_impl.cpp.

References help::section::add_section(), DBG_HP, config::debug(), era_prefix, game_config_manager::get(), game_config::images::level, and parse_config_internal().

Referenced by generate_sections().

◆ generate_era_topics()

std::vector< topic > help::generate_era_topics	(	const bool	sort_generated,
		const std::string &	era_id
	)

Definition at line 503 of file help_impl.cpp.

References _(), config_attribute_value::empty(), era_prefix, game_config_view::find_child(), game_config_manager::game_config(), generate_faction_topics(), game_config_manager::get(), markup::make_link(), t, config_attribute_value::t_str(), markup::tag(), and font::unicode_bullet.

Referenced by generate_topics().

◆ generate_faction_topics()

std::vector< topic > help::generate_faction_topics	(	const config &	era,
		const bool	sort_generated
	)

Definition at line 535 of file help_impl.cpp.

References _(), config::child_range(), config_attribute_value::empty(), f, faction_prefix, unit_type_data::find(), unit_type_data::find_race(), unit_type::HELP_INDEXED, id, markup::make_link(), make_unit_links_list(), race_prefix, utils::split(), t, config_attribute_value::t_str(), markup::tag(), font::unicode_bullet, and unit_types.

Referenced by generate_era_topics().

◆ generate_races_sections()

void help::generate_races_sections	(	const config &	help_cfg,
		section &	sec,
		int	level
	)

Definition at line 733 of file help_impl.cpp.

References _(), help::section::add_section(), description_type(), unit_type_data::find_race(), find_section(), FULL_DESCRIPTION, hidden_symbol(), i, game_config::images::level, parse_config_internal(), race_prefix, unit_type_data::types(), and unit_types.

Referenced by generate_sections().

◆ generate_sections()

void help::generate_sections	(	const config &	help_cfg,
		const std::string &	generator,
		section &	sec,
		int	level
	)

Dispatch generators to their appropriate functions.

Definition at line 243 of file help_impl.cpp.

References DBG_HP, generate_era_sections(), generate_races_sections(), generate_terrain_sections(), generate_unit_sections(), randomness::generator, game_config::images::level, utils::split(), utils::STRIP_SPACES, and WRN_HP.

Referenced by parse_config_internal().

◆ generate_terrain_sections()

void help::generate_terrain_sections	(	section &	sec,
		int
	)

Definition at line 850 of file help_impl.cpp.

References help::section::add_section(), utils::contains(), terrain_type::editor_name(), utils::find(), prefs::get(), terrain_type_data::get(), hidden_symbol(), terrain_type::hide_help(), help::section::id, terrain_type::id(), lg::info(), terrain_type::is_nonnull(), s, t, terrain_prefix, help::section::title, help::section::topics, and WRN_HP.

Referenced by generate_sections().

◆ generate_time_of_day_topics()

std::vector< topic > help::generate_time_of_day_topics ( const bool )

Definition at line 295 of file help_impl.cpp.

References _(), generic_combat_modifier(), tod_manager::get_max_liminal_bonus(), markup::img(), markup::make_link(), markup::tag(), time_of_day_bonus_colored(), tod_manager::times(), and resources::tod_manager.

Referenced by generate_topics().

◆ generate_topic_text()

std::string help::generate_topic_text	(	const std::string &	generator,
		const config &	help_cfg,
		const section &	sec
	)

Definition at line 262 of file help_impl.cpp.

References generate_contents_links(), randomness::generator, and utils::split().

Referenced by parse_config_internal().

◆ generate_topics()

std::vector< topic > help::generate_topics	(	const bool	sort_generated,
		const std::string &	generator
	)

Definition at line 214 of file help_impl.cpp.

References generate_ability_topics(), generate_era_topics(), generate_time_of_day_topics(), generate_trait_topics(), generate_unit_topics(), generate_weapon_special_topics(), randomness::generator, utils::split(), utils::STRIP_SPACES, and WRN_HP.

Referenced by parse_config_internal().

◆ generate_trait_topics()

std::vector< topic > help::generate_trait_topics ( const bool sort_generated )

Definition at line 610 of file help_impl.cpp.

References _(), description_type(), unit_type_data::find_race(), FULL_DESCRIPTION, HIDDEN_BUT_SHOW_MACROS, i, unit_type_data::traits(), unit_type_data::types(), and unit_types.

Referenced by generate_topics().

◆ generate_unit_sections()

void help::generate_unit_sections	(	const config &	,
		section &	sec,
		int	,
		const bool	,
		const std::string &	race
	)

Definition at line 916 of file help_impl.cpp.

References help::section::add_section(), hidden_symbol(), unit_type::hide_help(), i, help::section::id, unit_type::id(), help::section::title, help::section::topics, unit_type_data::types(), unit_prefix, unit_types, unit_type::variation_name(), and variation_prefix.

Referenced by generate_sections().

◆ generate_unit_topics()

std::vector< topic > help::generate_unit_topics	(	const bool	sort_generated,
		const std::string &	race
	)

Definition at line 947 of file help_impl.cpp.

References _(), game_config::debug, description_type(), unit_type_data::find_race(), FULL_DESCRIPTION, hidden_symbol(), i, markup::make_link(), unit_type_data::races(), markup::tag(), unit_type_data::types(), font::unicode_bullet, unit_prefix, unit_types, and VGETTEXT.

Referenced by generate_topics().

◆ generate_weapon_special_topics()

std::vector< topic > help::generate_weapon_special_topics ( const bool sort_generated )

Definition at line 345 of file help_impl.cpp.

References _(), config::child_range(), description_type(), FULL_DESCRIPTION, unit_ability_t::get_help_topic_id(), unit_ability_t::tooltip_info::help_topic_id, markup::make_link(), markup::tag(), unit_type_data::types(), font::unicode_bullet, unit_prefix, and unit_types.

Referenced by generate_topics().

◆ get_unit_type_help_id()

std::string help::get_unit_type_help_id ( const unit_type & t )

Given a unit type, find the corresponding help topic's id.

Definition at line 37 of file help.cpp.

References unit_type_data::find(), hidden_symbol(), unit_type::hide_help(), t, unit_prefix, unit_types, and variation_prefix.

Referenced by show_unit_description(), and unit_type().

◆ hidden_symbol()

std::string help::hidden_symbol ( bool hidden )

Definition at line 1280 of file help_impl.cpp.

Referenced by generate_races_sections(), generate_terrain_sections(), generate_unit_sections(), generate_unit_topics(), get_unit_type_help_id(), is_valid_id(), and show_terrain_description().

◆ is_valid_id()

bool help::is_valid_id ( const std::string & id )

Return true if the id is valid for user defined topics and sections.

Some IDs are special, such as toplevel and may not be be defined in the config.

Definition at line 1293 of file help_impl.cpp.

References translation::compare(), hidden_symbol(), and unit_prefix.

Referenced by parse_config_internal().

◆ is_visible_id()

bool help::is_visible_id ( const std::string & id )

Definition at line 1284 of file help_impl.cpp.

Referenced by generate_contents_links().

◆ make_unit_link()

std::string help::make_unit_link ( const std::string & type_id )

return a hyperlink with the unit's name and pointing to the unit page return empty string if this unit is hidden.

If not yet discovered add the (?) suffix

Definition at line 692 of file help_impl.cpp.

References description_type(), unit_type_data::find(), FULL_DESCRIPTION, unit_type::HELP_INDEXED, markup::make_link(), PLAIN_LOG, unit_prefix, unit_types, and unknown_unit_topic.

Referenced by make_unit_links_list().

◆ make_unit_links_list()

std::vector< std::string > help::make_unit_links_list	(	const std::vector< std::string > &	type_id_list,
		bool	ordered
	)

return a list of hyperlinks to unit's pages (ordered or not)

Definition at line 718 of file help_impl.cpp.

References make_unit_link().

Referenced by generate_faction_topics().

◆ parse_config()

section help::parse_config ( const config & cfg )

Parse a help config, return the top level section.

Return an empty section if cfg is nullptr.

Definition at line 205 of file help_impl.cpp.

References cfg, config::optional_child(), and parse_config_internal().

Referenced by generate_contents().

◆ parse_config_internal()

section help::parse_config_internal	(	const config &	help_cfg,
		const config &	section_cfg,
		int	level
	)

Recursive function used by parse_config.

Definition at line 107 of file help_impl.cpp.

References help::section::add_section(), config::find_child(), generate_sections(), generate_topic_text(), generate_topics(), id, help::topic::id, help::section::id, is_valid_id(), game_config::images::level, max_section_level, PLAIN_LOG, utils::quoted_split(), help::section::sections, help::section::title, and help::section::topics.

Referenced by generate_era_sections(), generate_races_sections(), and parse_config().

◆ print_trait_list()

static void help::print_trait_list	(	std::stringstream &	ss,
		const std::vector< trait_data > &	l
	)

static

Definition at line 341 of file help_topic_generators.cpp.

References i, and markup::make_link().

Referenced by help::unit_topic_generator::operator()().

◆ section_is_referenced()

bool help::section_is_referenced	(	const std::string &	section_id,
		const config &	cfg
	)

Return true if the section with id section_id is referenced from another section in the config, or the toplevel.

Definition at line 71 of file help_impl.cpp.

References cfg, config::child_range(), utils::contains(), config::optional_child(), and utils::quoted_split().

Referenced by generate_contents().

◆ show_help()

void help::show_help ( const std::string & show_topic = "" )

Open the help browser.

The help browser will have the topic with id show_topic open if it is not the empty string. The default topic will be shown if show_topic is the empty string.

Definition at line 83 of file help.cpp.

References help::help_manager::get_instance(), and show_with_toplevel().

Referenced by tooltips::click(), hotkey::command_executor::do_execute_command(), gui2::dialogs::addon_connect::help_button_callback(), gui2::dialogs::title_screen::init_callbacks(), gui2::dialogs::addon_manager::show_help(), gui2::dialogs::unit_advance::show_help(), events::menu_handler::show_help(), gui2::dialogs::units_dialog::show_help(), editor::editor_controller::show_help(), lua_gui2::show_help(), gui2::dialogs::game_version::show_license(), show_terrain_description(), show_unit_description(), and editor::editor_controller::unit_description().

◆ show_terrain_description()

void help::show_terrain_description ( const terrain_type & t )

Definition at line 73 of file help.cpp.

References hidden_symbol(), show_help(), t, and terrain_prefix.

Referenced by editor::editor_controller::terrain_description(), and events::menu_handler::terrain_description().

◆ show_unit_description() [1/2]

void help::show_unit_description ( const unit & u )

Definition at line 63 of file help.cpp.

References unit::type().

Referenced by gui2::dialogs::faction_select::profile_button_callback(), gui2::unit_preview_pane::profile_button_callback(), events::menu_handler::unit_description(), and editor::editor_controller::unit_description().

◆ show_unit_description() [2/2]

void help::show_unit_description ( const unit_type & t )

Definition at line 68 of file help.cpp.

References get_unit_type_help_id(), show_help(), and t.

◆ show_with_toplevel()

static void help::show_with_toplevel	(	const section &	toplevel_sec,
		const std::string &	show_topic
	)

static

Definition at line 78 of file help.cpp.

Referenced by show_help().

◆ time_of_day_bonus_colored()

static std::string help::time_of_day_bonus_colored ( const int time_of_day_bonus )

static

Definition at line 290 of file help_impl.cpp.

References markup::span_color().

Referenced by generate_time_of_day_topics().

◆ topic_is_referenced()

bool help::topic_is_referenced	(	const std::string &	topic_id,
		const config &	cfg
	)

Return true if the topic with id topic_id is referenced from another section in the config, or the toplevel.

Definition at line 89 of file help_impl.cpp.

References cfg, config::child_range(), utils::contains(), config::optional_child(), and utils::quoted_split().

Referenced by generate_contents().

Variable Documentation

◆ ability_prefix

const std::string help::ability_prefix = "ability_"

Definition at line 69 of file help_impl.cpp.

Referenced by generate_ability_topics(), and help::unit_topic_generator::operator()().

◆ default_show_topic

const std::string help::default_show_topic = "..introduction"

Definition at line 61 of file help_impl.cpp.

◆ era_prefix

const std::string help::era_prefix = "era_"

Definition at line 67 of file help_impl.cpp.

Referenced by generate_era_sections(), and generate_era_topics().

◆ faction_prefix

const std::string help::faction_prefix = "faction_"

Definition at line 66 of file help_impl.cpp.

Referenced by generate_faction_topics().

◆ max_section_level

const int help::max_section_level = 15

Definition at line 59 of file help_impl.cpp.

Referenced by parse_config_internal().

◆ race_prefix

const std::string help::race_prefix = "race_"

Definition at line 65 of file help_impl.cpp.

Referenced by generate_faction_topics(), and generate_races_sections().

◆ terrain_prefix

const std::string help::terrain_prefix = "terrain_"

Definition at line 64 of file help_impl.cpp.

Referenced by generate_terrain_sections(), help::terrain_topic_generator::operator()(), and show_terrain_description().

◆ unit_prefix

const std::string help::unit_prefix = "unit_"

Definition at line 63 of file help_impl.cpp.

Referenced by generate_ability_topics(), generate_unit_sections(), generate_unit_topics(), generate_weapon_special_topics(), get_unit_type_help_id(), is_valid_id(), make_unit_link(), and help::unit_topic_generator::operator()().

◆ unknown_unit_topic

const std::string help::unknown_unit_topic = ".unknown_unit"

Definition at line 62 of file help_impl.cpp.

Referenced by make_unit_link(), and help::unit_topic_generator::operator()().

◆ variation_prefix

const std::string help::variation_prefix = "variation_"

Definition at line 68 of file help_impl.cpp.

Referenced by generate_unit_sections(), get_unit_type_help_id(), and help::unit_topic_generator::operator()().

Classes

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ section_list

◆ topic_list

◆ trait_data

Enumeration Type Documentation

◆ UNIT_DESCRIPTION_TYPE

Function Documentation

◆ description_type()

◆ find_section() [1/2]

◆ find_section() [2/2]

◆ find_topic()

◆ generate_ability_topics()

◆ generate_contents()

◆ generate_contents_links() [1/2]

◆ generate_contents_links() [2/2]

◆ generate_era_sections()

◆ generate_era_topics()

◆ generate_faction_topics()

◆ generate_races_sections()

◆ generate_sections()

◆ generate_terrain_sections()

◆ generate_time_of_day_topics()

◆ generate_topic_text()

◆ generate_topics()

◆ generate_trait_topics()

◆ generate_unit_sections()

◆ generate_unit_topics()

◆ generate_weapon_special_topics()

◆ get_unit_type_help_id()

◆ hidden_symbol()

◆ is_valid_id()

◆ is_visible_id()

◆ make_unit_link()

◆ make_unit_links_list()

◆ parse_config()

◆ parse_config_internal()

◆ print_trait_list()

◆ section_is_referenced()

◆ show_help()

◆ show_terrain_description()

◆ show_unit_description() [1/2]

◆ show_unit_description() [2/2]

◆ show_with_toplevel()

◆ time_of_day_bonus_colored()

◆ topic_is_referenced()

Variable Documentation

◆ ability_prefix

◆ default_show_topic

◆ era_prefix

◆ faction_prefix

◆ max_section_level

◆ race_prefix

◆ terrain_prefix

◆ unit_prefix

◆ unknown_unit_topic

◆ variation_prefix