Re-enable the editor help, and use it to document the keyboard modifiers

... with the idea that these pages will either be improved or hidden again
before 1.16.0. I think the terrain-editor part will be good enough to stay in
1.16, but the scenario editor part needs to be updated by someone familiar with
it.

This puts the two tips that are currently in https://wiki.wesnoth.org/MapEditor
in to the in-game text.

data/core/editor/help.cfg

@@ -3,71 +3,126 @@
 [section]
     id=editor
     title= _ "Map and Scenario Editor"
-    topics=..editor, editor_modes, editor_toolkit, editor_palette, editor_brush, editor_terrain, editor_masks, editor_named_area, editor_playlist, editor_tool_paint, editor_tool_fill, editor_tool_label, editor_tool_select, editor_tool_paste, editor_tool_item, editor_tool_soundsource, editor_tool_village, editor_tool_unit, editor_tool_starting, editor_clipboard
+    topics=..editor, editor_modes, editor_toolkit, map_format
+    sections=editor_mode_terrain, editor_mode_scenario
     sort_topics=no
 [/section]
 
-# wmllint: markcheck off
-[topic]
-    id=editor_brush
-    title= _ "Editor Brush"
-    text= _ "TODO"
-[/topic]
-# wmllint: markcheck on
+[section]
+    id=editor_mode_terrain
+    title= _ "Terrain Editor"
+    topics=..editor_mode_terrain, editor_palette, editor_masks, editor_tool_paint, editor_tool_fill, editor_tool_select, editor_tool_paste, editor_tool_starting
+    sort_topics=no
+[/section]
 
-# wmllint: markcheck off
-[topic]
-    id=editor_clipboard
-    title= _ "Terrain Clipboard"
-    text= _ "TODO"
-[/topic]
-# wmllint: markcheck on
+[section]
+    id=editor_mode_scenario
+    title= _ "Scenario Editor"
+    topics=editor_named_area, editor_playlist, editor_tool_label, editor_tool_item, editor_tool_soundsource, editor_tool_village, editor_tool_unit
+    sort_topics=no
+[/section]
 
 # wmllint: markcheck off
 [topic]
     id=editor_tool_paint
     title= _ "Paint Tool"
     text= "<img>src=icons/action/editor-tool-paint_60.png align=left box=yes</img>" + _ "Paint terrain tiles on the map.
 
-The paint tool utilizes the brushes and the terrain palette."
+The paint tool utilizes the brush sizes and the terrain palette.
+
+<bold>text='Keyboard Modifiers'</bold>
+
+• Shift+mouse click: If a base terrain is selected, change the base without changing the overlay. If an overlay is selected, change the overlay without changing the base.
+• Control+mouse click: Select the terrain under the mouse cursor, as if it had been selected on the terrain palette (picks up both base and overlay).
+
+<bold>text='Brush Sizes'</bold>
+
+The selected brush changes the size of the tool:
+
+" +
+        "<img>src=icons/action/editor-brush-1_30.png align=left box=yes</img>" + _ "Paint single hexes." +
+        "<img>src=icons/action/editor-brush-2_30.png align=left box=yes</img>" + _ "Paint seven hexes at a time." +
+        "<img>src=icons/action/editor-brush-3_30.png align=left box=yes</img>" + _ "Paint nineteen hexes at a time." +
+        "<img>src=icons/action/editor-brush-nw-se_30.png align=left box=yes</img>" + _ "Paint three hexes in a line." +
+        "<img>src=icons/action/editor-brush-sw-ne_30.png align=left box=yes</img>" + _ "Paint three hexes in a line."
 [/topic]
 # wmllint: markcheck on
 
 # wmllint: markcheck off
 [topic]
     id=editor_tool_fill
     title= _ "Fill Tool"
-    text= "<img>src=icons/action/editor-tool-fill_60.png align=left box=yes</img>" + _ "Fill continuous regions of terrain with a different one!
+    text= "<img>src=icons/action/editor-tool-fill_60.png align=left box=yes</img>" + _ "Fill continuous regions of terrain with a different one.
+
+The fill tool utilizes the terrain palette.
 
