GTASource/rage/script/doc/overview_scripteditor/overview_scripteditor.dtx

@@Menus
<title Menus>

\ \ 

@@FileMenu
<title File Menu>
<GROUP Menus>

The File Menu contains many of the standard new, open, save,
close, and printing buttons that one would expect in a text
\or code editor.

* Menu Items *
<table>
Menu Item          \Description
-----------------  ---------------------------------------------
New...             Create a new File or Project.
Open File...       Open an existing file.
Close File         
Open Project...    Open an existing Project file.
Close Project      
Save               Saves the currently active file if changes
                    have been made. If the file is new, you will
                    be prompted for a file name and location.
Save As...         Save the currently active file with a
                    different name.
Save All           Saves any unsaved changes to project and
                    script files.
Print...           Print the currently active file.
Print Setup...     
Print Preview...   
Recent Files       List of recently closed files.
Recent Projects    List of recently closed projects.
Exit               
</table>

* Tutorials *
<link HowToCreateNewProject, Create a New Project>

@@EditMenu
<title Edit Menu>
<GROUP Menus>

This menu list contains many of the standard text and code
editing functions.

* Menu Items *
<table>
Menu Item     \Description
------------  ----------------------------------------------------
Undo          Undo the last edit. Unfortunately with
               ActiproSoftware SyntaxEditor, a selective Undo
               \History is not possible.
Redo          Redo the last edit. Unfortunately with
               ActiproSoftware SyntaxEditor, a selective Redo
               \History is not possible.
Cut           
Copy          
Paste         
Delete        
Indent        Insert a tab at the beginning of the current line.
Outdent       Remove a tab at the beginning of the current line.
Comment       Insert "// " at the beginning of the current line.
 Selection     
Uncomment     Remove "// " from the beginning of the current
 Selection     line.
Make          Convert all letters in the selection to uppercase.
 Uppercase     
Make          Convert all letters in the selection to lowercase.
 Lowercase     
Delete        Remove trailing whitespace at the end of the
 Horizontal    current line.
 Whitespace    
Bookmarks     Toggle, Next, Previous, and Clear bookmarks.
Show Line     Hide/show line numbers on the left side of the
 Numbers       document.
Insert Code   If your Code Snippets Path has been set, allows
 Snippet       you to browse and insert one of those snippets. See
               <link LanguageSettingsCategory, Language Settings Category>.
</table>

@@ViewMenu
<title View Menu>
<GROUP Menus>

The View Menu allows you to open and/or give focus to any of the dockable
windows found in the application: Project Explorer, Document Outline,
Output, Find Results, Errors, and Help.

Each window's menu item contains a drop down menu with the following items:
<table>
Menu Item   \Description
----------  --------------------------------------------------------
Show        Shows the window and gives it focus.
Center      Centers the window over the Main Window.
Dock        If the window is floating, it returns to its last known
             docked position, if any.
Float       If the window is docked, it will float in its last
             known floating position or in its default floating
             position.
</table>

@@CompilingMenu
<title Compiling Menu>
<GROUP Menus>

All of your compiling needs can be found here.



When compiling a Project, the date-time stamp of each script
\file is checked against it's compiled object files and
skipped if the object files are newer. Compiling a single
script file ignores the date-time stamp.

* Menu Items *
<table>
Menu Item     \Description
------------  ------------------------------------------------------------------------------------------
Compile       Compiles the project (or all open files if no project
 Project /     is loaded), sending progress messages to the <link OutputWindow, Output Window>.
 Compile All   Errors are directed to the <link ErrorsWindow, Errors Window>.<p/><p/>In
 Files         the case of a project, a list of all the files that
               were compiled (all the files in the project) is
               generated and saved in the project directory. It has
               the same file name as the project file, but with a
               '.scolist' extension. This list is used in a
               Post-Compile process that you can specify in the <link ProjectSettingsCategory, Project Settings Category>
               \of the Settings dialog.<p/><p/>Also, a batch file is
               saved so that you may compile your projects offline.
Recompile     Deletes the project's .sco and .scd files (or the
 Project /     \output files for all open files if no project is
 Recompile     loaded) before compiling it.
 All Files     
Compile       Compiles the current script file, sending relevant
 \File         progress and error information to the <link OutputWindow, Output Window>.
               Errors are directed to the <link ErrorsWindow, Errors Window>.
Stop          Halts the compiling process.
 Compile       
Goto Next     After a compile that has generated errors, this button
 Error         will cycle you through the line or lines in the file
               \on which a compile error occurred.
Save Before   Toggle this on to save the current script file before
 Compile       attempting to compile it.
Don't Save    Disables 'Save Before Compile'.
 Before        
 Compile       
Save All      Saves all open script files before compiling.
 Before        
 Compile       
Start Debug   Executes the Run Command specified on the <link ToolsMenuSettings, Settings>
               dialog. Performs a compile if you have edited any of
               the project's file(s) (or open files if no project is
               loaded) since the last time they were compiled.
</table>

* Tutorials *
<link HowToCompileScript, Compile a Script>

<link HowToCompileProject, Compile a Project>

@@IntellisenseMenu
<title Intellisense Menu>
<GROUP Menus>

From the MSDN Website :



"IntelliSense provides an array of options that make language
references easily accessible. When coding, you do not need to
leave the Code Editor or the Immediate Mode command window to
perform searches on language elements. You can keep your
context, find the information you need, insert language
elements directly into your code, and even have IntelliSense
complete your typing for you."



If autocomplete is enabled, a dropdown menu will appear with
a list of alphabetically matching syntax keywords when you
begin typing. Double-click the left mouse button on the
desired item, or use the arrow keys to scroll through the
list and press enter or tab to select it. Press escape to
close the dropdown menu, thus canceling autocomplete.



The list of autocomplete keywords is derived from keywords in
the current file and from files included with the USING
directive. In addition, your Compiler settings for Include
\File and Include Path will have their keywords added as
well. If a project is loaded, we also add the keywords for
every file in the project. See <link ToolsMenuSettings, Settings>
for more information. The exact behavior of the Intellisense
system is determined by your game-specific <link ParserPluginDll, Parser Plugin DLL>.



In an effort to emulate Visual Studio and plugins such as
Whole Tomato's Visual Assist X, many of the files'
Intellisense are reparsed for you. This happens the first
time a file is loaded (or reloaded). Also, it can happen
every time the file is saved and/or every time the active
\file is changed via the Document Tab. In addition, whenever
the <link ToolsMenuSettings, Settings> are updated, all
files are reparsed in case the <link CompilingSettingsCategory, Compiling Settings Category's>
Include File and/or Include Path were changed.

* Menu Items *
<table>
Menu Item      \Description
-------------  ----------------------------------------------------------
Refresh        Refreshes the Intellisense on the current file by
 Intellisense   forcing a Semantic Parse that looks for keywords and
                colors them appropriately.
Intellisense   Enables IntelliPrompt Autocomplete (if checked),
 Enabled        IntelliPrompt Struct MemberList, QuickInfo Popups
                (when the mouse hovers over keywords) and the Document
                Outline.
Autocomplete   Displays the IntelliPrompt Autocomplete list providing
 Enabled        keywords that begin with the letter typed.
Autocomplete   Keywords that are function calls will add the
 With           parentheses automatically when selected from the
 Brackets       IntelliPrompt Autocomplete list.  Also, typing ", (, [, or << will automatically add the ending pair.
Complete       When this is enabled, and the word typed matches a
 Word On        word in the IntelliPrompt Autocomplete List,
 First Match    case-insensitively,, then Complete Word is triggered. For
                \example, if the List contains "INT" and "INT_TO_ENUM"
                and the user types "int", Complete Word will replace
                "int" with "INT" and close the Autcomplete List. Complete
                Word can be triggered manually by pressing Ctrl +
                Space, or by selecting an item from the IntelliPrompt
                Autocomplete List.
Complete       When this is enabled, and only one item exists in the
 Word On        IntelliPrompt Autocomplete List, and the word typed
 Exact Match    matches case-insensitively, then Complete Word is
                triggered. This means "activate" will become
                "ACTIVATE" and, when Autocomplete With Brackets is
                enabled, "ENDACTIVATE" will also be inserted. Complete
                Word can be triggered manually by pressing Ctrl +
                Space, or by selecting an item from the IntelliPrompt
                Autocomplete List.
Complete       No Complete Word is triggered based on the words typed
 Word           by the user. Complete Word can be triggered manually
 Disabled       by pressing Ctrl + Space, or by selecting an item from
                the IntelliPrompt Autocomplete List.
Show Items     When checked, the IntelliPrompt Autocomplete list
 That           includes keywords that contain the letter(s) typed.
 Contain        
 Current        
 String         
Add Project    When this option is checked, symbols from every file
 Symbols        in the current project will be added to the
                IntelliPrompt Autocomplete list.
Add            When this option is checked, symbols from files
 IncludePath    residing in the IncludePath will be added to the
 Symbols        IntelliPrompt Autocomplete list.
Filter         This menu items in this drop down menu allow the user
                to control what kinds of language elements get added
                to the IntelliPrompt Autocomplete List. Selections
                include Constants, Subroutines, Struct Types, and
                several more.
