What's this all about?
----------------------

"nh330-dump" is a patch for Nethack version 3.3.0.  It enables you to
automaticaly dump certain data on the (most likely) premature death of
your character to a file.  But dumping, of course, also works after an
ascension; I'm not _that_ evil (this reminds me of something I've once
read on comp.editors: "Emacs users aren't evil, but just severely
misguided." -- too true).  In other words, each time a game really ends
(character either dead, quit, or ascended), you can get the dump.

The following data can be dumped:

	- inventory
	
	- the contents of containers you are carrying
	
	- attributes (just what you get from, say, quaffing a potion of
	  enlightenment)
	
	- vanquished monsters

	- genocided monsters

	- voluntary challenges

The dumping takes place exactly at the time when you get presented this
data on the screen, and exactly the data is dumped that you actually see
on the screen.  So, whenever you type 'q' or 'n' on the question whether
to continue, say, showing inventory, the dumping also stops.  Or, if you
answer "no" to the question "Do you want to see <foo>" right at the
start, then the dump will not contain anything regarding <foo> at all:
WYGDIWYS -- What You Get Dumped Is What You See.

Why this patch?  Well, after having gloriously ascended a character, I
sometimes wished to keep notes on how this guy has performed.  The only
way (known to me) to achieve this was to either make a screenshot, or to
write it down by hand.  Certainly not really appropriate...



How do I install the patch, and how do I enable this feature?
-------------------------------------------------------------

Installing is easy.  Enter a fresh Nethack source directory (from where
you can see the src, the include, and all the other sub-directories), and
type

  patch -p1 < name-of-the-patch-file

Configure, compile, install, voila.

The feature is DISabled by default.  To enable it, you have to set the
option "dumpfile" in your rc-file (most probably $HOME/.nethackrc under
Unix; I don't know about other OS) or in the environment variable
NETHACKOPTIONS. The argument is the file the dump is to be written to.
Example:

  OPTIONS=dumpfile:/tmp/nh.dump

enables the dumping feature, and all dumps are written to /tmp/nh.dump.

Note that _you_ have to make sure that the game actually _can_ write to
this file (usually, under Unix systems, it runs under UID=games and
GID=bin).  No "wierd" stuff is allowed in the file name, no "~", no
"$HOME", no blanks.

All data present before a dump is _overwritten_, once opening a dump
file is successful.  Make sure you copy it to somewhere else in case you
want to keep it.

Important: check for dependecies with other settings, e.g., disclose.
If you tell Nethack to never disclose any information (or only
partially) on death, quitting, or ascension by default, then there won't
be no dumping (or only partially) as well!



Implementation issues
---------------------

I haven't been able to do much testing, sorry (almost none, actually).
Furthermore, the implementation most probably is far from being perfect.
I haven't used any #ifdef's, the new code is placed just right into the
existing one.  Please feel free to provide a patch for the patch to
clean up things a bit.

The starting point is function disclose() in end.c.  There, the dump
file is opened at the beginning and closed at the end (_if_ you want to
dump, that is).  All relevant functions called from within disclose()
have a new (boolean) parameter, "want_dump".  If want_dump is set to
TRUE, then dumping is performed.  If one of these functions is called
from somewhere else, say, after quaffing a potion of enlightenment, then
no dump is performed (want_dump then is set to FALSE). The relevant
functions are

  - display_inventory() in invent.c

  - container_contents() in end.c

  - enlightenment() in cmd.c

  - list_vanquished() in end.c

  - list_genocided() in end.c

  - show_conduct() in cmd.c

Basically, whenever some information is printed to the screen, then
there's an additional call to dump() (defined in end.c) that also writes
to the dump file (if want_dump is TRUE).

The other files affected by the patch are artifact.c, decl.c,
fountain.c, options.c, pickup.c, zap.c, decl.h, and extern.h (mostly due
to calls to one of the above mentioned functions, when parameter lists
had to be adapted -- the orginal functions simply didn't have the
want_dump parameter).



All the rest
------------

I'd appreciate any suggestions or comments (also regarding typos and
grammar mistakes here or in what is dumped), please direct them to 

  friedetz@in.tum.de

Please note that during the next few weeks I may not always be able to
frequently check my email or the newsgroup.  In urgent cases, write to

  petra@dcs.warwick.ac.uk

and indicate in subject or body that this email is for me (a simple "For
Tom" suffices).


Disclaimer: I cannot be made reliable for any damage this patch,
application of it, or running a patched binary may cause (not that I
think that there is much danger).  


Since I assume that the patch is "derived from the Nethack source code",
I think that it falls under the same licence restrictions as Nethack
itself.  So, feel free to copy and modify, but grant others the same
rights that you have been granted.  It's just fair.


Enjoy,
	Tom  [25/07/2000]