Add usage guidance to README.md

[thundergolfer]

This project was quite helpful in supporting dependency shading in Bazel, but when first arriving at the repo the README seemed quite unapproachable and unloved.

I've attempted to add usage instruction right on the README.md that are hopefully accurate and useful but they're just what I produced from having used this Bazel rule and figuring out how it worked.

There's still a couple of things that I think are unclear.

• rule com.twitter.scalding.** foo.@1 this syntax is undocumented. Can you do scalding.* or @2, instead of what's shown in example?
• jar_jar.rules is plural, but it accepts a string. Can it also accept a list? It would be nice if this info was front and centre.

If I look into the source I could submit an update to this PR that adds more detail.

[johnynek]

This is great. Thank you for the help.

Maybe we should also link to the jar jar manual which might help people find more complex examples? Does that manual exist? :)

[thundergolfer]

Thank you for the help.

Thank you for being a huge reason Bazel + Scala is a viable combo.

Does that manual exist? :)

I couldn't find it easily.

[johnynek]

Kind of you to say!

https://code.google.com/archive/p/jarjar/wikis/CommandLineDocs.wiki

looks like it says:

Rules file format

The rules file is a text file, one rule per line. Leading and trailing whitespace is ignored. There are three types of rules:

rule <pattern> <result>
zap <pattern> 
keep <pattern>

The standard rule (rule) is used to rename classes. All references to the renamed classes will also be updated. If a class name is matched by more than one rule, only the first one will apply.

<pattern> is a class name with optional wildcards. ** will match against any valid class name substring. To match a single package component (by excluding . from the match), a single * may be used instead.

<result> is a class name which can optionally reference the substrings matched by the wildcards. A numbered reference is available for every * or ** in the , starting from left to right: @1, @2, etc. A special @0 reference contains the entire matched class name.

The zap rule causes any matched class to be removed from the resulting jar file. All zap rules are processed before renaming rules.

The keep rule marks all matched classes as "roots". If any keep rules are defined all classes which are not reachable from the roots via dependency analysis are discarded when writing the output jar. This is the last step in the process, after renaming and zapping.

=========

maybe we should just copy that to the README. What do you think?

[thundergolfer]

Yeah in the context of this project linking someone to CommandLineDocs.wiki is a little misleading.

I'll put a PR up today.