-The fill tool utilizes the terrain palette."
+<bold>text='Keyboard Modifiers'</bold>
+
+• Shift+mouse click: If a base terrain is selected, change the base without changing the overlay. If an overlay is selected, change the overlay without changing the base.
+• Control+mouse click: Select the terrain under the mouse cursor, as if it had been selected on the terrain palette (picks up both base and overlay)."
 [/topic]
 # wmllint: markcheck on
 
 # wmllint: markcheck off
 [topic]
     id=editor_tool_select
     title= _ "Select Tool"
-    text= "<img>src=icons/action/editor-tool-select_60.png align=left box=yes</img>" + _ "Selects a set of hex fields. The best tool ever!
+    text= "<img>src=icons/action/editor-tool-select_60.png align=left box=yes</img>" + _ "Selects a set of hex fields, for use with with the cut, copy and fill-selection buttons below the menu bar.
+
+<bold>text='Keyboard Modifiers'</bold>
 
-This tool utilizes the brushes."
+• Shift+mouse click: ‘Magic Wand’ mode, select the hex under the mouse cursor, and adjoining hexes of the same terrain type.
+• Control+mouse click: Unselect hexes.
+
+<bold>text='Brush Sizes'</bold>
+
+The selected brush changes the size of the tool:
+
+" +
+        "<img>src=icons/action/editor-brush-1_30.png align=left box=yes</img>" + _ "Select single hexes." +
+        "<img>src=icons/action/editor-brush-2_30.png align=left box=yes</img>" + _ "Select seven hexes at a time." +
+        "<img>src=icons/action/editor-brush-3_30.png align=left box=yes</img>" + _ "Select nineteen hexes at a time." +
+        "<img>src=icons/action/editor-brush-nw-se_30.png align=left box=yes</img>" + _ "Select three hexes in a line." +
+        "<img>src=icons/action/editor-brush-sw-ne_30.png align=left box=yes</img>" + _ "Select three hexes in a line."
 [/topic]
 # wmllint: markcheck on
 
 # wmllint: markcheck off
 [topic]
     id=editor_tool_paste
-    title= _ "Paste Tool"
-    text= "<img>src=icons/action/editor-paste_60.png align=left box=yes</img>" + _ "Paste the terrain in the clipboard"
+    title= _ "Clipboard and Paste Tool"
+    text= "<img>src=icons/action/editor-paste_60.png align=left box=yes</img>" + _ "Rotate, flip and paste the terrain in the clipboard
+
+Hexes can be cut or copied to the clipboard using the <ref>dst='editor_tool_select' text='Select Tool'</ref>.
+
+The paste tool shows an outline of the clipboard, which can be pasted with a mouse-click. Only the outline is shown, but mistakes can be corrected with the undo function, which is bound to both Control+Z and to the same key as the in-game undo function.
+
+The paste tool also has some clipboard-manipulation functions:
+" +
+        "<img>src=icons/action/editor-clipboard-rotate-cw_30.png align=left box=yes</img>" + _ "Rotate clockwise by 60°." +
+        "<img>src=icons/action/editor-clipboard-rotate-ccw_30.png align=left box=yes</img>" + _ "Rotate counter-clockwise by 60°." +
+        "<img>src=icons/action/editor-clipboard-flip-horizontal_30.png align=left box=yes</img>" + _ "Flip horizontally" +
+        "<img>src=icons/action/editor-clipboard-flip-vertical_30.png align=left box=yes</img>" + _ "Flip vertically"
 [/topic]
 # wmllint: markcheck on
 
 # wmllint: markcheck off
 [topic]
     id=editor_tool_starting
-    title= _ "Starting Tool"
+    title= _ "Starting Locations Tool"
     text= "<img>src=icons/action/editor-tool-starting-position_60.png align=left box=yes</img>" + _"Defines the side leader starting position
 
