various doc fixes

Author: jneen

README.md

@@ -260,7 +260,7 @@ for a year are automatically closed by GitHub's [Probot][].
 These submission will be rejected and we don't want you to waste your time.
 
 We want to make it as easy as we can for anyone to contribute a lexer to Rouge.
-To help get you started, we have [a shiny new guide][lexer-dev-doc] on lexer
+To help get you started, we have [a guide][lexer-dev-doc] on lexer
 development in the documentation. The best place is to start there.
 
 [lexer-dev-doc]: https://rouge-ruby.github.io/docs/file.LexerDevelopment.html "Rouge's lexer development guide"
@@ -289,12 +289,6 @@ you should have a web server running and ready to go. Visit
 Once you've selected a particular lexer, you can add `?debug=1` to your URL
 string to see a lot of helpful debugging info printed on stdout.
 
-## Versioning
-
-Rouge uses [Semantic Versioning 2.0.0][sv2].
-
-[sv2]: http://semver.org/
-
 ## Maintainers
 
 Rouge is largely the result of the hard work of unpaid volunteers. It was

docs/LexerDevelopment.md

@@ -243,6 +243,18 @@ Inside a complex rule's block, it's possible to call {Rouge::RegexLexer#push},
 {Rouge::RegexLexer#pop!}, {Rouge::RegexLexer#token} and
 {Rouge::RegexLexer#delegate}.
 
+One common use case of the block syntax is to use {Rouge::RegexLexer#groups}
+to easily assign token types to various capture groups of the regex. For
+example, in Java, we might detect attribute accessors with:
+
+```rb
+rule /([.])(\w+)/ do
+  groups Operator, Name::Attribute
+end
+```
+
+Make sure you don't forget to include *all* of the matched text in the output!
+
 You can see an example of these more complex rules in [the Ruby lexer][ruby-lexer].
 
 ### Additional Features
@@ -283,10 +295,10 @@ Filename Globs][conflict-globs] below.
 
 #### Special Words
 
-Every programming language reserves certain words for use as identifiers that
+Most programming languages reserve certain words for use as identifiers that
 have a special meaning in the language. To make regular expressions that search
-for these words easier, many lexers will put the applicable keywords in an
-array and make them available in a particular way (be it as a local variable,
+for these words easier, many lexers will put the applicable keywords in a
+set and make them available in a particular way (be it as a local variable,
 an instance variable or what have you).
 
 For performance and safety, we strongly recommend lexers use a class method:
@@ -295,13 +307,14 @@ For performance and safety, we strongly recommend lexers use a class method:
 module Rouge
   module Lexers
     class YetAnotherLanguage < RegexLexer
-    ...
+      ...
 
-    def self.keywords
-      @keywords ||= Set.new %w(key words used in this language)
-    end
+      def self.keywords
+        @keywords ||= Set.new %w(key words used in this language)
+      end
 
-    ...
+      ...
+    end
   end
 end
 ```
@@ -495,10 +508,8 @@ The spec and the demo can be run using the `rake` command. You can run this by
 typing `bundle exec rake` at the command line. If everything works, you should
 see a series of dots. If you have an error, this will appear here, too.
 
-You can also run `bundle exec rake VERBOSE=1` to see all warnings.
-
 To see your visual sample, launch Rouge's visual test app by running
-`bundle exec rackup`. You can choose your sample from the complete list by going
+`bundle exec puma`. You can choose your sample from the complete list by going
 to <http://localhost:9292>.
 
 ## How to Submit