This is Info file scr2ifm, created by infoize v1.0 from scr2ifm.inf

INFO-DIR-SECTION Gaming tools
START-INFO-DIR-ENTRY
* scr2ifm: (scr2ifm.info).   Create an IFM map from a game transcript
END-INFO-DIR-ENTRY


File: scr2ifm  Node: Top, Up: (dir)

scr2ifm -- create an IFM map from a game transcript
***************************************************

This Info file describes scr2ifm, a program for creating maps in IFM (*note
Ifm:(ifm).) format from one or more files containing game transcripts.

* Menu::

* Introduction::               What is scr2ifm?
* Options::                    Command-line options
* Operation::                  How scr2ifm works
* Making Transcripts::         While playing the game
* Ifm Commands::               Adding items and tasks
* Fixing Problems::            Patching things up
* Example::                    Example scr2ifm session
* Limitations::                What scr2ifm can't do


File: scr2ifm  Node: Introduction, Up: Top, Next: Options

Description
***********

scr2ifm reads one or more transcripts of an Interactive Fiction game and
produces a map of it in IFM format. It works on Infocom-style transcripts
-- those produced by Inform- and TADS-generated games (and of course
Infocom games themselves). The idea is that you play your game in a
carefree manner, without worrying about mapping anything, and after the
session use scr2ifm to get a map. Well, that's the theory anyway.

scr2ifm offers two basic ways of mapping: you can create an initial
(incomplete) map from your first transcript and then add the rest 'by
hand', or you can create a set of transcripts, each exploring different
parts of the game, and then merge them all into a final map. Which you
choose is up to you.


File: scr2ifm  Node: Options, Prev: Introduction, Up: Top, Next: Operation

Options
*******

These are the command-line options for scr2ifm:

    -c file
	Append the given file of IFM and parameter commands to the end of
	the map. This allows you to fix various problems in the resulting
	map (see *note Fixing Problems::).

    -o file
	Write output to the given file instead of stdout.

    -i	Indent the output nicely (according to *my* definition, anyway).
	This makes things look better if you've added 'item' and 'task'
	commands (see *note Ifm Commands::). Default is no indentation at
	all.

    -l	Add a comment to each IFM command indicating the file and line
	number of the transcript command that generated it.

    -w	Don't print warnings.

    -h	Print a short usage message and exit.


File: scr2ifm  Node: Operation, Prev: Options, Up: Top, Next: Making Transcripts

Operation
*********

scr2ifm works by recognizing several key things in the transcript:

    *	The commands you type. These are easy to spot, because they are
	preceded by a prompt (usually ">").

    *	When the current room changes. This is not quite so easy, but
	still fairly simple. When you enter a new room, a short room title
	is printed (for example, "West of House"). The program looks for
	these short titles in the text that follows a command. First, a
	line is checked for an invalid format -- things that never appear
	in a title (e.g. "?" or "!"). Then the word count is checked --
	titles are hardly ever more than 7 or 8 words long. Finally the
	maximum length of an uncapitalized word is examined -- this is
	almost always 3 or less in titles (the length of "the").

    *	When a previously-visited room is visited again. This is the most
	difficult thing to determine, since anything might have changed in
	the room since the last visit. If there is a description, an exact
	description match is tried. If that fails, a substring match is
	attempted. If *that* fails, the first few words are examined to
	see if they match. If there's no description, an exact room name
	match is tried. This isn't as reliable, which is why you should
	always create a transcript in 'verbose' mode (see *note Making
	Transcripts::).

    *	Special IFM commands that are (hopefully) ignored completely by
	the game -- see *note Ifm Commands::.

Some of these checks can be tailored to a particular transcript -- see
*note Fixing Problems::.

Output from scr2ifm is as follows. First, if the title of the map was
specified with the 'title' command (see *note Ifm Commands::), it is
printed. Then, if there's more than one map section, a list of map section
titles is printed.

Next, there's a list of IFM commands derived from the transcript. Each
time a new room is seen, a room command is output for it. Each room is
given a tag name formed by the initials of each capitalized word in its
name. To make tags unique, the second and subsequent occurrences of a tag
name have that number appended. For example, room 'West of House' would
get tag 'WH'.

If a movement command was up, down, in or out, then a compass direction is
chosen for it that doesn't clash with other rooms (if possible) and the
'go' attribute is used to mark its real direction. If a movement command
isn't recognized, the same is done except this time the 'cmd' attribute is
used to record the command instead.

If movement is seen between two already-visited rooms, a link command is
output (or a join, if the rooms appear to be on different map sections).
Link tags are built by concatenating the room tags of the linked rooms
with an underscore in between. Link movement is dealt with in the same
manner as for rooms.

