manual/inform.1

   1 .\" -*- nroff -*-
   2 .TH INFORM 1 6.33
   3 .SH NAME
   4 inform \- compiler of interactive fiction for Z-machine and Glulx VMs
   5
   6 .SH SYNOPSIS
   7 .B inform
   8 [\fICOMMANDS\fR]...\ [\fIFILE1\fR] [\fIFILE2\fR]
   9
  10 .SH DESCRIPTION
  11 .B Inform
  12 is a programming language and design system for interactive fiction
  13 originally created in 1993 by Graham Nelson. Inform can generate
  14 programs designed for the Z-Machine or Glulx virtual machines.
  15
  16
  17 .SH USAGE
  18 .B Inform
  19 translates FILE1 into a source file name (see below) for its
  20 input.  FILE2 is usually omitted: if so, the output filename is made
  21 from FILE1 by cutting out the name part and translating that (see
  22 below). If FILE2 is given, however, the output filename is set to just
  23 FILE2 (not altered in any way).
  24
  25 Filenames given in the game source (with commands like Include "name"
  26 and Link "name") are also translated by
  27 .B RULES OF TRANSLATION
  28 below.
  29
  30 .SH USING THE INFORM6 LANGUAGE
  31 This manpage just documents the invocation of the
  32 .B Inform
  33 compiler and library.  "The Inform Designer's Manual" and "The Inform
  34 Beginner's Guide may be found at
  35 .B http://inform-fiction.org/manual/
  36 and in hardcopy from Amazon.
  37
  38 .SH SWITCHES
  39 .TP
  40 .B \-a
  41 Trace assembly-language (without hex dumps; see -t).
  42
  43 .TP
  44 .B \-c
  45 More concise error messages.
  46
  47 .TP
  48 .B \-d
  49 Contract double spaces after full stops in text.
  50
  51 .TP
  52 .B \-d2
  53 Contract double spaces after exlamation and question marks, too.
  54
  55 .TP
  56 .B \-e
  57 Economy mode (slower): make use of declared abbreviations.
  58
  59 .TP
  60 .B \-f
  61 Frequencies mode: show how useful abbreviations are.
  62
  63 .TP
  64 .B \-g
  65 Traces calls to functions (except in the library).
  66
  67 .TP
  68 .B \-g2
  69 Traces calls to all functions.
  70
  71 .TP
  72 .B \-h
  73 Print options information.
  74
  75 .TP
  76 .B \-i
  77 Ignore default switches set within the file.
  78
  79 .TP
  80 .B \-j
  81 List objects as constructed.
  82
  83 .TP
  84 .B \-k
  85 Output Infix debugging information to "gameinfo.dbg" (and switch -D on).
  86
  87 .TP
  88 .B \-l
  89 List every statement run through Inform.
  90
  91 .TP
  92 .B \-m
  93 Say how much memory has been allocated.
  94
  95 .TP
  96 .B \-n
  97 Print numbers of properties, attributes, and actions.
  98
  99 .TP
 100 .B \-o
 101 Print offset addresses.
 102
 103 .TP
 104 .B \-p
 105 Give percentage breakdown of story file.
 106
 107 .TP
 108 .B \-q
 109 Keep quiet about obsolete usages.
 110
 111 .TP
 112 .B \-r
 113 Record all the text to "gametext.txt".
 114
 115 .TP
 116 .B \-s
 117 Give statistics.
 118
 119 .TP
 120 .B \-t
 121 Trace assembly-language (with full hex dumps; see -a).
 122
 123 .TP
 124 .B \-u
 125 Work out most useful abbreviations (very very slowly).
 126
 127 .TP
 128 .B \-v3
 129 Compile to version-3 ("Standard") story file.
 130
 131 .TP
 132 .B \-v4
 133 Compile to version-4 ("Plus") story file.
 134
 135 .TP
 136 .B \-v5
 137 Compile to version-5 ("Advanced") story file (DEFAULT).
 138
 139 .TP
 140 .B \-v6
 141 Compile to version-6 ("Graphical") story file.
 142
 143 .TP
 144 .B \-v7
 145 Compile to version-7 (expanded "Advanced") story file.
 146
 147 .TP
 148 .B \-v8
 149 Compile to version-8 (expanded "Advanced") story file.
 150
 151 .TP
 152 .B \-w
 153 Disable warning messages.
 154
 155 .TP
 156 .B \-x
 157 Print # for every 100 lines compiled.
 158
 159 .TP
 160 .B \-y
 161 Trace linking system.
 162
 163 .TP
 164 .B \-z
 165 Print memory map of the Z-machine.
 166
 167 ---
 168
 169 .TP
 170 .B \-B
 171 Use big memory model (for large V6/V7 files).
 172
 173 .TP
 174 .B \-C0
 175 Text character set is plain ASCII only.
 176
 177 .TP
 178 .B \-Cu
 179 Text character set is UTF-8.
 180
 181 .TP
 182 .B \-Cn
 183 Text character set is ISO 8859-n (n = 1 to 9) (1 to 4, Latin 1 to
 184 Latin4; , 5, Cyrillic; 6, Arabic; 7, Greek; 8, Hebrew; 9, Latin5.
 185 Default is -C1).
 186
 187 .TP
 188 .B \-D
 189 Insert "Constant DEBUG;" automatically.
 190
 191 .TP
 192 .B \-E0
 193 Archimedes-style error messages (current setting).
 194
 195 .TP
 196 .B \-E1
 197 Microsoft-style error messages.
 198
 199 .TP
 200 .B \-E2
 201 Macintosh MPW-style error messages.
 202
 203 .TP
 204 .B \-F1
 205 Use temporary files to reduce memory consumption.
 206
 207 .TP
 208 .B \-G
 209 Compile a Glulx game file.
 210
 211 .TP
 212 .B \-H
 213 Use Huffman encoding to compress Glulx strings.
 214
 215 .TP
 216 .B \-M
 217 Compile as a Module for future linking (deprecated).
 218
 219 .TP
 220 .B \-S
 221 Compile strict error-checking at run-time (on by default)
 222
 223 .TP
 224 .B \-U
 225 Insert "Constant USE_MODULES;" automatically (deprecated).
 226
 227 .TP
 228 .B \-Wn
 229 Header extension table is at least n words (n = 3 to 99)
 230
 231 .TP
 232 .B \-X
 233 Compile with INFIX debugging facilities present
 234
 235
 236 .SH RULES OF TRANSLATION
 237 .B Inform
 238 translates plain filenames (such as "xyzzy") into full pathnames (such
 239 as "adventure/games/xyzzy") according to the following rules.
 240
 241 .TP
 242 .B 1
 243 If the name contains a '/' character (so it's already a pathname), it
 244 isn't changed.
 245
 246 [Exception: when the name is given in an Include command using the >
 247 form (such as Include ">prologue"), the ">" is replaced by the path of
 248 the file doing the inclusion and a suitable file extension is added.]
 249
 250 Filenames must never contain double-quotation marks ".  To use filenames
 251 which contain spaces, write them in double-quotes: for instance,
 252
 253 "inform +code_path="Jigsaw Final Version" jigsaw"
 254
 255 .TP
 256 .B 2
 257 The file is looked for at a particular "path" (the filename of a
 258 directory), depending on what kind of file it is.
 259
 260 File type                       Name            Usual setting
 261 .br
 262 Source code (in)        source_path     (unset)
 263 .br
 264 Include file (in)       include_path    /usr/share/inform/include
 265 .br
 266 Story file (out)        code_path       (unset)
 267 .br
 268 Temp file (out) temporary_path  /tmp/
 269 .br
 270 ICM command file (in)   icl_path        (unset)
 271 .br
 272 Module (in & out)       module_path     (unset)
 273
 274 If the path is unset, then the current working directory is used (so the
 275 filename doesn't change): if, for instance, include_path is set to
 276 "backup/oldlib" then when "parser" is included it is looked for at
 277 "backup/oldlib/parser".
 278
 279 The paths can be set or unset on the Inform command line by, eg,
 280 "inform +code_path=finished jigsaw" or
 281 .br
 282 "inform +include_path= balances" (which unsets include_path).
 283
 284 The four input path variables can be set to lists of alternative
 285 paths separated by ',' characters: these alternatives are always tried
 286 in the order they are specified in, that is, left to right through the
 287 text in the path variable.
 288 .br
 289 (Modules are written to the first alternative in the module_path
 290 list; it is an error to give alternatives at all for purely output
 291 paths.)
 292
 293 .TP
 294 .B 3
 295 The following file extensions are added:
 296 .br
 297         Source code:            .inf
 298 .br
 299         Include files:          .h
 300 .br
 301         Story files:            .z3, .z4, .z5 (default),
 302 .br
 303                                         .z6, .z7, z8, .ulx (Glulx)
 304 .br
 305         Temporary files:        .tmp
 306 .br
 307         Modules:                        .m5
 308
 309 except that any extension you give (on the command line or in a filename
 310 used in a program) will override these.  If you give the null extension
 311 "." then Inform uses no file extension at all (removing the ".").
 312
 313 Names of four individual files can also be set using the same + command
 314 notation (though they aren't really pathnames).  These are:
 315
 316         transcript_name (text written by -r switch)
 317 .br
 318         debugging_name  (data written by -k switch)
 319 .br
 320         language_name   (library file defining natural language of game)
 321 .br
 322         charset_map     (file for character set mapping)
 323
 324
 325 .SH PATH SETTING
 326
 327 .TP
 328 .B \+PATH=<dir>
 329 Set a particular path.  These include the following:
 330
 331 .br
 332 source_path
 333 .br
 334 include_path
 335 .br
 336 code_path
 337 .br
 338 temporary_path
 339 .br
 340 icl_path
 341 .br
 342 module_path
 343 .br
 344
 345
 346
 347 .SH CAVEATS
 348 .B Inform
 349 is not capable of creating story files conforming to versions 1 or 2 of
 350 the Z-Machine.
 351 .br
 352 The Inform Library (currently 6/12) is incompatible with versions of the
 353 Z-Machine lower than version 5.
 354 .br
 355 Modules cannot be used with Glulx and are deprecated for Z-machine.
 356
 357
 358 .SH AUTHORS
 359 .B Inform
 360 was originally created by Graham Nelson.
 361 .br
 362 Documentation: Graham Nelson and Gareth Rees.
 363 .br
 364 Demo games: Graham Nelson and Roger Firth.
 365 .br
 366 Tutorial material: Gareth Rees, David Cornelson, and Ethan Dicks.
 367 .br
 368 Manpage: David Griffith.