home *** CD-ROM | disk | FTP | other *** search
/ The Education Master 1994 (4th Edition) / EDUCATIONS_MASTER_4TH_EDITION.bin / files / progmisc / qparser1 / qphelp.hlp < prev    next >
Encoding:
Text File  |  1991-09-21  |  31.4 KB  |  739 lines

  1.                  QPARSER help file 'qphelp.hlp'.
  2.      COPYRIGHT (C) 1990, QCAD Systems, Inc.  All rights reserved.
  3.  
  4.   This is the help file for Qparser's debugging and other menus.
  5.   This is supposed to reside in a file designated by the environment
  6. variable QPHELP, or if QPHELP isn't defined, in the local directory as
  7. file 'qphelp.hlp'.
  8.   It is called out through a 'topic', which appears in here prefixed
  9. by an @ sign in column one, e.g. '@inspect_sem' below.
  10.   You can add topics, or make use of the 'help.c' ('uhelp.pas') file
  11. that displays help information on the screen.
  12.  
  13. @inspect_sem
  14.  
  15.   [inspect_sem] ?(help, N(ame, A(ll names, T(ree, U(p
  16.  
  17.   This lets you inspect one semantics structure (record), for example, any
  18. semantics structure carried on the stack.  You can also examine other
  19. parser features.
  20.  
  21.   F1 key (PC only) -- append the screen contents to file 'screen.txt'.
  22.  
  23.   N(ame -- prompt for a user-level identifier, and describe its properties.
  24. The name is case-sensitive -- the name 'SAM' is considered different than
  25. 'sam' or 'Sam'.  The name is supposed to match something placed in the
  26. symbol table, for example by the function 'get_symbol'.
  27.  
  28.   A(ll -- report all the identifiers carried in the symbol table.  Reserved
  29. words (at level -1) are ignored.
  30.  
  31.   T(ree -- report the semantic tree structure rooted in this semantics
  32. record.  For this to work properly, you must have generated the tree with
  33. the QTREEs option set, and have taken care to follow the tree-building
  34. conventions if you have generated tree nodes through private code.  The
  35. tree report of a ROOT node and its children looks like this:
  36.  
  37.    ROOT (this is a production tag, or GENL_KIND if the production is untagged)
  38.    +-1 left child (position ONE, CHILD or LEFT)
  39.    |
  40.    |
  41.    +-2 next child (position TWO or RIGHT)
  42.    |
  43.    +-3 next child (position THREE)
  44.  
  45. Any of the children of ROOT can be tree structures.  For example,
  46.  
  47.    ROOT
  48.    +-1 STMTLIST
  49.      +-1 ASSIGN
  50.      |  +-1 IDENT
  51.      |  +-2 PLUS
  52.      |     +-1 FIXED
  53.      |     +-2 IDENT
  54.      +-2 GOTO
  55.  
  56. represents a code fragment that might look like this originally:
  57.  
  58.    k = 16 + l;    /* the ASSIGN */
  59.    goto 15;       /* the GOTO */
  60.  
  61.    U(p -- return to the previous debug level, if any.  After working
  62. down into a semantics tree structure, you can go back up with 'U'.
  63. (the ENTER key also returns).
  64.  
  65.    S(ym -- appears when the object is a user identifier.  This brings up
  66. a submenu that reports the identifier's properties, and perhaps
  67. additional semantics information to explore.  See the '?' option
  68. under this submenu, or topic 'dump_sym'.
  69.  
  70.    The values of literal numbers and strings are reported.  Identifiers
  71. can be explored more deeply through a symbol table inspection prompt.
  72.    In order for this to work well, you need to keep function 'dump_sym'
  73. and 'dump_sem' in good repair, corresponding to the typedefs 'symtabtype'
  74. and 'semrectype', respectively.  With QTREES, you probably don't need
  75. to do anything about 'semrectype', but you will almost surely have several
  76. more identifier types to deal with.
  77.  
  78. @inspect_stack
  79.  
  80.      1:   1 Stmts      GENL_KIND:
  81.      2:  18 QUIT       NULL
  82.   *  3:  22 <eol>      NULL
  83.   [inspect_stack] ?(help, N(ame, A(ll names,
  84.      I(nspect, T(ree, +(tos, -(tos, ENTER?
  85.  
  86.   This permits inspection of the state and semantics stack.  These two
  87. stacks correspond, except when error recovery is in progress.
  88.   The parser stack is shown -- in the example, it contains 3 items.
  89. TOS is the last item shown -- #3 in the example.  A 'referenced' stack
  90. element is marked with '*'; its position can be moved up and down with
  91. the '+' and '-' keys.
  92.   From left to right in each stack element:
  93.  
  94.      stack position, counting 1 at the bottom of the stack (ex: 1)
  95.      state number (ex: 1)
  96.      in-symbol corresponding to the state (ex: Stmts)
  97.      semantics type (ex: GENL_KIND)
  98.      (optionally) other semantics information
  99.  
  100.   F1 key (PC only) -- append the screen contents to file 'screen.txt'.
  101.  
  102.   N(ame -- prompt for a user-level identifier, and describe its properties.
  103. The name is case-sensitive -- the name 'SAM' is considered different than
  104. 'sam' or 'Sam'.  The name is supposed to match something placed in the
  105. symbol table, for example by the function 'get_symbol'.
  106.  
  107.   A(ll names -- report all the identifiers carried in the symbol table.
  108. Reserved words (at level -1) are ignored.
  109.  
  110.   I(nspect -- inspect the 'referenced' semantics frame (marked with '*').
  111. This option will appear only if the semantics frame is coordinated with
  112. the state stack.  See the help option or topic 'inspect_sem' for details.
  113.  
  114.   T(ree -- display the semantics tree attached to the 'referenced' semantics
  115. frame.  This option will appear only if the semantics frame is coordinated
  116. with the state stack.  See topic 'inspect_sem' for details about tree
  117. representation.
  118.  
  119.   +(tos -- move the referenced stack position toward to the stack top.
  120.  
  121.   -(tos -- move the referenced stack position away from the stack top.
  122.  
  123.   ENTER -- return to the calling environment.
  124.  
  125. @inspect_sym
  126.  
  127.   What symbol (case-sensitive!) ? A
  128.    0> SYM: A  (USER)
  129.    0>  U(p u
  130.  
  131.    This menu invites you to explore the properties of the identifier,
  132. based on information in its symbol table struct.  The default information
  133. isn't much, but you will want to expand this description as you design
  134. attribute classes for identifiers.
  135.  
  136.    What symbol (case-sensitive!) ? -- enter a name, usually upper case
  137. is required.
  138.  
  139.    U(p -- return to calling environment.
  140.    F1 key (PC only) -- append the screen contents to file 'screen.txt'.
  141.  
  142. @set_prodtraps
  143.  
  144.   1:   Expr -> Expr + Term #PLUS
  145.   2:   Expr -> Expr - Term #MINUS
  146.        (etc.)
  147.  17:   Term -> Fact
  148.  18:   Term -> Term * Fact #MPY
  149. [set_prodtraps] ?(help, C(lear all, S(elect all,
  150.   #( <number>, SPACE, ENTER
  151.  
  152.    This menu invites you to set a parser trap on one or more productions.
  153.  
  154.    F1 key (PC only) -- append the screen contents to file 'screen.txt'.
  155.    C(lear all -- clear all the traps.
  156.    S(elect all -- set a trap on every production.
  157.    #( <number> -- set or clear a trap on a production by its
  158. number in the list.  You can enter several numbers, including numbers not
  159. shown on the screen.  The number associated with a production is its
  160. reduce state, which won't change unless you change the grammar and
  161. recompile.  The same production may appear more than once in the list
  162. in different reduce states.
  163.    SPACE -- continue the listing of productions, one screen at
  164. a time.  When the end is reached, it will start over from the top.
  165.    ENTER -- return to the calling debug environment.
  166.  
  167.    The productions are ordered by their reduce state number, and the
  168. same production may appear in the list more than once.  A trap may be
  169. set on a production whether or not it is tagged.
  170.    The trap is sprung in a reduce state in function 'parser', and will
  171. occur regardless of the setting of the 'debug' level.
  172.    You must have compiled your parser with the '-d' option of LR1P for
  173. each file containing the 'debugging' flag.
  174.  
  175. @set_nodetraps
  176.  
  177.   OTHER
  178.   SEMERR
  179.     (etc.)
  180.   REALVAL
  181.   UMINUS
  182. [set_nodetraps] ?(help, S(elect all, C(lear all,
  183.   #( <tag>, SPACE, ENTER?
  184.  
  185.    This menu sets traps in a tree evaluator or semantics checker AFTER
  186. an abstract tree has been generated.  Recall that under QTREES, an AST
  187. is built through parsing actions, during which the source is scanned.
  188.  
  189.    F1 key (PC only) -- append the screen contents to file 'screen.txt'.
  190.    S(elect all -- set a trap on every node.
  191.    C(lear all -- clear all node traps.
  192.    #( <tag> -- select or unselect this particular tag.  The tags
  193. are associated with productions, which are displayed on the screen.
  194. You can enter several names on this line, and the names don't have
  195. to appear on the display.  Enter the tags like this:
  196.  
  197.         # ADD  SUB  ASSIGN  (etc.)
  198.  
  199.    SPACE -- show more names and productions, or start over with the list.
  200.    ENTER -- return to the previous environment or continue.
  201.  
  202.    At some point, you need to call a tree walking function through a
  203. production REDUCE action, in the APPLY function.  The tree walker is
  204. usually a set of recursive functions that select on the production tags
  205. found as tree tags.
  206.    In order to trap on a tree node, you need to include calls to the functions
  207. 'traceit' and 'endit' wherever the tree walker will encounter a node.
  208. These must appear in nested-pair fashion, i.e. every 'traceit' call must
  209. be accompanied at some later time by a matching 'endit' call.  See the
  210. tiny Pascal example semantics routines for examples of this coding.
  211.    When the trap is sprung, you can examine the tree in detail, walking
  212. down through it, looking at its structure, attributes, etc. just prior
  213. to its evaluation by the tree walker.
  214.  
  215. @idebug
  216.  
  217.   [idebug] ?(help, N(ame, A(ll, D(bug level,
  218.      P(rodTrap, T(race, L(ex, S(tack, ENTER?
  219.  
  220.    This is a master debugging menu, called on any trap, which was
  221. triggered in one of these ways:
  222.     1) By a debug level > 0 through a parser action.
  223.     2) By the '-d' option when the compiled parser is executed.
  224.     3) By including the debug trap character '!' in the parsed source
  225. file somewhere.  (The trap character '!' is defined in function GET_TOKEN
  226. in file SKELLEX.)
  227.  
  228.    F1 key (PC only) -- append the screen contents to file 'screen.txt'.
  229.  
  230.    N(ame -- prompts for a user identifier name, and reports its symbol
  231. attributes.
  232.  
  233.    A(ll -- report all the user identifiers known at this point, except
  234. reserved names.
  235.  
  236.    D(bug level -- set parser trap levels and reporting levels.
  237. Level 0 is no reporting.  Level 1 reports each reduce action, showing the
  238. production about to be reduced, and this menu line.  Level 2 reports each
  239. reduce action, the current stack contents, and the production about to
  240. be reduced.  Level 3 reports all level 2 activity, and in addition, each
  241. SHIFT and LOOKAHEAD transition.  Level 4 reports all the level activity,
  242. and in addition, all parser actions involved in an error recovery sequence.
  243.    The parser traps are written into function 'parser' and require
  244. source generation with the '-d' option of LR1P to be effective.
  245.  
  246.    P(rodtrap -- set traps on particular productions.  Set the debug level
  247. to 0 to bypass all reduce actions except those for the productions you've
  248. selected.  See 'help' under this menu selection or topic 'set_prodtraps'
  249. for details.
  250.  
  251.    T(race -- set a trap on the evaluation phase of an abstract syntax
  252. tree, AFTER the tree has been constructed.  This requires careful attention
  253. to coding the tree evaluator functions.  See 'help' under this selection
  254. or topic 'set_nodetraps' for details.
  255.  
  256.    L(ex -- report the current state of the lexical analyzer.  The 'next'
  257. token, its token number and other information are given.
  258.  
  259.    S(tack -- enter a semantics stack inspector, to examine the
  260. semantics stack and any trees rooted in the stack in detail.  See 'help'
  261. under this selection or topic 'inspect_sem' for details.
  262.  
  263.    ENTER -- continue parsing from wherever this menu was called.
  264.  
  265. @gramchk
  266.  
  267.   'gramchk' checks some basic grammar properties, including the grammar
  268. syntax.  It also provides listings of useful information.
  269.   You can run 'gramchk' with just a grammar name, as follows:
  270.  
  271.   gramchk  gramfile
  272.  
  273. This will cause gramchk to check your grammar's syntax, to look for
  274. nonterminals that can't generate any terminal strings, and for any
  275. tokens that can't be derived from the goal symbol.
  276.   Some of the 'gramchk' tests are built into LR1, and others aren't.
  277. (LR1 also complains if the grammar isn't LALR(1), which 'gramchk'
  278. doesn't check for.)
  279.  
  280.   To obtain more details on gramchk's services, do the following:
  281.  
  282.   Run 'gramchk' with no parameters -- you will obtain a list of the
  283. options possible.  You can combine several options under the same '-'
  284. flag, or separate them.  Any number of options can be chosen, or none,
  285. and their order doesn't matter.
  286.  
  287.   If you want more detailed help on any one option, for example, the 'f'
  288. option, run gramchk as follows:
  289.  
  290.   gramchk -f?
  291.  
  292. This will display help information on that topic.
  293.  
  294.   Any of the information or tables may be redirected to a file or printer,
  295. as follows:
  296.  
  297.   gramchk (options) grammar > FILE
  298.  
  299. Your printer is probably attached to device PRN, LPT1 or LPT2 -- use one
  300. of those names as FILE to print the information.
  301.  
  302.   The line length of certain reports -- production rules in particular --
  303. is not bounded, which may cause problems in your editor or printer.  Most
  304. of the report line are limited to 75 characters.
  305.  
  306. @lex
  307.  
  308.   Option -l causes a series of lexical tests to be
  309. performed.  These tests depend on the language mode you are in -- see
  310. topic 'langmode' for more details.  This version is set up to
  311. deal with the C and Pascal languages only.
  312.   These tests look for problems that the Qparser lexical analyzer
  313. will likely have in identifying the tokens you have specified in your
  314. grammar.
  315.   Gramchk can only look for problems with the STANDARD Qparser lexical
  316. analyzer under C or Pascal lexical rules.  If you are using non-standard
  317. skeleton files, the reported problems may not exist, or you may have
  318. lexical problems that this can't look for.  (The C code for gramchk is
  319. shipped with the product so that you can adapt it to unusual lexical
  320. situations if you want to.)
  321.   Details on Qparser's lexical analysis are given in the manual.  Here's
  322. a summary:
  323.  
  324.   1. Identifiers (<identifier>) are assumed to start with a letter
  325. and continue with letters, digits or underscore (_).  It's OK to have
  326. specific tokens look like an identifier, but it's NOT OK to have a
  327. token that starts with a letter, but includes any character other than
  328. letters, digits or underscore.  For example, any of these tokens
  329. are considered illegal:
  330.  
  331.     TOK*
  332.     C++
  333.     alphabet%soup
  334.  
  335. You will have to modify the lexical analyzer, in particular 'get_token'
  336. and 'get_symbol', to deal with such cases.
  337.   A WARNING will appear if an identifier can be followed by some token
  338. whose first character is a letter, digit or underscore -- you will have
  339. to make sure that a SPACE appears as a separator between such tokens.
  340.   A WARNING will appear if any token starts with a lower-case letter.  The
  341. default lexical analyzer upshifts the letters in all such tokens from
  342. lowercase to uppercase, making such tokens unrecognizable.  You can
  343. easily change this convention -- see skellex.c or skellex.pas.  When
  344. such tokens are built into the Qparser tables, their case is NOT changed --
  345. they will appear in the tables exactly as entered in the grammar. 
  346.  
  347.   2. Integers (<integer>) are assumed to start with a digit and continue
  348. with digits.  It's NOT OK to have any other token start with a digit.
  349. For example, any of these are considered illegal:
  350.  
  351.     5xyz
  352.     0*66
  353.  
  354. You will have to modify the lexical analyzer, in particular 'get_token'
  355. and 'get_number', to deal with such cases.
  356.   A WARNING will appear if an integer can be followed by some token
  357. whose first character is a digit -- you will have
  358. to make sure that a SPACE appears as a separator between such tokens.
  359.  
  360.   3. Real numbers (<real>) are assumed to start with a digit or a
  361. decimal point.  It's NOT OK to have any other token start with a digit
  362. or a decimal point, therefore.
  363.  
  364. For example, any of these are considered illegal:
  365.  
  366.     5xyz
  367.     ..
  368.     .XOR.
  369.  
  370. You will have to modify the lexical analyzer, in particular 'get_token'
  371. and 'get_number', to deal with such cases.
  372.   A WARNING will appear if an integer or real can be followed by some token
  373. whose first character is a digit, letter or '.' -- you will have
  374. to make sure that a SPACE appears as a separator between such tokens.
  375. The reason for this warning is that if a '.' or letter 'E' follows a
  376. digit string with no separating space, the lexical analyzer assumes that
  377. a real number is being scanned.
  378.  
  379.   4. Strings (<string>) are assumed to start with a string-quote
  380. character -- " in C, ' in Pascal.  It's NOT OK to have any other token
  381. start with a quote character.
  382.  
  383. For example, this is considered illegal tokens under C rules:
  384.  
  385.     "xx
  386.  
  387. You will have to modify the lexical analyzer, in particular 'get_token'
  388. and 'get_string', to deal with such cases.
  389.  
  390.   5. Comments can appear anywhere.  In the C skeletons, a comment
  391. follows C rules -- it opens with '/*' and closes with '*/'.  Clearly,
  392. no token should start with '/*', otherwise it'll be confused with
  393. a comment opening.  In the Pascal skeletons, a comment is assumed to
  394. open with '{' and close with '}'.
  395.   If your grammar contains the token <eol>, the rules change -- a
  396. comment is assumed to open with a semicolon ';' and close at the
  397. end of the line.  Clearly no token can open with ';'.
  398.   See function 'skipblanks' in file 'skellex' for details on
  399. how comments are identified and scanned.  You can easily change the
  400. rules to suit your situation.
  401.  
  402. @nullables
  403.  
  404.   A 'nullable' nonterminal is a nonterminal that can derive the
  405. empty string <empty>.  The derivation can entail any number of rule
  406. expansions.  Option -n prints the nullable nonterminals that exist
  407. in your grammar.
  408.  
  409. @prods
  410.  
  411.   Option -p prints the productions with their flags in the order that
  412. they appear in your grammar.  These are reformatted, and not just a
  413. copy of how they appear in your source grammar.  The index numbers
  414. refer to their position in the input file.
  415.   NOTE: When you run 'lr1', the table 'prodx' is indexed by a reduce
  416. state number, not a production number, and refers to the associated
  417. production.  The reduce state number will usually not correspond to
  418. the production's input file index.
  419.  
  420. @flags
  421.  
  422.   Option -f prints the production flags -- sorted alphabetically --
  423. and the production or productions with which each one is associated.
  424. You can use this to look for multiply-defined flags, which are legal
  425. but may not be what you expect.
  426.   Note that each flag name will be declared within your parser program
  427. as a #define (in C) or a 'const' (in Pascal).  You need to be aware
  428. that a flag may conflict with a keyword or user symbol in its scope.
  429. Gramchk will warn you about conflicts with host language keywords
  430. and Qparser names.
  431.  
  432.   Option -fC prints the production flags -- sorted alphabetically --
  433. and the productions, then lists the child node flags that can appear
  434. under each of the production's right member nonterminals.
  435.  
  436.   Option -fP prints the production flags -- sorted alphabetically --
  437. and the productions, then lists the node flags that can appear as this 
  438. node's parent.
  439.  
  440. @preds
  441.  
  442.   Option -P displays the predecessors of each token in the language,
  443. whether terminal or nonterminal.  The predecessor set pred(T) for a
  444. token T is defined as follows:
  445.  
  446.   Given a production
  447.  
  448.      A -> w1 w2 w3 ...
  449.  
  450.   then 1) pred(w1) will contain pred(A),
  451.        2) pred(w2) contains w1,
  452.        3) pred(w3) contains w2, etc.
  453.  
  454.   It can be shown that if token T appears in the semantics stack
  455. during an LR parse, then the token preceding it in the stack (i.e. deeper
  456. in the stack) will be a member of pred(T).  The converse is true if
  457. the grammar is closed -- i.e. every nonterminal can derive the empty
  458. string and can be reached from the goal token by some derivation.
  459.  
  460. @crossref
  461.  
  462.   Option -r generates a cross-reference table of tokens in your
  463. grammar.  The tokens are sorted, and the production indices that
  464. contain at least one instance of the token are listed.  We suggest
  465. running
  466.  
  467.   gramchk -pr
  468.  
  469. to also produce an indexed production list.
  470.  
  471. @sprods
  472.  
  473.   Option -s generates an indexed list of productions sorted by
  474. their left member.  (The index numbers correspond to their position
  475. in the input file, but are usually out of order).
  476.  
  477. @tokens
  478.  
  479.   Option -t generates a list of the tokens and their token indices
  480. assigned by Qparser.  The terminal tokens are listed first, followed
  481. by the nonterminal tokens.
  482.   The token index will be built into the parsing tables and into
  483. the function 'get_token'.  Function 'get_token' is partially built
  484. by Qparser based on this list of token numbers.
  485.  
  486. @firstfol
  487.  
  488.   Option -F generates a list of the 'first' and 'follow' sets.  These
  489. are explained in more detail in the manual and in most popular compiler
  490. construction textbooks.  They are useful in constructing an LL(1)
  491. parser, and in understanding LR(1) parser conflicts.  A summary follows:
  492.  
  493.   first(N) is a mapping of the set {terminals, nonterminals} to the
  494. set {terminals, <empty>}.  Essentially, first(N) is the set of all
  495. terminal tokens that can appear as the leftmost token in any string
  496. derivable from N.
  497.  
  498.   follow(N) is a mapping of the set {terminals, nonterminals} to the
  499. set {terminals, nonterminals, <stop>}.  Let S be any sentential
  500. form derivable from the goal symbol G:
  501.  
  502.   G ==>* S
  503.  
  504. and let S contain a token W followed by a string w:
  505.  
  506.   S = x W w
  507.  
  508. Then head(w follow(S)) is in follow(W), where 'head' is the left-most
  509. character of the composite string
  510.  
  511.   w follow(S)
  512.  
  513. The token <stop> will always be in follow(G).
  514.  
  515. @ll1gen
  516.  
  517.   The -L option causes gramchk to ignore its other options (except
  518. for this help feature) and generate a set of arrays that can be used to
  519. build an LL(1) parser.  (This is primarily for the benefit of our academic
  520. users -- we don't recommend an LL(1) parser for commercial use).
  521.   The syntax of the tables will be in either C or Pascal form, depending
  522. on the setting of the language mode option '-m'.
  523.   The tables can be included in a parser program (not supplied), which
  524. can use the 'lex' file generated from 'skellex' as the lexical analyzer.
  525. A more complete description of the tables can be found in "Compiler
  526. Construction: Theory and Practice", Barrett and Couch.
  527.   LL(1) conflicts are reported as comments, and should be dealt with in
  528. order that the parser recognize the whole language.
  529.   The 'token' table is an array of tokens indexed by token number.  This
  530. isn't required in the LL(1) parser, but can be used to make a table-driven
  531. lexical analyzer.
  532.   The 'rpartx' table is an array of indices into 'rpart'.  Given the
  533. production rule index P, where the length of the right member is N, then
  534. the production is
  535.  
  536.    A -> rpart[rpartx[P]+N-1] rpart[rpartx[P]+N-2] ...
  537.           rpart[rpartx[P]+0]
  538. Notice that the right member is in reverse order as it appears in the
  539. 'rpart' table.  The element rpart[rpartx[P]] is always 0, so that it
  540. can be used as a stopper.  Except for the '0', each 'rpart' element is
  541. a token number.  Only the right members are listed -- the left member
  542. isn't required.
  543.   The 'nttx', 'nttl' and 'aprodn' tables are organized in a similar manner,
  544. and are entered by a token number.  Their use is explained below.
  545.  
  546.   If your grammar is LL(1), then an LL(1) parser can be built as follows:
  547.  
  548.   1. Provide a pushdown stack containing token numbers, initially containing
  549. the 'goal' token -- this is token rpart[0].
  550.   2. Given a token T on the stack top, and a token R under the read head,
  551.       a. If token N is the <stop> token, the stack should be empty.  HALT.
  552.       b. If T is a terminal, it must match token R, else SYNTAX ERROR.
  553.          Pop the stack and move the read head one position (i.e. request
  554.          the next token by calling 'next_token').  Go to step (a).
  555.       c. If T is nonterminal, enter the 'nttx' table with the index
  556.             T - NT_OFFSET
  557.          Let n = nttx[T - NT_OFFSET].
  558.       d. Scan the 'nttl' table starting at index n, continuing until
  559.            nttl[n] == 0  (syntax error)
  560.          OR
  561.            nttl[n] == R. (OK)
  562.       e. Table aprodn[n] is an index into the 'rpartx' table.  Pop the
  563.          stack and push the right member of the production onto the
  564.          stack such that the left-most token in the right member is
  565.          on the stack top.  You can just push the 'rpart' elements
  566.          into the stack, starting with index k= n, incrementing k,
  567.          until rpart[k] == 0. This is an 'apply' step and can be
  568.          used to develop semantics and/or code generation based on the
  569.          selected production.
  570.       f. Table 'map' is indexed by 'n' from step (e); it contains
  571.          a flag index related to the 'flags' table.  Use this to apply
  572.          your semantics to a particular production rule on an apply step.
  573.          Go to step (a).
  574.   3. Recovery from a syntax error is a difficult topic and can't be dealt
  575.      with here.
  576.  
  577. @langmode
  578.  
  579.   Option -mX selects one of three 'language modes': C, P (for Pascal),
  580. or N (for none).  If you are using a semantics-extended grammar, it's
  581. important that you select this mode when using gramchk, otherwise you'll
  582. probably get a grammar syntax error.
  583.   The default language is C.
  584.   This mode is also used in the -l and -L options, which are sensitive
  585. to the language choice.
  586.  
  587. @lr1
  588.  
  589.   lr1 [options] GFILE
  590.  
  591.   GFILE is a grammar file name, which can appear with or without its
  592. standard suffix '.grm'.  lr1 generates a binary table file 'GFILE.tbl'.
  593. A grammar file consists of BNF-style production rules, in the form
  594.  
  595.   Left -> { RightToken } [ #tag ]
  596.  
  597. in one line, i.e. a line feed terminates a production rule.  The token
  598. 'Left' is considered a nonterminal.  All rules with the same 'Left' must
  599. be grouped together.  Each 'RightToken' is a nonterminal or a terminal.
  600. Terminal tokens stand for themselves, and can be quoted if special
  601. characters are used.
  602.   The 'tag' is a case-sensitive name that must be compatible with a
  603. user identifier in the host language -- it will show up as a 'const'
  604. in Pascal or a 'define' in C skeletons.
  605.   The special terminals
  606.  
  607.   <stop> <eol> <identifier> <real> <integer> <string>
  608.  
  609. stand for end-of-file, end-of-line, user identifier, floating-point
  610. number, integer, and quoted string, repectively in the source file.
  611. The form of these is defined in file SKELLEX and can be modified.
  612.   The default <identifier> starts with a letter, and continues with
  613. letters, digits and the underbar character.  See function 'get_symbol'
  614. in file skellex.
  615.   The default <real> is known through an embedded decimal point, or
  616. an exponent part or both.  See function 'get_number' in file skellex.
  617.   The default <integer> is a simple decimal number.  See function
  618. 'get_number' in file skellex.
  619.   The default <string> is Pascal-style in the Pascal skeletons and
  620. C-style in the C skeletons.  See function 'get_string' in file skellex.
  621.  
  622.   A brief list of the options are provided by running 'lr1' with no
  623. options, i.e.
  624.  
  625.   lr1
  626.  
  627. which should produce the following report:
  628.  
  629.   QPARSER vs. 4.7
  630.   Copyright (c) QCAD Systems, Inc. 1990.  All rights reserved.
  631.   Usage: lr1 [options] GrammarFile [RptFile]
  632.   options:  -t   dump tokens
  633.           -p   dump productions
  634.           -n   dump nullable nonterminals
  635.           -i   dump itemsets
  636.           -mL  language mode -- L==C, P, N
  637.           -MN  dump state machine
  638.                  N= 1, 2: dump level
  639.           -r   dump reads/includes/lookbacks
  640.           -T tablefile   table file name
  641.           -s   suppress single-production bypassing
  642.           -?   help: more description of the options
  643.           -C   generate table file compatible with 3.0
  644.   (default tablefile name is grammar-filename.tbl)
  645.  
  646.   The token and production lists are self-explanatory.
  647.   A "nullable nonterminal" is a nonterminal that can generate an
  648. empty string.  Option -n lists all of these associated with the grammar.
  649.   An "itemset" (-i) is a collection of marked productions associated with
  650. a state in the LR parsing machine.  You need to study LR table construction
  651. to understand these.  Option '-r' produces an itemset dump at a later
  652. stage that reports the LALR 'reads', 'includes' and 'lookback' sets,
  653. described in the Penello/DeRemer paper on this construction method.
  654.   The language mode (-mC, -mP, -mN) is required if you are using a
  655. semantics-extended grammar.  (Such a grammar has semantics attached to
  656. one or more production rules).  The grammar scanner must know the
  657. language mode (C, Pascal or None) in order to scan the semantics rules
  658. properly.
  659.   The "state machine" (option -M) is a semi-reduced representation of 
  660. the LALR state machine in terms of reduce, shift and lookahead states, 
  661. and their transitions.  This is derived from the itemsets, but the 
  662. states have been renumbered.
  663.   Option -T specifies an alternative table file name.  The default table
  664. file name is derived from the grammar name.
  665.   Option -s suppresses an optimization by which some single productions
  666. are bypassed.
  667.   Option -C causes LR1 to generate a table file compatible with the
  668. older version 3.0 Qparser system.  You can use such a file with any
  669. earlier version of LR1P.
  670.  
  671. @lr1p
  672.  
  673.   lr1p requires a table file and a skeleton file.  It produces an
  674. expanded source file as its 'standard-out' -- this is normally
  675. redirected to a source file.
  676.   The skeleton file is mostly copied, except for sections delimited
  677. by the special tokens '{##' and '##}'.  These contain a source
  678. generator program, whose definition is too complicated to describe
  679. here.  Each generator program section is replaced by source code
  680. based on the grammar tables and the generator directions.  The intent
  681. is to produce source ready to compile, whether by a C or Pascal
  682. compiler or whatever.
  683.   Running lr1p by itself produces a brief listing of its options,
  684. similar to the following:
  685.  
  686.   LR1P [options] tablefile skeletonfile [targetfile]
  687.        (or redirect output to target source file)
  688. Options:
  689.   -d   include debug code (default: no debug code)
  690.   -mX  language mode (X= P or C).  C is the default.
  691.   -t charfile  
  692.   -?   help: describes options and operations
  693.   -C   accept vs. 3.0 compatible table file
  694.  
  695.   Option -d causes lr1p to generate material needed by the debugging
  696. system.
  697.  
  698.   Option -mP selects Pascal mode, and -mC C mode.  These are used to
  699. determine how 'qstring' and 'qcharacter' will expand strings and
  700. characters.  Option -t selects a character translation file, which is
  701. a more general way of controlling string and character expansion.
  702.   In Pascal mode, a single-quote character in a string or character will 
  703. expand into a pair of single quotes.  qstring and qcharacter will enclose
  704. the resulting string or character in a pair of single quotes.
  705.   In C mode, a double-quote in qstring will appear as \", a backslash
  706. in qstring or qcharacter will appear as \\, and a single quote in a
  707. qcharacter will appear as \'.  qstring will enclose the string in double
  708. quotes.  qcharacter will enclose a character in single quotes.  All other
  709. characters appear "as is".
  710.   If the -t option is selected, a character expansion file is read.  Please
  711. see the user manual or release notes regarding its format and usage.  It
  712. specifies how qstring and qcharacter map characters and enclose a string
  713. or character.  An expansion file for C, which also contains documentation,
  714. is CFILE.CEF.
  715.  
  716.   Option -C causes lr1p to accept a table file generated by a vs. 3.0
  717. Qparser lr1 program.
  718.  
  719. @opt
  720.  
  721.   Program 'opt' applies several optimizations to the table file
  722. generated by lr1.  You don't need to use it, but the time spent in
  723. running opt is usually less than a few seconds, and is worth it in
  724. terms of smaller tables.  Opt can be applied to an optimized table
  725. file and does nothing to the file.
  726.  
  727.   Running 'opt' by itself produces a brief description of its options:
  728.  
  729. Usage: opt [-h][-C] table_filename
  730.   -?  help: more program description
  731.   -C  optimize vs. 3.0 table file
  732.  
  733.   Option -C causes opt to accept a vs. 3.0 table file.  This is for
  734. compatibility only.  Version 3.0 supports a similar optimization built
  735. into its lr1 program, so running opt provides no space improvement.
  736. However, by running lr1 and opt with -C, you can then use the vs. 3.0
  737. (or earlier) lr1p and other skeleton files with the generated table file.
  738.  
  739.