Repository: softdevteam/grmtools (language: rust)

Issue:
Add `rust,noplaypen` to example grammar code in the documentation
Much of the example code in the documentation is not syntax highlighted, presumably because it is a mix of both Rust and `lrpar` syntax rather than pure Rust. However, highlighting it as Rust code seems to work quite well. Also, the failure mode of Highlight.js is quite benign: in the worst case, a few tokens are left the default text color (black/dark gray). 

The playpen feature (the ▶️ button) doesn't make much sense on those code blocks, as the code will not compile on https://play.rust-lang.org/. The `noplaypen` annotation turns this off.

Here's an example:

    ```rust,noplaypen
	Assign -> ASTAssign: "ID" "+" Expr
	{
        let id = $lexer.span_str($1.as_ref().unwrap().span()).to_string();
	    ASTAssign::new(id, $3)
	}

	%%

	struct ASTAssign {
	    id: String
	}

	impl ASTAssign {
	    fn new(name: String) -> Self {
	        ASTAssign { name }
	    }
	}
    ```

<img width="508" alt="Screen Shot 2020-02-23 at 3 25 10 PM" src="https://user-images.githubusercontent.com/1412598/75119418-be66c500-5650-11ea-8648-11d2d263343d.png">


I've already done this for the grmtools parsing idioms page but thought I'd ask if this PR would be welcome before I do the rest of the docs.


Discussion / hints:
Sorry, I had somehow not noticed that this issue had been raised -- mea culpa! I agree that highlighting things with Rust syntax highlighting is a good idea, and that `noplaypen` makes sense. I'd certainly welcome a PR that did that.

Fix patch:
diff --git a/doc/src/ast_example.md b/doc/src/ast_example.md
index b5346e5c9..c4df93d1e 100644
--- a/doc/src/ast_example.md
+++ b/doc/src/ast_example.md
@@ -10,7 +10,7 @@ The `calc.l` file remains unchanged from that in the [Quickstart
 guide](quickstart.md). However the `calc.y` file is change as follows:
 
 
-```rust
+```rust,noplaypen
 %start Expr
 %avoid_insert "INT"
 %%
@@ -64,7 +64,7 @@ successful parse, this will give us an arbitrarily deeply nested `Expr`.
 
 Our `main.rs` file then looks as follows:
 
-```rust
+```rust,noplaypen
 use std::io::{self, BufRead, Write};
 
 use lrlex::lrlex_mod;
diff --git a/doc/src/errorrecovery.md b/doc/src/errorrecovery.md
index ab958d562..77d0301c5 100644
--- a/doc/src/errorrecovery.md
+++ b/doc/src/errorrecovery.md
@@ -48,7 +48,7 @@ make use of error recovery.
 
 A simple calculator grammar looks as follows:
 
-```yacc
+```rust,noplaypen
 %start Expr
 %%
 Expr -> u64:
@@ -162,7 +162,7 @@ case of the calculator, default values are likely to lead to confusing results.
 We thus change the grammar so that inserted integers prevent evaluation from
 occurring:
 
-```yacc
+```rust,noplaypen
 %start Expr
 %%
 Expr -> Result<u64, ()>:
@@ -201,7 +201,7 @@ actions to percolate errors upwards, but this is a trivial change.
 
 We then need to make a small tweak to our `main.rs` changing:
 
