----------------------------------------------------------------------------
              Creating your first file and your wizard home
                 a mini-tutorial on the in-game editor

                          written by Gnadnar
----------------------------------------------------------------------------

        this is a quick example of using the genesis text editor.
        it demonstrates a very basic subset of the editor commands.
        for full details, do 'man general ed'.

        let's assume you want to create yourself a workroom that's
        slightly more interesting than the default. let's put the new
        workroom in a file named NEWworkroom.c -- that way, your current
        workroom will be safely untouched if something goes wrong.

        in all that follows, my comments are indented, while the commands
        you type and the results are not indented.  the string "my_name"
        will be replaced with whatever your name is.

        first, type "cd" to be sure you're in your home directory.
        here's what you should see (the "> " is the usual mud prompt):

> cd
/w/my_name

        if you don't have the autopwd option set, you'll just see "Ok."

        instead of "/w/my_name".

        then type "ed NEWworkroom.c" to edit the file.

> ed NEWworkroom.c
'w/my_name/NEWworkroom.c' isn't readable.
:
        the "isn't readable" message just means that the file doesn't
        exits yet. the : on the next line is the editor's prompt.  so
        you've opened an empty file -- you need to put your code in it.
        you do this via the editor's 'a' (append) command. you type the
        letter a on a line by itself to start append mode, then you type
        the code.  when you're finished, you type a period on a line by
        itself to leave append mode.  so, continuing on the line with
        the editor's : prompt, it looks like:

:a
*
        notice that when you entered append mode, the editor's prompt
        changed from : to *. also notice that after it's printed the *,
        it backspaces so that your cursor is on top of the *.  you're now
        ready to enter your code.  i won't show the editor's * prompt on
        each line here -- just the code that you type in:

/*
 *  /w/my_name/NEWworkroom.c
 */
#pragma strict_types

inherit "/std/workroom";

/* prototypes */
public void     create_workroom();

/*
 * Function name:       create_workroom
 * Description  :       create a temporary workroom;
 *                      i'll decorate later
 */
public void
create_workroom()
{
    set_short("a dusty room");
    set_long("Except for the pile of boxes in the middle of the "
     +  "floor, this room is empty of all but dust.\n");
    /* TBD: exits, item descriptions */
} /* create_workroom */

        that's all the code -- now type a period on a line by itself
        to exit append mode:
.
:
        notice that the editor prompt changes back to : when you leave
        append mode.

        the editor has remembered all that you typed in its internal
        buffer, but at this point it has not written it to the file.
        you use the 'w' (write) command to write the file:

:w
"w/my_name/NEWworkroom.c" 24 lines 566 bytes

        now your code has been saved in NEWworkroom.c and it is safe to
        use the 'q' (quit) command to leave the editor.  but first ..
        let's see what we have.  you can print one or more lines in the
        file by the 'p' (print) command.  'p' by itself prints the current
        line, or you can give it a range of line numbers to print.  you
        can print the first three lines, for example, by doing '1,3p':

:1,3p
/*
 * /d/Gondor/my_name/NEWworkroom.c
 */
:

        $ means the last line, so 1,$p would print the entire file.
        do that now, to see what you have:

:1,$p

[contents of file displayed here]

        now, let's change something.  suppose you want to change
        "pile of boxes" to "stack of boxes" ... well, first you need
        to find the line that contains that string.  you can use
        the / command to search:

:/pile of boxes
    set_long("Except for the pile of boxes in the middle of the "
:
        the editor found the first (and in this case, only) line that
        contains "pile of boxes", and printed that line. now, to change
        something, you use the 's' (substitute) command.  the format is
        s/str1/str2/, where  str1 is the current string, and str2 is
        the string you want to replace str1.  if you want it to print
        the line again, after it's made the change, you can append a 'p'
        to the command -- s/str1/str2/p -- so you'd type:

:s/pile/stack/p
    set_long("Except for the stack of boxes in the middle of the "

:

        ok, all done. what if you try to quit:

:q
File has been changed.
:

        you have changed the file since the last time you wrote it
        out to NEWworkroom.c.  you must write it again before you can
        quit.

:w
"w/my_name/NEWworkroom.c" 24 lines 567 bytes
:q
Exit from ed.
>

        you're out of the editor and back at the mud prompt. time
        to "load NEWworkroom" :-)

        if you have made, but not saved, some changes and you decide
        that they were wrong, you can quit without saving by using
        the Q command.  be sure you mean it, though, because once you
        type Q any unsaved changes are lost forever.

        If all worked well, you can go back into the editor and spiff
        up your workroom, making it look the way you want, and using
        things like add_item() to provide things that can be looked at
        by visitors and yourself. Once you are satisfied, the room loads
        properly, and you are sure it should be your new home, you can:

        "goto NEWworkroom"

        presuming it loads, and you are there, you can:

        "mv NEWworkroom.c workroom.c" 

        which will replace your old default workroom with the new code,
        so now finally:

        "goto workroom"

        and admire your new home!