If the special 'item' or 'task' commands are seen (see *note Ifm
Commands::), then an item or task command is output following the room
that it appears in. If an item or task hasn't been given a tag, it is
assigned one. The tag is made by translating all invalid tag characters in
the name to underscores, capitalizing (to avoid clashes with IFM commands)
and, if the tag clashes with a previously-defined tag, adding a numerical
suffix to make it unique. For example, 'black rod' might get a tag
'Black_rod_2'.

Finally, the IFM commands from the file indicated by the -c option are
echoed (if any).


File: scr2ifm  Node: Making Transcripts, Prev: Operation, Up: Top, Next: Ifm Commands

Making Transcripts
******************

For best results with scr2ifm, you should follow these guidelines when
making a transcript:

    *	Always use 'verbose' mode. If you don't, then when you revisit a
	room you've been in before, no description will be printed. In
	that case, scr2ifm will have to rely on the room name to tell
	where it is. If there's more than one room with that name, it'll
	get confused (and so will you when you look at the map!).

    *	After starting the script, look around. Otherwise your starting
	room may not be included on the map, since the room description
	may not get printed.

    *	If there's a bend in a link (e.g. if you leave a room by going
	east, and enter the next room from the south) make sure you do the
	return journey. Otherwise, scr2ifm won't know about the bend.

    *	Avoid places where different rooms have the same room description
	(i.e. mazes). scr2ifm can't resolve cases like this, and will
	assume there's just a single room. Note that this doesn't exclude
	*all* mazes -- the 'twisty passages, all different' maze from
	Colossal Cave would still work, since the descriptions are
	different.

    *	If you play the game over several sessions, and create several
	separate transcripts, pay attention to the starting rooms. If a
	transcript starts in a room already visited in the previous
	transcript, then its rooms will be added to the same map section.
	If not, a new map section will be created (and you should use the
	'map' command to give it a name -- see *note Ifm Commands::).

Some games will be more amenable to scr2ifm than others -- in general the
ones with reasonable map connections, where each connection makes sense in
relation to the others. For these games, the order in which rooms are
visited will probably make no difference to the resulting map. But for
perverse games (e.g. Colossal Cave, above ground) the order of visiting
makes a big difference. In these cases, it's probably best to avoid trying
to get all the connections on the map -- you'll spew forth lots of IFM
warnings otherwise, and the map will look awful. See *note Example:: for
an example. Sometimes it's worth having a second attempt at a transcript,
choosing different directions to go in, to see if it improves things.

Another problem with mapping is that some games have these inconvenient
things called puzzles, which sometimes block you from exploring everywhere
so you can map it properly. Come on, IF authors, let's get our priorities
right!


File: scr2ifm  Node: Ifm Commands, Prev: Making Transcripts, Up: Top, Next: Fixing Problems

Ifm Commands
************