Highlight      Not functional. May be used again at a future date.
 Enums          
Highlight      When checked, QuickInfo Popup text will be colorized
 QuickInfo      according to the current Syntax Highlighting options.
 Popups         Turn this off if your color scheme does not mesh well
                with a light yellow background.
</table>

* Tips for Improving Performance *
If you feel the text editor is performing too slowly or is
less responsive that you would like, try disabling the
following items one after the other until the performance is
acceptable:
  * Add IncludePath Symbols and/or Add Project Symbols
  * Show Items that Contain Current String
  * Autocomplete Enabled
  * Intellisense Enabled

On certain single core machines, or machines without
hyper-threading capability, it may be advantageous to disable
a couple of advanced <link ToolsMenuSettings, settings>:
  * Parsing Service enabled during Project loads. See <link ProjectSettingsCategory, Project Settings>.
  * Parsing Service enabled during File editing. Set <link FileSettingsCategory, File Settings>.

@@SearchMenu
<title Search Menu>
<GROUP Menus>

The Search menu contains the most common functionality for
searching your documents for words and phrases.

* Menu Items *
<table>
Menu Item                                                          \Description
-----------------------------------------------------------------  -------------------------------------------------
Use new Find/Replace dialog
<link SearchMenuFindReplace, Find/Replace...>                  Launches the Find/Replace window for searching
                                                                    the current selection (if a file is open), the
                                                                    current file (if there is one), all open
                                                                    documents, or the entire project (if one is
                                                                    loaded).
Use new Find/Replace in Files dialog
<link SearchMenuFindReplaceInFiles, Find/Replace In Files...>   Launches the Find/Replace In Files window for
                                                                    searching the current file, open files, files in
                                                                    the project and/or files in a specified
                                                                    directory.
Goto Next                                                          After a Find/Replace in Files operation has
 Find Result                                                        filled the Output window with results, this
                                                                    button will cycle through them.
Incremental                                                        An incremental search will find the first
 Search                                                             matching pattern of characters past the cursor
                                                                    as you type them.
Reverse                                                            Same as incremental search except it finds the
 Incremental                                                        first match before the cursor.
 Search                                                             
Go To Line...                                                      Launches a dialog box where you enter the
                                                                    desired line number to place the cursor on.
Go To                                                              In the current open file and context, locates
 Definition                                                         the definition of the keyword underneath or
                                                                    right before the cursor.
</table>


@@SearchMenuFindReplace
<title Find/Replace>
<GROUP SearchMenu>

This dialog provides most of the same functionality as
Microsoft Visual Studio .NET's Find dialog with the Replace
functionality. When you launch the dialog box, It will
attempt to seed the 'Find what' text box with one of the
following:
  * Highlighted text if no newline character is found.
  * The word (separated by white space) found at the current
    cursor position, if any.
  * The last search text if the first two options fail.

* Search Options *
<table>
Option        \Description
------------  ------------------------------------------------------
Match Case    Perform a case-sensitive search.
Match Whole   Only match letters/words separated by white space
 Words         characters.
Search Up     When unchecked, searches down the document from the
               current cursor position. Otherwise searches up.
Use           Use Regular Expressions
Mark with     Not allowed on an Entire Project search. When checked
 Bookmarks     and the Mark All button is pressed, will mark any
               line that has the search text with a blue box,
               similar to Microsoft Visual Studio .NET. When not
               checked, will underline each occurrence found.
</table>

* Search Filter *
<table>
Filter      \Description
----------  ------------------------------------------------
Current     Search is confined to the highlighted text.
 Selection   
Current     Search through the current active script file.
 Document    
All Open    Search through all open script files.
 Documents   
Entire      Searches through all files found in the current
 Project     project (if any), plus all open documents not
             found in the project. <b>Replace All cannot be
             undone if this is selected.</b>
</table>

* Buttons *
<table>
Button        \Description
------------  ----------------------------------------------------------
Find          Highlights the next occurrence of the search text. After
               the initial find, acts like a Find Next. Enabled when
               text is entered in the 'Find what' box.
Replace       Replaces the search text with the replacement text, then
               finds the next occurrence. Enabled when text is entered
               in the 'Replace with' box
Replace All   Replaces all occurrences of the search text with the
               replacement text. <b>This process cannot be reversed if
               'Entire Project' is selected. </b>Enabled when text is
               entered in the 'Replace with' box.
Mark All      Places a bookmark next to each line with an occurrence of
               the search text. Enabled when text is entered in the
               'Find what' box, and anything but 'Entire Project' is
               selected.
Close         Closes the dialog
</table>


@@SearchMenuFindReplaceInFiles
<title Find/Replace in Files>
<GROUP SearchMenu>

Like the Find/Replace dialog, this dialog also provides most
\of the same functionality as Microsoft Visual Studio .NET's
Find in Files dialog with the Replace functionality. When you
launch the dialog box, It will attempt to seed the 'Find
what' text box with one of the following:
  * Highlighted text if no newline character is found.
  * The word (separated by white space) found at the current
    cursor position, if any.
  * The last search text if the first two options fail.

The line(s) in each file that contain the search text will
fill the Output Window.



<b>Search Options</b>
<table>
Option          \Description
--------------  -------------------------------------------------
Match Case      Perform a case-sensitive search.
Match Whole     Only match letters/words separated by white
 Words           space characters.
Look in         When searching a directory, indicates whether to
 Subfolders      recursively search subfolders.
\File Types     Filter what type(s) of files to search in.
                 Separated by semi-colons.
Open modified   When performing a Replace All, all files in
 files after     which replacements occurred will be opened after
 Replace All     the operation has completed.
</table>

<b>Search Filter</b>
<table>
Filter      \Description
----------  ------------------------------------------------
Current     Search through the current active script file.
 Document    
All Open    Search through all open script files.
 Documents   
Entire      Searches through all files found in the current
 Project     project (if any), plus all open documents not
             found in the project.
\<User      Type or browse for a folder to search in. The
 defined\>   search will also include all open documents and
             project files.
</table>

<b>Buttons</b>
<table>
Button        \Description
------------  ------------------------------------------------------------------
Find          Searches for the text and displays the results in the
               \Output Window.. Enabled when text is entered in the
               'Find what' box.
Find Next     Finds the next occurrence in the current file. When the
               end of the file is reached, opens the next file and
               highlights the search text.
Replace       Replaces the search text with the replacement text, then
               finds the next occurrence. Enabled when text is entered
               in the 'Replace with' box
Replace All   Replaces all occurrences of the search text with the
               replacement text. <b>This process cannot be reversed. </b>Enabled
               when text is entered in the 'Replace with' box.
...           Browse for a folder to search in.
Stop          Halt the current search.
Close         Closes the dialog
</table>

@@SearchMenuRegularExpressions
<title Regular Expressions>
<GROUP SearchMenu>

The SyntaxEditor regular expression engine accepts an
extensive set of regular expression elements that enable you
to efficiently search for text patterns.



This section details the set of characters, operators, and
constructs that you can use to define regular expressions.



Whitespace characters are ignored in all regular expression
patterns. Use the \\s character class to indicate whitespace
matching.

* Character Escapes *

Most of the important regular expression language operators
are unescaped single characters. The escape character \\ (a
single backslash) signals to the regular expression parser
that the character following the backslash is not an
\operator. For example, the parser treats an asterisk (*) as
a repeating quantifier and a backslash followed by an
asterisk (\\*) as the Unicode character <i>\\u002A</i>.

<table>
Escaped       \Description
 Character     