-```rust,ignore
+```rust,noplaypen
 match res {
     Some(r) => println!("Result: {}", r),
     _ => eprintln!("Unable to evaluate expression.")
@@ -210,7 +210,7 @@ match res {
 
 to:
 
-```rust,ignore
+```rust,noplaypen
 match res {
     Some(Ok(r)) => println!("Result: {}", r),
     _ => eprintln!("Unable to evaluate expression.")
@@ -220,7 +220,7 @@ match res {
 Now the input which previously caused a panic simply tells the user that it
 could not evaluate the expression:
 
-```ignore
+```
 >>> 2+
 Parsing error at line 1 column 3. Repair sequences found:
    1: Insert INT
@@ -230,7 +230,7 @@ Unable to evaluate expression.
 Usefully, our inability (or unwillingness) to evaluate the expression does not
 prevent further syntax errors from being discovered and repaired:
 
-```ignore
+```
 >>> (2+)+3+4+
 Parsing error at line 1 column 4. Repair sequences found:
    1: Insert Int
@@ -255,7 +255,7 @@ few lines of code.
 By default, pretty-printing lexeme types prints out their identifier in the
 grammar. These rarely match what the user would expect:
 
-```ignore
+```
 >>> 2 3
 Parsing error at line 1 column 3. Repair sequences found:
    1: Delete 3
@@ -269,7 +269,7 @@ are far from obvious. `grmtools` allows users to provide human friendly versions
 of these for error recovery using the `%epp` declaration in grammars. For
 example, we can extend the `calc` grammar as follows:
 
-```ignore
+```
 %epp PLUS "+"
 %epp MUL "*"
 %epp LBRACK "("
@@ -279,7 +279,7 @@ example, we can extend the `calc` grammar as follows:
 
 leading to the following output:
 
-```ignore
+```
 >>> 2 3
 Parsing error at line 1 column 3. Repair sequences found:
    1: Delete 3
@@ -294,7 +294,7 @@ Result: 2
 Depending on your language, some repair sequences are better than others. For
 example, sometimes `Insert` repairs are less welcome than `Delete` repairs:
 
-```ignore
+```
 >>> 2 + + 3
 Parsing error at line 1 column 3. Repair sequences found:
    1: Insert INT
@@ -321,7 +321,7 @@ way (e.g. `INT`), but we don't need to worry about lexemes whose value we never
 expect (e.g. `(`, `+` etc.). In the case of the calculator grammar a good
 use of this directive is as follows:
 
-```ignore
+```
 %avoid_insert "INT"
 ```
 
@@ -403,7 +403,7 @@ The first surprising condition is that even with the small `calc` grammar, some
 user inputs lead to such a massive search space that no repair sequences can be
 found. The easiest way to trigger this in most grammars is bracket expressions:
 
-```ignore
+```
 >>> 1+(
 Parsing error at line 1 column 4. Repair sequences found:
    1: Insert Int, Insert )
@@ -438,7 +438,7 @@ weaker condition, which is that a repair sequence ends with 3 `Shift` repairs,
 showing that parsing has got back on track, at least for a little bit. This
 condition explains the following:
 
-```ignore
+```
 >>> 2 + + 3
 Parsing error at line 1 column 5. Repair sequences found:
    1: Delete +
@@ -512,7 +512,7 @@ By default, `lrpar` uses the `CPCT+` error recovery algorithm. You can use the
 the first parsing error, with the `recoverer` method in `CTParserBuilder` or
 `RTParserBuilder`. For example, we can change `calc`'s `build.rs` file to:
 
-```rust,ignore
+```rust,noplaypen
     let lex_rule_ids_map = CTParserBuilder::new()
         .yacckind(YaccKind::Grmtools)
         .recoverer(lrpar::RecoveryKind::None)
diff --git a/doc/src/lrlex.md b/doc/src/lrlex.md
index eefcb18f5..e68b34a8d 100644
--- a/doc/src/lrlex.md
+++ b/doc/src/lrlex.md
@@ -11,7 +11,7 @@ However, when it is suitable, it is a very convenient way of expressing lexing.
 `lrlex` also has a simple command-line interface, allowing you to check whether
 your lexing rules are working as expected:
 
-```ignore
+```
 $ cat C.java
 class C {
     int x = 0;
diff --git a/doc/src/othertools.md b/doc/src/othertools.md
index 43470c525..c1659a961 100644
--- a/doc/src/othertools.md
+++ b/doc/src/othertools.md
@@ -4,3 +4,6 @@ When parsing text in Rust, you should also evaluate the following tools to see
 if they are more suitable for your purposes:
 
  * [LALRPOP](http://lalrpop.github.io/lalrpop/)
+ * [nom](https://crates.io/crates/nom)
+ * [pest](https://pest.rs/)
+ * [rust-peg](https://github.com/kevinmehall/rust-peg)
diff --git a/doc/src/parsing_idioms.md b/doc/src/parsing_idioms.md
index 26098bca7..8ab655fc1 100644
--- a/doc/src/parsing_idioms.md
+++ b/doc/src/parsing_idioms.md
@@ -9,14 +9,14 @@ using the `Grmtools` format, the simple idioms below can often make life easier.
 When executing grammar actions one is often building up an Abstract Syntax Tree
 (AST) or equivalent. For example consider a simple language with assignments:
 
-```ignore
+```
 Assign: "ID" "=" Expr;
 ```
 
 Perhaps the "obvious" way to build this into an AST is to extract the string
 representing the identifier as follows:
 
-```
+```rust,noplaypen
 Assign -> ASTAssign: "ID" "=" Expr
     {
         let id = $lexer.span_str($1.as_ref().unwrap().span()).to_string();
@@ -46,7 +46,7 @@ parsing, but simply to return a
 [`Span`](https://docs.rs/lrpar/~0/lrpar/struct.Span.html). An outline of this
 is as follows:
 
-```
+```rust,noplaypen
 Assign -> ASTAssign: "ID" "=" Expr
     {
         ASTAssign { id: $1, expr: Box::new($3.span()) }
@@ -84,7 +84,7 @@ is generally a good idea to give rules a `Result` return type. This allows a
 simple interaction with error recovery. However, it can lead to endless
 instances of the following `map_err` idiom:
 
-```ignore
+```rust,noplaypen
 R -> Result<..., ()>:
     "ID" { $1.map_err(|_| ())? }
     ;
@@ -93,7 +93,7 @@ R -> Result<..., ()>:
 It can be helpful to define a custom `map_err` function which hides some of this
 mess for you:
 
-```ignore
+```rust,noplaypen
 R -> Result<Lexeme<StorageT>, ()>:
     "ID" { map_err($1)? }
     ;
@@ -113,7 +113,7 @@ fn map_err(r: Result<Lexeme<StorageT>, Lexeme<StorageT>>)
 Yacc grammars make specifying sequences of things something of a bore. A common
 idiom is thus:
 
-```
+```rust,noplaypen
 ListOfAs -> Result<Vec<A>, ()>:
       A { Ok(vec![$1?]) }
     | ListOfAs A
@@ -130,7 +130,7 @@ A -> Result<A, ()>: ... ;
 Since this idiom is often present multiple times in a grammar, it's generally
 worth adding a `flatten` function to hide some of this:
 
-```
+```rust,noplaypen
 ListOfAs -> Result<Vec<A>, ()>:
       A { Ok(vec![$1?]) }
     | ListOfAs A { flatten($1, $2) }
@@ -156,7 +156,7 @@ multiple places in the grammar.
 
 Happily, `flatten`, `map_err`, and `Lexeme` combine well:
 
-```
+```rust,noplaypen
 ListOfIds -> Result<Vec<Lexeme<StorageT>>, ()>:
       "ID" { Ok(vec![map_err($1)?]) }
     | ListOfIds "Id" { flatten($1, map_err($2)?) }
diff --git a/doc/src/quickstart.md b/doc/src/quickstart.md
index 7d81e9461..68ec2f91f 100644
--- a/doc/src/quickstart.md
+++ b/doc/src/quickstart.md
@@ -45,7 +45,7 @@ into Rust code. We thus need to create a
 file inside the root of our project which can process the lexer and grammar.
 Our `build.rs` file thus looks as follows:
 
-```rust
+```rust,noplaypen
 use cfgrammar::yacc::YaccKind;
 use lrlex::LexerBuilder;
 use lrpar::{CTParserBuilder};
@@ -101,7 +101,7 @@ is lexed, but no lexemes are created from it.
 ## The grammar
 
 Our initial version of calc.y looks as follows:
-```yacc
+```rust,noplaypen
 %start Expr
 %%
 Expr -> Result<u64, ()>:
@@ -185,7 +185,7 @@ The `build.rs` file will statically compile the lexer and grammar into Rust code
 that we can then call. The `src/main.rs` file below provides a simple
 Python-esque REPL to the user into which they can write calculator expressions:
 
-```rust
+```rust,noplaypen
 use std::io::{self, BufRead, Write};
 
 use lrlex::lrlex_mod;
diff --git a/doc/src/yacccompatibility.md b/doc/src/yacccompatibility.md
index 60d39dcda..63330a307 100644
--- a/doc/src/yacccompatibility.md
+++ b/doc/src/yacccompatibility.md
@@ -37,7 +37,7 @@ actions must adhere to. Note that whilst a rule's productions must all adhere
 to a single type, different rules can have different types.  Consider the
 following snippet:
 
-```
+```rust,noplaypen
 R1 -> Result<i32, ()>:
      'a' { Ok(5) }
    | 'b' { Err(()) }


Test patch: