- Get VPATH build to work
[rodin/chimara.git] / interpreters / nitfol / nitfol.info
1 This is ../../../interpreters/nitfol/nitfol.info, produced by makeinfo
2 version 4.13 from ../../../interpreters/nitfol/nitfol.texi.
3
4 INFO-DIR-SECTION Games
5 START-INFO-DIR-ENTRY
6 * nitfol: (nitfol).               Z-code interpreter and debugger.
7 END-INFO-DIR-ENTRY
8
9 \1f
10 File: nitfol.info,  Node: Top,  Next: Invoking nitfol,  Prev: (dir),  Up: (dir)
11
12 Introduction
13 ************
14
15 Nitfol is a portable interpreter for Z-machine code, the game format
16 used by Infocom and more recently, Inform
17 (http://www.gnelson.demon.co.uk/inform.html).  Nitfol handles versions
18 one through eight of the format, and attempts to comply with version
19 1.0 of the Z-machine specification.
20
21    You will need game files to use nitfol.  The "if-archive" contains a
22 large collection of these, available at
23 `ftp://ftp.gmd.de/if-archive/games/zcode/' or at the USA mirror
24 `http://ifarchive.org/indexes/if-archiveXgamesXzcode.html'.
25
26    This manual describes how to use nitfol and how it differs from
27 other Z-machine interpreters.  This manual was written with UNIX-like
28 systems in mind; ignore that which does not apply to your platform.
29 Comments on and corrections for this manual and nitfol are appreciated
30 and should be sent to <nitfol@my-deja.com>.
31
32 * Menu:
33
34 * Invoking nitfol::               How to start nitfol under UNIX
35 * Features::                      Useful extras
36 * Debugger::                      Built in source-level debugger
37
38 * Bugs::                          What I know is wrong
39 * Thanks::                        List of people who've helped
40 * Games Cited::                   The games used as examples in this manual
41
42 \1f
43 File: nitfol.info,  Node: Invoking nitfol,  Next: Features,  Prev: Top,  Up: Top
44
45 1 Invoking nitfol
46 *****************
47
48 Invoke nitfol with the game filename, and options.  If you omit the
49 game filename, nitfol will prompt you for one.  The following options
50 are recognized:
51
52 `-ignore'
53 `-no-ignore'
54 `-i'
55      Ignore Z-machine strictness errors.  Normally nitfol checks for
56      illegal and undefined Z-machine behaviour and alerts the user.  If
57      you're playing someone else's buggy game, this can be annoying and
58      you should use this option.
59
60 `-fullname'
61 `-no-fullname'
62 `-f'
63      For running under Emacs or DDD.  Tells nitfol to give
64      machine-recognizeable markers when stack frames are displayed
65      instead of displaying the line. Only useful if you are using
66      nitfol as an inferior debugger.
67
68 `-command FILE'
69 `-x FILE'
70      Read commands from this file.  Load a script from a file for
71      playback in the game.
72
73 `-pirate'
74 `-no-pirate'
75 `-P'
76      Aye, matey.  Make the piracy opcode not branch, letting the game
77      know the game disc is not "genuine." Infocom never used this
78      opcode and neither should you, but if obscurity amuses you...
79
80 `-quiet'
81 `-no-quiet'
82 `-q'
83      Do not print introductory messages.  For GDB compatibility.
84
85 `-spell'
86 `-no-spell'
87      Perform spelling correction.  Normally Z-machine games are
88      unforgiving of typos (though they do have an `oops' command). If
89      you type in a word which isn't in the game's dictionary and have
90      typo correction enabled, nitfol will search for a word which is
91      off by one letter by a substitution, deletion, insertion or
92      transposition.
93
94 `-expand'
95 `-no-expand'
96      Expand one letter abbreviations.  Early Z-machine games don't
97      include `x' as a synonym for `examine' and such.  If the first
98      word in a sentence is one letter long and not recognized by the
99      game, this will attempt to expand it to a full word.
100
101 `-symbols FILE'
102 `-s FILE'
103      Specify symbol file for game.  If you want to perform source-level
104      debugging, you will need to specify a symbol file, which contains
105      the names of variables and tells nitfol how source code
106      corresponds to object code.
107
108 `-tandy'
109 `-no-tandy'
110 `-t'
111      Censors some Infocom games.  Some version 3 games perform minor
112      wording changes when this bit is set to appease the sensitivity of
113      Tandy Corporation.
114
115 `-transcript WFILE'
116 `-T WFILE'
117      Write transcript to this file.  This transcript begins as soon as
118      the game starts.
119
120 `-debug'
121 `-no-debug'
122 `-d'
123      Enter debugger immediatly.  Imitate GDB by not automatically
124      starting the story.
125
126 `-prompt STRING'
127      Specify debugging prompt.  This is the prompt nitfol prints when
128      it is waiting for a debugging command (as opposed to the > the
129      game story prints when waiting for a game command).  DDD requires
130      this to be `(gdb) '.
131
132 `-path STRING'
133      Look for games in this directory.  If nitfol cannot find the
134      requested game in the current directory, it looks through the
135      directories listed in the given colon separated string.  The
136      directories specified here are also used to search for gamefiles
137      from saved games.   If this option is not used, nitfol looks at
138      the `INFOCOM_PATH' environment variable.
139
140 `-autoundo'
141 `-no-autoundo'
142      Ensure `@save_undo' is called every turn.  If a turn passes with
143      no `@save_undo' between, this option performs the `@save_undo'
144      automagically.  Could cause problems with some games which have a
145      different concept of a turn.
146
147 `-stacklimit NUMBER'
148 `-S NUMBER'
149      Exit when the stack is this deep.  If a game is infinitely
150      recursing, nitfol will allocate large amounts of memory and take a
151      long time before the problem is reported.  This option makes it
152      fatal to recurse more than the given number of stack frames.
153      Setting this to 0 makes nitfol allow as many as fit contiguously
154      in memory.  The Z-machine Standards Document recommends games use
155      no more than 1024 words of total stack (frames and pushed data) in
156      ZIP, which roughly works out to 90 routine calls deep.
157
158 `-alias STRING'
159 `-a STRING'
160      Specify an alias.  Adds an alias which will be expanded in read
161      lines before tokenisation.  The alias is of the form NAME VALUE;
162      you will need to use quotes around it on the commandline.
163
164 `-ralias STRING'
165      Specify an recursive alias.  Adds an alias whose result is checked
166      for further alias expansion.  Identical syntax to adding a normal
167      alias.
168
169 `-unalias STRING'
170      Remove an alias.  Removes an alias previously added by -alias.
171      Useful for removing aliases in preference files.
172
173 `-random NUMBER'
174 `-r NUMBER'
175      Set random seed.  Normally the random number generator is
176      initialized with the time of day.  If this option is used with a
177      non-zero argument, the given number will be used to initialize the
178      generator and for `@random 0'.
179
180 `-mapsym STRING'
181      Specify mapping glyphs.  Nitfol draws maps using ASCII characters;
182      you can choose which characters it uses to draw rooms.  Defaults
183      to `*udb@UDB+', which is, in order: empty room, room with down
184      exit, room with up exit, room with up and down exits, room with
185      player, room with player and up exit, room with player and down
186      exit, room with player and up and down exits, bend symbol.
187
188 `-mapsize NUMBER'
189      Specify map size.  Determines the number of lines to be used for
190      the map.
191
192 `-maploc STRING'
193      Specify map location.  Nitfol creates a Glk window for the map it
194      generates.  The map can be placed `above', `below', to the
195      `right', or the `left', of the main game window.  Follow this
196      option with one those locations.
197
198 `-terpnum NUMBER'
199      Specify interpreter number.  Each port of Infocom's Z-machine
200      interpreter was given a number.  `1' for their own DECSystem-20,
201      `2' for Apple IIe, `3' for Macintosh, `4' for Amiga, `5' for Atari
202      ST, `6' for IBM PC, `7' for Commodore 128, `8' for Commodore 64,
203      `9' for Apple IIc, `10' for Apple IIgs, `11' for Tandy Color.
204      Giving this option makes nitfol claim to be running on the
205      specified system.  A few games change their behaviour slightly
206      depending on which machine type they run.  By default nitfol
207      claims to be on an Apple IIe, as this makes Beyond Zork not do
208      character graphics.
209
210 `-terpver STRING'
211      Specify interpreter version.  Infocom's interpreters were given
212      versions, typically a capital letter.  Nitfol defaults to `N',
213      Frotz uses `F', and ZIP uses `B'.  Any single character version is
214      allowed.  Multicharacter options are read as a number instead of
215      an ASCII character.  Only known effect upon games is the letter
216      printed by banners and the `version' command.  Version 6 games
217      interpret this as a number instead of a letter.
218
219
220 \1f
221 File: nitfol.info,  Node: Features,  Next: Debugger,  Prev: Invoking nitfol,  Up: Top
222
223 2 Features
224 **********
225
226 * Menu:
227
228 * Preferences::                   Store options in `~/.nitfolrc'
229 * Infinite undo/redo::            Erase your mistakes and bad luck
230 * Aliases::                       Abbreviate long/common words
231 * Abbreviation Expansion::        Expand one letter commands
232 * Typo correction::               Nitfol uses a smart tokeniser
233 * Automapping::                   Automatically generate an on-screen map
234 * Quetzal::                       Save files are in Quetzal format
235 * Blorb::                         Nitfol supports Blorb resources
236
237 \1f
238 File: nitfol.info,  Node: Preferences,  Next: Infinite undo/redo,  Prev: Features,  Up: Features
239
240 2.1 Preferences
241 ===============
242
243 If you don't like the default options and don't want to recompile, you
244 can set your preferences by writing a `.nitfolrc' in your home
245 directory.
246
247    Each line should be of the form `OPTION=VALUE'.  Blank lines and
248 lines starting with a `#' are ignored.  If you want to specify
249 different options for different copies of nitfol, you can put those
250 options in a block which will only be read by copies of nitfol with a
251 specific name.
252
253    Here's an example `.nitfolrc':
254      path=/usr/local/games/infocom
255      alias=v verbose
256      alias=asierra tone cordial. ask sierra about
257      ignore=true
258
259      [strictnitfol]
260      ignore=false
261      spell=false
262      expand=false
263      autoundo=false
264      unalias=v
265      unalias=asierra
266
267      [xnitfol]
268      tandy=true
269      pirate=true
270
271    Nitfol will look in `/usr/local/games/infocom' for game files.
272 Copies of nitfol named `strictnitfol' will report Z-machine strictness
273 errors, perform strict tokenisation, and not automatically
274 `@save_undo'.  All others will ignore strictness errors and have two
275 aliases.  `xnitfol' will set the Tandy bit and branch on the piracy
276 opcode.
277
278    Options specified in the preference file may be overruled by
279 environment variables and command line options.
280
281 \1f
282 File: nitfol.info,  Node: Infinite undo/redo,  Next: Aliases,  Prev: Preferences,  Up: Features
283
284 2.2 Infinite undo/redo
285 ======================
286
287 Multiple `@restore_undo' opcodes with no intervening `@save_undo' will
288 restore earlier and earlier saved states.  However, Inform games will
289 not do this, so if you want infinite undo, you must enter the commands
290 `/undo' and `/redo'. The `/...' commands are part of the debugger, so
291 you will need to compile in debugger support to use this feature.
292
293    Z-machine games prior to version 5 do not provide undo (none of them
294 provide redo), and some version 5 games don't use it (like
295 `Wishbringer').  If the game performs two `@read' opcodes with no
296 intervening `@save_undo' or `@restore_undo', nitfol will perform a
297 `@save_undo'.
298
299 \1f
300 File: nitfol.info,  Node: Aliases,  Next: Abbreviation Expansion,  Prev: Infinite undo/redo,  Up: Features
301
302 2.3 Aliases
303 ===========
304
305 If the game has long words which you wish to abbreviate, you can use
306 aliases.  Use the command `/alias NAME VALUE'.  All instances of NAME
307 in line input will be replaced with VALUE.  NAME may not contain
308 whitespace.
309
310    Unlike abbreviation expansion and typo correction, alias expansion
311 modifies the text buffer, inserting the requested text.  This is
312 necessary to allow multiple commands to be given in an alias through
313 the use of periods.
314
315    Aliases are not expanded recursively, so you could do something
316 clever like this:
317      >/alias e w
318      /alias w e
319      /alias nw ne
320      /alias ne nw
321      /alias sw se
322      /alias se sw
323
324    And your east-west movement will be swapped (`e' will do a `w',
325 though `east' will still do `east').  Aliases expand on all input the
326 game receives using `@read', including transcripts and directions from
327 the automapper.
328
329    If you want the expansion of the alias to be checked for further
330 aliases, you must use the `/ralias' command.  This expansion is stopped
331 when an alias would expand itself.
332      >/ralias e w
333      /ralias w e
334
335    Would do nothing, as `e' is expanded to `w', which is expanded to
336 `e', and then it stops because the rule for expanding `e' has already
337 taken place.
338
339      >/ralias hanoi2 move src to extra. move src to dest. move extra to dest
340      /alias src left
341      /alias dest center
342      /alias extra right
343      hanoi2
344      You move the small disc from the left peg to the right peg.
345      You move the medium disc from the left peg to the middle peg.
346      You move the small disc from the right peg to the middle peg.
347      >move left to right
348      You move the large disc from the left peg to the right peg.
349      >/alias src center
350      /alias dest right
351      /alias extra left
352      hanoi2
353      You move the small disc from the middle peg to the left peg.
354      You move the medium disc from the middle peg to the right peg.
355      You move the small disc from the left peg to the right peg.
356
357    Ideally you should be able to define an alias which recursively
358 solves any depth by relying on lower levels being solvable, but this
359 isn't yet possible.  You must keep the expansion of aliases to a
360 reasonable size, since Inform has a fairly small buffer size.
361
362    You can remove aliases using the `/unalias' command.
363      >/unalias hanoi2
364
365    Aliases do not effect `/...' commands; if they did, it wouldn't be
366 possible to `/unalias'.
367
368 \1f
369 File: nitfol.info,  Node: Abbreviation Expansion,  Next: Typo correction,  Prev: Aliases,  Up: Features
370
371 2.4 Abbreviation Expansion
372 ==========================
373
374 Early Infocom games don't provide abbreviations like `x' for `examine'.
375 If you enable abbreviation expansion, nitfol will attempt to expand one
376 letter words at the beginning of inputs which are not in the game's
377 dictionary.
378
379    Nitfol supports the following expansions (note that some are
380 non-standard):
381
382 c   close       d   down        e   east        g   again
383 i   inventory   k   attack      l   look        n   north
384 o   oops        p   open        q   quit        r   drop
385 s   south       t   take        u   up          w   west
386 x   examine     y   yes         z   wait            
387
388    From `Zork I':
389      *West of House*
390      You are standing in an open field west of a white house, with a
391      boarded front door.
392      There is a small mailbox here.
393
394      >x mailbox
395      [x -> examine]
396      The small mailbox is closed.
397
398      >p it
399      [p -> open]
400      Opening the small mailbox reveals a leaflet.
401
402      >t leaflet
403      [t -> take]
404      Taken.
405
406 \1f
407 File: nitfol.info,  Node: Typo correction,  Next: Automapping,  Prev: Abbreviation Expansion,  Up: Features
408
409 2.5 Typo correction
410 ===================
411
412 In the Z-machine, the `@read' opcode provides the interpreter with a
413 dictionary to search in order to do tokenisation and word matching.  If
414 you enable typo correction and enter a word not in the provided
415 dictionary, nitfol will search for near misses.
416
417    From `Curses':
418      >ask jemmia about gloves
419      [jemmia -> jemima]
420      "Those are my gloves."
421
422    Nitfol takes the following steps to correct typos:
423
424   1. If the entered word is in the dictionary, behave as normal.
425
426   2. If the length of the word is less than 3 letters long, give up.
427      We don't want to make assumptions about what so short words might
428      be.
429
430   3. If the word is the same as a dictionary word with one
431      transposition, assume it is that word.  `exmaine' becomes
432      `examine'.
433
434   4. If it is a dictionary word with one deleted letter, assume it is
435      that word.  `botle' becomes `bottle'.
436
437   5. If it is a dictionary word with one inserted letter, assume it is
438      that word.  `tastey' becomes `tasty'.
439
440   6. If it is a dictionary word with one substitution, assume it is
441      that word.  `opin' becomes `open'.
442
443    This behavior can be annoying when nitfol "corrects" intentionally
444 entered words which are similar to dictionary words.  Usually this has
445 no effect upon the game, perhaps slightly changing the game's error
446 message, but may have negative effects when it causes an undesired
447 action.  Games like `Beyond Zork' expect you to type words not in their
448 dictionary to name things.  Nitfol might "correct" your entered word to
449 a dictionary word, which the game might complain about.
450
451    If typo correction is getting in your way, run nitfol with
452 `-no-smart', compile it without applying `-DSMART_TOKENISER', or edit
453 `nitfol.opt' to change the compile-time default.
454
455 \1f
456 File: nitfol.info,  Node: Automapping,  Next: Quetzal,  Prev: Typo correction,  Up: Features
457
458 2.6 Automapping
459 ===============
460
461 Nitfol has the ability to display an on-screen map showing visited
462 rooms and their connections on the current floor.  Below is a map
463 generated from `Enchanter'.
464                                         *-* *
465                                         |   |
466                         u-*-*-*-*-------*---*
467                         |               |
468             * *   *     |     *---*     |
469             |/ \ /      |    /|\ / \    |
470             *   *       *   / | X * \   *
471            /     \      |  /  |/ v|  \  |
472           /   *   *-*-*-*-*---*---u---*-*-*-@
473          /    |  /      | |\  |\ ^|  /  |
474       *-*     * *       | | \ | X * /   *-*
475          \    |/        | |  \|/ \ /    |
476           *   *         * *   *---*     *
477            \ /          | |             |
478             *           u-d-*-----------*-u
479                                         |
480                                         *
481                                          \
482                                           *
483
484    The `*'s designate rooms; the `@' the current room.  Rooms
485 containing staircases are shown with a `u' or `d', or `b' if the
486 staircase is bi-directional.  If the current room contains a staircase,
487 nitfol draws it with a `U', `D', or `B'.  Passageways are shown with
488 lines; the `X's are crossed lines.  One-way passages are shown as lines
489 with arrows.  Nitfol uses `v', `^', `<', and `>' for arrow heads.
490
491    In Glks which provide mouse events, you can click on rooms and it
492 will display the room name (and number) in the upper left hand corner
493 of the map.  Note that XGlk is slightly broken, so you need to click on
494 the left-hand side of the room.  Clicking on an empty map space clears
495 the name.
496
497    In order to use automapping, you must tell nitfol how to calculate
498 the current location.  You do this by specifying an Inform expression,
499 so you must have debugging enabled.
500
501    Typically the current location is available in a global.  In Z-code
502 versions 3 and prior, the current location is always stored in global
503 zero, so typing `/automap (global) 0' should work.  In later versions,
504 you must figure out an expression which evaluates to the current
505 location.
506
507    First, find out where the player object is.  Typically, the player
508 object is named `self', `cretin', `self-object', or the name of the PC.
509 You can use the `find' command to search object names.  If this all
510 fails, try `object-tree' to find the location number.
511
512    Once you have found the number of the location, you need to figure
513 out which global keeps track of the location.  You can use the
514 `globals' command to search the globals.
515
516    From `Spider And Web':
517      >/find self
518      20 "(self object)"
519      25 "yourself" in 91 "End of Alley"
520      26 "yourself" in 48 "chair"
521      /globals 91
522      G15 G36 G39
523      s
524
525      *Mouth of Alley*
526      You're in the entrance of a narrow brick alley, which runs further
527      in to the north. To the south a broad street courses by, congested
528      with traffic and bicycles, although none of them seem to notice you.
529
530      >/find self
531      20 "(self object)"
532      25 "yourself" in 94 "Mouth of Alley"
533      26 "yourself" in 48 "chair"
534      /globals 94
535      G15 G36 G39
536      /automap (global) 15
537
538    Obviously we have 3 globals tracking the player location.  Typically
539 there are only two, but some games have more.  In this, we just picked
540 the first one, which is probably the Inform `location' variable;
541 another is probably the `real_location' variable.  Depending on how you
542 want automapping to behave in the dark, or when dealing with
543 game-specific stuff, you may want to pick a different one.
544
545    To figure out what is in which direction, nitfol checks the current
546 location, tells the game to go north, checks the new location, undoes
547 the north movement, tries to go northeast, and so on.  During all of
548 this, output is disabled.
549
550    Drawing the map is more complicated.  First nitfol looks for cycles
551 in the graph and makes the cycles connect properly.  Then it draws the
552 map.  If parts of the map overlapp, it finds a path connecting the
553 overlapping bits and tries increasing the length of each passage in
554 this path by one, and recalculates cycle connections.  If this solves
555 the problem, it's done; otherwise, it tries increasing the length of
556 two passages, or of one of the passages by two.  If this fails, it
557 gives up.
558
559    This technique isn't perfect.  The implementation of this technique
560 isn't perfect either.  So expect nitfol to misbehave a lot on complex
561 maps, and a little on simple maps.  If you clever ideas on how to
562 improve it, let me know.
563
564    Nitfol makes an effort to simplify the map.  If multiple exits go
565 from the barn to cornfield and you've been to both places, nitfol will
566 draw a single two-way passage if possible.  If both up and west go up
567 the stairs and nitfol knows east returns from the top of the stairs,
568 nitfol will draw it as a simple west-east passage ignoring the up/down.
569 If east doesn't return from the top of the staircase, nitfol will draw
570 it as up/down, leaving out the west passage.
571
572    If you've been north of a gate, and come up to the gate from the
573 south, and unlock the gate, nitfol will draw it as a one-way passage
574 since last time it was north of the gate, it couldn't go south.
575
576    Some games feature reincarnation, perhaps moving you to a new
577 location.  If movement leads to your death, this makes nitfol think the
578 reincarnation location is in that direction.  Nitfol watches for three
579 asterisks in a row and will assume they mean death instead of a normal
580 passage.
581
582    Some of these problems could be avoided by having nitfol explore
583 each neighboring room, but this would make automapping even slower.
584
585 \1f
586 File: nitfol.info,  Node: Quetzal,  Next: Blorb,  Prev: Automapping,  Up: Features
587
588 2.7 Quetzal
589 ===========
590
591 Nitfol uses Quetzal version 1.4 for its save format, so you can use
592 your saves between different computers and interpreters.  More
593 information about Quetzal is available at
594 `http://www.geocities.com/SiliconValley/Vista/6631/'.
595
596    If you specify a save-file on the command-line on UNIX, nitfol uses
597 a `UNIX' `IntD' chunk to locate the game file associated with the save
598 name.  This chunk is included in save games when nitfol can figure out
599 the current filename.  If you compile nitfol with -D__USE_GNU,
600 -D__USE_BSD, or -D__USE_XOPEN_EXTENDED, nitfol will canonicalize the
601 file name, so you don't have to worry about relative file name
602 specifications no longer working if you invoke nitfol from a different
603 directory.
604
605    On MacOS, nitfol uses alias records from a `MACS' `IntD' chunk to
606 locate the game file.  This won't work for games built-in to the
607 interpreter.
608
609    If no `IntD' chunk is included, nitfol searches the environment
610 variable `INFOCOM_PATH' for a game with matching release number, serial
611 number, and checksum.
612
613    Looking for games without an `IntD' chunk isn't foolproof, but it
614 should work most of the time.  Serial numbers are basically the date
615 and it's extremely unlikely more than ten games will be compiled on the
616 same day (the only time lots of games are compiled on same day is right
617 before competition time).  Assuming they all have the same release
618 number, there's still only a .0686% chance that at least two of these
619 ten will share the same checksum.  If someone reports this as a
620 problem, I'll make nitfol ensure the game contains a `save' opcode
621 right before the restored PC.
622
623 \1f
624 File: nitfol.info,  Node: Blorb,  Prev: Quetzal,  Up: Features
625
626 2.8 Blorb
627 =========
628
629 If you wish to hear sounds or see graphics in your games, they must be
630 packaged in Blorb files.  The Z-machine game may included in the Blorb
631 file or may be specified separately.  Nitfol does not support the
632 traditional Infocom `.mg1' and `.snd' files.
633
634    Note that graphics are displayed incorrectly, and sound has not yet
635 been tested.
636
637 \1f
638 File: nitfol.info,  Node: Debugger,  Next: Bugs,  Prev: Features,  Up: Top
639
640 3 Debugger
641 **********
642
643 Nitfol debugging mode tries to imitate the GDB interface.  If you're
644 familiar with that, you should have no problem using nitfol (other than
645 dealing with the current incompleteness).
646
647    You need inform 6.21 or later, as earlier versions don't produce
648 correct infix files without a patch.  You then need to compile infix
649 information for your game.  I recommend doing:
650
651    `inform -k -~S -~X -~D MYGAME.inf'
652
653    Then your debug information will be in `gameinfo.dbg'.  If you have
654 a command-line on your platform, run nitfol like `nitfol MYGAME.z5
655 -symbols gameinfo.dbg'.  Otherwise, start up your game and type
656 `/symbol-file gameinfo.dbg' the first time you get a prompt.
657
658    When the game stops to read a line of text, you can begin that line
659 with `/' to give a debug command.  If you want to pass a line beginning
660 with a `/' to the game, double the `/' and the game will be passed the
661 second one.  When at a `(nitfol) ' prompt, starting commands with `/'
662 is neither necessary nor recommended.
663
664    All expressions are like the ones used in Inform.
665
666    You can perform casts to get the result in the form you want:
667
668 `(number) EXPRESSION'
669      Use EXPRESSION as if it were a number.  Useful when you want to
670      know the number of something, not the object, routine, or string
671      information nitfol normally gives.
672
673 `(object) EXPRESSION'
674      Use EXPRESSION as if it were an object.  Most useful when printing
675      the result, as it will show the object's attributes and properties.
676
677 `(routine) EXPRESSION'
678      Use EXPRESSION as if it were the packed address of a routine.
679      Useful if you have the packed address of a routine which you want
680      to set a breakpoint at.
681
682 `(string) EXPRESSION'
683      Use EXPRESSION as if it were the packed address of a string.
684      Useful for printing it.
685
686 `(global) EXPRESSION'
687      Evaluates to the value of a numbered global.  `(global) 0' is the
688      player location for version 3 Infocom games.
689
690 `(local) EXPRESSION'
691      Evaluates to the value of a numbered local.  Not terribly useful
692      unless you're debugging something without source.
693
694    Here are short descriptions of the debugger commands.  *note
695 (gdb)Top::, for more information.  Some of these were taken/adapted
696 from GDB's help.
697
698 `up-silently'
699 `up-silently NUM'
700      Select the parent of the selected frame silently.  An argument
701      specifies how many frames up to go.
702
703 `set EXP'
704      Evaluate an expression without printing its value.
705
706 `backtrace'
707 `backtrace NUM'
708 `backtrace - NUM'
709      Display the parent functions of the current frame.  An argument
710      specifies how many frames back to show.  If the argument is
711      negative, start from the first frame instead of the current.
712
713 `break LINESPEC'
714 `break LINESPEC if EXP'
715      Set a breakpoint.  An `if' clause specifies a condition.
716
717 `recording off'
718      Stop recording a script.
719
720 `recording on'
721      Start recording a script.
722
723 `down-silently'
724 `down-silently NUM'
725      Silently select the child of the selected frame.  An argument
726      specifies how many frames down to go.
727
728 `show copying'
729      Show licensing information.
730
731 `condition NUM EXP'
732      Set a condition for an existing breakpoint.
733
734 `step'
735 `step NUM'
736      Step through program to a different source line.  An argument
737      specifies a repeat count.
738
739 `remove EXP'
740      Remove an object from the object tree.
741
742 `replay'
743      Replay a recorded script.
744
745 `down'
746 `down NUM'
747      Select the child of the selected frame.  An argument specifies how
748      many frames down to go.
749
750 `globals'
751 `globals EXP'
752      List all global variables and their values.  With an argument,
753      list all only those with a specific value.
754
755 `enable display NUM'
756      Re-enable an automatic display.
757
758 `nexti'
759 `nexti NUM'
760      Step one instruction, stepping over subroutine calls.  Step a
761      specified number of instructions, stepping over subroutine calls.
762
763 `until'
764      Resume execution until the program reaches a line number greater
765      than the current line.
766
767 `object-tree'
768 `object-tree EXP'
769      Display the object tree.  An argument says which object to use as
770      the root of the tree.
771
772 `stepi'
773 `stepi NUM'
774      Step exactly one instruction.  An argument specifies a repeat
775      count.
776
777 `show warranty'
778      Show warranty information.
779
780 `restart'
781      Restart the game.
782
783 `undo'
784      Undo last move (not last debugger command).
785
786 `frame'
787 `frame NUM'
788      Show the selected stack frame.  An argument specifies a stack
789      frame to show.
790
791 `select-frame NUM'
792      Select a specific stack frame.
793
794 `continue'
795 `continue NUM'
796      Continue execution.  An argument sets the ignore count of the
797      current breakpoint.
798
799 `finish'
800      An argument specifies a repeat count.
801
802 `give EXP NUM'
803 `give EXP ~ NUM'
804      Give an object an attribute.  With a tilde clears the attribute
805      instead of setting it.
806
807 `find'
808      Find objects whose shortnames contain a string.
809
810 `jump LINESPEC'
811      Continue execution at a new location.
812
813 `show language'
814      Show the current source language.
815
816 `dumpmem FILE'
817      Dump memory to a file
818
819 `undisplay NUM'
820      Stop automatically displaying an expression.
821
822 `disable NUM'
823      Temporarily disable a breakpoint.
824
825 `restore'
826      Restore a saved game.
827
828 `redo'
829      Redo undid move.  Only works immediately after an `undo'.
830
831 `info sources'
832      List source files.
833
834 `symbol-file FILE'
835      Load debugging info from a file (usually `gameinfo.dbg').
836
837 `display EXP'
838      Print value of an expression each time the program stops.
839
840 `next'
841 `next NUM'
842      Step through program, stepping over subroutine calls.  An argument
843      specifies a repeat count.
844
845 `info breakpoints'
846 `info breakpoints NUM'
847      List breakpoints.  An argument specifies a specific breakpoint to
848      list.
849
850 `unalias NAME'
851      Remove an alias
852
853 `help'
854      Print list of commands.
855
856 `move EXP to EXP'
857      Move an object around the object tree.
858
859 `delete NUM'
860      Delete a breakpoint.
861
862 `quit'
863      Exit nitfol.
864
865 `up'
866 `up NUM'
867      Select the parent of the selected frame.  An argument specifies
868      how many frames up to go.
869
870 `alias NAME VALUE'
871      Add an alias
872
873 `enable NUM'
874      Re-enabled a breakpoint.
875
876 `automap EXP'
877      Start automapping
878
879 `info source'
880      Get information on the current source file.
881
882 `replay off'
883      Halt replay.
884
885 `#  comment'
886      Enter a comment
887
888 `ralias NAME VALUE'
889      Add a recursive alias
890
891 `ignore NUM NUM'
892      Set the ignore count for a breakpoint.
893
894 `print EXP'
895      Evaluates an expression and prints the result.  This can include
896      function calls.
897
898 `disable display NUM'
899      Temporarily disable an automatic display.
900
901
902    If you're on a UNIX and you don't like the GDB interface, you can
903 compile cheapnitfol and run it as the inferior debugger under Emacs or
904 DDD.  You can also try compiling `xnitfol' with `-DSTDOUT_DEBUG' and
905 trying that, but I haven't tested that much.
906
907 `ddd MYGAME.z5 --debugger cheapnitfol -s gameinfo.dbg -prompt "(gdb) "'
908
909 \1f
910 File: nitfol.info,  Node: Bugs,  Next: Thanks,  Prev: Debugger,  Up: Top
911
912 4 Bugs
913 ******
914
915 A nitfol bug is any behaviour which makes nitfol reliably misbehave,
916 with the exceptions of bugs in Glk libraries.  These include: anything
917 which makes nitfol crash (other than when nitfol reports `FATAL'
918 errors), anything which causes nitfol to contradict the Z-machine
919 standards documents (except for optional enhancements like spelling
920 correction and debug mode), any buffer overflows, and anything which
921 makes nitfol infinite loop other than infinite loops in the game itself.
922
923    Before reporting a bug, make sure the bug is not listed below and
924 your copy of nitfol is not compiled with `-DFAST'.  Please report the
925 version of nitfol, your system type and a series of commands which
926 reliably cause the bug.
927
928    Nitfol is lacking:
929    - Graphical font (`Beyond Zork')  (should use images for this)
930
931    - Terminating character support (mostly `Beyond Zork')
932
933    - Reverse video, full color (should querry Glk more aggressively)
934
935    - Unicode support
936
937    - keypad character codes
938
939    - its own random number generator (relies on system one)
940
941    Nitfol does incorrectly:
942    - Play is not paused to wait for sounds to complete in `The Lurking
943      Horror'.
944
945    - Pictures and text are not placed correctly for v6 games.
946
947    - block quotes are placed in the upper window, so `cheapnitfol'
948      can't see them.
949
950    - Corrupted save files may make nitfol do bad things.
951
952    - Should figure out a way to handle buggy games like `AMFV' and
953      `Varicella' which assume the upper window is 80 columns wide.
954
955    - Doesn't catch header writing other than `@storeb' and `@storew'.
956
957    Debugger problems:
958    - Sometimes says there's no code at a location where it could be
959      clever and   find some.
960
961    - `ofclass', superclass not implemented.
962
963    - Should perform more sanity checks everywhere.
964
965    - Lots of useful commands not yet implemented.
966
967    - OBJECT.FUNCTION is handled incorrectly, both for assignments and
968      calls.
969
970    - Assumes you know what you're doing, so `quit', `run', etc., don't
971      prompt you for confirmation.
972
973    Automapping problems:
974    - Doesn't work well for random destinations (the forest in `Advent')
975
976    - `@get_cursor' doesn't return the correct value during automapping
977      since output is disabled.
978
979    - Requires too much work for the end-user; should put in stuff to
980      make it figure out the location global in 95% of games.
981
982    - Doesn't really work if multiple locations are coded as being in
983      the same room (long road in `Enchanter').
984
985    - Doesn't show exits which go nowhere, but change the game.
986
987    - Perhaps should use graphics windows when available.
988
989    - Movement causing teleportation confuses it.
990
991    - Reincarnation handling isn't optimal.
992
993    - Still very buggy.
994
995    - It's too slow.
996
997    - Should realize it can add extra bends (especially in one-way
998      passages).
999
1000    - Should be able to output nice-looking Postscript.
1001
1002    - Should store map in saved games (wait until automapping code
1003      stabilizes).
1004
1005 \1f
1006 File: nitfol.info,  Node: Thanks,  Next: Games Cited,  Prev: Bugs,  Up: Top
1007
1008 5 Thanks
1009 ********
1010
1011 The following people have given comments, suggestions, bug reports,
1012 answered questions, or helped port nitfol (in alphabetical order):
1013    - John Cater
1014
1015    - Paul David Doherty
1016
1017    - Martin Frost
1018
1019    - Doug Jones
1020
1021    - David Picton
1022
1023    - Andrew Plotkin
1024
1025    - Andrew Pontious
1026
1027    - L. Ross Raszewski
1028
1029    - Dan Shiovitz
1030
1031 \1f
1032 File: nitfol.info,  Node: Games Cited,  Prev: Thanks,  Up: Top
1033
1034 6 Games Cited
1035 *************
1036
1037 `Wishbringer' Copyright (C) 1985, 1988 Infocom Inc.
1038
1039 `Zork I' Copyright (C) 1981-1986 Infocom Inc.
1040
1041 `Curses' Copyright (C) 1993-1994 Graham Nelson.
1042
1043    `http://ifarchive.org/if-archive/games/zcode/curses.z5'
1044
1045 `Beyond Zork' Copyright (C) 1987 Infocom Inc.
1046
1047 `Enchanter' Copyright (C) 1983, 1984, 1986 Infocom Inc.
1048
1049 `Varicella' by Adam Cadre 1999.
1050
1051    `http://adamcadre.ac/content/vgame.z8'
1052
1053 `Spider And Web' Copyright (C) 1997-1998 Andrew Plotkin.
1054
1055    `http://ifarchive.org/if-archive/games/zcode/Tangle.z5'
1056
1057
1058 \1f
1059 Tag Table:
1060 Node: Top\7f263
1061 Node: Invoking nitfol\7f1602
1062 Node: Features\7f8478
1063 Node: Preferences\7f9127
1064 Node: Infinite undo/redo\7f10483
1065 Node: Aliases\7f11257
1066 Node: Abbreviation Expansion\7f13781
1067 Node: Typo correction\7f14898
1068 Node: Automapping\7f16812
1069 Node: Quetzal\7f22591
1070 Node: Blorb\7f24312
1071 Node: Debugger\7f24738
1072 Node: Bugs\7f31713
1073 Node: Thanks\7f34768
1074 Node: Games Cited\7f35184
1075 \1f
1076 End Tag Table