minor cleanup of RewriteRules API
align rst.RewriteRules with changes in default RewriteRules
adjust scaladoc comments for the fact that many rewrite rules that were
specific to rst have been "promoted" to the generic rules
minor API change: 'Parse as X asRawDocument fromX' now returns an
instance of RawDocument

This change allows for a parser to pass out custom rewrite rules which
are specific to the format (e.g. reStructuredText substitution
references). It allows to manually compose them with other custom rules
for the actual rewrite operation.

Normal (and most common) use of the API which does not require a raw
document to be returned is not affected by this change.