COLOUR documentation
====================

BabbleMUD server.

Author:  Nick Gammon 
          http://www.gammon.com.au/ 

Written: 13th August 2004.

(C) Copyright Nick Gammon 2004. Permission to copy, use, modify, sell and
distribute this document is granted provided this copyright notice appears
in all copies. 


Introduction
------------

The server allows you to imbed colour codes into messages (eg. room descriptions, help text, error messages) to add to the general experience.

Caution
-------

Modern clients let players "map" ANSI colours to their own choice of displayed colours, so you should be careful about referring to actual colours. For instance, you may have chosen red text, but they may see it as blue, brown, or grey. Thus, if you said to "select the word in red" it might be confusing.

Also, some people may set their clients to a monochromatic display, be colour-blind, or be using a client that doesn't support colours. Thus, colours should only be used to enhance the experience, not as a primary form of communicating information.

Method
------

Rather than hard-coding ANSI escape sequences, which is - to say the least - tedious to do, the server will recognise special "colour sequences". These will be converted into ANSI codes at the last moment before being sent to the player, or even removed entirely if wanted.

The technique uses the special "tick" character ` which is not generally used in normal text. It is followed by a single letter to designate the colour, that letter being generally mnemonic (eg. r for red). 

There are:

Normal colours (darker)
-----------------------

`s  - silver (actually, black, but "b" is used for blue)
`r  - red
`g  - green
`y  - yellow
`b  - blue
`m  - magenta
`c  - cyan
`w  - white

Example:  This is `y YELLOW `b BLUE `m MAGENTA `X text.

Bold colours (bright)
---------------------

To get "bright" (or bold/highlighted) versions, use the capital-letter equivalents:

`S  - silver (grey)
`R  - red
`G  - green
`Y  - yellow
`B  - blue
`M  - magenta
`C  - cyan
`W  - white

Example:  This is `R BRIGHT RED `G BRIGHT GREEN `C BRIGHT CYAN `X text.

Others
------

Other special cases are to use `` to display a single ` character (eg. in help files which talk about colours), and codes to do underlining, and reset the colours to standard. The "reset" sends an ANSI (ESC [0m ) which basically tells the client to return to default colours.

``  - ` itself
`_  - underline subsequent words
`x  - reset 
`X  - reset (also empties stack)

`[   - use text in "colour_macro_start" in control file
`]   - use text in "colour_macro_end" in control file


Colour stacking
---------------

The colour outputting system allows you to "save and restore" the current colour. This is intended for places like help files or message text, where you don't necessarily know what colour the message is in, but want to change it temporarily.

`^   - push current colour(s)    (for recall by `& or `^)
`=   - use last pushed colour(s) (use but leave on stack)
`v   - pop last pushed colour(s) (remove from stack)


Example:  `r RED  `^ red saved, still red `G BRIGHT GREEN `v  RED AGAIN

The difference between `= and `v is that `= leaves the saved colour "stacked" so you can still recall it later.

For example, in writing help text, you don't necessarily know what colour the server is going to output the help text in, but you want to highlight a couple of words in white. You might do this:

`^ To leave, type `W exit `= or `W leave `v now

Breaking up this line to explain each part:

`^              - save current colour, whatever it is.
To leave, type  - this is still in the current colour
`W              - switch to bright white
exit            - the word "exit" will be in white
`=              - recall original colour from start of line
or              - the word "or" is in the original colour
`W              - switch to bright white
leave           - the word "leave" will be in white
`v              - recall original colour and remove from stack as we have finished
now.            - the word "now" is in the original colour


Macro sequences
---------------

The "macro" colours are intended to let you easily use a frequent sequence, one that is tedious to do otherwise. For instance, to emphasise a word in help text, like:  

  "To take something use the verb `[take`]."
  
In the control file (control.xml) you might define the macros as:

    colour_macro_start="*`^`W"
    colour_macro_end="*`v"

This will have the net effect that the user would see:

    To take something use the verb *take*.
    
... with the word "take" in bold white. The asterisks (which are part of the macro text) would also be substituted.

This makes writing help files easier than constantly using sequences like this:

   "To take something use the verb *`^`Wtake*`v"
   
It also lets you change your mind later about how to highlight words by simply changing the macro text. For example, you might later decide to put the word in red, not white, and change the text on each side, like this:

  To take something use the verb --> take <--.

Hopefully it goes without saying that you should not use the macro sequence itself inside the macro replacement text. Doing so would send the server into a loop.
