====== Text Strings ======

Much of the text and color that the BBS [[server:terminal|Terminal Server]] displays (sends to a remote user-terminal) is stored as strings of CP437 text in the file: ''[[dir:ctrl]]/text.dat''.

**Notes:**\\
  * The syntax of the ''text.dat'' file is very specific and extreme caution should be taken when modifying the file (especially when dealing with strings that contain the ''%s'' printf-specifier).
  * Each line of the ''text.dat'' is limited to 255 characters (including comments), while each text string defined in the ''text.dat'' file has a maximum length of 2000 characters.
  * The original/stock ''text.dat'' strings are actually compiled (as the auto-generated ''text_defaults.c'' file) and linked into the Synchronet executable (i.e. ''sbbs.dll'' or ''libsbbs.so'') so that any strings missing (or commented-out with the ''#'' character) in a sysop's copy of ''text.dat'' will be replaced with the stock string value by default


===== Syntax =====
Each ''text.dat'' string value is defined with a string of ASCII characters between double-quote characters:
  "this is an example text.dat string"
Any text after the terminating (ending) double-quote character is ignored when the ''text.dat'' file is parsed by Synchronet. The stock ''text.dat'' file contains helpful comments includes the string numbers and IDs after the terminating quotes, but these comments are not strictly required.

The content between the double-quotes is mostly just printable ASCII characters, but may also include:
  * [[custom:Ctrl-A codes]] (e.g. to change the color of the text, if/when supported by the terminal)
  * [[custom:atcodes|@-codes]] (e.g. used to perform terminal cursor control or include external content)
  * [[wp>Printf_format_string|C printf-specifiers]] (e.g. ''%s'', ''%d'', used for dynamic variable content)
  * [[wp>Escape_sequences_in_C|C printf escape sequences]] (e.g. ''\r'', ''\n'', used for special non-printable characters)
  * Mmemonics (e.g. prompts with command keys denoted with a ''~'' character)

The syntax of the characters between the double quotations is similar to 
the C language printf() format string with an important exception: the escape sequence ''\xxx'' where ''x'' are
digits (0-9) are used to represent a character encoded with a **decimal** value, **not an octal value**. The range is
0 to 255. If for example, you wanted to set a background color (e.g. 4 for a blue background) using \1 to represent the Ctrl-A code, 
you might try to use the sequence "\14" (Ctrl-A character followed by the character ''4'') which won't work as expected; use hexadecimal encoding (e.g. "\x014") instead.

==== Escape Sequences ====

^ Sequences ^ Explanation ^
| ''\\''    | Backslash ('\') character |
| ''\?''    | Question Mark (not normally necessary) |
| ''\'''    | Single Quotation Mark |
| ''\"''    | Double Quotation Mark |
| ''\xXX''  | Embedded character in hexadecimal notation (''\x00'' through ''\xFF'') |
| ''\nnn''  | Embedded character in decimal notation (''\000'' through ''\255'') |
| ''\r''    | Carriage Return (ASCII 13) character |
| ''\n''    | Line-feed (ASCII 10) character |
| ''\t''    | Horizontal Tab (ASCII 9) character |
| ''\b''    | Backspace (ASCII 8) character |
| ''\a''    | Alarm/bell (ASCII 7) character |
| ''\f''    | Form-feed (ASCII 12) character |
| ''\v''    | Vertical Tab (ASCII 11) character |
See Also: [[wp>Escape_sequences_in_C]]

To continue a text string onto the next line of the ''text.dat'' file (e.g. to create long text strings, up to 2000 characters, from multiple shorter lines): place a backslash ('\') character immediately after the terminating double-quote character of each line, except for the last.

The order of the % specifiers (if they exist) in a ''text.dat'' line cannot be
altered. The display of %s specifiers can be suppressed by changing the ''%s'' to
''%.0s''. There are advanced Ctrl-A codes that may also be used for the suppression of text sent to users with an insufficient security level or lacking a security flag.

You can suppress the display of an entire ''text.dat'' line by simply
setting the text to a blank string (''""'').

==== Mnemonics ====

Some of the ''text.dat'' strings have characters preceded by a tilde ('~'). These strings
are referred to as mnemonics. The tilde precedes a character that is to be
highlighted for users supporting ANSI and enclosed in parenthesis for non-ANSI
users. Mnemonics are usually used for prompt strings that contain the valid key commands.
The colors to use for the highlighted characters, normal characters, and the
command character are specified in the ''[[dir:ctrl]]/attr.cfg'' file.

==== @-Codes ====

So-called [[custom:atcodes|@-codes]] may be used in many ''text.dat'' lines. With the use of the ''MENU'', ''TYPE'', ''INCLUDE'', ''EXEC'', and ''EXEC_XTRN'' @-codes, the text.dat may be enhanced with externally-loaded and potentially dynamically-changing content.

**Exception**: For security reasons, ''text.dat'' lines that contain %-specifiers **may not** also include @-codes.


===== Customize =====

Knowledge of the C programming language may be very helpful in producing the desired results. If all you want to
do is change colors of a certain text line, take care not to disturb the
arrangement of the other characters on the line. Ctrl-A codes can be preceded
by an embedded actual Ctrl-A (ASCII 0x01) character or by a '\1' 
(the C printf() escape sequence representing a Ctrl-A character).


==== Customization Methods ====
There are multiple ways to customize the contents of the ''text.dat'' file:
  - Create a ''[[dir:ctrl]]/[[text.ini]]'' file that contains a "key: value" line for each string you wish to over-ride in the ''text.dat'' file
  - Alternate-language translations of specified strings can be added to ''[[dir:ctrl]]/text.//lang//.ini'' files
  - Edit the ''text.dat'' file directly (e.g. using a text editor, but do this with care, see above)
  - Use the [[util:Baja]] ''REPLACE_TEXT'' or [[custom:JavaScript]] ''bbs.replace_text'' function to replace a single line, programmatically (e.g. in a login/logon script or command-shell)
  - Use the [[util:Baja]] ''LOAD_TEXT'' or [[custom:JavaScript]] ''bbs.load_text'' function to load an alternative ''text.dat'' file (e.g. in a login/logon script or command-shell)
  - The [[util:Baja]] ''REVERT_TEXT'' or [[custom:JavaScript]] ''bbs.revert_text'' function may be used to revert to the original set of text strings loaded from the ''text.dat'' file upon initialization

The current ''text.dat'' strings may be obtained (e.g. for display purposes) using the [[custom:JavaScript]] ''bbs.text()'' or ''system.text()'' functions. The caller must pass the 1-based index or ID of the text string they wish to obtain.

All of the ''text.dat'' IDs and index numbers can be found in:
  - The [[custom:JavaScript]] load file: ''[[dir:exec]]/load/[[https://gitlab.synchro.net/sbbs/sbbs/-/blob/master/exec/load/text.js|text.js]]''
  - Properties of the JavaScript ''bbs.text'' or ''system.text'' functions (no need to require/load the ''text.js'' file)
  - The C header file: ''[[https://gitlab.synchro.net/sbbs/sbbs/-/blob/master/src/sbbs3/text.h]]''

**Note**: The default (US-English) values of all ''text.dat'' strings are hard-coded into Synchronet (e.g. ''sbbs.dll'' or ''libsbbs.so'') so if any lines are missing from your ''text.dat'' file or the file itself is missing, the default values will be automatically used. The default string value will also be used if the corresponding line in the ''text.dat'' begins with the ''#''((octothorp or hash)) character.

** WARNING **
Make a backup of the ''text.dat'' file before you edit it. If you damage the file
syntax when editing it, Synchronet may execute erroneously or even fail to
initialize.

==== Suppressing Questions ====

The Yes/No prompts in the ''text.dat'' file may by identified by their names (in the comments) which end in a capital ''Q'' (for "Question"). Examples:
  * AnonymousQ
  * DeleteMailQ
  * DeletePostQ
  * AreYouSureQ
  * LogOffQ

These questions may be suppressed (never asked of the user) by changing the corresponding text value to a blank string (i.e. ''""''). When suppressed, the default answer to the question will be assumed by the BBS (script or program) and user will never be prompted for an answer to that particular question. The default answer may be "Yes" or "No", depending on the context of the question.

In many cases, ''Q'' or Ctrl-C (abort) may also be an acceptable answer to the question, but this will never be the default answer.

==== Suppressing Prompts ====

Many user input prompts can be defeated/disabled by setting them to blank strings. Examples:

  * HitYourBackspaceKey
  * EnterYourRealName
  * EnterYourCompany
  * EnterYourAddress
  * EnterYourZipCode
  * EnterYourPhoneNumber
===== Use Defaults =====

The default values of all the ''text.dat'' strings are stored in the Synchronet Terminal Server library (''sbbs.dll'', ''libsbbs.so'').

To use all default text strings you can either:

1. Download the ''[[https://gitlab.synchro.net/sbbs/sbbs/-/commits/master/ctrl/text.dat|text.dat]]'' revision from the Source Repository which correlates with the executables you're using and overwrite your local file, or

2. Replace (overwrite) your ''text.dat'' file with a 0-length file (each 'missing' string is replaced with the default string), e.g. (on *nix):

  cp /dev/null /sbbs/ctrl/text.dat
  
===== See Also =====
  * [[text.ini]] File
  * [[:dir:ctrl]] Directory
  * [[https://gitlab.synchro.net/sbbs/sbbs/-/raw/master/ctrl/text.dat|Current text.dat file in Git]]
  * [[:config:|Customization]]

{{tag>text.dat customization ansi}}
