From: David Griffith Date: Sun, 26 Aug 2018 19:23:28 +0000 (-0700) Subject: Add manpage for SDL Frotz. Not done yet. X-Git-Url: https://scope-eye.net/git/?a=commitdiff_plain;h=c3af039f377d4a8f55a83f22f633c48ee7f6797a;p=liskon_frotz.git Add manpage for SDL Frotz. Not done yet. --- diff --git a/doc/sfrotz.6 b/doc/sfrotz.6 new file mode 100644 index 0000000..b9ee29d --- /dev/null +++ b/doc/sfrotz.6 @@ -0,0 +1,654 @@ +.\" -*- nroff -*- +.TH SFROTZ 6 2.45pre +.SH NAME +sfrotz \- interpreter for Infocom and other Z-Machine games (SDL interface) + + +.SH SYNOPSIS +.B sfrotz +.RI [ options "] " file + + +.SH DESCRIPTION +.B Frotz +is a Z-Machine interpreter. The Z-machine is a virtual machine designed +by Infocom to run all of their text adventures. It went through multiple +revisions during the lifetime of the company, and two further revisions +(V7 and V8) were created by Graham Nelson after the company's demise. +The specification is now quite well documented; this version of Frotz +supports version 1.0. +.P +This version of Frotz fully supports all these versions of the Z-Machine +including the graphical version 6. Graphics and sound are created +through the use of the SDL libraries. AIFF sound effects and music in +MOD and OGG formats are supported when packaged in Blorb container files +or optionally from individual files. + + +.SH STANDARD OPTIONS +.TP +.B \-a +Watch attribute setting. Setting and clearing of attributes on objects +will be noted in debugging messages. + +.TP +.B \-A +Watch attribute testing. Every time the z-machine tests an attribute +value, the test and the result will be reported. + +.TP +.B \-b +Sets the default background color. corresponds to one of the +Z-machine colors, which are as follows: +.br +.I black red green yellow blue magenta cyan white +.br +If color support is disabled or not available on your terminal, this +option does nothing. + +.TP +.B \-c N +Sets the number of context lines used. By default, after a ``[MORE]'' +prompt, and assuming there is enough output pending, Frotz will allow all +the currently visible lines to scroll off the screen before prompting +again. This switch specifies how many lines of text Frotz will hold +over and display at the top of the next screen. + +.TP +.B \-f +Sets the default foreground color. corresponds to one of the +Z-machine colors, which are as follows +.br +.I black red green yellow blue magenta cyan white +.br +If color support is disabled or is not available on your terminal, this +option does nothing. + +.TP +.B \-h N +Manually sets the screen height. + +.TP +.B \-i +Ignore fatal errors. If a Z-Machine interpreter encounters a zcode error +such as division-by-zero or addressing an illegal object, the proper +response is to abort execution. This is done because the zcode program +doesn't have a clear idea of what is going on. There are some games out +there that cause fatal errors because the authors were careless and used +an interpreter that didn't properly check for errors. This option is +intended to get around such bugs, but be warned that Strange Things may +happen if fatal errors are not caught. + +.TP +.B \-I N +Set the interpreter number. Infocom designed the Z-machine such that a +game could tell on what kind of machine the interpreter was running. +See INTERPRETER NUMBER below. + +.TP +.B \-l N +Sets the left margin, for those who might have specific formatting needs. + +.TP +.B \-L +When the game starts, load this saved game file. + +.TP +.B \-o +Watch object movement. This option enables debugging messages from the +interpreter which describe the moving of objects in the object tree. + +.TP +.B \-O +Watch object location. These debugging messages detail the locations of +objects in the object tree. + +.TP +.B \-P +Alter the piracy opcode. The piracy opcode was never used by Infocom. +This switch is really only useful for those who like to toy around with +Z-code. + +.TP +.B \-r N +Sets the right margin. + +.TP +.B \-R +Restricted read/write. Reading and writing files will be restricted +only to the provided path. Ordinarily Frotz will write or read its +saves, transcripts, and move recordings in whatever path or directory +the user provides when the +.B SAVE, +.B SCRIPT, +or +.B RECORDING +commands are given. This can be undesirable if Frotz is run in a +restricted environment, by a front end, or by a chatbot. This option will +cause Frotz to write or read only to the provided path and nowhere else. +Then the controlling process can then watch that directory for changes +and need not worry about someone scribbling or snooping who-knows-where. + +.TP +.B \-s N +Set the random number seed value. The given seed value is used as the initial +seed value on every restart. This is helpful for testing games like +.B Curses +which make random decisions before the first input (such that the hot +key Alt\-S does not really help). + +.TP +.B \-S N +Set the transcript width. By default your transscript files are formatted +to a width of 80 columns per line, regardless of the current screen width. +This switch allows you to change this setting. In particular, use \-S 0 +to deactivate automatic line splitting in transscript files. + +.TP +.B \-t +Sets the z-machine's +.I Tandy bit, +which may affect the behavior of certain Infocom games. For example, +Zork I pretends not to have sequels, and Witness has its language +toned down. + +.TP +.B \-u N +Sets the number of slots available for Frotz's multiple undo hotkey (see +below). This defaults to twenty, which should be sufficient for most +purposes. Setting too high a number here may be dangerous on machines +with limited memory. + +.TP +.B \-w N +Manually sets the screen width. Again, this should not be necessary +except in special circumstances. + +.TP +.B \-x +Expand the abbreviations "g", "x", and "z" to "again", "examine", and +"wait". This switch is for use with old Infocom games that lack these +common abbreviations which were introduced in later games. Use it with +caution: A few games might use "g", "x" or "z" for different purposes. + +.TP +.B \-Z N +Error checking mode. +.br +0 = don't report errors. +.br +1 = report first instance of an error. +.br +2 = report all errors. +.br +3 = exit after any error. +.br +Default is 1 (report first instance of an error). + +.SH EXTENDED OPTIONS + +.TP +.B \-@ +Use resource files listed in . + +.TP +.B \-F +Run in fullscreen mode (see NOTES). + +.TP +.B \-L +Use local resource files. + +.TP +.B \-m +Set the timer interrupt cycle to milliseconds, instead of the +default 100 (1/10 sec). + +.TP +.B \-N +Set the mode for creating default file names for save/script etc. + +.TP +.B \-T +Use traditional in-game requests for file names, intead of on-screen dialogs. + +.TP +.B \-V +Force the use of default monospaced VGA font. + + +.SH HOT KEYS +Sfrotz supports the same hot keys as standard Frotz, plus the Ctl-Alt-X +combination for immediate exit, which may be used in case of emergency. +Note that these hot keys are enabled only when the z-machine is waiting +for line input (for z-machine experts: @read opcode), with the +exception of Ctl-Alt-X which also works in single character input mode +(@read_char opcode). + +.TP +.B Alt-D +Set debugging options. + +.TP +.B Alt-H +Help (print the list of hot keys). + +.TP +.B Alt-N +New game (restart). + +.TP +.B Alt-P +Playback on. + +.TP +.B Alt-R +Recording on/off. + +.TP +.B Alt-S +Set random number seed. + +.TP +.B Alt-U +Undo one turn. + +.TP +.B Alt-X +Exit game (after confirmation). + +.TP +.B Ctl-Alt-X +Exit game immediately (no confirmation). + + +.SH WINDOW +Sfrotz has a hardwired default screen size of 640x400. The screen size +can be changed by the values in this section, by the values found in the +Reso chunck of a Blorb file, and finally by the -w and -h command line +options (in that order). Note however that Sfrotz shall refuse to set a +screen width less than 640 and/or a height less than 400. NOTE: for +normal (windowed) usage, the screen size should obviously be less than +the PC screen resolution (taking into account also window decorations, +taskbars etc.) For fullscreen usage, the size should preferably be one +of those supported by the PC video driver; otherwise, SDL shall try to +use the next higher available resolution, with black borders around the +z-machine screen. In fullscreen mode, however, it may happen that for +some strange resolutions SDL accepts the request, but the screen goes +blank... In such a case, you may shut down the program by pressing +Ctrl-Alt-X. + + +.SH INTERPRETER NUMBER +The interpreter number is a setting in the Z-machine header which is +used to tell the game on what sort of machine the interpreter is +running. Frotz will automatically choose the most appropriate number for +a given Infocom-produced game. Should you want to override the number, +the +.B \-I +option is available. + +An interpreter should choose the interpreter number most suitable for +the machine it will run on. In Versions up to 5, the main consideration +is that the behaviour of 'Beyond Zork' depends on the interpreter +number (in terms of its usage of the character graphics font). In +Version 6, the decision is more serious, as existing Infocom story files +depend on interpreter number in many ways: moreover, some story files +expect to be run only on the interpreters for a particular machine. +There are, for instance, specifically Amiga versions. The DECSystem-20 +was Infocom's own in-house mainframe. + +Infocom used the following interpreter numbers: + +.PP +.BR 1 +.BR \ \ DECSystem\ 20 + +.PP +.BR 2 +.BR \ \ Apple\ IIe + +.PP +.BR 3 +.BR \ \ Macintosh + +.PP +.BR 4 +.BR \ \ Amiga + +.PP +.BR 5 +.BR \ \ Atari\ ST + +.PP +.BR 6 +.BR \ \ IBM\ PC + +.PP +.BR 7 +.BR \ \ Commodore 128 + +.PP +.BR 8 +.BR \ \ Commodore 64 + +.PP +.BR 9 +.BR \ \ Apple\ IIc + +.PP +.BR 10 +.BR \ \ Apple\ IIgs + +.PP +.BR 11 +.BR \ \ Tandy\ Color + + +.SH CONFIGURATION FILES +On startup, +.B frotz +will first check the system's frotz.conf then $HOME/.frotzrc for +configuration information. The configuration file uses a simple syntax +of +.br + + +.PP +Color names may be any of the following: +.br +black\ |\ red\ |\ green\ |\ blue\ |\ magenta\ |\ cyan\ |\ white + + +.PP +.BR ascii +\ \ on\ |\ off +.br +Use plain ASCII only. Default is "off". + +.PP +.BR background +\ \ +.br +Set background color. Default is terminal's default background color. + +.PP +.BR color +\ \ yes\ |\ no +.br +Use color text. Default is "yes" if supported. + +.PP +.BR errormode +\ \ never\ |\ once\ |\ always\ |\ fatal +.br +Set error reporting mode. +.br +.I never +Don't report any errors except for fatal ones. +.br +.I once +Report only the first instance of an error. +.br +.I always +Report every instance of an error. +.br +.I fatal +Abort on any error, even non-fatal ones. +.br +Default is "once". + +.PP +.BR expand_abb +\ \ on\ |\ off +.br +Expand abbreviations. Default is off. Expand the abbreviations "g", "x", +and "z" to "again", "examine", and "wait". This switch is for use with +old Infocom games that lack these common abbreviations which were +introduced in later games. Use it with caution. A few games might use +the "g", "x", or "z" for different purposes. + +.PP +.BR foreground +\ \ +.br +Set foreground color. Default is terminal's default forground color. + +.PP +.BR ignore_fatal +\ \ on\ |\ off +.br +Ignore fatal errors. If a Z-Machine interpreter encounters a zcode error +such as division-by-zero or addressing an illegal object, the proper +response is to abort execution. This is done because the zcode program +doesn't have a clear idea of what is going on. There are some games out +there that cause fatal errors because the authors were careless and used +an interpreter that didn't properly check for errors. This option is +intended to get around such bugs, but be warned that Strange Things may +happen if fatal errors are not caught. +.br +Default is "off" + +.PP +.BR piracy +\ \ on\ |\ off +.br +Alter the piracy opcode. Default is off. The piracy opcode was never +used by Infocom. This option is only useful for those who like to toy +around with Z-code. + +.PP +.BR randseed +\ \ +.br +Set random number seed. Default comes from the Unix epoch. + +.PP +.BR sound +\ \ on\ |\ off +.br +Turn sound effects on or off. Default is "on". + +.PP +.BR tandy +\ \ on\ |\ off +.br +Set the machine's +.I Tandy bit. +This may affect the behavior of certain Infocom games. For example, Zork +I pretends not to have sequels, and Witness has its language toned down. +Default is "off". + +.PP +.BR undo_slots +\ \ +.br +Set number of undo slots. Default is 500. + +.PP +.BR zcode_path +\ \ /path/to/zcode/files:/another/path +.br +Set path to search for zcode game files. This is just like the $PATH +environmental variable except that you can't put environmental variables +in the path or use other shortcuts. For example, "$HOME/games/zcode" is +illegal because the shell can't interpret that $HOME variable. + +.P +The following options are really only useful for weird terminals, weird +curses libraries or if you want to force a certain look (like play in +40-column mode). + +.PP +.BR context_lines +\ \ +.br +Set the number of context lines used. By default, after a ``[MORE]'' +prompt, and assuming there is enough output pending, frotz will allow all +the currently visible lines to scroll off the screen before prompting +again. This switch specifies how many lines of text frotz will hold over +and display at the top of the next screen. Default is "0". + +.PP +.BR left_margin +\ \ +.br +Set the left margin. This is for those who might have special formatting +needs. + +.PP +.BR right_margin +\ \ +.br +Set the right margin. This is for those who might have special formatting +needs. + +.PP +.BR screen_height +\ \ +.br +Manually set screen height. Most curses libraries are intelligent enough +to determine the current width of the terminal. You may need to use this +option to override the default. + +.PP +.BR screen_width +\ \ +.br +Manually set screen width. Again, this should not be necessary except in +special circumstances. + +.PP +.BR script_width +\ \ +.br +Set the transcript width. Default is 80 columns per line, regardless of +the current screen width. This switch allows you to change this setting. +You may set this to "0" to deactivate automatic line-splitting in +transcript files. + +.P +The following options are mainly useful for debugging or cheating. + +.PP +.BR attrib_set +\ \ on\ |\ off +.br +Watch attribute setting. Setting and clearing of attributes on objects +will be noted in debugging messages. Default is "off" + +.PP +.BR attrib_test +\ \ on\ |\ off +.br +Watch attribute testing. Every time the z-machine tests an attribute +value, the test and the result will be reported. Default is "off". + +.PP +.BR obj_loc +\ \ on\ |\ off +.br +Watch object location. These debugging messages detail the locations of +objects in the object tree. Default is "off". + +.PP +.BR obj_move +\ \ on\ |\ off +.br +Watch object movement. This option enables debugging messages from the +interpreter which describe the movement of objects in the object tree. +Default is "off". + + +.SH ENVIRONMENT +If the ZCODE_PATH environmental variable is defined, frotz will search +that path for game files. If that doesn't exist, INFOCOM_PATH will be +searched. + + +.SH FURTHER INFORMATION +.PP +The Frotz homepage is at https://661.org/proj/if/frotz/. +.PP +A +.BR git(1) +repository of all versions of Unix Frotz back to 2.32 is available +for public perusal here: +.br +https://gitlab.com/DavidGriffith/frotz/. +.PP +The bleeding edge of Frotz development may be followed there. A wiki +summarising Frotz is also there at this URL: +.br +https://gitlab.com/DavidGriffith/frotz/wiki/ +.PP +The Interactive Fiction Archive is a good place to find games to play +with Frotz. Various ports and builds for Frotz may also be found here. +Here is its URL: +.br +http://www.ifarchive.org/ +.PP +Most distributions of Linux and BSD include Frotz in their package +repositories. + + +.SH CAVEATS +.PP +The Z Machine itself has trouble with the concept of resizing a terminal. +It assumes that once the screen height and width are set, they will never +change; even across saves. This made sense when 24x80 terminals were the +norm and graphical user interfaces were mostly unknown. I'm fairly sure +there's a way around this problem, but for now, don't resize an xterm in +which frotz is running. Also, you should try to make sure the terminal +on which you restore a saved game has the same dimensions as the one on +which you saved the game. + +.PP +You can use a path like "/usr/local/games/zcode:$HOME/zcode" with +$ZCODE_PATH or $INFOCOM_PATH because the shell will digest that $HOME +variable for you before setting $ZCODE_PATH. While processing frotz.conf +and $HOME/.frotzrc, a shell is not used. Therefore you cannot use +environmental variables in the "zcodepath" option within the config files. + +.PP +This manpage is not intended to tell users HOW to play interactive +fiction. Refer to the file HOW_TO_PLAY included in the Unix Frotz +documentation or visit one of the following sites: +.br +http://www.microheaven.com/ifguide/ +.br +http://www.brasslantern.org/beginners/ +.br +http://www.musicwords.net/if/how_to_play.htm +.br +http://ifarchive.org/ + +.PP +If you prefer a PDF file of how to play, here is one: +.br +http://inform-fiction.org/I7Downloads/Examples/dm/IntroductionToIF.pdf + + +.SH BUGS +This program has no bugs. no bugs. no bugs. no *WHAP* thank you. If +you find one, please report it to the Gitlab site referenced above in +.B +FURTHER INFORMATION. + + +.SH AUTHORS +.B frotz +was written by Stefan Jokisch for MSDOS in 1995-7. +.br +The SDL port was done in 2009 by Aldo Cumani and is currently maintained by +David Griffith . + + +.SH "SEE ALSO" +.BR frotz (6) +.BR dfrotz (6) +.BR nitfol (6) +.BR rezrov (6) +.BR jzip (6) +.BR xzip (6) +.BR inform (1)