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.
develop
PeridexisErrant 2015-10-24 17:41:21 +11:00
parent 54f3c6a138
commit 69090e114c
7 changed files with 33 additions and 33 deletions

@ -9,44 +9,14 @@ of the ``ls`` command output.
Note: scripts in subdirectories of hack/scripts/ can still be called, but will 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 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 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 ``kill-lua`` stops any currently-running Lua scripts. By default, scripts can
only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt
the next instruction. the next instruction.
The following pages document all the standard DFHack scripts. 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:: .. toctree::
:maxdepth: 2 :maxdepth: 2

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

@ -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.

@ -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.

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

@ -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.

@ -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.