update docs for reveal

docs/plugins/reveal.rst

@@ -2,29 +2,41 @@
 
 reveal
 ======
-This reveals the map. By default, HFS will remain hidden so that the demons
-don't spawn. You can use ``reveal hell`` to reveal everything. With hell revealed,
-you won't be able to unpause until you hide the map again. If you really want
-to unpause with hell revealed, use ``reveal demons``.
+Tags:
+:dfhack-keybind:`reveal`
+:dfhack-keybind:`unreveal`
+:dfhack-keybind:`revforget`
+:dfhack-keybind:`revtoggle`
+:dfhack-keybind:`revflood`
+:dfhack-keybind:`nopause`
 
-Reveal also works in adventure mode, but any of its effects are negated once
-you move. When you use it this way, you don't need to run ``unreveal``.
+Reveals the map. This reveals all z-layers in fort mode. It also works in
+adventure mode, but any of its effects are negated once you move. When you use
+it this way, you don't need to run ``unreveal`` to hide the map again.
 
-Usage and related commands:
+Usage:
 
-:reveal:        Reveal the whole map, except for HFS to avoid demons spawning
-:reveal hell:   Also show hell, but requires ``unreveal`` before unpausing
-:reveal demon:  Reveals everything and allows unpausing - good luck!
-:unreveal:      Reverts the effects of ``reveal``
-:revtoggle:     Switches between ``reveal`` and ``unreveal``
-:revflood:      Hide everything, then reveal tiles with a path to the cursor.
-                Note that tiles behind constructed walls are also revealed as a
-                workaround for :bug:`1871`.
-:revforget:     Discard info about what was visible before revealing the map.
-                Only useful where (e.g.) you abandoned with the fort revealed
-                and no longer want the data.
-
-nopause
-=======
-Disables pausing (both manual and automatic) with the exception of pause forced
-by `reveal` ``hell``. This is nice for digging under rivers.
+``reveal [hell|demon]``
+    Reveal the whole map. If ``hell`` is specified, also reveal HFS areas, but
+    you are required to run ``unreveal`` before unpausing is allowed in order
+    to prevent the demons from spawning. If you really want to unpause with hell
+    revealed, specify ``demon`` instead of ``hell``.
+``unreveal``
+    Reverts the effects of ``reveal``.
+``revtoggle``
+    Switches between ``reveal`` and ``unreveal``. Convenient to bind to a
+    hotkey.
+``revforget``
+    Discard info about what was visible before revealing the map. Only useful
+    where (for example) you abandoned with the fort revealed and no longer need
+    the saved map data when you load a new fort.
+``revflood``
+    Hide everything, then reveal tiles with a path to the cursor. This allows
+    reparing maps that you accidentally saved while they were revealed. Note
+    that tiles behind constructed walls are also revealed as a workaround for
+    :bug:`1871`.
+``nopause 1|0``
+    Disables pausing (both manual and automatic) with the exception of the pause
+    forced by `reveal` ``hell``. This is nice for digging under rivers. Use
+    ``nopause 1`` to prevent pausing and ``nopause 0`` to allow pausing like
+    normal.

plugins/reveal.cpp

@@ -82,24 +82,30 @@ command_result nopause(color_ostream &out, vector<string> & params);
 
 DFhackCExport command_result plugin_init ( color_ostream &out, vector <PluginCommand> &commands)
 {
-    commands.push_back(PluginCommand("reveal","Reveal the map.",reveal,false,
-        "Reveals the map, by default ignoring hell.\n"
-        "Options:\n"
-        "hell     - also reveal hell, while forcing the game to pause.\n"
-        "demon    - reveal hell, do not pause.\n"));
-    commands.push_back(PluginCommand("unreveal","Revert the map to its previous state.",unreveal,false,
-        "Reverts the previous reveal operation, hiding the map again.\n"));
-    commands.push_back(PluginCommand("revtoggle","Reveal/unreveal depending on state.",revtoggle,false,
-        "Toggles between reveal and unreveal.\n"));
-    commands.push_back(PluginCommand("revflood","Hide all, and reveal tiles reachable from the cursor.",revflood,false,
-        "This command hides the whole map. Then, starting from the cursor,\n"
-        "reveals all accessible tiles. Allows repairing perma-revealed maps.\n"
-        "Note that constructed walls are considered passable to work around DF bug 1871.\n"));
-    commands.push_back(PluginCommand("revforget", "Forget the current reveal data.",revforget,false,
-        "Forget the current reveal data, allowing to use reveal again.\n"));
-    commands.push_back(PluginCommand("nopause","Disable manual and automatic pausing.",nopause,false,
-        "Disable pausing (doesn't affect pause forced by reveal).\n"
-        "Activate with 'nopause 1', deactivate with 'nopause 0'.\n"));
+    commands.push_back(PluginCommand(
+        "reveal",
+        "Reveal the map.",
+        reveal));
+    commands.push_back(PluginCommand(
+        "unreveal",
+        "Revert a revealed map to its unrevealed state.",
+        unreveal));
+    commands.push_back(PluginCommand(
+        "revtoggle",
+        "Switch betwen reveal and unreveal.",
+        revtoggle));
+    commands.push_back(PluginCommand(
+        "revflood",
+        "Hide all, then reveal tiles reachable from the cursor.",
+        revflood));
+    commands.push_back(PluginCommand(
+        "revforget",
+        "Forget the current reveal data.",
+        revforget));
+    commands.push_back(PluginCommand(
+        "nopause",
+        "Disable manual and automatic pausing.",
+        nopause));
     return CR_OK;
 }