-This tool sets the side leaders' default starting locations, and named special locations."
+This tool sets the side leaders’ default starting locations, and named special locations. Both types of location are enabled in both <ref>dst='..editor_mode_terrain' text='Terrain Editor'</ref> and Scenario Editor modes. The location names are shown as a list in the editor palette, clicking on the map will place that name on a hex, each location can only be placed on a single hex, and the editor will only allow one location per hex.
+
+To add named special locations, click “Add” at the bottom of the editor palette, and enter the name. These names must start with a letter and may contain numbers and underscores.
+
+More than nine teams can be added to a map, by clicking “Add” and entering a number, for example “10”. The UI will automatically show this as “Player 10”.
+
+Named locations can be accessed from WML using the Standard Location Filter’s <italic>text='location_id='</italic>. Player starts can also be accessed from WML using <italic>text='location_id=1'</italic>, <italic>text='location_id=2'</italic>, etc — use only the number, without adding “Player ” in front of the number.
+
+<bold>text='Keyboard Modifiers'</bold>
+
+• Control+mouse click on a hex that already has a location: select that location for placing with a subsequent mouse click, as if it was selected in the editor palette."
 [/topic]
 # wmllint: markcheck on
 
@@ -139,100 +194,93 @@ Have a look at the addon server for easy to use additional music tracks."
     id=..editor
     title= _ "Map/Scenario Editor"
     # generator="contents:editor"
-    text= "<img>src=icons/icon-editor.png align=left box=no float=yes</img>" + _ "Wesnoth's Map and Scenario Editor allows users to create and edit the maps on which every Wesnoth scenario takes place. It also provides a limited set of features for setting up a basic scenario.
+    text= "<img>src=icons/icon-editor.png align=left box=no float=yes</img>" + _ "Wesnoth’s Map and Scenario Editor allows users to create and edit the maps on which every Wesnoth scenario takes place. It also provides a limited set of features for setting up a basic scenario.
 
-The editor can be launched from the <italic>text='Map Editor'</italic>" + _ " option at the title screen.
+The editor can be launched from the <italic>text='Map Editor'</italic> option at the title screen." + _ "
 
 <header>text='What you get'</header>" + _ "
 
-• <ref>dst='editor_terrain' text='Terrain Editor'</ref>
-An easy to use map editor, similar to simple paint applications.
+• <ref>dst='..editor_mode_terrain' text='Terrain Editor'</ref>
+An easy to use map editor, similar to simple paint applications." + _ "
 
-• Scenario Editor
+• Scenario Editor" + _ "
 
-• <ref>dst='editor_playlist' text='Playlist Manager'</ref>" + _ "
-Predefine the scenario's music track playlist.
+• <ref>dst='editor_playlist' text='Playlist Manager'</ref>
+Predefine the scenario’s music track playlist." + _ "
 
-• Time Schedule Editor
+• Time Schedule Editor" + _ "
 
-" + "<header>text='What you do *not* get'</header>" + _ "
+<header>text='What you do *not* get'</header>" + _ "
 
 • What-you-see-is-what-you-get
 The editor is not a WYSIWYG application.
 
-Because which exact graphic tile represents a terrain in the map depends on all terrain rules loaded (which is different between the editor and each other use case) the map won't look exactly the same.
+Because which exact graphic tile represents a terrain in the map depends on all terrain rules loaded (which is different between the editor and each other use case) the map won’t look exactly the same." + _ "
 
 • Event handlers and scripting
-The editor is not a tool to help you scripting the scenario's event handlers.
+The editor is not a tool to help you scripting the scenario’s event handlers." + _ "
 
 • Infinite Backwards Compatibility
-The editor can't load maps from versions prior to 1.10.
-TODO is that true?
+The editor can load most maps from older versions of Wesnoth, but not all. Maps from 1.3.2 and later will normally be supported, unless they use terrains which are no longer in mainline Wesnoth. Maps from add-ons which have their own terrains will need that add-on to tell the editor about their terrains." + _ "
 
-" + "<header>text='Basic Concepts'</header>" + _ "
+<header>text='Basic Concepts'</header>
 • <ref>dst='editor_modes' text='Editing Modes'</ref>
 • <ref>dst='editor_toolkit' text='Editor Toolkit'</ref>
 • <ref>dst='editor_palette' text='Editor Palette'</ref>
