Site Frontier:Editing HelpFiles
From BattletechMUX
Help files are currently edited via a web interface that can be found at http://uplink.frontiermux.com/admin/. Log in with your in-game username/password. If you are unable to do so due to permissions or account errors, please inform me (KM) and I'll get it fixed for you.
Upon logging in, you should find yourself in the admin interface. Depending on your privileges, you will see a number of sub-links leading to different areas. The help system box should be near the bottom. You'll primarily be interested in "Help topics" and "Help entries". Before we get into the nitty-gritty details of editing, we'll go over basic organization.
Contents |
Help Topics
Topics (or categories) are loose labels we apply to help entries. Not every help entry needs to have a topic, but it does help for specialized things. Topics allow us to automatically generate indexes for the players to easily browse through, and groups similar information. A given help entry can have more than one topic.
Adding Topics
You may add topics by simply going to the "Help topics" section and hitting the "Add Help topic" button in the upper right corner.
Help Entries
These are obviously individual help entries. Each has several fields:
- Name: The topic's name. This is what players will need to enter to get to the topic. Note that they can enter part of the name or all of it to get to the help file. For example, if a topic is called "Some Topic Name", players could get to it by doing a "help some", "help some top", "help some topic", or "help some topic name".
- Body: The actual body of the help entry. I'll go into details about formatting later, for now just know that it's the actual text of the help entry.
- See also: This is a list of related help topic names. For example, a page on Autocannons might have a See also value of "Weapons, Ammo, Technology". Notice that this is a comma/space separated list. It's automatically appended at the bottom of each help file.
- Topic: As mentioned earlier, this is used to group similar help topics. You may select one or more topics, or none at all.
Viewing Entries In-Game
You may currently view help entries that are in this new help system via the help2 command. help is currently pointing to the old system that's been in place for ages now, help2 is this new external DB backed system you're working with. It essentially works the same as the old help system though. For more details, see help2 help.
Editing Help Entries
Editing help entries is pretty straightforward aside from a bunch of specifics regarding the body field. We'll go into detail on this and point you to the relevant reading material.
Entry Names
Entry names can't contain any of the following characters:
[ ] ( ) { } ^ ~
If you must use a bracket of some sort, use <>'s instead. Spaces are ok to use, as is pretty much any other punctuation.
Body Text
ANSI Substitutions
This is where it gets fun. Let's start by explaining basic MUX formatting characters. If you look at help substitutions, you'll see a bunch of percent signs followed by letters. When parsed by the MUX, these sequences are replaced by certain things. The ones we're concerned with are:
%r = carriage return %t = tab character %b = space character %% = literal '%' character
Let's begin by putting these into use immediately. We can use the think command to emit things to ourselves in-game. Let's try this:
think TabTest%t%tTabtest think Carriage%rReturn think SpaceTest%bSpaceTest think A percent sign %%
This should return something like this:
TabTest Tabtest Carriage Return SpaceTest SpaceTest A percent sign %
From this you should see that each of these two-character substitutions were replaced with their equivalent values. For example, every %t was replaced with a tab, every %r was replaced by a hard return, %b was replaced by a single space, etc. We can combine these tags to give us something formatted
think Formatting Test%r-------------------------------------------%rColum1%t%tColumn2%t%tColumn3%rColum1%t%tColumn2%t%tColumn3%r%rHere's%b%b%bSpaces
This should yield something like:
Formatting Test ------------------------------------------- Colum1 Column2 Column3 Colum1 Column2 Column3 Here's Spaces
From here we'll go on to colors. This is done via the %c substitution. Check out help ansi() for a chart on the different color codes. Ignore the function syntax at the top, we'll be using the substitution instead. So, let's start by making something red:
think %crthis is read%cn
Notice that I used a %c followed by one of the characters on the chart. This will make your text red. The %cn at the end sets the color back to normal (n on the chart). This isn't normally needed unless you want to prevent bleed, for example:
think %crthis is read%cn, but this isn't
Notice how color codes bleed across words until terminated by a %cn. Also note that you can combine the color codes at the top with regular colors. For example, how about hilighted red:
think %ch%crthis is bright red
This should make a brighter, bolder red. This is generally a bit more readable on many clients than the dimmer, normal red.
Body Text Formatting
With the fun stuff out of the way, we'll get into guidelines about body text formatting now. Here are the important ones:
- Don't use excessive amounts of colors. It's good to hilight commands and the names of other help topics, but keep it clean and classy looking. Use colors to enhance readability, not to be flashy.
- There should be no blank lines in your body text box. Use %r's for line breaks. Put these at the end of paragraphs, not on a line by them self. This sounds picky, but it's a quirk of our database back-end.
- Never use any of these characters: ~ ^
- There should be no spaces at the end of each line. For example:
blah blah blah%r%r<there should be no spaces after this %r>
The best way to learn this stuff is by opening up existing help files and looking how they render with help2. If you have any questions, feel free to ask on the Royalty channel.
