============================================================================ User's Guide to PennMUSH 1.8.x ============================================================================ Some of this Guide was written by Amberyl, and is used with permission. Most of it is by Paul/Javelin. This most recent version has been updated by Alex/Talek and Javelin. Installation information can be found in the files INSTALL or UPGRADING, depending on whether it's a new install or an upgrade. The file I18N discusses internationalization. I. Introduction and history II. Getting Help, Reporting Bugs III. Getting a .pennmush.org hostname and mailing lists IV. Comments You may also want to take a look at Javelin's Guide for PennMUSH Gods, at http://pennmush.org/~alansz/guide.html or by ftp from pennmush.org, /pub/PennMUSH/Guide ============================================================================ I. Introduction and history PennMUSH uses a version-numbering system that includes version numbers (like 1.7.2) and patchlevels (like p32), usually written together (1.7.2p32). Starting with 1.7.2, version numbers that are even (like 1.7.2) are stable releases - patchlevels on the latest stable release will only be issued to fix serious bugs. Version numbers that are odd (like 1.7.3) are development releases - patchlevels on the latest development release may include new features as well as bugfixes, and development releases may not be as stable as stable releases. On the other hand, some new features may *increase* stability without fixing bugs per se, and it's quite likely that later patchlevels on the development version will be more stable than those on the "stable" version. PennMUSH is a TinyMUD derivative, and one of the branches along the MUSH line. "Vanilla" TinyMUSH, which added the "v" registers and functions to the basic TinyMUD building commands, was written by Larry Foard. The code was later expanded by Jin, of MicroMUSH. In January of 1991, MicroMUSH changed its name to MicroMUSE, and the code there continued to develop under the MUSE name. At that same point in time, Moonchilde took the last public release of that code and began a series of improvements and extensions. That code was released as PernMUSH, named for the MUSH that Moonchilde was running. The last released version of that code was version 1.15, at the end of November 1991. PernMUSH itself had switched over to TinyMUSH 2.0, which Moonchilde had co-written with Glenn Crocker (Wizard of TinyCWRU); there was no longer a reason for Moonchilde to maintain this code. In January of 1992, Amberyl began working on the PernMUSH 1.15 code release, for TinyKrynn. She took over the code, which no one was supporting, and is continuing to work on extending this code, as well as improving its compatibility with TinyMUSH 2.0. She changed the name to PennMUSH (named for her school, the University of Pennsylvania), to avoid the confusion that resulted from PernMUSH actually running TinyMUSH 2.0. In January of 1995, Amberyl passed on her mantle to Javelin (aka Paul@Dune, Alan Schwartz), who is now the maintainer of the primary public distribution in development. He released two patchlevels numbered "dune-1" and "dune-2" before releasing PennMUSH 1.50 pl11 and later distributions. The numbering scheme changed again with PennMUSH 1.6.0 (see CHANGES.OLD). Gradually during the early part of 1995, Alan formed the PennMUSH development team with T. Alexander Popiel (Talek) and Ralph Melton. The development process became more formalized, with official patches, a dedicated bug reporting email address, and better tracking of outstanding issues and history. In August of 1997, Ralph Melton left the PennMUSH development team, and Thorvald Natvig joined as a new member. Many thanks go to Ralph who contributed much time, code, and good cheer to PennMUSH. Javelin, in conjunction with Talek (T. Alexander Popiel) and Thorvald Natvig, are the current PennMUSH development team. A MUSH manual should be available at ftp.digex.net, ftp.math.okstate.edu, primerd.prime.com, or from wherever you got this code from. The manual should be numbered version 2.007 or higher. If you are planning on modifying the source code to PennMUSH, you'll probably want Javelin's Guide for PennMUSH Gods, which should be available where you got this code, or, in hypertext, as http://pennmush.org/~alansz/guide.html Enjoy! ============================================================================ II. Getting Help, Reporting Bugs Here are some guidelines about where and how to report bugs or problems or generally look for help. There are three places one could get help with a problem: 1. pennmush@pennmush.org is the PennMUSH mailing list. To subscribe, visit http://www.pennmush.org/mailman/listinfo/pennmush The PennMUSH mailing list should only be used for problems, bugs, suggestions, ideas, discussion, etc. that are OF GENERAL INTEREST. It's often hard to say what's of general interest, but a good rule of thumb is: Anything that occurs before the MUSH process is running is *not* of general interest That is, don't report problems with downloading PennMUSH, compilation, installation, restarts, or database corruption to the mailing list. These are often system specific. (If you don't want to hear these discussions, but do want to be informed of new patches, subscribe to pennmush-announce instead, at http://www.pennmush.org/mailman/listinfo/pennmush-announce) 2. pennmush-bugs@pennmush.org is the bug reporting address for the PennMUSH developers (suggestions go to pennmush-developers, bugs to pennmush-bugs). This will generally give you the fastest response and is ideal for unusual bugs. A web-based submission form is at http://www.pennmush.org/jitterbug/pennmush 3. dunemush@pennmush.org is Javelin's email address. This is a good place for small suggestions, common-seeming bugs, etc. -- stuff you wouldn't want to bother all the developers with. You will receive a quick response. When reporting a problem, please always include the following information: 1. PennMUSH version number 2. The type of machine you are using (Sun SparcStation, IBM RS/6000, etc.) 3. The operating system and version (SunOS 4.1.2, AIX 3.2.4, etc.), 4. The compiler and compiler version (gcc 2.4.5, SGI cc 2.10, etc. -- the 'file' command usually tells you the compiler version, if there's no built-in option like '-v' or '-V' to give it), 5. Whether or not you have made any changes to the code. If the problem resulted in a crash and a core dump, a stack trace of the core dump (see the section above) should also be included. If I need additional stuff (like a log of the Configure or make), I'll ask for it, but if you know that it's relevant, you can send it along, too. ============================================================================ III. Getting a .pennmush.org hostname and mailing lists Thanks to donations from the PennMUSH community, Javelin was able to register the pennmush.org domain name, and, if you're running a PennMUSH, you can have yourmush.pennmush.org assigned as a hostname for your MUSH, so players don't need to telnet to obscuresite.obscuredomain.com! NOTE: A hostname is not the same thing as a site. We don't have accounts for you to run your MUSH from. You must already have your MUSH running at someplace.edu or whatever -- we just provide a nice hostname that will resolve into your current site's IP address. How do you get a pennmush.org hostname? Go to http://lists.pennmush.org/pennmush.html, and follow the instructions. It may take a day or two before the hostname will work. Thovald also has volunteered to host mailing lists for MUSHes in the pennmush.org domain. Details are on the same web page. ============================================================================ IV. Comments IV.a. Amberyl's Comments These are in the first person. :) I've been working with this code for a year and a quarter now. I can't claim that it's particularly elegant or inspired; all I can say is that it works (most of the time), and that I've had fun writing it. I'm also hoping that it's quite readable; the sections I've added or revised tend to be quite heavily commented. A number of people have been contributed a lot, directly and indirectly, to PennMUSH; many of them are credited in copyright.h. Read the file and embarrass them the next time you see them. ;) PennMUSH 1.50 patchlevel 3 contains the promised parser rewrite. A great deal of the code is derived or directly taken from the TinyMUSH 2.0 parser; credit goes to JT Traub (Moonchilde) and Glenn Crocker (Wizard) for writing the thing in the first place. In most cases, the 1.50 parser should now be functionally identical to the parser in TinyMUSH 2.0.9; see the news file for a brief summary of the changes. Major differences between the 1.50 and 2.0 parsers are almost certainly bugs, and should be reported to me. I do have a life, though, and academics/job/social stuff take priority. Thus, don't get too upset if it takes me a while to add your pet hack. :) I'm generally happy to discuss code and life in general, though, so if you see me on a MUSH, feel free to say hi. Enjoy your MUSH. -- Lydia Leong (lwl@digex.net) "Amberyl" just about everywhere IV.b. Paul/Javelin's Comments And let me recognize T. Alexander Popiel, Shawn Wagner, Nick Gammon, Dan Williams, Ervin Hearn III, Ralph Melton, David Cheatham, and Thorvald Natvig, other past and present members of the PennMUSH development or porting team. Working with them is a real pleasure. I am trying to keep extending the functionality of the server, while optimizing and rewriting things wherever possible. I'm always interested in improvements or ideas for the code, as well as anything you might have done to get it to compile and run on unusual systems. -- Alan Schwartz (dunemush@pennmush.org) Javelin at most places IV.c. Alex/Talek's Comments I would like to thank Ralph, Amberyl, Moonchilde, and all the others who went either with us or before us. PennMUSH is the embodiment of many years of hard work by many people. May it never stagnate. -- Alex (talek@pennmush.org)