-• <ref>dst='editor_brush' text='Editor Brushes'</ref> TODO: not sure if it needs a topic on its own
-• <ref>dst='editor_clipboard' text='Editor Clipboard'</ref>"
+• The clipboard is described in the <ref>dst='editor_tool_paste' text='Paste Tool'</ref>"
 [/topic]
 # wmllint: markcheck on
 
-# wmllint: markcheck off
 [topic]
     id=editor_modes
     title= _ "Editing Modes"
-    text= _ "The editor features two separate modes of operation:" + _ "
+    text= _ "The editor features two modes of operation:" + _ "
 
-<header>text='Pure Map Mode'</header>" + _ "
+<header>text='Terrain-only Mode'</header>
 
-Allows only the composing of the terrain map itself and the definition of leader starting positions." + _ "
-How the information is saved depends on the loaded file:
+Allows only the composing of the terrain map itself and the definition of leader starting positions.
 
-<bold>text='Native'</bold>" + _ "
-A new map or file containing only the arguments to the map_data attribute.
+When saved using “Save Map As” and saving to the default directory, the produced map can be found in the “User Maps” game type of the create multiplayer game dialog." + _ "
 
-The produced map can be played in the “User Maps” game type at the create multiplayer game dialog if saved to the default directory.
-
-<bold>text='Embedded'</bold>" + _ "
-Scenario files containing a valid map_data attribute (not a file include) will be opened in this submode. The editor replaces only the content of map_data and leaves everything else in the scenario untouched. Maps opened this way are marked [e] in the Maps menu." + _ "
-
-<header>text='Scenario Mode'</header>" + _ "
+<header>text='Scenario Mode'</header>
 
 The Scenario mode allows several extra tools to be used, such as the Unit tool. At least one side must be defined in order to use these tools, however.
 
 In this mode, terrain data is stored in the map_data attribute and saved into a file with any applicable WML."
 [/topic]
-# wmllint: markcheck on
 
-# wmllint: markcheck off
 [topic]
     id=editor_toolkit
     title= _ "Editor Tools"
-    text= _ "The editor provides several tools for editing your maps and scenarios. At all times, one of the editor tools is active. The active tool's context determines the content of the editor palette and context menu.
+    text= _ "The editor provides several tools for editing your maps and scenarios. At all times, one of the editor tools is active. The active tool’s context determines the content of the editor palette and context menu.
 
-These following tools are provided:
+These tools are available in both terrain-only mode and scenario mode:
 
 • <ref>dst='editor_tool_paint' text='Paint Tool'</ref>
 • <ref>dst='editor_tool_fill' text='Fill Tool'</ref>
 • <ref>dst='editor_tool_select' text='Select Tool'</ref>
 • <ref>dst='editor_tool_paste' text='Paste Tool'</ref>
-• <ref>dst='editor_tool_starting' text='Starting Tool'</ref>
+• <ref>dst='editor_tool_starting' text='Starting Locations Tool'</ref>
+
+These tools are only available in scenario mode:
+
 • <ref>dst='editor_tool_label' text='Label Tool'</ref>
 • <ref>dst='editor_tool_item' text='Item Tool'</ref>
 • <ref>dst='editor_tool_soundsource' text='Soundsource Tool'</ref>
 • <ref>dst='editor_tool_village' text='Village Tool'</ref>
 • <ref>dst='editor_tool_unit' text='Unit Tool'</ref>
-
 "
 [/topic]
-# wmllint: markcheck on
 
 # wmllint: markcheck off
 [topic]
-    id=editor_terrain
+    id=..editor_mode_terrain
     title= _ "Terrain Editor"
-    text= _ "The terrain editor's functionality is covered by the <ref>dst='editor_tool_paint' text='Paint'</ref> and <ref>dst='editor_tool_fill' text='Fill Tool'</ref>."
+    text= _ "The terrain editor’s functionality is similar to a simple paint application." + _ "
+
+The right-hand sidebar contains, from top to bottom, the mini-map, <ref>dst='editor_toolkit' text='Toolkit'</ref>, tool options, and <ref>dst='editor_palette' text='Palette'</ref>." + _ "
+
+To get started, refer to the <ref>dst='editor_tool_paint' text='Paint Tool'</ref>’s page."
 [/topic]
 # wmllint: markcheck on
 
