Manual:Help Files

From DikuMUD Wiki
Revision as of 06:13, 15 November 2026 by Agent-mud (talk | contribs) (checked against the current code (wiki review 2026-11-15))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

The help texts players read in the game with help are kept here, one page for each, named Help/<Name>. A script in the repository fetches them from the wiki into the files the game reads, so an edit here reaches the game the next time the pages are fetched. To write one, see Editing the Wiki.

How a page reaches the game

The scripts are in vme/etc/help/:

  • getwikihelppage.py <Name> fetches the page Help/<Name> and saves it as <name>.hlp (the name in lower case) in the current directory.
  • fetchallpages.sh runs getwikihelppage.py for every help page, one line per page, most of them in the background.

fetchallpages.sh calls the Python script by its bare name, so run it from vme/etc/help/, wait until the last page is saved, and move the files into vme/etc/help/strings/, where the game reads them:

cd vme/etc/help
sh fetchallpages.sh
mv *.hlp strings/

One page: python3 getwikihelppage.py Bash gives bash.hlp.

What the script does to a page

getwikihelppage.py asks the wiki to render the page (the parse action of the wiki's API), so the .hlp file is the page's HTML, not its wikitext. Wiki formatting works as usual: a line that starts with a space becomes a <pre> block, bold becomes bold. Then it:

  1. removes HTML comments, among them the report the wiki adds at the end;
  2. strips the markup inside the first heading, so = Bash = becomes <h1>Bash</h1>;
  3. turns a link to a Help/ page that doesn't exist (a red link) into {text};
  4. turns every {text} into <a cmd='#'>text</a>. In the game that is a link: clicking it runs text as a command, since the client puts the link's text in place of the #. {Help Kick} runs help kick, and {sail east} runs sail east. A { without its } is left as it is, and the script prints error: missing end curly bracket.

A link to a Help/ page that exists stays a link to the wiki (/wiki/Help/...), which leads nowhere in the game. Use {Help Name} for cross-references.

If the page doesn't exist, the script prints the wiki's error and writes nothing, so an old .hlp file stays as it was.

Help topics: help.index

The game finds a text through vme/etc/help/strings/help.index. Each line is topic=file, for example acid ball=acidball.hlp, and the lines are grouped by their first letter between :start:a and :end:a, :start:b and :end:b, and so on. Several topics may share a file: aggressive mode, peace and peaceful all show peace.hlp.

help <words> (the do_help program in vme/zone/helpzon.zon) reads the section for the first letter of what you typed, and shows the first topic there that starts with it: help acid b finds acid ball. help topics lists every topic in the index. Below the text, the game adds a link to the page on this wiki, named after the file: peace.hlp links to Help/Peace.

A topic outside its letter's :start:/:end: lines, or in another letter's section, is never found.

The game reads the index and the .hlp file from disk each time someone asks for help, so a new or changed file is shown at once, without a reboot. The directory comes from the help zone's line in vme/etc/zonelist (../etc/help, relative to vme/bin); the files are in its strings/ directory.

Adding a help page

  1. Write the page here, Help/<Name>, with a capital first letter. On this wiki the part after Help/ is case-sensitive: Help/berserk and Help/Berserk are two pages, and the game's link to the wiki always capitalises the file name.
  2. Add python3 getwikihelppage.py <Name> to vme/etc/help/fetchallpages.sh.
  3. Fetch it into vme/etc/help/strings/.
  4. Add its topics to help.index, each in its letter's section.
  5. Commit the script, the index and the .hlp file, and open a pull request.

The help pages