Draft: Convert PDF/ Word/ TeX Documentation to Markdown for online documentation.

docs/CLI/CommandIndex.md

@@ -0,0 +1,32 @@
+
+When issuing commands, the command name can be shortened so long as there is no
+ambiguity (e.g., `pref` instead of `preferences`). Arbitrary aliases may also
+be assigned using the `alias` command. Some of the more common shortcuts are
+listed with each command's synopsis under "Default Aliases".
+
+1. [File System Commands](cmd_file_system)
+1. [alias](cmd_alias)
+1. [chunk](cmd_chunk)
+1. [debug](cmd_debug)
+1. [decide](cmd_decide)
+1. [echo](cmd_echo)
+1. [epmem](cmd_epmem)
+1. [explain](cmd_explain)
+1. [gp](cmd_gp)
+1. [help](cmd_help)
+1. [load](cmd_load)
+1. [output](cmd_output)
+1. [preferences](cmd_preferences)
+1. [print](cmd_print)
+1. [production](cmd_production)
+1. [rl](cmd_rl)
+1. [run](cmd_run)
+1. [save](cmd_save)
+1. [smem](cmd_smem)
+1. [soar](cmd_soar)
+1. [sp](cmd_sp)
+1. [stats](cmd_stats)
+1. [svs](cmd_svs)
+1. [trace](cmd_trace)
+1. [visualize](cmd_visualize)
+1. [wm](cmd_wm)

docs/CLI/cmd_alias.md

@@ -0,0 +1,61 @@
+## alias
+
+Define a new alias of existing commands and arguments.
+
+#### Synopsis
+
+```
+alias
+alias <name> [args]
+alias -r <name>
+```
+### Adding a new alias
+
+This command defines new aliases by creating Soar procedures with the given name. The new procedure can then take an arbitrary number of arguments which are post-pended to the given definition and then that entire string is executed as a command. The definition must be a single command, multiple commands are not allowed. The alias procedure checks to see if the name already exists, and does not destroy existing procedures or aliases by the same name. Existing aliases can be removed by using the [unalias](cmd_unalias) command.
+
+### Removing an existing alias
+
+To undefine a previously created alias, use the `-r` argument along with the name of the alias to remove.
+
+```alias -r existing-alias```
+
+Note:  If you are trying to create an alias for a command that also has a `-r` option, make sure to enclose it in quotes.  For example:
+
+```alias unalias "alias -r"```
+
+### Printing Existing Aliases
+
+With no arguments, alias returns the list of defined aliases. With only the name given, alias returns the current definition.  
+
+### Examples
+
+The alias `wmes` is defined as:
+
+```
+alias wmes print -i
+```
+
+If the user executes a command such as:
+
+```
+wmes {(* ^superstate nil)}
+```
+
+... it is as if the user had typed this command:
+
+```
+print -i {(* ^superstate nil)}
+```
+
+To check what a specific alias is defined as, you would type
+
+```
+alias wmes
+```
+### Default Alias Aliases
+
+```
+a               alias
+unalias, un     alias -r     
+```
+

docs/CLI/cmd_chunk.md

