README improvements (#2219)

* add an example of formatting to terminal with a style

* add a section about writing your own formatter

* document Rouge::Lexer.enable_debug!

* link to the plugin example repository

---------

Co-authored-by: jneen <jneen@jneen.net>

Author: jneen

README.md

@@ -67,9 +67,10 @@ use and whether to enable line numbers or not. More information is available in
 Rouge ships with a `rougify` command which allows you to easily highlight files
 in your terminal:
 
-```bash
-rougify foo.rb
-rougify style monokai.sublime > syntax.css
+```console
+$ rougify foo.rb
+$ rougify foo.rb -t monokai.sublime
+$ rougify style monokai.sublime > syntax.css
 ```
 
 ## Configuration
@@ -138,12 +139,35 @@ The built-in formatters are:
   highlighted text for use in the terminal. `theme` must be an instance of
   `Rouge::Theme`, or a `Hash` structure with `:theme` entry.
 
+- `Rouge::Formatters::TerminalTruecolor.new(theme)` is similar to the previous,
+  except it outputs ANSI truecolor codes, instead of approximating with a 256-color
+  scheme.
+
+- `Rouge::Formatters::Tex.new` is a formatter for TeX systems which wraps each
+  token with an `\RG{toktype}{text}` tag. You can then use
+  `rougify style mystyle --tex`
+  to generate definitions for these tags and the surrounding environment.
+
 #### Writing your own HTML formatter
 
-If the above formatters are not sufficient, and you wish to customize the layout
-of the HTML document, we suggest writing your own HTML formatter. This can be
-accomplished by subclassing `Rouge::Formatters::HTML` and overriding specific
-methods:
+For the majority of applications, there are custom requirements for presenting
+highlighted text, as HTML or otherwise. In these cases, rather than patching or
+post-processing the output of Rouge, it is usually better to **write your own
+formatter**.
+
+This may sound intimidating, but it is actually quite easy! All you have to do
+is subclass `Rouge::Formatter`, define a `tag`, and implement a method
+`#stream(tokens, &block)`, which receives an Enumerable of token/value pairs,
+and yields out chunks of strings which will be concatenated.
+
+The `Formatter` base class contains the helper method `#token_lines(stream, &block)`,
+which separates tokens into distinct lines, and `Rouge::Formatters::HTML`
+contains the helper `#span(token, value)` to escape and render
+standard `<span>` tags for HTML.
+
+Alternatively, if you want to override how individual spans are rendered,
+you can override `#safe_span(token, safe_value)`, which will be passed the
+token type and pre-escaped content for the token.
 
 ```ruby
 class MyFormatter < Rouge::Formatters::HTML
@@ -189,11 +213,11 @@ end
 
 ### Lexer Options
 
-- `debug: false` will print a trace of the lex on stdout.
+- `debug: true` will print a trace of the lex on stdout. For safety, this only works if `Rouge::Lexer.enable_debug!` has been called.
 
 - `parent: ''` allows you to specify which language the template is inside.
 
-### CSS Options
+### Theme Options
 
 - `scope: '.highlight'` sets the CSS selector to which styles are applied,
   e.g.:
@@ -270,6 +294,12 @@ make it clear in your submission that the lexer isn't finished yet. We'll do our
 best to answer any questions you have and sometimes the best way to do that is
 with actual code.
 
+If your language is internal or obscure, or it is taking far too long to merge
+into baseline Rouge, you can very easily write a plugin for language support.
+Check out our [plugin example repository][plugin-example] for a good starting point.
+
+[plugin-example]: https://github.com/rouge-ruby/rouge-plugin-example "Rouge Plugin Example"
+
 ### Testing Rouge
 
 Once you've cloned the repository from GitHub, you can test the core of Rouge