@@ -256,36 +304,48 @@ These following tools are provided:
 [topic]
     id=editor_palette
     title= _ "Editor Palette"
-    text= _ "The editor palette contains the applicable items you may use with the currently selected tool. For example, the Paint tool will display a full list of all available terrains, and the unit tool will provide a list of available units."
+    text= _ "The editor palette contains the applicable items you may use with the currently selected tool. For example, the Paint tool will display a full list of all available terrains, and the unit tool will provide a list of available units. When using the Starting Locations Tool, the palette changes to a list of “Player 1”, “Player 2”, etc.
+
+<bold>text='Filter'</bold>
+
+There is a filter function to show only a subset of the available items — this is the leftmost of the four buttons at the top of the palette, and the graphic changes depending on what is selected. Examples:" +
+        "<img>src=icons/terrain/terrain_group_all_30.png align=left box=yes</img>" + _ "Show all kinds of terrain" +
+        "<img>src=icons/terrain/terrain_group_water_deep_30.png align=left box=yes</img>" + _ "Show only water terrains" +
+        "<img>src=icons/terrain/terrain_group_village_30.png align=left box=yes</img>" + _ "Show only villages"
 [/topic]
 # wmllint: markcheck on
 
 # wmllint: markcheck off
+# This section uses << >> quotes so that curly brackets can be used without being interpreted by the preprocessor
+# Note: wmllint will attempt to improve lines that include, without the space character, "map_data ="
 [topic]
     id=map_format
     title= _ "Wesnoth Map Format"
-    text= _ "Wesnoth stores its maps in human readable plain text files.
+    text= _ "Wesnoth stores its maps in human readable plain text files." + _ <<
 
-A map file consists of rows with comma separated terrain code strings. The files can be edited with a general purpose text editor like notepad.
+<header>text='Native'</header>
 
-The only additional information provided by the map syntax are the starting positions of the scenario's sides.
+A map file consists of rows with comma separated terrain code strings. The only non-terrain information provided by the map syntax are the locations created by the <ref>dst='editor_tool_starting' text='Starting Locations Tool'</ref>. The files can be edited with a general purpose text editor like notepad.
 
-Additional information, such as teams, custom events, and complex side setups still need to be manually coded in WML."
-[/topic]
-# wmllint: markcheck on
+These files can be used directly for multiplayer games, the number of players is automatically determined by the number of starting positions. When saved in the default directory, the map can be found in the “Custom Maps” game type of the multiplayer “Create Game” dialog; you may need to refresh the cache (press F5 on the title screen) before a newly-created map appears.
 
-# wmllint: markcheck off
-[topic]
-    id=scenario_format
-    title= _ "Scenario Format"
-    text= _ " "
-[/topic]
-# wmllint: markcheck on
+These files can be used in a scenario’s .cfg file, with the scenario’s WML providing additional information such as teams, custom events, and complex side setups. The .cfg file loads the map file with either of:
 
-# wmllint: markcheck off
-[topic]
-    id=editor_starting_positions_in_general
-    title= _ "Starting Positions Howto"
-    text= _ "TODO"
+• map_file = maps/01_First_Map.map <italic>text='— supported since Wesnoth 1.14'</italic>
+• map_data = {maps/01_First_Map.map} <italic>text='— a WML preprocessor include'</italic>
+
+The <italic>text='map_file'</italic> method is preferred over using a preprocessor include.>> + _ <<
+
+<header>text='Embedded'</header>
+
+The map data can stored as part of a scenario’s .cfg file, directly in the <italic>text='map_data'</italic> attribute. In other words, in the place that the preprocessor would include it when using the preprocessor-include method.
+
+<bold>text='Using Embedded Format in Terrain Mode'</bold>
+
+If you are editing the map and not using the Scenario Mode support, then it’s trivial to move the data to a native map file before opening it in the editor. This conversion is recommended — the editor supports editing the content of map_data while leaving everything else in the file untouched, but this is rarely-used code. Maps opened this way are marked (E) in the Window menu.>> + _ <<
+
+<bold>text='Using Embedded Format in Scenario Mode'</bold>
+
+TODO.>>
 [/topic]
 # wmllint: markcheck on