While you're making your transcript, you can use a subset of IFM commands
to add extra things that scr2ifm will recognize. (Of course, the game
almost certainly won't understand these commands, and will print a
suitable indignant reply. But that shouldn't affect the state of things.)
The commands recognized are:

    title <name>
	Give the map a title. The name must be in double-quotes. This
	command can appear anywhere, and has the same effect each time.

    map <name>
	Indicate that the current room starts a new map section with the
	given name. The name must be in double-quotes. This is useful if
	it seems like the map divides into different sections (e.g. the
	floors of a house).

	If you use the 'map' command, you'll end up with two or more map
	sections. The first map section is the one that contains the very
	first room, and will have a default name unless you give it one
	using another 'map' command.

    item <name> [attrs]
	Declare an item in the current room. The name must be in
	double-quotes. If you don't give it a tag attribute, one is
	generated automatically by changing all invalid tag characters in
	the name to underscores.

    item [attrs]
	Add the given attributes to the last declared item, if any.

    item delete
	Delete the last declared item, if any.

    task <name> [attrs]
	Declare a task in the current room in a similar manner to items.
	The name must be in double-quotes.

    task [attrs]
	Add the given attributes to the last declared task, if any.

    task delete
	Delete the last declared task, if any.

Note that scr2ifm knows almost nothing about IFM command syntax. If
there's a syntax error in a command, you'll have to manually edit the
resulting transcript (or delete the item/task and do it again).


File: scr2ifm  Node: Fixing Problems, Prev: Ifm Commands, Up: Top, Next: Example

Fixing Problems
***************

The map produced by scr2ifm will not be perfect in a lot of cases. When
running it through IFM you might get warnings about overlapping rooms, or
crossed link lines. These problems are usually fixed by stretching the
link lines of some of the rooms. Some overlapping-room problems are caused
by the program making a bad choice of direction to put an up/down/in/out
connection in. Another problem might be not recognizing when a room is the
same as a previously-visited room, because the room description changed
too much between visits.

You can fix most of these problems by creating a command file and
specifying it with the -c option. There are two types of entry: scr2ifm
commands and IFM commands. In a command file, blank lines and comment
lines (those starting with a #) are ignored. If a command isn't recognized
as a scr2ifm command, it's assumed to be an IFM command, and is passed
straight into the output verbatim. You can use these to resolve conflicts
in the generated map, by stretching certain links or hiding them
altogether.

Here's a list of the commands available:

    is_room TEXT
	Declare a line of text that is actually the name of a room.
	Normally room names get recognized properly, but there may be some
	special cases that aren't.

    not_room TEXT
	Declare a line of text that definitely isn't the name of a room.
	This is for opposite cases to the above.

    use_name TEXT
	Use only the room name to decide whether a room has been
	previously visited. This is for cases where a room description
	changes too much between visits to be called the same room. Note
	that this implies that there can only ever be one room with this
	name.

    set_option LETTER
	This is a convenience that lets you specify scr2ifm command-line
	options in the command file instead. E.g. 'set_option i' will
	indent output nicely.

    set_param VAR = VALUE
	This evaluates the given perl expression. You can use this to set
	various parameters that control how the transcript is parsed (see
	below). Setting a value of undef will remove that parameter (so
	that it won't be used).

Here's a list of the parameters that control how the transcript is parsed,
and their defaults. You can use the scr2ifm 'set_param' command to set
them in the command file.

    $name_remove (default: '\s+\(.+\)')
	Matched text to remove before seeing if a line of text is a room
	name. This is for getting rid of stuff like " (in the dodgem
	car)".

    $name_maxwords (default: 8)
	Maximum no. of words in a room name.

    $name_maxuncap (default: 3)
	Maximum length of an uncapitalized word in a room name.

    $name_invalid (default: '[.!?"]')
	Regexp which, if matched, signals an invalid room name.

    $desc_minwords (default: 20)
	Minimum no. of matching words required to match a room
	description.

    $cmd_prompt (default: '^>\s*')
	Regexp matching a command prompt.

    $cmd_look (default: '^l(ook)?$')
	Regexp matching a 'look' command (case-insensitive).

    $cmd_undo (default: '^undo$')
	Regexp matching an UNDO command (case-insensitive). It's assumed
	that only a single level of UNDO is available.

    $cmd_teleport (default: '^(restart|restore)$')
	Regexp matching commands that are known to cause a teleport to an
	arbitrary room (case-insensitive).


File: scr2ifm  Node: Example, Prev: Fixing Problems, Up: Top, Next: Limitations

Example Session
***************

Here's a simple example of scr2ifm in action on Colossal Cave. First, the
transcript in file advent.scr (with annotation):

    Start of a transcript of
    ADVENTURE
    The Interactive Original
    By Willie Crowther and Don Woods (1977)
    David M. Baggett's 1993 reconstruction, ported by Graham Nelson
    Release 3 / Serial number 951220 / Inform v1502 Library 5/12
    Interpreter 1 Version B / Library serial number 951024

    >verbose
    ADVENTURE is now in its "verbose" mode, which always gives
    long descriptions of locations (even if you've been there
    before).

    >l

    At End Of Road
    You are standing at the end of a road before a small brick
    building. Around you is a forest. A small stream flows out
    of the building and down a gully.

The previous two commands are recommended after starting the transcript.

    >e

    Inside Building
    You are inside a building, a well house for a large spring.

    There are some keys on the ground here.

    There is tasty food here.

    There is a shiny brass lamp nearby.

    There is an empty bottle here.

    >item "keys"
    That's not a verb I recognise.

    >item "food"
    That's not a verb I recognise.

    >item "lamp"
    That's not a verb I recognise.

    >item "bottle"
    That's not a verb I recognise.

The previous four commands declare the given items to the program. You
don't have to bother with this if you don't want item locations on your
map.

    >get all
    stream: You have nothing in which to carry the water.
    well house: That's hardly portable.
    spring: That's hardly portable.
    pair of 1 foot diameter sewer pipes: That's hardly portable.
    set of keys: Taken.
    tasty food: Taken.
    brass lantern: Taken.
    small bottle: Taken.

    >w

    At End Of Road
    You are standing at the end of a road before a small brick
    building. Around you is a forest. A small stream flows out
    of the building and down a gully.

    >s

    In A Valley
    You are in a valley in the forest beside a stream tumbling
    along a rocky bed.

    >s

    At Slit In Streambed
    At your feet all the water of the stream splashes into a
    2-inch slit in the rock. Downstream the streambed is bare
    rock.

    >s

    Outside Grate
    You are in a 20-foot depression floored with bare dirt. Set
    into the dirt is a strong steel grate mounted in concrete. A
    dry streambed leads into the depression.

Note that in this game we don't go in all possible directions -- there's
no logic to the connections, and it'd just make a complete mess on the
map.

    >unlock grate
    What do you want to unlock the steel grate with?

    >keys
    You unlock the steel grate.

    >task "Unlock grate" need Keys
    That's not a verb I recognise.

That last command declared a task -- again, you don't have to bother with
this if you don't want to.

    >open grate
    You open the steel grate.

    >task "Open grate" after last
    That's not a verb I recognise.

    >d

    Below the Grate
    You are in a small chamber beneath a 3x3 steel grate to the
    surface. A low crawl over cobbles leads inward to the west.

    The grate stands open.

    >w

    In Cobble Crawl
    You are crawling over cobbles in a low passage. There is a
    dim light at the east end of the passage.

    There is a small wicker cage discarded nearby.

    >item "cage"
    That's not a verb I recognise.

    >get cage
    Taken.

    >w

    Darkness
    It is pitch dark, and you can't see a thing.

    >undo
    In Cobble Crawl
    [Previous turn undone.]

Oops! Stumbled into the dark by mistake. Without the UNDO, that would have
meant 'Darkness' appeared on the map as a room.

    >turn lamp on
    You switch the brass lantern on.

    >w

    In Debris Room
    You are in a debris room filled with stuff washed in from
    the surface. A low wide passage with cobbles becomes plugged
    with mud and debris here, but an awkward canyon leads upward
    and west.

    A note on the wall says, "Magic word XYZZY."

    A three foot black rod with a rusty star on one end lies
    nearby.

    >item "black rod" tag Rod
    That's not a verb I recognise.

    >xyzzy

    Inside Building
    You are inside a building, a well house for a large spring.

Goodness me! That was unexpected -- we've been teleported. The link almost
certainly won't look good on the map. We have the option of UNDOing, right
now, or fixing the map later. Let's do the latter.

    >xyzzy

    In Debris Room
    You are in a debris room filled with stuff washed in from
    the surface. A low wide passage with cobbles becomes plugged
    with mud and debris here, but an awkward canyon leads upward
    and west.

    A note on the wall says, "Magic word XYZZY."

    A three foot black rod with a rusty star on one end lies
    nearby.

    >get rod
    Taken.

    >w

    Sloping E/W Canyon
    You are in an awkward sloping east/west canyon.

    >w

    Orange River Chamber
    You are in a splendid chamber thirty feet high. The walls
    are frozen rivers of orange stone. An awkward canyon and a
    good passage exit from east and west sides of the chamber.

    A cheerful little bird is sitting here singing.

    >item "bird"
    That's not a verb I recognise.

    >unscript

    End of transcript.

Ok, now to create a map. To do that, use this command:

    scr2ifm -o advent.ifm advent.scr

To check for problems, just type:

    ifm advent.ifm

On the first run through, there are complaints about an overlapping room,
due to a bad choice of direction for the 'down' link from Outside Grate,
and the expected problems with the link between the Debris Room and the
Building. A command file, advent.cmd, will fix these problems:

    # Fix bad choice of direction.
    link BG dir s;

    # Hide "xyzzy" link.
    link IDR_IB hidden;

    # Replace it with join.
    join IDR to IB cmd "xyzzy";

Now, if we invoke

    scr2ifm -o advent.ifm -i -c advent.cmd advent.scr

we get the following map:

    ## IFM map created by scr2ifm.pl

    ## Commands generated by transcript.
    room "At End Of Road" tag AEOR;

    room "Inside Building" dir e from AEOR tag IB;
      item "keys" tag Keys;
      item "food" tag Food;
      item "lamp" tag Lamp;
      item "bottle" tag Bottle;

    room "In A Valley" dir s from AEOR tag IAV;

    room "At Slit In Streambed" dir s from IAV tag ASIS;

    room "Outside Grate" dir s from ASIS tag OG;
      task "Unlock grate" need Keys tag Unlock_grate;
      task "Open grate" after last tag Open_grate;

    room "Below the Grate" dir n from OG go down tag BG;

    room "In Cobble Crawl" dir w from BG tag ICC;
      item "cage" tag Cage;

    room "In Debris Room" dir w from ICC tag IDR;
      item "black rod" tag Rod;

    link IDR to IB dir n s cmd "xyzzy" tag IDR_IB;

    room "Sloping E/W Canyon" dir w from IDR tag SEC;

    room "Orange River Chamber" dir w from SEC tag ORC;
      item "bird" tag Bird;

    ## Customization commands.
    link BG dir s;
    link IDR_IB hidden;
    join IDR to IB cmd "xyzzy";


File: scr2ifm  Node: Limitations, Prev: Example, Up: Top

Limitations
***********

Here's a list of things that scr2ifm doesn't currently deal with:

    *	Mazes. Different maze rooms that look identical (i.e. have
	identical names *and* descriptions) will simply appear as a single
	room.

    *	One-way links. These aren't detected, so you'll have to add the
	appropriate IFM attribute yourself (in a command file, or by
	fixing the map directly).
