Explain script type at top of listing

Using an `about.txt` file in each directory.  This is nice because it
keeps the purpose notes in the actual script directories.

docs/Scripts.rst

@@ -9,44 +9,14 @@ of the ``ls`` command output.
 Note: scripts in subdirectories of hack/scripts/ can still be called, but will
 only be listed by ls if called as ``ls -a``. This is intended as a way to hide
 scripts that are obscure, developer-oriented, or should be used as keybindings
-or from the init file.
+or from the init file.  See the page for each type for details.
 
 ``kill-lua`` stops any currently-running Lua scripts. By default, scripts can
 only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt
 the next instruction.
 
-
 The following pages document all the standard DFHack scripts.
 
-* Basic scripts are not stored in any subdirectory, and can be invoked directly.
-  They are generally useful tools for any player.
-* ``devel/*`` scripts are intended for developers, or still substantially unfinished.
-  If you don't already know what they do, best to leave them alone.
-* ``fix/*`` scripts fix various bugs and issues, some of them obscure.
-* ``gui/*`` scripts implement dialogs in the main game window.
-
-  In order to avoid user confusion, as a matter of policy all these tools
-  display the word "DFHack" on the screen somewhere while active.
-  When that is not appropriate because they merely add keybinding hints to
-  existing DF screens, they deliberately use red instead of green for the key.
-
-* ``modtools/*`` scripts provide tools for modders, often with changes
-  to the raw files, and are not intended to be called manually by end-users.
-
-  These scripts are mostly useful for raw modders and scripters. They all have
-  standard arguments: arguments are of the form ``tool -argName1 argVal1
-  -argName2 argVal2``. This is equivalent to ``tool -argName2 argVal2 -argName1
-  argVal1``. It is not necessary to provide a value to an argument name: ``tool
-  -argName3`` is fine. Supplying the same argument name multiple times will
-  result in an error. Argument names are preceded with a dash. The ``-help``
-  argument will print a descriptive usage string describing the nature of the
-  arguments. For multiple word argument values, brackets must be used: ``tool
-  -argName4 [ sadf1 sadf2 sadf3 ]``. In order to allow passing literal braces as
-  part of the argument, backslashes are used: ``tool -argName4 [ \] asdf \foo ]``
-  sets ``argName4`` to ``\] asdf foo``. The ``*-trigger`` scripts have a similar
-  policy with backslashes.
-
-
 .. toctree::
    :maxdepth: 2
 

docs/conf.py

@@ -75,8 +75,10 @@ def document_scripts():
         'gui': 'GUI Scripts',
         'modtools': 'Scripts for Modders'}
     for k in head:
-        title = '.. _{k}:\n\n{l}\n{t}\n{l}\n\n.. contents::\n\n'.format(
-            k=k, t=head[k], l=len(head[k])*'#')
+        title = ('.. _{k}:\n\n{l}\n{t}\n{l}\n\n'
+                 '.. include:: /scripts/{a}about.txt\n\n'
+                 '.. contents::\n\n').format(
+            k=k, t=head[k], l=len(head[k])*'#', a=('' if k=='base' else k+'/'))
         mode = 'w' if sys.version_info.major > 2 else 'wb'
         with open('_auto/{}.rst'.format(k), mode) as outfile:
             outfile.write(title)

scripts/about.txt

@@ -0,0 +1,2 @@
+Basic scripts are not stored in any subdirectory, and can be invoked directly.
+They are generally useful tools for any player.

scripts/devel/about.txt

@@ -0,0 +1,2 @@
+``devel/*`` scripts are intended for developers, or still substantially unfinished.
+If you don't already know what they do, best to leave them alone.

scripts/fix/about.txt

@@ -0,0 +1 @@
+``fix/*`` scripts fix various bugs and issues, some of them obscure.

scripts/gui/about.txt

@@ -0,0 +1,6 @@
+``gui/*`` scripts implement dialogs in the main game window.
+
+In order to avoid user confusion, as a matter of policy all these tools
+display the word "DFHack" on the screen somewhere while active.
+When that is not appropriate because they merely add keybinding hints to
+existing DF screens, they deliberately use red instead of green for the key.

scripts/modtools/about.txt

@@ -0,0 +1,17 @@
+``modtools/*`` scripts provide tools for modders, often with changes
+to the raw files, and are not intended to be called manually by end-users.
+
+These scripts are mostly useful for raw modders and scripters. They all have
+standard arguments: arguments are of the form ``tool -argName1 argVal1
+-argName2 argVal2``. This is equivalent to ``tool -argName2 argVal2 -argName1
+argVal1``. It is not necessary to provide a value to an argument name: ``tool
+-argName3`` is fine. Supplying the same argument name multiple times will
+result in an error. Argument names are preceded with a dash. The ``-help``
+argument will print a descriptive usage string describing the nature of the
+arguments. For multiple word argument values, brackets must be used: ``tool
+-argName4 [ sadf1 sadf2 sadf3 ]``. In order to allow passing literal braces as
+part of the argument, backslashes are used: ``tool -argName4 [ \] asdf \foo ]``
+sets ``argName4`` to ``\] asdf foo``. The ``*-trigger`` scripts have a similar
+policy with backslashes.
+
+Any of these scripts can be called with ``-help`` for more information.