The 'charconvert.conf' file is found in the Discus administration directory (alongside discus.conf). This file allows you to define the conversion of certain characters and text strings into other characters and text strings. This is useful for converting symbols into their HTML equivalents. It can also be extended to turn text patterns into emoticons.

The default 'charconvert.conf' file distributed with Discus contains several types of definitions:

• Symbol conversions: Symbols, such as & and < and >, are converted into their HTML equivalents. & becomes &amp; ... < becomes &#60; ... and > becomes &#62; .

• Escapes for formatting tags: Definition of 'escaped' formatting tags, such as using \\ to represent a backslash without having the backslash being interpreted as part of a formatting tag. This is done by converting the sequence \\ to &#92;.

• Emoticons: Definitions of conversions that will convert :) and :( and :O into graphical emoticons.

• Non-English characters: Characters from languages such as German and Spanish that are not found in the English language are converted by default into their HTML equivalents. For example, ä becomes &auml; according to the specifications of the ISO 8859 (Latin-1) character table.

The definitions contained in the charconvert.conf file are applied whenever user input is processed for posting, naming threads, or otherwise prepared for storage and display. For example, when a message is posted, the conversions in the charconvert.conf file are applied to the incoming message.

The definitions are applied in reverse when posts or other stored information is made available for editing. For example, when a message is edited, conversions in the charconvert.conf file are applied in reverse to the text of the message prior to the message being made available for editing in a text box.

The charconvert.conf file has the following possible types of lines:

• Comments: Any line starting with a '#' character is treated as a comment and is completely ignored in all character conversions.

• Blank Lines: Any blank lines are completely ignored.

• Definitions: The original and final character string are contained on the same line, along with any flags (see section on Flags below). The original character string cannot contain spaces. One or more spaces separates the original character string from the final character string.

  The following example is a definition that converts the original character string, ä, into the final character string, &uml;:

  ä  &uml;

When converting from the original into the final string, such as when posting messages, the file is read from top to bottom. When converting from the final string back to the original, such as when preparing text to edit messages, the file is read from bottom to top. All definitions in the file are processed in each case (see section on Caveats below).

The file can be edited in a number of ways:

• Manually: Transfer the charconvert.conf file to your server using ASCII mode. Open it with a plain text editor (such as Notepad or Ultra Edit) and make whatever changes are necessary. Transfer it back to your server in ASCII mode.

• Version 3.10 Template Manager: Log in to your Discus 3.10 board as the board administrator and go to Template Manager. Click the 'charconvert.conf' link and edit the file in the pop-up box. (If you do not have permission to write to the file, change permissions on the charconvert.conf file to 0777 rwxrwxrwx.)

• Version 4.00 Appearance Manager: Log in to your Discus 4.00 board as the board administrator and go to Appearance Manager. Click the 'Editor' tab and the 'charconvert.conf' link to edit the file in the pop-up box. (If you do not have permission to write to the file, change permissions on the charconvert.conf file to 0777 rwxrwxrwx.)

By appending a special "Flag" to the end of a definition, it is possible to extend the character conversion capabilities.

Interpretation Flag (version 3.10 and 4.0)

By adding the characters <| to the end of a definition, variables in your definitions will be converted to their Discus variables. Some of the variables that can be used are:

• $html_url -- board's HTML URL
• $ext -- Extension for your HTML files
• $script_url -- board's Script URL
• $cgi_extension -- board's CGI extension
• $message_url -- generally the HTML URL plus '/messages'
• $title -- title of your board

This is used in the emoticon definitions to ensure that clipart images are taken from the proper location on the board ($html_url/clipart).

Reverse-Only Flag (version 4.00.b32+ only)

By adding the characters |> to the end of a definition, the conversion will not be applied when converting from original to final, but will be applied when reverse-converting from final to original. This is useful if your board has operated for a long time with conversions in place and then you wish to change them. To ensure that old messages can still be edited, you should add |> to the end of all lines you are changing, and then create a new line for your new definition.

Forward-Only Flag (version 4.00.b35+ only)

By adding the characters <> (no space between them) to the end of a definition, the conversion will be applied only when converting user input to its final form. The conversion will not be applied converting text from its final form back to the original. This is useful if certain characters or character conversations are being blocked from appearing on the board by using character conversion to convert them to something else. DiscusWare suspects that this flag will be used only very rarely.

All conversions in the file are processed for each conversion. It is possible that a conversion defined in a previous line will affect conversions on subsequent lines. For example, consider the following:

If you were to type ( into a message in the above example, it would be converted to &#40;. The second definition of the sad-face emoticon would not occur, because :( is not the same as :&#40;.

When defining conversions, it is therefore important to consider carefully the order of items in the file, and the possibility that previous definitions can affect those further down in the file. In the example above, reversing the order of the lines would eliminate the problem. If you get unexpected displays, it is likely that this caveat is affecting your edited file.