prev | toc | next

2.8 Editing the Online Manual

The +list and +info commands will make a great deal of information available to players. You will probably also want to set up a website for your MUCK, explaining its theme and policies, perhaps summarizing the character generation process, perhaps highlighting abilities and objects you've defined. All these informational tools are useful and recommended... But the central, authoritative documentation for your Argo system should be the online manual, accessed with the +man command. The online manual has several #options:

    +man Show default screen or contents
    +man <topic title or number> Display a manual entry
    +man #contents List manual contents
    +man #search <string> List all entries containing <string>
    +man #browse </string> Display all entries containing <string>
    +man #edit Edit manual's contents (staff)

As with other Argo commands that take command options, you do not have to type the entire option string: typing +man #search combat and +man #s combat will produce the same results.

Note that documents are available on a MUCK-wide scope. That is, the same set of documents is shared by all realms.

Typing +man #edit puts you at a prompt where you can select among various editing options:

    A) List all documents             F) Add an alias
    B) Add a document                 G) Remove an alias
    C) Edit a document                H) Add keywords
    D) Delete a document              I) Remove keywords
    E) Rename a document              J) Edit default screen
>>  Enter selection A - I, or .q to quit.

Most of these options should be self explanatory: enter an `a' to list all documents, `b' to add a new document, `c' to edit an existing document, `d' to delete an existing document, or `e' to rename an existing document. For options B - E, you will be prompted for the name or the number (as displayed in the list) for a document to work with.

When you specify a document to add or edit, the system will automatically put you in the list editor. Create or edit the document, using normal lsedit commands, and type .end on a line by itself to exit the editor and return to the main screen. You can talk and pose while at the main screen and follow-up prompts, but cannot talk or pose while in the list editor... your remarks and poses will go into the document you are editing.

When a new document has been created, a prompt asks whether the document should be displayed in the contents list. The purpose hiding of documents is not to make them `secret' in any way: they still show up in #search and #browse results. Rather, omit document titles to avoid cluttering the contents list with multiple, successive, closely related titles. For example, if your manual includes a series of documents explaining the character generation process, with examples and notes specific to your MUCK (not a bad idea, really), having titles like `CharGen', `CharGen2', `CharGen3', `CharGen4', etc., you don't necessarily want a big block of `CharGenX' titles to be shown in the contents list, taking up valuable screen space. You could instead specify that only the first document, `CharGen', be shown in the contents, and conclude each document in the series with a cross reference to the next (`See "chargen2" to continue').

`Aliases', added and removed by entering `f' or `g', are alternate titles that can be used instead of the main or display name to display a documents. If you run a MUCK called `Wormwood', where the characters are devils, grappling with each other in eternal internal infernal politics, and you have a manual entry for `Wormwood Levels', a simplified alias like `levels' would be a good idea, so long as this does not conflict with the name of an existing document. When you enter `f' or `g' at this main screen, the system will prompt you for the document to alias or unalias, and the alias string, and then add or remove the alias as needed.

`Keywords', added and removed by entering `h' or `i', are words that will trigger a `hit' with the #search and #browse options, even if they do not appear in the document itself. For example, there may be (there really should be) a number of entries in Wormwood's online manual explaining the MUCK's theme in overview, important groups and NPCs, outlines of the power structure, hints on how to caputre mortals and parlay their souls into power within the ranks of hell, and so forth. All of these entries deal with the theme of the MUCK, regardless of whether the word `theme' literally appears in them. It would be a very good idea to use the H option to add `theme' as a keyword for all of these documents. Players could then type +man #search theme to get a comprehensive listing of the manual's contents dealing with the world's theme. They could start a log file, type +man #browse theme, and close the log, to have an offline copy of all Wormwood documents explaining the theme. Since all realms share the same collection of documents, it's also a good idea to include a realm name as a keyword for documents that deal with topics pertaining to a single realm. When you enter `h' or `i' at this main screen, the system will prompt you for a document name or number, a keyword for that document, and then add or delete the keyword as needed.

Use the J option to configure a default screen, a list containing 20 or so lines of explanatory material on how to use the manual and how to contact staff members for help. If no default screen is configured, +man just shows the table of contents when users type the command with no argument. It is not unusual for Argo online manuals to have hundreds of entries, so this list can be a little overwhelming... especially to new players, the people who need the information most and will be most likely to type +man by itself. So, be sure to set up a default screen.

When you are through editing, type .quit or .q to exit the manual.

Again, your online manual may have hundreds of entries: writing an online manual is a nontrivial task. Configuration scripts can lighten the load considerably. The ascr-base script, uploaded when Argo is first installed, creates manual entries for all standard system commands and abilities, along with a series of `overview' documents, outlining Argo. Ascr-combat creates manual entries for weapon and armor types as well as defining weapons, armor, and combat abilities in the database. Similarly, ascr-magic creates manual entries for the spells, as well as database entries for the objects, spells, and other abilities used with the magic system. Ascr-psionics creates manual entries for psionic abilities. On the subject of scripts, ascr-muckhelp lets you combine the MUCK `help' command with the online Argo manual: it invokes the +reset to make help an alias for the +man command, and populates the manual with copies of the standard MUCK help files, allowing players to use either command to access information about any help topic, and allowing staff to edit and extend the standard MUCK documentation. Being able to #search for help docs on standard MUCK topics is a nice bonus. For new players, the group who most needs online help, the boundary between `MUCK stuff' and `Argo stuff' can be quite murky: the unified help system is therefore highly recommended.

Staff members on active Argo MUCKs are encouraged to mail useful manual documents to this site, where they will be collected and made available in script form as feasible. A log file containing the output of lsprop #0=@a/docs/<topic> works fine as a format for mailing the documents.

prev | toc | top | next