% link-parser internal command documentation.
%
% The internal help system first displays the hard-coded one-line description
% of each variable (or command) and its current and default values, and then
% the matching text entry from this file.

[graphics]
The displayed words are marked as follows:
 [word]            Null-linked word
 word[!]           word classified by a regex
 word[!REGEX_NAME] word classified by REGEX_NAME (turn on by !morphology=1)
 word[~]           word generated by a spell guess (unknown original word)
 word[&]           word run-on separated by a spell guess
 word[?].POS       word is unknown (POS is found by the parser)
 word.POS          word found in the dictionary as word.POS
 word.#CORRECTION  word is probably a typo - got linked as CORRECTION

For dictionaries that support morphology (enable with !morphology=1):
 word=             A prefix morpheme
 =word             A suffix morpheme
 word.=            A stem

For more details see:
 https://www.abisource.com/projects/link-grammar/dict/

[constituents]
Accepted values are:
 0      Disabled (no constituent tree display)
 1      Treebank-style constituent tree
 2      Flat, bracketed tree [A like [B this B] A]
 3      Flat, treebank-style tree (A like (B this))

[spell]
If zero, spell-guessing corrections and run-on corrections of unknown
words are not performed.  Otherwise, this indicates the number of
spelling-correction guesses per unknown word. The number of run-on
corrections (word splits) of unknown words is not limited when
spell-guessing is enabled.

[width]
The terminal width, used for wrapping the printing of long sentence
diagrams.

[verbosity]
The level of descriptive debug messages that will be printed.
Values 1-4 are appropriate for use by the program user.  Higher
values are intended for LG dictionary authors and library developers.

Some useful values:
 0      No prompt, minimal library messages
 1      Normal verbosity
 2      Show times of the parsing steps
 3      Display data file search and locale setup
 5-9    Tokenizer and parser debugging
 10-19  Dictionary debugging
 101    Print all the dictionary connectors, along with their length limit

[morphology]
When False, the Graphics display (see "!help graphics") morphemes
one token. When True, the morphemes are shown as separate tokens.
Also, when a word matches a RegEx, the matching dictionary entry
is shown.

[limit]
The maximum number of linkages that are considered for post-processing.
Up to this many linkages are generated; if there are fewer parses than
this limit, then they will all be printed, in deterministic,
cost-ranked order. If there are more parses than this limit, then a
random subset will be printed. The !random option is used to control
whether this sampling will use a repeatable (deterministic) random
sequence, or not.

[cost-max]
Determines the largest disjunct cost considered during parsing. That is,
only disjuncts with a cost less than this are used during the parse;
higher-cost disjuncts are ignored.  Raising the max allowed cost will
typically produce more parses, although these will less likely be
correct.

[bad]
When True, display also linkages that are rejected by post-processing,
along with the name of the rule that resulted in the rejection.

This mode is useful when editing the dictionary or the post-processing
rule-set.  The invalid linkages will be printed after the valid ones.

The parser will only output the linkages it finds at whatever stage it
had gotten to when it found a valid linkage. For example, if it had
gotten to null-link stage 2 before finding its first valid linkage,
it will also output invalid linkages found at null-link stage 2.
There is no way of seeing invalid linkages found at earlier stages.

[short]
Determines the maximum allowed length for certain connectors. The
intended use is to speed up parsing by not considering very long links
for most connectors, since they are rarely used in a correct parse.
Setting this too low will prevent valid parses; setting this too high
will slow the system, and occasionally generate unlikely parses.
The limit applies only to those connectors not exempted by the
UNLIMITED-CONNECTORS dictionary entry.

[timeout]
Determines the approximate maximum time (in seconds) that parsing is
allowed to take. If a parse is not found before this time, normal parsing
is halted, and a "panic parse" mode is entered. During the panic parse,
a looser, less restrictive set of parameters is used (primarily, a
larger !cost-max), in an effort to find some, any parse.  Panic mode
can be enabled and disabled with the !panic option.

For the SAT parser (see "!help use-sat") this option has no effect (yet).

[memory]
The value of this variable has no effect at this time.

[null]
When False, only linkages with no null links are considered.
When True, if the parser tries to find linkages with the minimal
possible number of null links.

[panic]
If enabled, then a "panic-mode" will be entered if a parse cannot be
found within the time limit set by !timeout. When in panic mode, various
parse options are loosened so a less accurate parse can be found quickly.

[use-sat]
Use the Boolean-SAT parser instead of the traditional parser. The SAT
parser can be much faster on long sentences, but is usually a little
bit slower for most "normal" sentences.

This parser is not able to find linkages with null-links.  It does not
honor the !timeout option.

[walls]
Alters the display of parsed sentences (see "!help graphics").
When True, the RIGHT-WALL and LEFT_WALL are always displayed.
When False, they are not displayed if their links are not considered
"interesting" (by a hard-coded criterion in the LG library).

[islands-ok]
This option determines whether or not "islands" of links are allowed.
For example, the following linkage has an island:

linkparser> this sentence is false this sentence is true
No complete linkages found.
Found 16 linkages (8 had no P.P. violations) at null count 1
	Linkage 1, cost vector = (UNUSED=0 DIS= 0.00 LEN=11)

    +----------->WV---------->+
    +------->Wd-------+       |
    |        +--Dsu*c-+--Ss*s-+-Paf-+       +--Dsu*c-+--Ss*s-+--Pa-+
    |        |        |       |     |       |        |       |     |
LEFT-WALL this.d sentence.n is.v false.a this.d sentence.n is.v true.a

[postscript]
Generate postscript output. The generated postscript requires a header
in order  to be properly displayed; the header is printed by setting
!ps-header=True.

The postscript output currently malfunctions for sentences longer
than a page width.

[ps-header]
When set, and when !postscript=True is set, then the postscript header
will be printed.

%[cost-model]
%The only allowed value is 1 for now (the source code may need fixes).

[links]
When enabled, this will display each link, one per line, with the
words and connectors at each end of the link. The post-processing
domains are also displayed.

This mode is set to True when the standard input is not a terminal.

[disjuncts]
When True, display the disjuncts that used for each word, together
with their cost.

[batch]
When True, the program process sentences in batch-mode. During batch
mode, the usual parse printing is suppressed; only errors are reported.
In batch mode, a leading * in the first column can be used to indicate
a non-grammatical sentence. If such a sentence parses, an error is
printed. Conversely, an error is reported if no parses are found for
a valid sentence.

Batch testing is typically performed by piping a file to the parser;
for example
   link-parser [dictionary name] [arguments] < input-file
or
   cat input-file | link-parser [dictionary name] [arguments]

This flag is then usually placed at the beginning of the input-file
(other options may be specified, as well). Setting the !echo flag
can be useful, as it will echo the input sentence.

Our GitHub repository contains several large batch-files used during
testing and development; for English, the three most important ones
are "corpus-basic.batch", "corpus-fixes.batch" and "corpus-fix-long.batch".
See: https://github.com/opencog/link-grammar/tree/master/data/en

For more details see BATCH-MODE in:
https://www.abisource.com/projects/link-grammar/dict/introduction.html

[echo]
Print the original input sentence. This is primarily useful when working
in !batch mode, which otherwise suppresses output.

This mode is set to True when the standard input is not a terminal.

[rand]
If set to true, then a repeatable random sequence will be used, whenever
a random number is required.  The parser almost never uses random
numbers; currently they are only used in one place: to sample a subset
of linkages, if there are more parses than the linkage limit.
See "!help limit" for info on the linkage limit.

[debug]
This variable is for LG library development.
Its purpose is to limit debug output, which may have a big volume
otherwise, to certain functions or files. For example:

  $ link-parser -verbosity=6 -debug=flatten_wordgraph,print.c

will only show messages from the `flatten_wordgraph()` function or the
print.c file.

For more details see debug/README.md in the LG library source code
directory.

[test]
This variable is used to enable features that are for debug or have yet
no other variable to control them.  For example, to show all the
linkages without a need to press RETURN, use:

  !test=auto-next-linkages

For more details, see debug/README.md and link-grammar/README.md
in our GitHub repository https://github.com/opencog/link-grammar .

[file]
Read text from this file. The file is assumed to contain sentences
and/or option settings.  It is typically used for reading in batch-mode
files (see "!help batch") but can also be useful in other scripting
situations.

[variables]
Variables can be set as follows:

 !<var>          Toggle the specified Boolean variable.
 !<var>=<val>    Assign that value to that variable.

[wordgraph]
This variable controls displaying the word-graph of the sentence.
The word-graph is a representation of the relations between the sentence
tokens, as set by the library tokenizer before the parsing step.

Its value may be:
 0      Disabled
 1      Default display
 2      Display parent tokens as subgraphs
 3      Use esoteric display flags as set by !test=wg:FLAGS

% FLAGS documentation:
% These flags are defined in wordgraph.h.
% Below, unsplit-word means a token before getting split.
% 1 and 2 mark the flags that are enabled in that modes.
%
% c                 Compact display
% d             1   Display debug labels
% h                 Display hex node numbers (for "dot" command debug)
% l             1,2 Add a legend
% p                 Display back-pointing links
% s             2   Display unsplit-words as subgraphs
% u             1   Display unsplit-word links
% x                 Display using X11 even on Windows (if supported)
