% 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 (turn on by !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]
Its value may be:
 0      Disabled
 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, no spell and run-on corrections of unknown words are performed.
Else, use up to this many spell-guesses per unknown word. In that case,
the number of run-on corrections (word split) of unknown words is not
limited.

[width]
When writing to a terminal, this value is set from its width.

[verbosity]
This is the level of description printed about the internal program working.
Values 1-4 are appropriate for use by the program user.
Higher values intended for LG dictionary writers 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 in post-processing. If
more than this number of linkages found by the parser, then a random
sample of linkages is chosen.

[cost-max]
Determines the maximum disjunct cost used during parsing, where the cost
of a disjunct is equal to the maximum cost of all of its connectors.

[bad]
When True, display also linkages that fail post-processing, along with the
post-processing error that was found.

This mode is useful for people editing the dictionary or post-processing.
The invalid linkages will be outputted 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 how long the links are allowed to be. The intended use of this
is to speed up parsing by not considering very long links for most
connectors, since they are rarely used in a correct parse. An entry for
UNLIMITED-CONNECTORS in the dictionary will specify which connectors
(according to the connector matching rules) are exempt from this length
limit.

[timeout]
Determines the approximate maximum time (in seconds) that parsing is
allowed to take. After this time has expired, the parsing process is
artificially forced to complete quickly by pretending that no further
solutions can be constructed. The actual parsing time might be slightly
longer.

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

[memory]
The value of this variable has no effect for now.

[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]
Use "panic-mode" if a parse cannot be found within the time set
by !timeout. In that mode, various parse options are adjusted so
a less accurate parse can be found quickly.

[use-sat]
Note: This parser cannot find yet linkages with null-links.
Also, the !timeout setup doesn't affect it.
It is supposed to be much faster than the standard parser on very long
sentences (that have a full parse - without null links).

[walls]
The setup of this variable affects the display of the Graphics-mode
(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]
For actual use, this postscript output needs a header that is printed when
!ps-header=True is set.
Note: The postscript output currently malfunctions for sentences longer
than a page width.

[ps-header]
When True, print also an appropriate postscript header when
!postscript=True is set.

%[cluster]
%This modes is not active for now (the source code may need fixes).

%[senses]
%This modes is not active for now (the source code may need fixes).

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

[links]
When True, display complete link data, including post-processing domains.
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, including their
cost.

[batch]
When True, the program process sentences in batch-mode, in which null-links
are not allowed (as if !null=False got issued).

It is normally used with:
link-parser [dictionary name] [arguments] < input-file

The user indicates in the input file which sentences should be rejected, and
which should be accepted; the parser then notifies the user when its judgments
differ. To say that the parser "rejects" a sentence means that it does not find
any linkages without null-links.

To prepare a file for use in batch-mode, put "!batch" at the top of the file
in order to toggle it to True.
Then, for each sentence that should be rejected, precede the sentence with "*"
in the file. If it should be accepted, precede it with nothing. After
processing a batch file, the parser will then print the number of errors in the
file: i.e., the number of sentences on which its judgments differ with the
judgments indicated by the symbols.

Our GitHub repository contains several large batch-files; 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]
This mode is set to True when the standard input is not a terminal.

[rand]
Random numbers are used for sampling linkages if needed
(see "!help 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, this setting will show all the linkages without a need to
press RETURN after each one:

!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]
This command gets as an argument a file name to run in batch-mode.
See "!help batch".

[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.
% (*) marks the flags that are enabled for the default display.
%
% c                 Compact display
% d             (*) Display debug labels
% h                 Display hex node numbers (for "dot" commands debug)
% l             (*) Add a legend
% p                 Display back-pointing word-graph links
% s                 Display unsplit-words as subgraphs
% u             (*) Display unsplit-word links
% x                 Display using X11 even on Windows (if supported)
