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 lineThe general structure should be as follows:
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
The command(s) with parameters follow here. Mind the following rules for syntax-descriptions:
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.
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
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'.
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