Issue 6945 - Add script to make filter list diffs

README.md

 # python-abp
 
 This repository contains a library for working with Adblock Plus filter lists
 and the script that is used for building Adblock Plus filter lists from the
 form in which they are authored into the format suitable for consumption by the
 adblocking software.
 
 ## Installation
 
 Prerequisites:
@@ skipping 68 matching lines @@
 If you don't know all the source names that are needed to render some list,
 just run `flrender` and it will report what it's missing:
 
     $ flrender easylist.txt output/easylist.txt
     Unknown source: 'easylist' when including 'easylist:easylist/easylist_gener
     al_block.txt' from 'easylist.txt'
 
 You can clone the necessary repositories to a local directory and add `-i`
 options accordingly.
 
+## Rendering diffs
+
+A diff allows a client running adblocking software such as Adblock Plus to update

[Sebastian Noack, 2018/09/24 22:21:09]

"ad blocking" are two words.

[rhowell, 2018/09/25 01:53:44]

Done.

+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 filterlists called

[Sebastian Noack, 2018/09/24 22:21:09]

... between two versions of a filter list ...

[rhowell, 2018/09/25 01:53:44]

Done.

+`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]:

[Sebastian Noack, 2018/09/24 22:21:09]

This URL is not defined at the bottom.

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

Oops! I had it in a markdown editor, but forgot to copy that line over. Done.

+* Special comments of the form `! <name>:[ <value>]`
+* Added filters of the form `+ <filter-text>`
+* Removed filter of the form `- <filter-text>`
+
+When applying the diff, a client will update any values in the form of special
+comments, remove any filters that have been removed, and then add any filters

[Sebastian Noack, 2018/09/24 22:21:09]

That is not accurate. As of the current specification, the client will
remove/add filters in the order the lines occur in the diff.

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

Ah right. I missed that change to the spec. Fixed.

+that have been added.
+
 ## Library API
 
 Python-abp can also be used as a library for parsing filter lists. For example
 to read a filter list (we use Python 3 syntax here but the API is the same):
 
     from abp.filters import parse_filterlist
 
     with open('filterlist.txt') as filterlist:
         for line in parse_filterlist(filterlist):
             print(line)
@@ skipping 76 matching lines @@
         > abp <- import("abp.filters.rpy")
 
 Now you can use the functions with `abp$functionname`, e.g. 
 `abp.line2dict("@@||g.doubleclick.net/pagead/$subdocument,domain=hon30.org")`
 
 
  [1]: https://adblockplus.org/filters#special-comments
  [2]: http://pytest.org/
  [3]: https://tox.readthedocs.org/
  [4]: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt