Improve markup in scripts documentation

Plus minor changes for clarification.

scripts/exportlegends.lua

@@ -7,8 +7,8 @@ Controls legends mode to export data - especially useful to set-and-forget large
 worlds, or when you want a map of every site when there are several hundred.
 
 The 'info' option exports more data than is possible in vanilla, to a
-:file:`region-date-legends_plus.xml` file developed to extend the World
+:file:`region-date-legends_plus.xml` file developed to extend
-Viewer utility and potentially compatible with others.
+:forums:`World Viewer <128932>` and other legends utilities.
 
 Options:
 

scripts/fix/fat-dwarves.lua

@@ -8,6 +8,8 @@ fix/fat-dwarves
 ===============
 Avoids 5-10% FPS loss due to constant recalculation of insulation for dwarves at
 maximum fatness, by reducing the cap from 1,000,000 to 999,999.
+Recalculation is triggered in steps of 250 units, and very fat dwarves
+constantly bounce off the maximum value while eating.
 
 =end]]
 local num_fat = 0

scripts/fix/stable-temp.lua

@@ -4,8 +4,8 @@
 fix/stable-temp
 ===============
 Instantly sets the temperature of all free-lying items to be in equilibrium with
-the environment and stops temperature updates. In order to maintain this efficient
+the environment, which stops temperature updates until something changes.
-state however, use `tweak` ``stable-temp`` and `tweak` ``fast-heat``.
+To maintain this efficient state, use `tweak fast-heat <tweak>`.
 
 =end]]
 local args = {...}
@@ -59,6 +59,7 @@ end
 if apply then
     print('Items updated: '..count)
 else
+    print("Use 'fix/stable-temp apply' to force-change temperature.")
     print('Items not in equilibrium: '..count)
 end
 
@@ -68,7 +69,3 @@ table.sort(tlist, function(a,b) return types[a] > types[b] end)
 for _,k in ipairs(tlist) do
     print('    '..df.item_type[k]..':', types[k])
 end
-
-if not apply then
-    print("Use 'fix/stable-temp apply' to force-change temperature.")
-end

scripts/gui/advfort.lua

@@ -17,7 +17,7 @@ An example of player digging in adventure mode:
 
 .. image:: /docs/images/advfort.png
 
-**WANRING:**  changes only persist in non procedural sites, namely: player forts, caves, and camps.
+**WARNING:**  changes only persist in non procedural sites, namely: player forts, caves, and camps.
 
 =end]]
 

scripts/gui/gm-editor.lua

@@ -4,10 +4,11 @@
 
 gui/gm-editor
 =============
-There are three ways to open this editor:
+This editor allows to change and modify almost anything in df. Press :kbd:`?` for
+in-game help. There are three ways to open this editor:
 
-* using gui/gm-editor command/keybinding - opens editor on what is selected
+* Callling ``gui/gm-editor``  from a command or keybinding opens the editor
-  or viewed (e.g. unit/item description screen)
+  on whatever is selected or viewed (e.g. unit/item description screen)
 
 * using gui/gm-editor <lua command> - executes lua command and opens editor on
   its results (e.g. ``gui/gm-editor "df.global.world.items.all"`` shows all items)
@@ -17,9 +18,6 @@ There are three ways to open this editor:
 
 .. image:: /docs/images/gm-editor.png
 
-This editor allows to change and modify almost anything in df. Press :kbd:`?` for
-in-game help.
-
 =end]]
 local gui = require 'gui'
 local dialog = require 'gui.dialogs'

scripts/gui/liquids.lua

@@ -15,7 +15,7 @@ allowing you to add or remove water & magma, and create obsidian walls & floors.
     There is **no undo support**.  Bugs in this plugin have been
     known to create pathfinding problems and heat traps.
 
-The :kbd:`b` key changes how the affected area is selected. The default *Rectangle*
+The :kbd:`b` key changes how the affected area is selected. The default :guilabel:`Rectangle`
 mode works by selecting two corners like any ordinary designation. The :kbd:`p`
 key chooses between adding water, magma, obsidian walls & floors, or just
 tweaking flags.

scripts/gui/mod-manager.lua

@@ -7,7 +7,7 @@ gui/mod-manager
 ===============
 A simple way to install and remove small mods.
 
-It looks for specially formatted mods in df subfolder 'mods'. Mods are not
+It looks for specially formatted mods in :file:`{<DF>}/mods/`. Mods are not
 included, but some examples are `available here`_.
 
 .. _`available here`: https://github.com/warmist/df-mini-mods

scripts/gui/workflow.lua

@@ -41,8 +41,7 @@ suit your need, and set the item count range.
 .. image:: /docs/images/workflow-new2.png
 
 Pressing :kbd:`s` (or, with the example config, Alt-W in the :kbd:`z` stocks screen)
-opens the overall status screen, which was copied from the C++ implementation
+opens the overall status screen:
-by falconne for better integration with the rest of the lua script:
 
 .. image:: /docs/images/workflow-status.png
 

scripts/modtools/create-item.lua

@@ -5,7 +5,7 @@
 
 modtools/create-item
 ====================
-This is mostly the same as the other create item tools, but it uses standard
+Replaces the `createitem` plugin, with standard
 arguments. The other versions will be phased out in a later version.
 
 =end]]

scripts/pref-adjust.lua

@@ -7,12 +7,13 @@ pref-adjust
 A two-stage script:  ``pref-adjust clear`` removes preferences from all dwarves,
 and ``pref-adjust`` inserts an 'ideal' set which is easy to satisfy::
 
-    Feb Idashzefon likes wild strawberries for their vivid red color, fisher berries
+    Feb Idashzefon likes wild strawberries for their vivid red color,
-    for their round shape, prickle berries for their precise thorns, plump helmets
+    fisher berries for their round shape, prickle berries for their
-    for their rounded tops, prepared meals, plants, drinks, doors, thrones, tables and
+    precise thorns, plump helmets for their rounded tops, prepared meals,
-    beds. When possible, she prefers to consume wild strawberries, fisher berries,
+    plants, drinks, doors, thrones, tables and beds. When possible, she
-    prickle berries, plump helmets, strawberry wine, fisher berry wine, prickle berry
+    prefers to consume wild strawberries, fisher berries, prickle
-    wine, and dwarven wine.
+    berries, plump helmets, strawberry wine, fisher berry wine, prickle
+    berry wine, and dwarven wine.
 
 =end]]
 

scripts/quicksave.lua

@@ -3,7 +3,7 @@
 
 quicksave
 =========
-If called in dwarf mode, makes DF immediately auto-save the game by setting a flag
+If called in dwarf mode, makes DF immediately saves the game by setting a flag
 normally used in seasonal auto-save.
 
 =end]]

scripts/remove-stress.lua

@@ -6,7 +6,7 @@ remove-stress
 =============
 Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or
 very stressed dwarves taking on negative or greater values respectively.
-Applies to the selected unit, or use "remove-stress -all" to apply to all units.
+Applies to the selected unit, or use ``remove-stress -all`` to apply to all units.
 
 =end]]
 

scripts/show-unit-syndromes.rb

@@ -14,7 +14,6 @@ Use one or more of the following options:
 :showall:               Show units even if not affected by any syndrome
 :showeffects:           Show detailed effects of each syndrome
 :showdisplayeffects:    Show effects that only change the look of the unit
-:ignorehiddencurse:     Hide syndromes the user should not be able to know about (TODO)
 :selected:              Show selected unit
 :dwarves:               Show dwarves
 :livestock:             Show livestock

scripts/stripcaged.rb

@@ -4,15 +4,15 @@
 stripcaged
 ==========
 For dumping items inside cages. Will mark selected items for dumping, then
-a dwarf may come and actually dump it. See also `autodump`.
+a dwarf may come and actually dump them (or you can use `autodump`).
 
-With the ``items`` argument, only dumps items laying in the cage, excluding
+Arguments:
-stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor``
-will dump everything worn by caged creatures (including armor and clothing),
-and ``all`` will dump everything, on a creature or not.
 
-``stripcaged list`` will display on the dfhack console the list of all cages
+:list:      display the list of all cages and their item content on the console
-and their item content.
+:items:     dump items in the cage, excluding stuff worn by caged creatures
+:weapons:   dump equipped weapons
+:armor:     dump everything worn by caged creatures (including armor and clothing)
+:all:       dump everything in the cage, on a creature or not
 
 Without further arguments, all commands work on all cages and animal traps on
 the map. With the ``here`` argument, considers only the in-game selected cage

scripts/view-item-info.lua

@@ -10,9 +10,9 @@ A script to extend the item or unit viewscreen with additional information
 including a custom description of each item (when available), and properties
 such as material statistics, weapon attacks, armor effectiveness, and more.
 
-The associated script ``item-descriptions.lua`` supplies custom descriptions
+The associated script `item-descriptions`.lua supplies custom descriptions
 of items.  Individual descriptions can be added or overridden by a similar
-script ``raw/scripts/more-item-descriptions.lua``.  Both work as sparse lists,
+script :file:`raw/scripts/more-item-descriptions.lua`.  Both work as sparse lists,
 so missing items simply go undescribed if not defined in the fallback.
 
 =end]]