Document debugging

README.md

@@ -9,7 +9,6 @@ A language agnostic parser generator
 * [Building](#building)
 * [Getting started](#getting-started)
 * [More examples](#more-examples)
-* [Tested with](#tested-with)
 * [Authors](#authors)
 * [License](#license)
 
@@ -126,6 +125,14 @@ Comments are from a `#` to the end of the line.
 Of course, how you use the generated parser highly depends on which backend you used to generate it. For the default c++ backend however, the easiest way of getting to know the parser is probably having a look at the class definition in the generated header file, usually named *<Parsername>.h*.
 In general, there should be some way to run the parser, along with user defined actions, and get back the generated structure or abstract syntax tree.
 
+### Debugging the parser
+
+Nobody is perfect, so it is unlikely a grammar will always be completely conflict free from the very first time. It will happen on several occasions that Parsodus will notify you of a problem with your and you're unable to simply see where things go wrong. Or maybe the parser is behaving differently than you would expect. That's why there is a command line option to Parsodus that allows you to inspect the decisions made by the generator.
+
+For the *LR* based parsers, that means that the information about the action and goto table is written, along with information about the configuration sets leading to the actual parser states. Conflicting actions are indicated with a leading exclamation mark, to be able to easily find the exact source of your troubles.
+
+`Parsodus --debug` emits a *debug.log* file to the same output directory as the generated parser.
+
 ### Error recovery
 
 If you provide a rule with `<error>` somewhere inside the body, this can be used to recover from errors. The generated parser will discard states until it encounters somewhere it can use such a rule. Afterwards, it will start discarding tokens until it can proceed in parsing. If it's impossible to recover from the error (cannot find a recovery rule or cannot find a synchronizing token before EOF), there will generally be an error (depending on the backend). Usually, some sort of reporting mechanism should also be in place by the generated parser.

TODO

@@ -5,7 +5,6 @@
     #K 1 LR(1) + LALR(1)
     #T 1 LR(0)
     -> Table generator (independent of specific tables)???
-R> README: debug
 
 K> Fix BF
 -----------------------------------------------------------------------
@@ -16,7 +15,7 @@ K> Fix BF
 -                                DONE                                 -
 -----------------------------------------------------------------------
 -> BF tests
-R> README: bash completion + precedence + error recovery
+R> README: bash completion + precedence + error recovery + debug
 T> Lexesis input file
 -> publication / LICENSE
 -> presentation