Issue 6945 - Add script to make filter list diffs

README.md

Index: README.md
===================================================================
--- a/README.md
+++ b/README.md
@@ -86,6 +86,33 @@
 You can clone the necessary repositories to a local directory and add `-i`
 options accordingly.
 
+## Rendering diffs
+
+A diff allows a client running ad blocking software such as Adblock Plus to update
+the filter lists incrementally, instead of downloading a new copy of a full list
+during each update. This is meant to lessen the amount of resources used when updating
+filter lists (e.g. network data, memory usage, battery consumption, etc.), allowing 
+clients to update their lists more frequently using less resources.
+
+Python-abp contains a script that produces the diff between two versions of a
+filter list called `fldiff`:
+
+    $ fldiff base.txt latest.txt output.txt
+
+This will produce a diff that shows how a client may get from `base.txt` to
+`latest.txt`, and write the output to `output.txt`. The output argument is
+optional. If ommitted, the data will be written to `stdout`.
+
+The script produces three types of lines, as specified in the [technical specification][5]:
+* Special comments of the form `! <name>:[ <value>]`
+* Added filters of the form `+ <filter-text>`
+* Removed filter of the form `- <filter-text>`
+
+The diff is generated such that the removed filters are listed before the added

[Sebastian Noack, 2018/09/25 17:00:39]

Maybe this is a bit too much detail, if we refer to the spec anyway. But I don't
care too much, so I leave it up to you (and Vasily), however, keep in mind if
the behavior should ever change this will be an additional resource that you
have to remember to update.

[rhowell, 2018/09/25 23:01:45]

Yeah, I see your point. Maybe it would be better to mention this where it's done
in the source code, in renderer.py. I moved it there.

+filters. This covers the case where a filter is both removed and added. The 
+client should process the diffs in order, so if this conflict happens, the rule
+will be added.
+
 ## Library API
 
 Python-abp can also be used as a library for parsing filter lists. For example
@@ -182,3 +209,4 @@
  [2]: http://pytest.org/
  [3]: https://tox.readthedocs.org/
  [4]: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+ [5]: https://docs.google.com/document/d/1SoEqaOBZRCfkh1s5Kds5A5RwUC_nqbYYlGH72sbsSgQ/