Style and content of help-pages in Icewind

by Ghorwin, September 2000

Documentation is important! Every command should have a complete and correct help-file and every mudlib function should have a man-page. Apart from the pure availability of help-pages it is very useful to have a clear structure and unique appearance. The following recommendations may help to create decent help-pages which have all a unique look and a clear structure.

In general you shouldn't use tabs but spaces to indent. Four spaces are a good size for indentations. Headlines should be written in uppercase.

For example:

HEADING

    first line
    second line

The general structure should be as follows:

1. NAME

First a line with the command (and only command) in ANSI-bold and a short description, seperated by '-'

For example:

    %^BOLD%^idle%^END%^ - blocks your keyboard and forces you 
                          to idle

2. SYNTAX

The command(s) with parameters follow here. Mind the following rules for syntax-descriptions:

necessary parameters are enclosed in <>
optional parameters are additionally enclosed in []
alternative parameters are seperated by |

    idle <why> [<time>] [<player>|<message>]

This means, parameter <why> must be passed, all other parameters are optional, if parameters 'player' or 'message' are passed, only 'player' OR 'message' have to be passed.

3. DESCRIPTION

A description of the command follows.

For example:

    The command idle forces you to idle. This is extremely 
    useful for players who sometimes faint because they were 
    starving while playing in the mud.

A list of options and explainations follows.

For example:

    <why>       - specify the reason why you are idle eg. Dinner
    <time>      - specify the time in minutes your keyboard will 
                  be blocked
    <player>    - give name of player who can allow you to unidle 
    <message>   - store message someone has to tell you to 
                  unblock your keyboard

4. EXAMPLES

In this section some examples should illustrate the use of the command.

For example:

    > idle breakfast 20
    You have now 20 minutes for breakfast.

    > idle lunch ghorwin
    You have now time for lunch, until Ghorwin tells you to unidle.

    > idle homework hiya
    You have now time for homework, until someone tells you 'hiya'.

5. SEE ALSO

Here a list of all related commands has to be given.

For example:

SEE ALSO
    mudpause, unidle

Of course the command 'idle' is pure fiction. However, the following sample help-file may illustrate the style that should be used to write help-files (the ANSI codes aren't necessary - looks nicer, though). Use the ANSI - bold code for the section headers, too.

NAME
    idle - blocks your keyboard and forces you to idle

SYNTAX
    idle <why> [<time>] [<player>|<message>]

DESCRIPTION
    The command idle forces you to idle. This is extremely 
    useful for players who sometimes faint because they were 
    starving while playing in the mud.

    <why>     - specify the reason why you are idle eg. Dinner
    <time>    - specify the time in minutes your keyboard will 
                be blocked
    <player>  - give name of player who can allow you to unidle 
    <message> - store message someone has to tell you to 
                unblock your keyboard

EXAMPLES
    > idle breakfast 20
    You have now 20 minutes for breakfast.

    > idle lunch ghorwin
    You have now time for lunch, until Ghorwin tells you to unidle.

    > idle homework hiya
    You have now time for homework, until someone tells you 'hiya'.

SEE ALSO
    mudpause, unidle

last changes: June 01, 2003 - Ghorwin