@@ -0,0 +1,178 @@
+## chunk
+
+Sets the parameters for explanation-based chunking.
+
+#### Synopsis
+
+```
+===================================================
+           Chunk Commands and Settings
+===================================================
+? | help                                              Print this help listing
+timers                                 [ on | OFF ]   Timing statistics (no args to print stats)
+stats                                                 Print statistics on learning
+------------------- Settings ----------------------
+always | NEVER | only | except                        When Soar will learn new rules
+bottom-only                            [ on | OFF ]   Learn only from bottom sub-state
+naming-style                     [ numbered | RULE]   Numeric names or rule-based names
+max-chunks                                 50         Max chunks learned per phase
+max-dupes                                   3         Max duplicate chunks (per rule, per phase)
+------------------- Debugging ---------------------
+interrupt                              [ on | OFF ]   Stop after learning from any rule
+explain-interrupt                      [ on | OFF ]   Stop after learning rule watched 
+warning-interrupt                      [ on | OFF ]   Stop after detecting learning issue
+------------------- Fine Tune ---------------------
+singleton                                             Print all WME singletons
+singleton                <type> <attribute> <type>    Add a WME singleton pattern
+singleton -r             <type> <attribute> <type>    Remove a WME singleton pattern
+----------------- EBC Mechanisms ------------------
+add-ltm-links                          [ on | OFF ]   Recreate LTM links in results
+add-osk                                [ on | OFF ]   Incorporate operator selection rules
+merge                                  [ ON | off ]   Merge redundant conditions
+lhs-repair                             [ ON | off ]   Add conds for unconnected LHS IDs
+rhs-repair                             [ ON | off ]   Add conds for unconnected RHS IDs
+user-singletons                        [ ON | off ]   Unify with domain singletons
+---------- Correctness Guarantee Filters ----------     Allow rules to form that...
+allow-local-negations                  [ ON | off ]   ...used local negative reasoning
+allow-opaque*                          [ ON | off ]   ...used knowledge from a LTM recall
+allow-missing-osk*                     [ ON | off ]   ...tested operators selected through OSK
+allow-uncertain-operators*             [ ON | off ]   ...tested operators selected probabilistically
+* disabled
+---------------------------------------------------
+
+To change a setting:                                  chunk <setting> [<value>]
+For a detailed explanation of these settings:         help chunk
+```
+
+### Description
+
+The `chunk` command controls the parameters for explanation-based chunking. With no arguments, this command prints out a basic summary of the current learning parameters, how many rules have been learned and which states have learning active. With an `?` argument, it will list all sub-commands, options and their current values.
+
+#### Turning on Explanation-Based Chunking
+
+Chunking is _disabled_ by default. Learning can be turned on or off at any point during a run. Also note that Soar uses most aspects of EBC to create justifications as well, so many aspects of the chunking algorithm still occur even when learning is off.
+```
+chunk always:      Soar will always attempt to learn rules from sub-state 
+                   problem-solving. 
+chunk never:       Soar will never attempt to learn rules.
+chunk unflagged:   Chunking is on in all states _except_ those that have had RHS 
+                   `dont-learn` actions executed in them. 
+chunk flagged:     Chunking is off for all states except those that are flagged 
+                   via a RHS `force-learn` actions.
+```
+The `flagged` argument and its companion `force-learn` RHS action allow Soar developers to turn learning on in a particular problem space, so that they can focus on debugging the learning problems in that particular problem space without having to address the problems elsewhere in their programs at the same time. Similarly, the `unflagged` flag and its companion `dont-learn` RHS action allow developers to temporarily turn learning off for debugging purposes. These facilities are provided as debugging tools, and do not correspond to any theory of learning in Soar.
+
+The `bottom-only` setting control when chunks are formed when there are multiple levels of subgoals. With bottom-up learning, chunks are learned only in states in which no subgoal has yet generated a chunk. In this mode, chunks are learned only for the "bottom" of the subgoal hierarchy and not the intermediate levels. With experience, the subgoals at the bottom will be replaced by the chunks, allowing higher level subgoals to be chunked.
+
+### Debugging Explanation-Based Chunking
+
+The best way to understand why and how rules formed is to use the `explain` command. It will create detailed snapshots of everything that existed when a rule or justification formed that you can interactively explore.  See  [explain](cmd_explain) for more information.  You can even use it in conjunction with the visualizer to create graphs depicting the dependency between rules in a sub-state.
+
+The `stats` command will print a detailed table containing statistics about all chunking activity during that run.
+
+The `interrupt` setting forces Soar to stop after forming any rule.
+
+The `explain-interrupt` setting forces Soar to stop when it attempts to form a rule from a production that is being watched by the explainer. See [explain](cmd_explain) for more information.
+
+The `warning interrupts` setting forces Soar to stop when it attempts to form a rule but detects an issue that may be problematic.
+
+The `record-utility` command is a tool to determine how much processing may be saved by a particular learned rule. When enabled, Soar will detect that a chunk matched, but will not fire it. Assuming that the rule is correct, this should lead to an impasse that causes a duplicate chunk to form. The amount of time and decision cycles spent in that impasse are recorded and stored for the rule. Rules are also flagged if a duplicate is not detected or if an impasse is not generated. 
+
+This feature is not yet implemented.
+
+### Preventing Possible Correctness Issues
+
+#### chunk allow-local-negations
+
+The option `allow-local-negations` control whether or not chunks can be created that are derived from rules that check local WMEs in the substate don't exist. Chunking through local negations can result in overgeneral chunks, but disabling this ability will reduce the number of chunks formed. The default is to enable chunking through local negations.
+
+If chunking through local negations is disabled, to see when chunks are discarded (and why), set `watch --learning print` (see [watch](cmd_watch) command).
+
+The following commands are not yet enabled.  Soar will currently allow all of these situations.
+
+#### allow-missing-osk
+Used operator selection rules to choose operator
+#### allow-opaque
+Used knowledge from opaque knowledge retrieval
+#### allow-uncertain-operators
+Used operators selected probabilistically
+#### allow-conflated-reasoning
+Tests a WME that has multiple reasons it exists
+
+### Other Settings that Control WHEN Rules are Learned
+
+#### chunk max-chunks
+
+The `max-chunks` command is used to limit the maximum number of chunks that may be created during a decision cycle. The initial value of this variable is 50; allowable settings are any integer greater than 0.
+
+The chunking process will end after max-chunks chunks have been created, even if there are more results that have not been backtraced through to create chunks, and Soar will proceed to the next phase. A warning message is printed to notify the user that the limit has been reached.
+
+This limit is included in Soar to prevent getting stuck in an infinite loop during the chunking process. This could conceivably happen because newly-built chunks may match immediately and are fired immediately when this happens; this can in turn lead to additional chunks being formed, etc. 
+
+Important note:
+
+If you see this warning, something is seriously wrong; Soar will be unable to guarantee consistency of its internal structures. You should not continue execution of the Soar program in this situation; stop and determine whether your program needs to build more chunks or whether you've discovered a bug (in your program or in Soar itself).
+
+#### chunk max-dupes
+
+The `max-dupes` command is used to limit the maximum number of duplicate chunks that can form from a particular rule in a single decision cycle. The initial value of this variable is 3; allowable settings are any integer greater than 0.  Note that this limit is per-rule, per-state.  With the default value, each rule can match three times in a sub-state and create two duplicate, reject rules before Soar will stop attempting to create new rules based on that rule.  The limit is reset the next decision cycle.
+
+This limit is included in Soar to prevent slowing down when multiple matches of a rule in a substate produce the same general rule. Explanation-based chunking can now produce very general chunks, so this can happen in problem states in which the logic leads to multiple matches, which leads to results being created multiple times in the same decision cycle.
+
+### Settings that Alter the Mechanisms that EBC Uses
+
+#### chunk add-osk
+
+The option `add-osk` control whether or not operator selection knowledge is backtraced through when creating justifications and chunks.  When this option is disabled, only requirement preferences (requires and prohibits) will be added backtraced through.  When this option is enabled, relevant desirability prefs (better, best, worse, worst, indifferent) will also be added, producing more specific and possibly correct chunks. This feature is still experimental, so the default is to not include operator selection knowledge.
+
+The following commands are not yet enabled.  Soar will always use the EBC mechanisms listed below.
+
+#### variablize-identity
+Variablize symbols based on identity analysis
+#### variablize-rhs-funcs
+Variablize and compose RHS functions
+#### enforce-constraints
+Track and enforce transitive constraints
+#### repair
+Repair rules that aren't fully connected
+#### merge
+Merge redundant conditions
+#### user-singletons
+Unify identities using domain-specific singletons
+
+If backtracing traces through the same WME multiple times via different backtrace paths, a resulting chunk may have duplicate conditions for that WME. This could be undesirable. Enabling user-singletons allows the user to specify duplicate conditions that should be merged.
+
+Singletons are defined using the `chunk singleton <type> <attr> <type>` command, where `<type>` is either "state", "identifier", or "constant", and `<attr>` is the domain-specific attribute to unify within chunks.
+
+### Chunk Naming Style
+
+The numbered style for naming newly-created chunks is:
+```
+<prefix><chunknum>
+```
+The rule-based (default) style for naming chunks is:
+```
+<prefix>*<original-rule-name>*<impassetype>*<dc>-<dcChunknum>
+```
+where:
+
+  * prefix is either chunk or justification, depending on whether learning was on for that state,
+  * chunknum is a counter starting at 1 for the first chunk created,
+  * original-rule-name is the name of the production that produced the result that resulted in this chunk,
+  * dc is the number of the decision cycle in which the chunk was formed,
+  * impassetype is one of Tie, Conflict, Failure, StateNoChange, OpNoChange,
+  * dcChunknum is the number of the chunk within that specific decision cycle.
+
+Note that when using the rule-based naming format, a chunk based on another chunk will have a name that begins with prefix followed by `-xN`, for example
+`chunk-x3*apply-rule*42-2`.
+
+### Default Aliases
+```
+learn    chunk
+cs       chunk --stats
+```
+
+### See Also
+[explain](cmd_explain) 
+[trace](cmd_trace) 
+[visualize](cmd_visualize)

docs/CLI/cmd_debug.md

@@ -0,0 +1,50 @@
+## debug
+
+Contains commands that provide access to Soar's internals.  Most users will not need to access these commands.
+
+#### Synopsis
+```
+======================================================================
+                     Debug Commands and Settings
+======================================================================
+allocate [pool blocks]         Allocates extra memory to a memory pool
+internal-symbols                                   Prints symbol table
+port                                             Prints listening port
+time <command> [args]           Executes command and prints time spent
+```
+
+#### debug allocate
+
+```
+debug allocate [pool blocks]
+```
+
+This `allocate` command allocates additional blocks of memory for a specified memory pool.  Each block is 32 kilobyte.
+
+Soar allocates blocks of memory for its memory pools as it is needed during a run (or during other actions like loading productions). Unfortunately, this behavior translates to an increased run time for the first run of a memory-intensive agent. To mitigate this, blocks can be allocated before a run by using this command.
+
+Issuing the command with no parameters lists current pool usage, exactly like [stats](cmd_stats) command's memory flag.
+
+Issuing the command with part of a pool's name and a positive integer will allocate that many additional blocks for the specified pool. Only the first few letters of the pool's name are necessary. If more than one pool starts with the given letters, which pool will be chosen is unspecified.
+
+Memory pool block size in this context is approximately 32 kilobytes, the exact size determined during agent initialization.
+
+### debug internal-symbols
+
+The `internal-symbols` command prints information about the Soar symbol table. Such information is typically only useful for users attempting to debug Soar by locating memory leaks or examining I/O structure.
+
+### debug port 
+
+The `port` command prints the port the kernel instance is listening on.
+
+### debug time
+
+```
+debug time command [arguments]
+```
+
+The `time` command uses a system clock timer to record the time spent while executing a command.  The most common use for this is to time how long an agent takes to run.
+
+### See Also
+
+[stats](cmd_stats)