------------  --------------------------------------------------------
(Ordinary     Characters other than <i>. $ ^ { [ ( | ) * + ? \\</i>
 characters)   match themselves.
\\a           Matches a bell (alarm) <i>\\u0007</i>.
\\t           Matches a tab <i>\\u0009</i>.
\\r           Matches a carriage return <i>\\u000D</i>.
\\v           Matches a vertical tab <i>\\u000B</i>.
\\f           Matches a form feed <i>\\u000C</i>.
\\n           Matches a new line <i>\\u000A</i>.
\\e           Matches an escape <i>\\u001B</i>.
\\040         Matches an ASCII character as octal (exactly three
               digits). The character <i>\\040</i> represents a space.
\\x20         Matches an ASCII character using hexadecimal
               representation (exactly two digits).
\\u0020       Matches a Unicode character using hexadecimal
               representation (exactly four digits).
\\            When followed by a character that is not recognized as
               an escaped character, matches that character. For
               \example, <i>\\*</i> is the same as <i>\\x2A</i>.
</table>

* Character Classes *

The following table summarizes character matching syntax.

<table>
Character     \Description
 Class         
------------  -------------------------------------------------------
.             Matches any character except <i>\\n</i>. When within a
               character class, the <i>.</i> will be treated as a
               period character.
[aeiou]       Matches any single character included in the specified
               set of characters.
[^aeiou]      Matches any single character not in the specified set
               \of characters.
[0-9a-fA-F]   Use of a hyphen (<28>) allows specification of
               contiguous character ranges.
\\w           Matches any word character, which includes letters,
               digits, and underscores.
\\W           Matches any non-word character.
\\s           Matches any whitespace character.
\\S           Matches any non-whitespace character.
\\d           Matches any decimal digit.
\\D           Matches any non-digit.
[.\\w\\s]     Escaped built-in character classes such as <i>\\w</i>
               and <i>\\s</i> may be used in a character class. This
               \example matches any period, word or whitespace
               character.
</table>

* Quantifiers *

Quantifiers add optional quantity data to a regular
expression. A quantifier expression applies to the character,
group, or character class that immediately precedes it.



The following table describes the metacharacters that affect
matching quantity.

<table>
Quantifier   \Description
-----------  -------------------------------------------------------------
\*           Specifies zero or more matches; for example, <i>\\w*</i>
              \or <i>(abc)*</i>. Same as <i>{0,}</i>.
\+           Specifies one or more matches; for example, <i>\\w+</i>
              \or <i>(abc)+</i>. Same as <i>{1,}</i>.
?            Specifies zero or one matches; for example, <i>\\w?</i>
              \or <i>(abc)?</i>. Same as <i>{0,1}</i>.
{n}          Specifies exactly n matches; for example, <i>(pizza){2}</i>.
{n,}         Specifies at least n matches; for example, <i>(abc){2,}</i>.
{n,m}        Specifies at least n, but no more than m, matches.
</table>

* Atomic Zero-Width Assertions *

The metacharacters described in the following table do not
cause the engine to advance through the string or consume
characters. They simply cause a match to succeed or fail
depending on the current position in the string. For
instance, <i>^</i> specifies that the current position is at
the beginning of a line or string. Thus, the regular
expression <i>^#region</i> returns only those occurrences of
the character string <i>#region</i> that occur at the
beginning of a line.

<table>
Assertion   \Description
----------  ---------------------------------------------------------------------
^           Specifies that the match must occur at the beginning of
             the document or the beginning of the line.
$           Specifies that the match must occur at the end of the
             string, before <i>\\n</i> at the end of the string, or at
             the end of the line.
\\A         Specifies that the match must occur at the beginning of
             the document.
\\z         Specifies that the match must occur at the end of the
             document.
\\b         Specifies that the match must occur on a boundary between <i>\\w</i>
             (alphanumeric) and <i>\\W</i> (nonalphanumeric)
             characters.
\\B         Specifies that the match must not occur on a <i>\\b</i>
             boundary.
</table>

* Grouping Constructs *

Grouping constructs allow you to capture groups of
subexpressions and to increase the efficiency of regular
expressions with noncapturing lookahead and lookbehind
modifiers.

<table>
Construct   \Description
----------  --------------------------------------------------------------------
( )         Captures the matched substring if used in a find/replace
             \operation. In lexical parsing, provides non-captured
             grouping. Find/replace captures using <i>( )</i> are
             numbered automatically based on the order of the opening
             parenthesis, starting from one. The first capture, capture
             element number zero, is the text matched by the whole
             regular expression pattern.
(?= )       Zero-width positive lookahead assertion. Continues match
             \only if the subexpression matches at this position on the
             right. For example, <i>_(?=\\w) </i>matches an underscore
             followed by a word character, without matching the word
             character.
(?! )       Zero-width negative lookahead assertion. Continues match
             \only if the subexpression does not match at this position
             \on the right. For example, <i>\\b(?!un)\\w+\\b</i> matches
             words that do not begin with <i>un</i>.
(?\<= )     Zero-width positive lookbehind assertion. Continues match
             \only if the subexpression matches at this position on the
             left. For example, <i>(?\<=19)99</i> matches instances of <i>99</i>
             that follow <i>19</i>.
(?\<! )     Zero-width negative lookbehind assertion. Continues match
             \only if the subexpression does not match at this position
             \on the left.
</table>

* Substitutions *

Substitutions are allowed only within find/replace
replacement patterns.



Character escapes and substitutions are the only special
constructs recognized in a replacement pattern. For example,
the replacement pattern <i>a*$1b</i> inserts the string <i>a*</i>
followed by the substring matched by the first capturing
group, if any, followed by the string <i>b</i>. The <i>*</i>
character is not recognized as a metacharacter within a
replacement pattern. Similarly, <i>$</i> patterns are not
recognized within regular expression matching patterns.
Within regular expressions, <i>$</i> designates the end of
the string.



The following table shows how to define named and numbered
replacement patterns.

<table>
Construct   \Description
----------  ---------------------------------------------------------
$1          Substitutes the last substring matched by group number 1
             (decimal). The second group is number 2 (<i>$2</i>), and
             so on.
$0          Substitutes a copy of the entire match itself.
$&          Substitutes a copy of the entire match itself.
$$          Substitutes a single <i>$</i> literal.
</table>

* Other Constructs *

The following table lists other regular expression
constructs.

<table>
Construct   \Description
----------  ---------------------------------------------------------------------
" "         Encapsulates a fixed string of characters.
{ }         Provides a call to a lexical macro. The use of a WordMacro
             (which is similar to <i>\\w</i>) would appear as <i>{WordMacro}</i>.
(?# )       Inline comment inserted within a regular expression. The
             comment terminates at the first closing parenthesis
             character.
|           Provides an alternation construct that matches any one of
             the terms separated by the <i>|</i> (vertical bar)
             character. For example, <i>cat|dog|tiger</i>. The leftmost
             successful match wins.
</table>

@@OutliningMenu
<title Outlining Menu>
<GROUP Menus>

Outlining provides a way to selectively hide blocks of code
to make working with a large file more manageable.

* Menu Items *
<table>
Menu Item     \Description
------------  -----------------------------------------------------------
Start         Turns on Automatic Outlining. Plus/minus boxes on
 Automatic     the left side of the document appear next to each
 Outlining     block of code, according to the methods in your
               game-specific <link ParserPluginDll, Parser Plugin DLL>.
Start         Turns on Manual Outlining. Now you can specify
 Manual        your own expandable and collapsable blocks of
 Outlining     code.
Stop          Turns off Outlining. All plus/minus boxes on the
 Outlining     left side of the document disappear.
Hide          Manual Mode only. Highlight a block of code and
 Current       select this option to create a code block and
 Selection     collapse it.
Stop Hiding   Manual Mode only. Expands the collapsed code block
 Current       immediately to the right of the cursor.
Toggle        Collapses or expands the code block closest to the
 Outlining     cursor.
 Expansion     
Toggle All    Collapses or expands all outlined code blocks.
 Outlining     
</table>

@@ToolsMenu
<title Tools Menu>
<GROUP Menus>

* Menu Items *
<table>
Menu Item      \Description
-------------  -----------------------------------------------------------
Macro Menu     See <link ToolsMenuMacros, Macros>
 Items
Settings...	   See <link ToolsMenuSettings, Settings>
Highlighting   See <link ToolsMenuHighlightingStyleEditor, Highlighting Style Editor>
  Style
  Editor...
Custom         See <link ToolsMenuCustomButtonManager, Custom Button Manager> 
 Button
 Manager...
View Log       View the program execution log.
Previous       This dropdown menu stores the last 10 program execution logs.
 Logs
</table>

* A note about logs *

The log files are stored in <i>%TEMP%/ragScriptEditor</i>.  They contain a record of
many of the high-level operations that the Script Editor performs.  Dialog boxes,
handled exceptions, and unhandled exceptions are all logged to this file.  The log
is automatically included when submitting bugs with the Submit Feedback Dialog 
(see <link HelpMenu, Help Menu>) and the Unhandled Exception Dialog.

Additional logging information may be stored by adding the <i>-admin</i> command line
parameter when launching the ragScriptEditor.exe executable.  This additional information
includes SanScriptIdentifierCache operations.  Be warned:  there is a steep performance penalty.

@@ToolsMenuMacros
<title Macros>
<GROUP ToolsMenu>

Macros Recording is a new feature for version 1.8.x of the
Script Editor. It allows the user to record any text editing
\operations performed on an open file and play back that
sequence of steps repeatedly. Currently, only one recording
is allowed. Additionally, mouse input is ignored during
recording.

* Menu Items *
<table>
Menu Item                \Description
-----------------------  ----------------------------------------
Record Temporary Macro   Begins recording a new temporary macro.
Play Temporary Macro     Plays the last macro recorded.
Cancel Recording         Cancels a macro recording operation.
</table>

Additional Functionality is provided on the Macro Toolstrip.

* Toolstrip Button Items *
<table>
Button Item             \Description
----------------------  -----------------------------------------
Record Macro            Begins recording a new temporary macro.
Pause Macro Recording   Pauses the recording.
Stop Macro Recording    Ends the recording, allowing you to play
                         the macro.
Cancel Macro            Cancels a macro recording operation.
 Recording               
Play Macro              Plays the last macro recorded.
</table>


@@ToolsMenuSettings
<title Settings>
<GROUP ToolsMenu>

The Settings dialog allows you to customize some of your
experience with the Script Editor. It contains several categories:
Projects, Files, Toolbar, and Compiling, Language, and Source Control.

Each category contains a "Reset to Defaults" button.  Clicking this will reset
the options in that category to the states defined by the current language (the project loaded,
or the type of the active file when the Settings dialog was opened, or the language of 
the specific Compiling sub-cateogory or Language category).  The change will not fully take effect
until the OK or Apply button is clicked.  See <link ParserPluginDll, Parser Plugin DLL>.

@@ProjectSettingsCategory
<title Project Category>
<GROUP ToolsMenuSettings>

\ \ 
<table>
Item           \Description
-------------  ------------------------------------------------------------------
Reload last    When checked, if a project file was loaded when the
 project        editor was last closed, it will be reloaded the next
                time you start the editor.
Close          With this checked, all open files that belong to the
 project        Project will be closed when the Project is closed.
 files when     
 Project        
 closes         
Clear          Removes all project files from the <link FileMenu, Files>
 Recent         Recent -\> Projects list.
 Projects       
Automatic      When checked, any files and folders that are moved or
 Sorting        added to the Project will be ordered alphabetically. If
                the folder to which you are adding the item(s) is not
                already sorted, the new item(s) will be added
                alphabetically from the top down. In this case, it is
                possible to have a partially sorted folder.
Post-Compile   A command line program to run after a project has been
 Command        compiled with no errors. Use the '...' button to browse
                for a command. You can add whatever command line
                argument(s) you want. Quotation marks are not allowed,
                so all command(s) and arguments must <i>not</i> contain
                any spaces in their path names.<p/><p/>After a
                successful project compile, a text file of all files
                that were compiled is generated. This file is appended
                to the end of the Post-Compile Command line so that you
                may use it at your discretion.
Start Debug    This command is executed when the <link CompilingMenu, Compiling>
 Command        \-\> Start Debug menu item is selected. If any of the
                project's files have been edited since the last project
                compile, the project will be compiled first before
                proceeding. The same formatting rules as the
                Post-Compile Command apply here as well.
Enable         When checked, the threaded Parsing Service is enabled,
 Semantic       allowing a minimal amount of user interaction during a
 Parsing        project's load, including the ability to see the number
 Service        \of files left to be parsed. This option is disabled by
 during         default on single-core, non-hyper-threaded machines to
 project        improve load times. Disabling this on mulit-core
 load           machines may also provide the same benefit.
</table>

@@FileSettingsCategory
<title Files Category>
<GROUP ToolsMenuSettings>

\ \ 
<table>
Item          \Description
------------  ------------------------------------------------------
Reload last   When checked, all files that were loaded when the
 files at      editor was last closed, will be reloaded the next
 startup       time you start the editor.<p/><p/>Also, all files
               belonging to a project that were open when you last
               closed the project (or closed the editor with a
               project open), will be loaded when that project is
               loaded. Even if this is unchecked, the project will
               still remember which file(s) it last had open.
Clear         Removes all files from the <link FileMenu, Files> -\>
 Recent        Recent Files list.
 Files         
Middle        When this is enabled, clicking the middle mouse
 mouse         button on the file's tab will close the file.
 button        
 closes file   
Enable        When checked, the threaded Parsing Service is enabled
 Semantic      allowing a smoother experience when typing with
 Parsing       Intellisense. Disabling this will likely hinder the
 Service       user's ability to type with Autocomplete enabled, but
 during File   may improve performance on a single core computer
 editing       without hyper-threading capability.
</table>

@@ToolbarSettingsCategory
<title Toolbar Category>
<GROUP ToolsMenuSettings>

\ \ 
<table>
Item         \Description
-----------  ----------------------------------------------------------
Remember     When checked, all buttons that were invisible when
 button       you last closed the editor will be Hidden the next
 visibility   time you open the editor. Even if this is unchecked,
              the editor will still remember which buttons were
              hidden and which were shown.
Clear        Delete any custom buttons that have been created. Changes
 Custom       will not take effect until the OK or Apply button is
 Buttons      clicked.
Reset        Resets the visibility of each button its their
 Visibility   default state. Changes will not take effect until the
              OK or Apply button is clicked.
</table>

@@CompilingSettingsCategory
<title Compiling Category>
<GROUP ToolsMenuSettings>

This category contains a sub-node for each language defined
for the Script Editor. Each sub-node displays an array of
compiling options specific to that language.



Every sub-node contains the same basic set of options:

<table>
Item            \Description
--------------  -------------------------------------------------------
Break on        Halts the compiling process on the first file with
 error           errors found.
Open Files      When checked, files that contain errors will be opened
 With Errors     and their errors highlighted during the compile
                 process.
Configuration   This combo box allows the user to select which
                 Configuration to view or edit.
\+              Adds a new configuration after the user is prompted to
                 provide a name. The new configuration is initialized
                 with the currently selected configuration.
\-              Permanently remotes the currently selected
                 configuration after a confirmation dialog.
Include         Sends the -include argument to the compiler.
 \File           
Include         Adds the -ipath argument to the compiler. The include
 Path            path can contain more than one item as long as there
                 are no spaces, with a semicolon separating each one.
Compiler        The executable for the script compiler, or a batch
 Executable      \file that calls it.
\Output         Set this to save output files (.sco and .scd) to a
 Directory       different directory from where the source files (.sc)
                 reside. This can be path-rooted or relative to the
                 currently loaded project (or the file if no project is
                 loaded).
</table>

* SanScript Compiling Settings *
These additional options are available to the SanScript
language:

<table>
Item          \Description
------------  -------------------------------------------------------
Debug         Turn on debugging output text during compilation.
 Parser        
Dump Thread   Display the thread state during the compile.
 State         
Display       Show the disassembly after the compile finishes.
 Disassembly   
Enable HSM    Enables the new Hierarchical State Machine features of
               the SanScript compiler.
Dependency    Check this to output a text file containing each
 \File         \file's dependencies. While the text box is blank by
               default, the compiler itself defaults to the
               equivalent of "%~n1.d".
Native File   Check this to output a text file containing a list of
               all of the NATIVE functions called by a file.
               ".native.txt" will be automatically appended by the
               compiler.
Globals       Specifies where global variables are stored. If not
 \File         path-rooted, this file will be saved in the Output
               Directory.
Custom        Enter your own custom commands and keywords here. Use
               '%1' to reference the current file that is being
               compiled when this command executes.
</table>

Each Text Box accepts file arguments similar to the way in
which batch files can be passed argument that is a file and
that argument can be interpreted as a file name, path,
directory root, file name without extensions, etc.. Here is a
complete list of supported file arguments:

<table>
\File      \Description
 Argument   
---------  --------------------------------------------------------
%1         Represents the script file being compiled. We always
            pass in the fully qualified path name of the file.
%~1        Removes the quotes around a fully qualified path name
%~f1       Fully qualified path name (t:\\rage\\assets\\script.sc)
%~d1       Directory root (c:, d:, etc.)
%~p1       Path (\\rage\\assets\\)
%~n1       \File name without the extension
%~x1       \File extension
%~a1       \File attributes (--a------)
%~t1       Last date/time the file was written to
%~z1       Size of the file
%~dp1      Directory root and path name (c:\\rage\\assets)
%~nx1      \File name and extension
%~ftza1    DIR-like output line (--a------ 06/15/2006 11:24 AM 73
            c:\\test.txt)
</table>

For example, in the sample script project <i>t:\\rage\\assets\\sample_scr_generic\\sample_scr_generic.scproj</i>,
we have Globals set to %~n1.sgv which will cause our globals
\file to be saved with the same name as the script that
contains them, but with the sgv extension. Since the global
variables can be found in <i>demo.sc,</i> the globals file is
saved as <i>demo.sgv</i>. in the output directory which
happens to be the same directory as the project.

@@LanguageSettingsCategory
<title Language Category>
<GROUP ToolsMenuSettings>

This category contains a sub-node for each language defined
for the Script Editor. Each sub-node displays an array of
compiling options specific to that language.



Every sub-node contains the same basic set of options:

<table>
Item        \Description
----------  ------------------------------------------------------------------------------------------------------------------
Save        Saves the settings file associated with the game-specific
 Default     Parser Plugin DLL for the current file type in the
 Settings    editor. You will be prompted to confirm before the save
 \File       takes place. Only available in Admin Mode. See <link HowToCreateDefaultSettings, Create a Default Settings File>.
Load        Loads the settings file associated with the game-specific
 Default     Parser Plugin DLL for the current file type in the
 Settings    editor.<p/><p/>Loading the setting file does not
 \File       automatically overwrite your current settings, but merely
             makes a "new" set of defaults available to revert to with
             each Setting Category's "Reset to Defaults" button. You
             are prompted if you want to make the default settings
             your current settings. The Compiling and Language
             settings for other languages remain untouched.
Clear       Deletes all files in the Cache Directory.
 Cache             
Cache       To improve performance, Language Parsers often store
 Directory   settings out to disk for faster retrieval than by
             reparsing each file in its entirety. This option
             specifies where those data files gets saved.<p/><p/>By
             default, the directory is
             %HOMEDRIVE%%HOMEPATH%\\\<languageName\>IdentifierCache.
             If an error occurs trying to retrieve either of the
             Environment Variables, %TEMP% is used in their place. If
             the Environment Variables exist, but the directory they
             form does not, C:\\ is used.<p/><p/>When making a change.
             the user is asked if they want to move the files from the
             previous Cache Directory into the new one.
Code        Semicolon-separated folder paths to script files
 Snippet     containing code which can be inserted with the Insert
 Path        Code Snippet option found on the <link EditMenu, Edit Menu>.
</table>

* SanScript Language Settings *
These additional options are available to the SanScript
language:

<table>
Item        \Description
----------  ---------------------------------------------------
Language    Specifies the language's help file. By default,
 Help File   this is defined by Rage and packaged with the
             Script Editor.
Reference   Specifies the language's Reference help file which
 Help File   contains a listing of all NATIVE items in the
             language.  This is typically defined per project.
</table>

* Tutorials *
<link HowToCreateDefaultSettings, Create a Default Settings File>

@@SourceControlSettingsCategory
<title Source Control Category>
<GROUP ToolsMenuSettings>

Source Control through Alien Brain and Perforce has been
integrated into the Script Editor. When it is enabled, you
will be able to check out files that are under source
control. Currently, there is no support for checking in.



The default for each of the check-out actions below may not
be the most desirable or useful, but they do reflect the way
the Script Editor originally behaved for read-only files.

<table>
Item         \Description
-----------  ---------------------------------------------------
Enabled      Turns on source control integration and enables
              editing of the items below.
Server       Specifies the Alien Brain server where your files
              reside.
Project      The name of the project on the Alien Brain server.
Login Name   Login Name to use to check out files. The default
              is "ReadOnly".
When         What to do when you start to edit a file under
 checked-in   source control for the first time and the file is
 script       checked in:
 files are    * Prompt to check out
 edited       * Automatically check out
              * Do nothing (default)
When         What to do when you save a file under source
 checked-in   control that is checked in:
 script       * Prompt to check out (default)
 files are    * Automatically check out
 saved        * Save as a new file
When         What to do with the compiler output files that are
 checked-in   checked-in under source control:
 \output      * Prompt to check out
 files are    * Automatically check out
 compiled     * Automatically overwrite the file (default)
</table>

@@ToolsMenuHighlightingStyleEditor
<title Highlighting Style Editor>
<GROUP ToolsMenu>

The Highlighting Style Editor is for customizing the syntax
coloring of your script files. You can change the overall
background color, as well as the foreground and background
colors of each syntax item. Your game-specific <link ParserPluginDll, Parser Plugin DLL>
determines the default colors.

* Text Background Color *
This is the color that fills all space apart from the text.
Select from Custom, System, and Web colors.

* Languages *
Select which language to customize the syntax coloring.

* Display Items *
The list of syntax items that you can choose the color for.
For each item, you can customize the following:
  * Foreground color
  * Background color
  * Bold
  * Italic
  * Underline


@@ToolsMenuCustomButtonManager
<title Custom Button Manager>
<GROUP ToolsMenu>

This dialog box is for viewing, creating, editing, and
deleting your own tool bar buttons. Your custom buttons are
saved with your layout file so they are persistent across
sessions with the Script Editor. Additionally, your game's
lead Scripter can create default custom buttons for everyone
\on their team. See <link HowToCreateDefaultSettings, Create a Default Settings File>.

* List Pane *
On the top half of the dialog, you can view a list containing
all the custom buttons you've created. Highlight one to view
it's details in the lower pane. Use the 'Move Up' and 'Move
Down' buttons to change it's position in the list.



Press 'Edit' to change any of it's details. Press 'Delete' to
permanently remove it. Press 'New' to create an entirely new
custom button.

* View/Edit Pane *
Below the List Pane, is the View/Edit Pane where you can see
the details for a button.



Name: The name of the custom button.

This becomes the tool tip you see when hovering over the
button on the tool bar.



Icon: The icon to use for the button.

The best icons to use are 16 x 16 pixels. We store a
reference to your icon file and load it each time you launch
the Script Editor, so if the original file is moved or
deleted, it will not show up on the tool bar or in the Custom
Button Manager.



Command: The command to execute when clicked.

You can type in the command to call, or browse for it. We
support any command that can normally be called from the
command line. This includes:
  * System programs (like notepad) and programs in your path
    (like rag), with or without arguments
  * File types registered with a program
  * Other executables with any number of arguments as long as
    the path does <i>not</i> contain spaces
<code>
notepad c:\\myfile.txt
c:\\myfile.txt
c:\\soft\\rage\\base\\samples\\mysample.exe -rag -cammachdebug
</code>

To help ensure unwanted changes, you must press the 'Accept'
button to make your changes permanent. However, your personal
layout file is not saved until you exit the Script Editor

* Tutorials *
<link HowToCreateCustomButton, Create a Custom Button>

@@WindowMenu
<title Window Menu>
<GROUP Menus>

Items in this menu allow you to split the current script into
multiple views so you can independently scroll through
different sections of the same file.

* Menu Items *
<table>
Menu Item            \Description
-------------------  ------------------
Split Horizontally   
Split Vertically     
Split Four-Way       
No Splits            Remove all splits
</table>

@@HelpMenu
<title Help Menu>
<GROUP Menus>

* Menu Items *
<table>
Menu Item       \Description
--------------  ---------------------
Contents        Select this menu item or press F1 to view this help file.
Language Help   A list of language-specific help files for the various Parser Plugins will appear here.
 File(s)
Submit          Opens a dialog that allows you to report bugs, make comments or suggestions,
 Feedback...     and provide general feedback.  The various settings and log files used by
                 the program will be included in the submission to aid in bug reporting.
About           Displays copyright information and the version number of the program.
</table>


@@ParserPluginDll
<title Parser Plugin DLL>
<toctitle Parser Plugin DLL>

This user-definable plug-in serves several purposes.
  * It provides a syntax definition for a language used by
    the Script Editor.
  * It defines the <link CompilingSettingsCategory, Compiling>
    and <link LanguageSettingsCategory, Language> classes used by
    the language, and their corresponding User Interface elements
    for the <link ToolsMenuSettings, Settings> Form.
  * It specifies the default options for users programming in
    the language.

We have implemented the SanScriptParser, CSharpParser, and
XmlParser plug-ins as examples.

* Syntax Definition *
A Syntax Definition consists of a Lexical Parser and an
\optional Semantic Parser.



Lexical Parsing breaks a document up into tokens, or
keywords, that can be colorized (also know as syntax
highlighting) for better readability. Language keywords,
colors, and strings are typically tokenized.



Semantic Parsing consists of analyzing the results of the
Lexical Parse to give meaning to groups of tokens. For
\example, identifying a function declaration. Defining a
Semantic Parser is essential in order to enable <link IntellisenseMenu, Intellisense>
and <link OutliningMenu, Outlining> features, but it is not
required. Intellisense features include Autocomplete,
IntelliPrompt, and Info Tips.

* Compiling and Language Settings *
Each Parser Plug-in must derive from CompilingSettings and
LanguageSettings to provide the language-specific options
that are not included in the base class. The
CompilingSettings class is for providing control over the
command line options that are passed to the Compiler. A
derived LanguageSettings class typically adds options for
specifying the Help File for the language.

* Default Options *
Each Parser Plug-in must also derive from
LanguageDefaultEditorSettingsBase to override methods that
allow the editor to create and manipulate the
language-derived CompilingSettings and LanguageSettings
classes. You may also add additional fields, as well. On the <link ToolsMenuSettings, Settings>
Form's Language category for a specific language, is a button
to Save and Load a Default Settings File. You must run the
Editor with "-admin" on the command line to be able to save.
These buttons allow you to save or load a default settings
\file that will be automatically loaded at startup.
Regardless of the existence of this file, your derived
LanguageDefaultEditorSettingsBase class will be used to reset
settings to their default states when commanded to do so.



For the SanScript language, teams typically define an options
\file that contains Code Snippet Folders, Include Paths, an
Include File, and Help Files specific to their game.

* SanScript Language LanguageDefaultEditorSettingsBase *
Now you can add custom NativeItems (that is, Intellisense
keywords) to your SanScript Parser Options File to provide
commonly used keywords and lines of code or comments that
cannot be found in a script file or among the includes. There
are 3 types of NativeItems: Constant/Enum, Struct, and
Procedure/Function. Element names (aka nodes or tags) start
with a capital letter while attributes do not.

<table>
Xml Tag            Required Attributes       Optional Attributes
-----------------  ------------------------  -------------------------------
ConstOrEnumItem    * type - Type of the      
                      constant or enum such   
                      as CONST_INT or         
                      CONST_FLOAT.            
                    * name                    
                    * value                   
StructItem         * name                    
NativeProcOrFunc   * name                    * args - The arguments to
                                                pass to the function,
                                                separated by commas.
                                              * returnType - Designates
                                                this as a Func rather than a
                                                Proc.
</table>

The StructItem tag should have at least one "Contents" tag as
a child node to specify the members of the struct. Typically,
you'll want to include a tab at the beginning of each line of
text.



Additionally, each tag may optionally include any of the
following child nodes:
<table>
Xml Child Tag                  Required Attributes      Optional Sub
                                                         children
-----------------------------  -----------------------  -------------
Source<p/><p/>Since you are    * file - Source file     
 adding these NativeItems to      where the keyword is   
 the language because they        defined or declared.   
 are not readily accessible     * line - Line number     
 through the standard means,      in that file,          
 it is probably rare that you     starting with 1. If    
 will ever add this node, but     line is not            
 it is here for completeness.     specified, file is     
                                  ignored.               
Comments                                                You can
                                                         include one
                                                         \or more of
                                                         each of
                                                         these.
                                                         * Purpose
                                                         * Params
                                                         * Returns
                                                         * Notes
</table>

\Example:
<code>
\<NativeItems\>
  \<ConstOrEnumItem type="CONST_INT" name="MY_TEST_CONST" value="33" /\>
  \<NativeProcOrFunc name="MY_TEST_FUNC" args="FLOAT f, BOOL b" returnType="INT"\>
    \<Comments\>
      \<Purpose\>Test function\</Purpose\>
      \<Params\>f - floating point number\</Params\>
      \<Params\>b - boolean\</Params\>
      \<Returns\>an integer\</Returns\>
    \</Comments\>
  \</NativeProcOrFunc\>
  \<NativeProcOrFunc name="MY_TEST_PROC"\>
  \<StructItem name="MY_TEST_STRUCT"\>
    \<Contents\>    FLOAT x\</Contents\>
    \<Contents\>    FLOAT y\</Contents\>
    \<Source file="c:\\myfile.sc" line="42" /\>
  \</StructItem\>
\</NativeItems\>
</code>

@@Windows

@@DocumentEditor
<title Document Editor>
<GROUP Windows>

@@DocumentEditorTabContextMenu
<title Tab Context Menu>
<GROUP DocumentEditor>

This context menu can be found by right-clicking on the
Document Tab.

<table>
Menu Item     \Description
------------  -------------------------------------------------
\File Name    Displays the full path of the selected document.
               Click this menu item to copy the path to the
               clipboard.
Open          Opens the folders that contains the file in
 Containing    Explorer.
 Folder        
New Tab       Creates a new Document in a new tab.
Close Tab     Closes the selected document tab.
Close Other   Closes document tabs other than the currently
 Tabs          selected one.
Close All     Closes all document tabs.
 Tabs          
</table>

@@DocumentEditorActiveFilesDropDownMenu
<title Active Files Drop Down Menu>
<GROUP DocumentEditor>

On the right side of the Document Editor Window and next to
the X (to close the current document), you may find a small
triangle shaped button.  Clicking this reveals a drop-down
with a list of all of the documents that are currently open. 

Hover over an item to view its full path.  

Click the item to make it the active document.

@@DocumentEditorContextMenu
<title Context Menu>
<GROUP DocumentEditor>

Over any part of the Document Editor's text, right-clicking
reveals this context menu:

<table>
Menu Item     \Description
------------  --------------------------------------------------------
Undo          Reverts the last edit.
Redo          Restores the last action that was reverted.
Cut           Cuts the selected text to the keyboard.
Copy          Copies the selected text to the keyboard.
Paste         Pastes text from the keyboard.
Delete        Deletes the currently selected text.
Select All    Selects all text in the current document.
Insert Code   Shows the Insert Code Snippet popup to select from
 Snippet       the list of pre-defined code snippets.
Go To         Opens the document and highlights the line on which
 Definition    the currently selected symbol is defined.
Outlining     This drop-down menu contains the Outlining options. See
               <link OutliningMenu, Outlining Menu>.
</table>

@@DocumentEditorKeyboardCommands
<title Keyboard Commands>
<GROUP DocumentEditor>

The following tables detail the keyboard shortcuts available
when focus is given to a Document. Most of them cannot be
found on the <link EditMenu, Edit Menu> or any other
menus.

* Return Commands *
<table>
Key              Command
---------------  ----------------------------------------
Enter            Insert line break
Shift + Enter    Insert line break
Ctrl + Enter     Insert line break on the line above the
                  cursor
Ctrl + Shift +   Insert line break on the line below the
 Enter            cursor
</table>

* Delete/Backspace Commands *
<table>
Key                 Command
------------------  ---------------------------
Delete              Delete
Ctrl + Shift + L    Delete Line
Ctrl + Delete       Delete to next word
Backspace           Backspace
Shift + Backspace   Backspace
Ctrl + Backspace    Backspace to previous word
</table>

* Clipboard/Undo Commands *
<table>
Key                Command
-----------------  ----------------------
Ctrl + C           Copy to Clipboard
Ctrl + L           Cut line to Clipboard
Ctrl + X           Cut to Clipboard
Ctrl + V           Paste from Clipboard
Ctrl + Z           Undo
Ctrl + Y           Redo
Ctrl + Shift + Z   Redo
</table>

* Movement Commands *
<table>
Key                Command
-----------------  ----------------------------------------------
Down               Move caret down
Up                 Move caret up
Left               Move caret left
Right              Move caret right
Ctrl + Left        Move to previous word
Ctrl + Right       Move to next word
Home               Move to start of line
End                Move to end of line
Ctrl + Home        Move to start of document
Ctrl + End         Move to end of document
Page Up            Page up
Page Down          Page down
Ctrl + Page Up     Move to the top of the visible portion of the
                    document
Ctrl + Page Down   Move to the bottom of the visible portion of
                    the document
Ctrl + ]           Move to matching bracket
</table>

* Scroll Commands *
<table>
Key           Command
------------  ------------
Ctrl + Down   Scroll down
Ctrl + Up     Scroll up
</table>

* Indenting Commands *
<table>
Key           Command
------------  --------
Tab           Indent
Shift + Tab   Outdent
</table>

* Selection Commands *
<table>
Key                          Command
---------------------------  ---------------------------------
Shift + Down                 Select down
Shift + Up                   Select up
Shift + Left                 Select left
Shift + Right                Select right
Ctrl + Shift + Left          Select to previous word
Ctrl + Shift + Right         Select to next word
Shift + Home                 Select to start of line
Shift + End                  Select to end of line
Ctrl + Shift + Home          Select to start of document
Ctrl + Shift + End           Select to end of document
Shift + Page Up              Select page up
Shift + Page Down            Select page down
Ctrl + Shift + Page Up       Select to the top of the visible
                              portion of the document
Ctrl + Shift + Page Down     Select to the bottom of the
                              visible portion of the document
Ctrl + A                     Select all
Ctrl + Shift + W             Select word
Ctrl + Shift + ]             Select to matching bracket
Shift + Alt + Down           Select block down
Shift + Alt + Up             Select block up
Shift + Alt + Left           Select block left
Shift + Alt + Right          Select block right
Ctrl + Shift + Alt + Left    Select block to previous word
Ctrl + Shift + Alt + Right   Select block to next word
</table>

* IntelliPrompt Commands *
<table>
Key                    Commands
---------------------  ----------------------------------
Ctrl + Space           IntelliPrompt Complete Word
Ctrl + Shift + Space   Show IntelliPrompt Parameter Info
</table>

* Other Commands *
<table>
Key            Command
-------------  -------------------------------------------------
Ctrl + Shift   Make selection uppercase
 \+ U           
Ctrl + U       Make selection lowercase
Ctrl +         De-selects code blocks that contain the caret in
 Number Pad -   increasing scope depth. Currently works only for
                CSharp files.
Ctrl +         Selects code blocks that contain the caret in
 Number Pad +   decreasing scope depth. Currently works only for
                CSharp files.
Escape         Cancel IntelliPrompt, Code Snippets, Incremental
                Search, etc.
Ctrl + I       Incremental Search
Ctrl + Shift   Reverse Incremental Search
 \+ I           
Insert         Toggle Overwrite Mode
Ctrl + T       Transpose characters on either side of the caret
Ctrl + Shift   Transpose words on either side of the caret.
 \+ T           Current doesn't work very work very well for
                SanScript files.
Ctrl + Shift   Transpose the current line with the next line
 \+ Alt + T     
</table>

@@ProjectExplorerWindow
<title Project Explorer Window>
<GROUP Windows>

When you load a project, it's files and folders appear here.
In this window, you can add and remove existing script files.
You can also create, rename, and delete folders. This can all
be accomplished through a series of right-click context
menus.



At the top, is a Sort button that will arrange all files and
folders alphabetically (case-insensitive) with folders at the
top and files at the bottom.



When a project is saved, not only are the files and folders
remembered, but many settings are saved as well. Which
folders and files that were open when you closed the project
\or quit the Script Editor are remembered so they can be
\opened the next time you open the project. The project file
also contains items off of the <link ProjectSettingsCategory, Project Settings Category>
the <link CompilingSettingsCategory, Compiling Settings Category>
\on the Settings dialog.

* Right-click Context Menu *
<table>
Item                                      \Description
----------------------------------------  --------------------------------------------------
Open                                      When a file is selected, attempts to open it.
<link HowToCompileScript, Compile File>   Compiles the selected script file.
<link HowToCompileProject, Compile All>   Compiles all script files in the project.
Rebuild All                               Rebuilds all script files in the project.
Add Existing                              Add existing script files to your project.
                                           Item(s)...
Add New                                   Adds a new folder, and puts you in edit mode to
                                           Folder give it a name.
Reload Missing                            When the selected file's icon is grayed out,
 \File                                     searches for the file in its last known location.
                                           If found, the icon is activated.
Locate                                    When the selected file's icon is grayed out,
 Missing File                              allows the user to search for the file. If one is
                                           selected, the icon is activated.
Rename                                    When a folder is selected, puts you in edit mode
                                           to rename the folder.
Remove                                    Removes the file or folder (and its files) from
                                           the project. Does <i>not</i> delete any script
                                           files from your hard drive.
</table>



* Tutorials *
<link HowToCreateNewProject, Create a New Project>

@@DocumentOutlineWindow
<title Document Outline Window>
<GROUP Windows>

When enabled, this window displays an outline of the current
\file, according to information provided by it's Semantic
Parse. Nodes will be grouped by their scope.



For example, this code:

<code>
PROC FOO( )
    int MyMultiDimArray[4][3]
    int i, j
    FOR i = 0 to 4
        FOR j = 0 to 3
            // do something
        ENDFOR
    ENDFOR

    IF TRUE
        // do something
    ELSE
        // do something else
    ENDIF
ENDPROC

PROC BOO( INT I )
ENDPROC
</code>

will produce the following outline:

  * PROC FOO( )
    * FOR i = 0 to 4
      * FOR j = 0 to 3
    * IF
    * ELSE
  * PROC BOO( INT I )

* Context Menu *
When Update Document Outline is checked, right-click anywhere
inside the TreeView area.

<table>
Menu Item      \Description
-------------  ------------------------------------------------
Collapse All   Collapses all outlining nodes and their
                children
Expands All    Expands all outlining nodes and their children.
</table>

* Tips for Improving Performance *
  * Hide the window behind another one. The refresh can be
    costly.
  * Uncheck the Update Document Outline option at the top of
    the window.

For a more complete outline, run the Script Editor with the
\-admin command line parameter.

@@OutputWindow
<title Output Window>
<GROUP Windows>

The Output Window, by default, can be found docked at the
bottom of the editor. It is to this window that compile
messages are written. If errors are found, they appear in
this window and the user can select them and go to the
specified error in the script. The user can also highlight
and copy text. A right-click context menu, along with
keyboard shortcuts, provide this functionality.

<table>
Menu Item   \Description
----------  --------------------------------------------------------------------
Go To       On an error line, opens the appropriate file and
 Error/Tag   highlights the line with the error in question. Alternatively,
             you can just double-click on the error line.
Copy        Copies the highlighted text to the system Clipboard. Alternatively,
             Ctrl+C with this window in focus will accomplish the
             same task. Use Ctrl+A to select all before copying.
Clear all   Clears all text from the window.
Find        Opens a Find/Replace dialog for searching in this window.
</table>

* Additional Shortcuts *
	* Select All (Ctrl + A)
	* Search Again Down (F3)
	* Search Again Up (Shift + F3)
	* Search Highlighted Down (Ctrl + F3)
	* Search Highlighted Up (Ctrl + Shift + F3)

@@FindResultsWindow
<title Find Results Window>
<GROUP Windows>

The Find Results Window, by default, can be found docked at
the bottom of the editor. It is to this window that the
results of Find in Files searches are displayed. Each result
can then be double-clicked to open the file and highlight the
instance of the search text. The user can also highlight and
copy text from the Find Results Window. A right-click context
menu, along with keyboard shortcuts, provide this
functionality.

<table>
Menu Item   \Description
----------  --------------------------------------------------------------------
Go To       On a result line, opens the appropriate file and
 Error/Tag   highlights the line with the found text in question. Alternatively,
             you can just double-click on the error line.
Copy        Copies the highlighted text to the system Clipboard. Alternatively,
             Ctrl+C with this window in focus will accomplish the
             same task. Use Ctrl+A to select all before copying.
Clear all   Clears all text from the window.
Find        Opens a Find/Replace dialog for searching in this window.
</table>

* Additional Shortcuts *
	* Select All (Ctrl + A)
	* Search Again Down (F3)
	* Search Again Up (Shift + F3)
	* Search Highlighted Down (Ctrl + F3)
	* Search Highlighted Up (Ctrl + Shift + F3)

@@ErrorsWindow
<title Errors Window>
<GROUP Windows>

For your convenience, compile errors are output directly to
this window from the Output Window, succinctly presenting the
errors in a more easily-read format. Double-click on the
error line to open up the file and go to the line it is on.



This window only appears when compile errors are found.

@@HelpWindow
<title Help Window>
<GROUP Windows>

This window displays the text of the last Intellisense Info popup that was shown by the document.

@@DockableWindowKeyboadShortcuts
<title Window Navigation Keyboard Commands>

There are a few keyboard commands for navigating between the
various Dockable Windows and Tabbed Documents

* Dockable Window Navigation *
<table>
Key           Command
------------  ----------------------------------------------
Ctrl + Page   Switch to the previous Dockable Window in the
 Up            currently selected tab group
Ctrl + Page   Switch to the next Dockable Window in the
 Down          currently selected tab group
</table>

* Tabbed Document Navigation *
<table>
Key          Command
-----------  -----------------------------------------------------
Ctrl + Tab   Cycle through the Tabbed Documents
Ctrl +       Cycle through the Tabbed Documents in opposite order
 Shift +
 Tab
</table>

@@HowTo
<title How To>

@@HowToCompileScript
<title Compile a Script>
<GROUP HowTo>

  1. If you have not yet setup your compiling options
     1. Click on the <link ToolsMenu, Tools Menu> and
        select <link ToolsMenuSettings, Settings>.
     2. Select the <link CompilingSettingsCategory, Compiling Category>
        and choose your options
     3. Click OK.
  2. With a script loaded, open the <link CompilingMenu, Compiling Menu>
     and select 'Compile'. Alternatively, you may press Ctrl+F7 to
     compile the current script.

Information about the compile process will appear in the
\Output Window.



If your script file is part of a project, you may also do the
following:
  1. Right-click the script file in the <link ProjectExplorerWindow, Project Explorer>
     window.
  2. Select 'Compile'.



@@HowToCreateNewProject
<title Create a New Project>
<GROUP HowTo>

  1. Open the <link FileMenu, File Menu>, then New,
     then Project....
  2. Browse for the location where you want to store your
     project.
  3. Give it a name and click OK.

Your project will appear in the <link ProjectExplorerWindow, Project Explorer>
window. Now you can add existing script files and organize
them into folders. Note that these folders don't necessarily
relate to the location of the script files on your hard
drive.



You now have the option of selecting certain project-specific
settings.
  1. Click on the <link ToolsMenu, Tools Menu> and open
     the <link ToolsMenuSettings, Settings dialog>.
  2. On the Settings dialog:
     1. Select the <link ProjectSettingsCategory, Project Category>
        and choose your Post-Compile Command and/or Start Debug
        Command.
     2. Select the <link CompilingSettingsCategory, Compiling Category>
        and choose your compiling options.
     3. Click OK.
  3. Save the project by clicking <link FileMenu, File>
     \-\> Save Project.


@@HowToCompileProject
<title Compile a Project>
<GROUP HowTo>

If you do not have a project created and populated with
files, do <link HowToCreateNewProject, this tutorial> first and
return here.

  1. If it is your first time compiling a project and you did
     not setup your Compiling options. Return to <link HowToCreateNewProject, this tutorial>
     and do so now.
  2. Right-click on the Project folder in the <link ProjectExplorerWindow, Project Window>
     and select 'Compile All'. Alternatively, you may press F7.

Information about the compile process will appear in the
\Output Window.



Additionally, you may setup a Start Debug Command on the <link ProjectSettingsCategory, Project Settings Category>,
and press F5 to compile and begin debugging.



When a project is successfully compiled, a couple of
additional files are saved in the project folder. First, a
list of all files in the project is saved as
"\<project_name\>.scolist". Second, a batch file called
"compile_one.\<project_name\>.bat is saved. This batch file
can be called on each file in the .scolist to compile the
project files outside of the editor.


@@HowToCompileProjectCommandLine
<title Compile From the Command Line>
<GROUP HowTo>

You have two options for compiling: a basic method by calling
ragScriptEditor (or equivalent) or a more feature-rich method
by calling ragScriptCompiler. This topic describes how to
compile with each method.



For both programs, compiling a project from the command line
will do everything a normal <link HowToCompileProject, project compile>
does, but without running the Script Editor interface.
Similarly, <link HowToCompileScript, compiling individual script files>
\or list of files on their own will use your last user
settings. If you combine a project file with one or more
script files on the command line, the project file has
precedence and will be used for things like the <link CompilingSettingsCategory, Compiling Settings>
and where the log file is placed (when that file is not path
rooted).



Each named argument is preceded with a hyphen (-), as shown.
The arguments and parameters are separated by a spaces.
However, the equals sign (=) is also accepted between
\arguments and a single parameter.

* Compiling with ragScriptEditor *
This method is very basic and only offers a 4 commands
<table>
Argument     Parameter(s)                \Description                                          Required
-----------  --------------------------  ----------------------------------------------------  =========
\-build      projectFile|scriptFile...   One project file and/or any number of script files    Yes
                                          to compile.                                           
\-clean                                  Clean the file(s) before compiling.                   No
\-config     configuration               Specifies the configuration on which to perform the   No
              name                        build and/or clean operation. Without this option,    
                                          the last active configuration is used.                
\-log        [textFile]                  Indicates that we want all Standard Output to be      No
                                          piped to a file. The parameter is optional and if     
                                          it is not path-rooted, we will use the path of the    
                                          project or the first script file. If no file is       
                                          provided, the default is 'log.txt' and will be        
                                          saved using the same path rules.                      
\-guiName    name                        Needed by compiles that use the Default Compiling     No
                                          \option. If not specified, we attempt to find an      
                                          executable name that contains 'ScriptEditor'          
                                          located in the same directory as ragScriptCompiler.   
\-cacheDir   languageName                Overrides the Cache Directory used by the given       No
              directory                   language. More than one <i>pair</i> of parameters     
                                          may be passed in. Current supported languages are     
                                          "SanScript", "CSharp", and "Xml".                     
</table>

* Compiling with ragScriptCompiler *
This method of compiling offers the same functionality as the
basic method, adding the ability to override any of the <link CompilingSettingsCategory, Compiling Settings>
saved in the Project and the user's last settings.
<table>
Argument            Parameter(s)                \Description                                        Required
------------------  --------------------------  --------------------------------------------------  ===============
\                   projectFile|scriptFile...   One project file and/or any number of               Yes
                                                 script files to compile.                            
\-clean                                         Clean the file(s) before compiling.                 No
\-config            configuration               Specifies the configuration on which to             <align center>
                     name                        perform the build and/or clean operation. Without   No
                                                 this option, the last active configuration          </align>
                                                 is used.                                            
\-log               [textFile]                  Indicates that we want all Standard Output          <align center>
                                                 to be piped to a file. The parameter is             No
                                                 \optional and if it is not path-rooted, we          </align>
                                                 will use the path of the project or the             
                                                 first script file. If no file is provided,          
                                                 the default is 'log.txt' and will be saved          
                                                 using the same path rules.                          
\-guiName           name                        Needed by compiles that use the Default             <align center>
                                                 Compiling option. If not specified, we              No
                                                 attempt to find an executable name that             </align>
                                                 contains 'ScriptEditor' located in the same         
                                                 directory as ragScriptCompiler.                     
\-override          [true|false]                Overrides the current                               <align center>
                                                 OverrideDefaultCompilerSettings value.              No
                                                 Without a value, defaults to true.                  </align>
\-debugparser       [true|false]                Overrides the current DebugParser value.            <align center>
                                                 Without a value, defaults to true.                  No
                                                                                                     </align>
\-dump              [true|false]                Overrides the current DumpThreadState               <align center>
                                                 value. Without a value, defaults to true.           No
                                                                                                     </align>
\-dis               [true|false]                Overrides the current DisplayDisassembly            <align center>
                                                 value. Without a value, defaults to true.           No
                                                                                                     </align>
\-include           scriptFile                  Overrides the current IncludeFile value.            <align center>
                                                                                                     No
                                                                                                     </align>
\-ipath             path                        Overrides the current IncludePath value.            No
\-globals           scriptFile                  Overrides the current Globals value.                No
\-custom            text                        Overrides the current Custom value.                 No
\-scriptCompiler    executable                  Overrides the current ScriptCompiler value.         No
\-outputDirectory   path                        Overrides the current Output Directory              No
                                                 value.                                              
\-break             [true|false]                Overrides the current Break On Errors               No
                                                 value.                                              
\-version           [textFile]                  Displays the version number or saves it to          No
                                                 the specified text file and exits.                  
\-cacheDir          languageName                Overrides the Cache Directory used by the           No
                     directory                   given language. More than one <i>pair</i>           
                                                 \of parameters may be passed in. Current            
                                                 supported languages are "SanScript",                
                                                 "CSharp", and "Xml".                                
</table>

* Examples *
  1. c:\\\>ragScriptEditor -build c:\\MyScriptProject.scproj
     \-clean
  2. c:\\\>ragScriptCompiler c:\\MyScriptProject.scproj
     \-clean
  3. c:\\\>ragScriptEditor -build c:\\MyScriptProject.scproj
     \-log="C:\\Documents and Settings\\username\\My
     Documents\\MyScriptProjectLog.txt"
  4. c:\\\>ragScriptEditor -build
     t:\\sample_scr_generic.scproj -log
  5. c:\\\>ragScriptEditor -bulid demo.sc faultdemo.sc -clean
  6. c:\\\>ragScriptCompiler c:\\MyScriptProject.scproj
     \-override -debugparser true
  7. c:\\\>ragScriptCompiler c:\\MyScriptProject.scproj
     \-ipath="" -guiName myEditorForScripts

\#1 and #2 are functionally equivalent.

\#4 creates a log file named t:\\log.txt because t:\\ is
where the project lives and no name was given.

\#7 clears ipath by passing in double-quotes as it's
parameter. It also sets the guiName, because they renamed
their script editor executable.

@@HowToCreateCustomButton
<title Create a Custom Button>
<GROUP HowTo>

  1. Click the Tools Menu and select <link ToolsMenuCustomButtonManager, Custom Button Manager>.
  2. Click the 'New' button.
  3. In the Name text box, give your custom button a
     descriptive name.
  4. Click the '...' button next to the empty Icon box, and
     select an icon file.
  5. In the Command text box, either type your command, or
     browse for a program using the '...' button next to it.
  6. When you are satisfied with your inputs, click 'Accept'.
     Your button will appear in the Custom Button List and on the
     Tool Bar.

* Valid commands *
  * System programs (like notepad) and programs in your path
    (like rag), with or without arguments
  * File types registered with a program
  * Other executables with any number of arguments as long as
    the path does <i>not</i> contain spaces
<code>
notepad c:\\myfile.txt
c:\\myfile.txt
c:\\soft\\rage\\base\\samples\\mysample.exe -rag -cammachdebug
</code>


@@HowToCreateDefaultSettings
<title Create a Default Settings File>
<GROUP HowTo>

This tutorial instructions your game's lead Scripter how to
create a set of default options for all of the scripters on
your team.

  1. Run the Script Editor with the "-admin" command line
     \option (without the quotes, obviously).  This will enable the "Save Default Settings File" in the Language categories of the <link ToolsMenuSettings, Settings> dialog.
  2. Open the <link ToolsMenuCustomButtonManager, Custom Button Manager>
     from the <link ToolsMenu, Tools Menu>.
     1. <link HowToCreateCustomButton, Create any custom buttons>
        you want available to your entire scripting team.
     2. Close the window.
  3. Open the <link ToolsMenuSettings, Settings> dialog
     from the <link ToolsMenu, Tools Menu>.
     1. Edit the options in each category as you see fit.
     2. Once you are finished, go to the <link LanguageSettingsCategory, Language Settings> for the language you want, 
        and click "Save Default Settings File". It should tell you
        the file saved successfully. Click OK.
     3. Click OK to close the Settings dialog.
  4. Check your settings
     1. Open the Settings dialog again and change any
        setting. For thoroughness, you may want to change something
        in each category.
     2. Go to the Language category for the language and click "Load Default
        Settings File".
     3. It should tell you the file loaded successfully.
        Select "Yes" to make the default settings your current
        settings.
     4. Verify that your settings are correct.

You are now free to customize your settings
knowing that you always have the option to revert back to
your game's defaults.


@@HowToUseTheScriptEditorOnTheCommandLine
<title Use the Script Editor on the Command Line>
<GROUP HowTo>

There are a few basic commands one can pass into
ragScriptEditor through the command line. By passing in no
\arguments, you of course, launch the Script Editor GUI as
normal.



Each named argument is preceded with a hyphen (-), as shown.
The arguments and parameters are separated by a spaces.
However, the equals sign (=) is also accepted between
\arguments and a single parameter..

<table>
Argument     Parameter(s)                \Description                                    Required
-----------  --------------------------  ----------------------------------------------  ===============
\            projectFile|scriptFile...   One project file and/or any number of           No
                                          script files to load.                           
\-file       scriptFile...               One or more files to load.                      <align center>
                                                                                          No
                                                                                          </align>
\-project    projectFile                 One project to load.                            <align center>
                                                                                          No
                                                                                          </align>
\-admin                                  Enables admin mode so one can modify            <align center>
                                          the Default Settings that get loaded by         No
                                          the Parser Plugin DLL.                          </align>
\-version    [textFile]                  Displays the version number or saves it         No
                                          to the specified text file and exits.           
\-usage                                  Displays this usage information.                <align center>
                                                                                          No
                                                                                          </align>
\-cacheDir   languageName                Overrides the Cache Directory used by           No
              directory                   the given language. More than one <i>pair</i>   
                                          \of parameters may be passed in.                
                                          Current supported languages are                 
                                          "SanScript", "CSharp", and "Xml".               
</table>

There are a few additional commands available for compiling a
project and/or one or more files. See <link HowToCompileProjectCommandLine, Compile From the Command Line>.