Add markdown documentation (4.5-pre) #1104

docs/3500_ibeam_ride.md

@@ -0,0 +1,21 @@
+
+
+
+
+### 3500⌶ (Send HTML to the RIDE)
+
+
+Syntax: `R←{X}(3500⌶)Y`
+
+
+Optionally, `X` is a simple character vector or scalar, the contents of which are used as the caption of an embedded browser window opened by the RIDE client. If omitted, then the caption defaults to "`3500⌶`".
+
+
+`Y` is a simple character vector of HTML markup, the contents of which are displayed in the embedded browser tab.
+
+
+`R` identifies whether the write to the RIDE was successful. Possible values are:
+
+- `0` : the write to the RIDE client was successful
+- `¯1` : the RIDE client is not enabled
+

docs/3501_ibeam_ride.md

@@ -0,0 +1,18 @@
+
+
+
+
+### 3501⌶ (Connected to the RIDE?)
+
+
+Syntax: `R←{X}(3501⌶)Y`
+
+
+`X` and `Y` can be any value (ignored).
+
+
+`R` identifies whether the Dyalog Session is running through the RIDE. Possible values are:
+
+- `0` : the Session is not running through the RIDE
+- `1` : the Session is running through the RIDE
+

docs/3502_ibeam_ride.md

@@ -0,0 +1,47 @@
+
+
+
+
+### 3502⌶ (Manage RIDE Connectors)
+
+
+
+By default, the RIDE is not enabled on run-time executables. For security reasons, enabling the RIDE is a two-step process rather than using (for example) a single configuration parameter. To enable the RIDE, two steps must be taken:
+
+1. Set the RIDE_INIT configuration parameter (see [Section ](ride_init.md#)) on the machine on which the run-time interpreter is running to an appropriate value.
+2. Execute `3502⌶1` in your application code.
+
+The run time interpreter can then attempt to connect to a RIDE client.
+
+
+Enabling the RIDE to access applications that use the run-time interpreter means that the APL code of those applications can be accessed. The I-beam mechanism described above means that the APL code itself must grant the right for a RIDE client to connect to the run time interpreter. Although Dyalog Ltd might change the details of this mechanism, the APL code will always need to grant connection rights. In particular, no mechanism that is only dependent on configuration parameters will be implemented.
+
+
+
+Syntax: `R←3502⌶Y`
+
+
+`R` is `0` if the call is successful, otherwise an integer (positive or negative) is returned.
+
+
+`Y` can be any of the following possible values:
+
+- `0` : disable any active RIDE connections.`R` is always `0`
+- `R` is always `0`
+- `1` : enable the RIDE using the initialisation string defined in the RIDE_INIT configuration parameter  (see [Section 1.0.1](ride_init.md#)):if `R` is `0`, then the RIDE was disabled and is now successfully enabledif `R` is `¯1`, then the RIDE was already activeif `R` is `32`, then the RIDE DLL/shared library is not availableif `R` is `64`, then the RIDE_INIT configuration parameter is not correctly defined
+- if `R` is `0`, then the RIDE was disabled and is now successfully enabled
+- if `R` is `¯1`, then the RIDE was already active
+- if `R` is `32`, then the RIDE DLL/shared library is not available
+- if `R` is `64`, then the RIDE_INIT configuration parameter is not correctly defined
+- a simple character vector : replace the RIDE_INIT configuration parameter with the specified initialisation string, which should be in the format specified in [Section ](ride_init.md#). For example, `3502⌶'SERVE:*:4502'` configures the interpreter to accept incoming RIDE connections from any machine on port 4502, and then enables the RIDE with that configuration.if `R` is `0`, then the RIDE was disabledif `R` is `¯2`, then the RIDE was active
+- if `R` is `0`, then the RIDE was disabled
+- if `R` is `¯2`, then the RIDE was active
+
+
+On a run-time interpreter, `3502⌶1` is the only way to enable the RIDE.
+
+
+If the RIDE_INIT configuration parameter is set but the RIDE DLLs/shared libraries are not available, then a run-time interpreter will start but the subsequent call to `3502⌶` will be unsuccessful.
+
+
+

docs/about_this_document.md

@@ -0,0 +1,19 @@
+
+
+
+
+# About This Document
+
+
+This document introduces the Remote Integrated Development Environment (RIDE). It describes the installation process and the RIDE's user interface (windows, menus, customisation options, keycode/keystroke mappings, etc.).
+
+
+RIDE can be extensively customised; this document assumes that the default configuration is in use.
+
+## Audience
+
+It is assumed that the reader has a working knowledge of Dyalog.
+
+For information on the resources available to help develop your Dyalog knowledge, see https://www.dyalog.com/introduction.htm. New users might also find that it is helpful to select the Show tips for glyphs check box in the [General tab](general_tab.md) of the **Preferences** dialog box.
+
+

docs/action_menu.md

@@ -0,0 +1,18 @@
+
+
+
+
+#### Action Menu
+
+
+The options available under the Action menu are detailed in [](#action_menu)below. These enable Edit and Trace windows to be opened and allow currently-running APL code to be interrupted with trappable events.
+
+| Item | Description |
+| --- | --- |
+| Edit | If the cursor is on or immediately after `<object name>` , then opens an Edit window on that name. |
+| Trace | In the Session window: If the cursor is on a line containing calls to multi-line functions, a Trace window is opened and the functions traced ( explicit trace ). If the cursor is on a line containing no text and there is a suspended function (or operator) on the execution stack, open a Trace window for that function ( naked trace ) In a Trace window: Open a new Trace window for any multi-line function (or operator) in that line and trace that line as it is evaluated. |
+| Clear all trace/stop/monitor | Removes any trace/stop/monitor flags  (as set by `⎕TRACE` / `⎕STOP` / `⎕MONITOR` ) from all functions in the workspace. |
+| Weak Interrupt | Suspends execution at the start of the next line. |
+| Strong Interrupt | Suspends execution after the current primitive operation. |
+
+

docs/autocomplete.md

@@ -0,0 +1,34 @@
+
+
+
+
+### Autocomplete
+
+
+Applicable in the Session window and the Edit window
+
+
+The RIDE includes autocomplete functionality for names to reduce the likelihood of errors when including them in an expression (and to save the user having to enter complete names or remember cases for case-sensitive  names).
+
+
+As a name is entered, the RIDE displays a pop-up window of suggestions based on the characters already entered and the context in which the name is being used.
+
+
+For example, if you enter a `⎕` character, the pop-up list of suggestions includes all the system names (for example, system functions and system variables). Entering further characters filters the list so that only those system functions and variables that start with the exact string entered are included.
+
+
+When you start to enter a name in the Session window, the pop-up list of suggestions includes all the namespaces, variables, functions and operators that are defined in the current namespace. When you start to enter a name in the Edit window, the pop-up list of suggestions also includes all names that are localised in the function header.
+
+
+To select a name from the pop-up list of suggestions, do one of the following:
+
+- click the mouse on the name in the pop-up list
+- use the right arrow key to select the top name in the pop-up list
+- use the up and down arrow keys to navigate through the suggestions and the right arrow key or the TAB key to enter the currently-highlighted name
+
+The selected name is then completed in the appropriate window.
+
+
+This feature can be disabled or customised in the General tab of the Preferences dialog box (see [Section ](general_tab.md#)).
+
+

docs/breakpoints.md

@@ -0,0 +1,21 @@
+
+
+
+
+### Breakpoints
+
+
+Applicable in the Edit window and the Trace window
+
+
+When a function that includes a breakpoint is run, its execution is suspended immediately before executing the line on which the breakpoint is set and the Trace window is automatically opened (assuming that automatic trace is enabled – see [Section ](trace_window.md#)).
+
+
+Breakpoints are defined by dyadic `⎕STOP` and can be toggled on and off in an Edit or Trace window by left-clicking on the far left of the line before which the breakpoint is to be applied or by placing the cursor anywhere in the line before which the breakpoint is to be applied and entering the Toggle Breakpoint command (<BP>). Note that:
+
+- Breakpoints set or cleared in an Edit window are not established until the function is fixed.
+- Breakpoints set or cleared in a Trace window are established immediately.
+
+When a breakpoint is reached during code execution, event 1001 is generated; this can be trapped. For more information, see  `⎕TRAP` in the Dyalog APL Language Reference Guide.
+
+

docs/caption.md

@@ -0,0 +1,13 @@
+
+
+
+
+### Caption
+
+
+The caption at the top of the Session window is the name of the Session.
+
+
+The caption can be customised (see [Section ](title_tab.md#)).
+
+

docs/colours_tab.md

@@ -0,0 +1,39 @@
+
+
+
+
+### Colours Tab
+
+
+Allows customisation of the syntax colouring (see [Section ](syntax_colouring.md#)). Several schemes are provided, any of which can be used as they are or further customised.
+
+
+To change the syntax colouring to a predefined scheme
+
+1. Open the Colours tab.
+2. In the Scheme field, select the syntax colouring scheme that you want to use. When a scheme is selected, the example shown is updated to use that colour scheme.
+3. Click OK to save your changes and close the Preferences dialog box, Apply to save your changes without closing the Preferences dialog box or Cancel to close the Preferences dialog box without saving your changes.
+
+
+
+
+To define a new syntax colouring scheme
+
+1. Open the Colours tab.
+2. In the Scheme field, select the syntax colouring scheme that is closest to the scheme that you want to define. When a scheme is selected, the example shown is updated to use that colour scheme.
+3. Click Clone.
+4. Define your colour scheme. To do this:Select the element that you would like to change the display of from the drop-down list or by clicking in the example. The customisation options reflect the current settings for the selection made. Some elements have a limited set of options, for example, the cursor element has no bold/italic/underline option.Select a foreground colour and background (highlighting) colour for that syntax as required. If a background colour is selected, then the slide bar can be used to set its transparency.Select the appropriate check boxes to make that syntax bold, italic or underlined as required.Repeat as required.
+5. Select the element that you would like to change the display of from the drop-down list or by clicking in the example. The customisation options reflect the current settings for the selection made. Some elements have a limited set of options, for example, the cursor element has no bold/italic/underline option.
+6. Select a foreground colour and background (highlighting) colour for that syntax as required. If a background colour is selected, then the slide bar can be used to set its transparency.
+7. Select the appropriate check boxes to make that syntax bold, italic or underlined as required.
+8. Repeat as required.
+9. Optionally, rename your colour scheme. To do this:Click Rename.
+The name in the Scheme field becomes editable.
+Edit the name in the Scheme field.
+10. Click Rename.
+11. Edit the name in the Scheme field.
+12. Click OK to save your changes and close the Preferences dialog box, Apply to save your changes without closing the Preferences dialog box or Cancel to close the Preferences dialog box without saving your changes.
+
+
+
+

docs/configuration_ini_file.md

@@ -0,0 +1,19 @@
+
+
+
+
+## Configuration (.ini) File
+
+
+A .ini configuration file can be used to define settings for the RIDE_INIT configuration parameter. By default, the interpreter will look for a ride.ini file in:
+
+-  the directory in which the default session and log files are stored, for example, C:\Users\JohnDoe\AppData\Local\Programs\Dyalog\ (on Microsoft Windows)
+-  $HOME/.dyalog/ (on IBM AIX, macOS and Linux)
+
+This file is not automatically created by Dyalog but can be created manually. Examples of the fields that you might want to include within the .ini configuration file are included in [Appendix 1](sample_configuration_file.md#).
+
+
+A different name and location for the .ini configuration file can be specified by including a second `mode`, `CONFIG`, in the RIDE_INIT parameter (see [Section 1.0.1](ride_init.md#)) and setting it so that `CONFIG=<filename>`, where `<filename>` is the fully-qualified path to, and name of, a .ini configuration file containing name-value pairs related to mode, certificate details, and so on.
+
+The .ini configuration file must be located on the machine on which the interpreter is running (this is not necessarily the same machine as the one on which the RIDE is running).
+

docs/configuration_parameters.md

@@ -0,0 +1,11 @@
+
+
+
+
+## Configuration Parameters
+
+
+Some customisation can be performed using configuration parameters outside a Session. For details of other configuration parameters that can be set, and the syntax used to set them, see the Dyalog for <operating system> Installation and Configuration Guide specific to the operating system that you are using.
+
+Changes made to configuration parameters in the dyalog.config file only impact local interpreters (that is, interpreters that are configured by that file) and do not impact interpreters that the RIDE can connect with on other machines.
+

docs/configuration_parameters_ridespecific.md

@@ -0,0 +1,12 @@
+
+
+
+
+## Configuration Parameters
+
+
+There are two configuration parameters that are relevant to the RIDE:
+
+- RIDE_EDITOR (set on the machine that the RIDE is running on) – see [Section ](ride_editor.md#)
+- RIDE_INIT (set on the machine that the interpreter is running on) – see [Section ](ride_init.md#)
+

docs/context_menu.md

@@ -0,0 +1,20 @@
+
+
+
+
+### Context Menu
+
+
+A context menu is available by right-clicking within the Session, Edit and Trace windows. The options available under the context menu are dependent on the window from which it was accessed and are detailed in [](#context_menu)below.
+
+| Item | Description |
+| --- | --- |
+| Fix | Edit : Fixes the function without closing the Edit window. |
+| Skip to line | Trace : Moves the current execution marker to the line on which the cursor is positioned. |
+| Cut | Session/Edit/Trace : Deletes the selected text from the active window and places it on the clipboard. Only enabled when text is selected. Never enabled in the Trace window. |
+| Copy | Session/Edit/Trace : Copies the selected text to the clipboard. Only enabled when text is selected. |
+| Paste | Session/Edit/Trace : Pastes the text contents of the clipboard into the active window at the current location. Never enabled in the Trace window. |
+| Undo | Session/Edit/Trace : Reverses the previous action (where possible). Never enabled in the Trace window. |
+| Redo | Session/Edit/Trace : Reverses the effect of the previous Undo. Never enabled in the Trace window. |
+
+

docs/context_sensitive_help.md

@@ -0,0 +1,13 @@
+
+
+
+
+### Context-Sensitive Help
+
+
+Applicable in the Session window, Edit window and Trace window
+
+
+With the cursor on or immediately after any system command, system name, control structure keyword or primitive glyph, enter the Help command (<HLP>). The documentation for that system command, system name, control structure keyword or primitive glyph will be displayed.
+
+