From 90d93ec874729f60927ab1c3b65c4b36acf7648f Mon Sep 17 00:00:00 2001 From: Alan deLevie Date: Sun, 7 Sep 2014 11:30:19 -0400 Subject: [PATCH 01/10] Create diffs.md --- md/diffs.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 md/diffs.md diff --git a/md/diffs.md b/md/diffs.md new file mode 100644 index 0000000..513b773 --- /dev/null +++ b/md/diffs.md @@ -0,0 +1,3 @@ +# Chapter ???: Diffs + +Diffs express the difference between two files. Originally designed to track the changes made between different versions of software files, they are increasingly powerful in non-software applications. From 1a8779a8cd8f84006d3e6fdb5cdab286a4ffac39 Mon Sep 17 00:00:00 2001 From: Alan deLevie Date: Sun, 7 Sep 2014 12:07:56 -0400 Subject: [PATCH 02/10] Added terminal (osx) examples to diff chapter --- md/diffs.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/md/diffs.md b/md/diffs.md index 513b773..fc850d5 100644 --- a/md/diffs.md +++ b/md/diffs.md @@ -1,3 +1,58 @@ # Chapter ???: Diffs -Diffs express the difference between two files. Originally designed to track the changes made between different versions of software files, they are increasingly powerful in non-software applications. +Diffs express the difference between two files. Originally designed to track the changes made between different versions of software files, they are increasingly powerful in non-software applications. Diffs make changes to a document obvious and easy for humans to look at. + +You might be familiar with the "track changes" of your favorite word processor where deletions have a line strike-through and insertions are underlined: + +![screenshot of track changes in a word processor](http://i.imgur.com/wwRfTjb.png) + +## Exercise 1 (OSX) + +Create a file called `README.md`. Add some text to the file, such as: + +``` +This exercise is not interesting yet. +``` + +Now copy that file and paste the new file in the same directory. Name it something like `NEW-README.md`. Bonus: You can accomplish all this with a single terminal command, `cp`: + +``` +cp README.md NEW-README.md +``` + +In `NEW-README.md`, edit the text and then save the file: + +``` +This exercise is becoming more interesting. +``` + +To get a diff of these two files, use the `diff` command in your terminal: + +``` +diff README.md NEW-README.md +``` + +You should see the following output: + +``` +1c1 +< This exercise is not interesting yet. +\ No newline at end of file +--- +> This exercise is becoming more interesting. +\ No newline at end of file +``` + +This output is a diff. It shows the old version of the line of text right above the new version. + +If you're more interested in knowing whether or not files differ (and less interested in what those actual differences are), you can add the `--brief` option to the `diff` command: + +``` +diff README.md NEW-README.md --brief +``` + +Output: + +``` +Files README.md and NEW-README.md differ +``` From 40be98e90a0a41ee9abe070f51c8150517455c4b Mon Sep 17 00:00:00 2001 From: Alan deLevie Date: Sun, 7 Sep 2014 12:18:57 -0400 Subject: [PATCH 03/10] added CongressEdits example to diff chapter --- md/diffs.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/md/diffs.md b/md/diffs.md index fc850d5..1a52717 100644 --- a/md/diffs.md +++ b/md/diffs.md @@ -1,12 +1,14 @@ # Chapter ???: Diffs -Diffs express the difference between two files. Originally designed to track the changes made between different versions of software files, they are increasingly powerful in non-software applications. Diffs make changes to a document obvious and easy for humans to look at. +Diffs express the difference between two files. Originally designed to track the changes made between different versions of software files, they are increasingly powerful in non-software applications. You might be familiar with the "track changes" of your favorite word processor where deletions have a line strike-through and insertions are underlined: ![screenshot of track changes in a word processor](http://i.imgur.com/wwRfTjb.png) -## Exercise 1 (OSX) +Like "track changes", diffs make changes to a document obvious and easy for humans to look at. However, unlike "track changes", diffs make it easy for software programs to automatically detect and analyze changes to documents. For example, the Twitter bot, [CongressEdits](https://twitter.com/congressedits), automatically published edits ([example](http://en.wikipedia.org/w/index.php?diff=623325721&oldid=623325294)) made to Wikipedia by computers in Congressional offices. The [code](https://github.com/edsu/anon) behind CongressEdits, because it is open source, has been forked (copied) and modified many times over for [use in other contexts](https://github.com/edsu/anon#community) all over the world. + +## Exercise (OSX) Create a file called `README.md`. Add some text to the file, such as: @@ -56,3 +58,5 @@ Output: ``` Files README.md and NEW-README.md differ ``` + +
From 25be81b079f4c3e8fb7a8a972657b0907cc84e0d Mon Sep 17 00:00:00 2001 From: Alan deLevie Date: Sun, 7 Sep 2014 12:34:58 -0400 Subject: [PATCH 04/10] diff: cleaned up exercise, added scotus servo example --- md/diffs.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/md/diffs.md b/md/diffs.md index 1a52717..08de2cd 100644 --- a/md/diffs.md +++ b/md/diffs.md @@ -6,10 +6,18 @@ You might be familiar with the "track changes" of your favorite word processor w ![screenshot of track changes in a word processor](http://i.imgur.com/wwRfTjb.png) -Like "track changes", diffs make changes to a document obvious and easy for humans to look at. However, unlike "track changes", diffs make it easy for software programs to automatically detect and analyze changes to documents. For example, the Twitter bot, [CongressEdits](https://twitter.com/congressedits), automatically published edits ([example](http://en.wikipedia.org/w/index.php?diff=623325721&oldid=623325294)) made to Wikipedia by computers in Congressional offices. The [code](https://github.com/edsu/anon) behind CongressEdits, because it is open source, has been forked (copied) and modified many times over for [use in other contexts](https://github.com/edsu/anon#community) all over the world. +Like "track changes", diffs make changes to a document obvious and easy for humans to look at. However, *unlike* "track changes", diffs make it easy for software programs to automatically detect and analyze changes to documents. + +For example, the Twitter bot, [CongressEdits](https://twitter.com/congressedits), automatically publishes anonymous edits ([example](http://en.wikipedia.org/w/index.php?diff=623325721&oldid=623325294)) made to Wikipedia by computers in Congressional offices. The [code](https://github.com/edsu/anon) behind CongressEdits, because it is open source, has been forked (copied) and modified many times over for [use in other contexts](https://github.com/edsu/anon#community) all over the world. + +The quick rise in popularity of CongressEdits and its progeny speaks to the tremendous power (and need) for tracking impossibly large collections of text documents. Diffs serve as powerful oversight tools and can lead to discoveries of edits being made right under our collective nose. + +In the legal world, perhaps one of the most important uses of diffing was [ScotusServo](https://twitter.com/SCOTUS_servo) ((code)[https://github.com/vzvenyach/scotus-servo]). ScotusServo, which was coded by the creator/author/editor of this very book, lead to the discovery that the Supreme Court of the United States frequently makes unannounced edits to its published opinions ((example)[https://twitter.com/SCOTUS_servo/status/504758688494526466]). ScotusServo has been called "the most interesting SCOTUS development of the year" ((source)[https://twitter.com/kedarbhatia/status/481454638466891778]) and is used by the Supreme Court correspondent for the New York Times ((source)[https://twitter.com/derekwillis/status/481602952671817728]). ## Exercise (OSX) +At the end of this short exercise, you'll write code that automatically detects whether two files are different. The concepts here will serve as an important building block for understanding other chapters of this book, such as [git]() and [GitHub](). Additionally, this exercise will help you build comfort and familiarity with the command line, an indispensible tool for all coders, lawyers or not. + Create a file called `README.md`. Add some text to the file, such as: ``` @@ -58,5 +66,3 @@ Output: ``` Files README.md and NEW-README.md differ ``` - -
From 8fef9d88d03da0c7a5d6bf22dd8340a2799731f8 Mon Sep 17 00:00:00 2001 From: Alan deLevie Date: Sun, 7 Sep 2014 12:38:30 -0400 Subject: [PATCH 05/10] fixed md links in diff chapter --- md/diffs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/md/diffs.md b/md/diffs.md index 08de2cd..d13af34 100644 --- a/md/diffs.md +++ b/md/diffs.md @@ -12,7 +12,7 @@ For example, the Twitter bot, [CongressEdits](https://twitter.com/congressedits) The quick rise in popularity of CongressEdits and its progeny speaks to the tremendous power (and need) for tracking impossibly large collections of text documents. Diffs serve as powerful oversight tools and can lead to discoveries of edits being made right under our collective nose. -In the legal world, perhaps one of the most important uses of diffing was [ScotusServo](https://twitter.com/SCOTUS_servo) ((code)[https://github.com/vzvenyach/scotus-servo]). ScotusServo, which was coded by the creator/author/editor of this very book, lead to the discovery that the Supreme Court of the United States frequently makes unannounced edits to its published opinions ((example)[https://twitter.com/SCOTUS_servo/status/504758688494526466]). ScotusServo has been called "the most interesting SCOTUS development of the year" ((source)[https://twitter.com/kedarbhatia/status/481454638466891778]) and is used by the Supreme Court correspondent for the New York Times ((source)[https://twitter.com/derekwillis/status/481602952671817728]). +In the legal world, perhaps one of the most important uses of diffing was [ScotusServo](https://twitter.com/SCOTUS_servo) ([code](https://github.com/vzvenyach/scotus-servo)). ScotusServo, which was coded by the creator/author/editor of this very book, lead to the discovery that the Supreme Court of the United States frequently makes unannounced edits to its published opinions ([example](https://twitter.com/SCOTUS_servo/status/504758688494526466)). ScotusServo has been called "the most interesting SCOTUS development of the year" ((source)[https://twitter.com/kedarbhatia/status/481454638466891778]) and is used by the Supreme Court correspondent for the New York Times ([source](https://twitter.com/derekwillis/status/481602952671817728)). ## Exercise (OSX) From 08d0ba190753c17b50e12e797bb3246077b5e33c Mon Sep 17 00:00:00 2001 From: Alan deLevie Date: Sun, 7 Sep 2014 12:39:05 -0400 Subject: [PATCH 06/10] fixed last link in diff chapter --- md/diffs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/md/diffs.md b/md/diffs.md index d13af34..880a3ec 100644 --- a/md/diffs.md +++ b/md/diffs.md @@ -12,7 +12,7 @@ For example, the Twitter bot, [CongressEdits](https://twitter.com/congressedits) The quick rise in popularity of CongressEdits and its progeny speaks to the tremendous power (and need) for tracking impossibly large collections of text documents. Diffs serve as powerful oversight tools and can lead to discoveries of edits being made right under our collective nose. -In the legal world, perhaps one of the most important uses of diffing was [ScotusServo](https://twitter.com/SCOTUS_servo) ([code](https://github.com/vzvenyach/scotus-servo)). ScotusServo, which was coded by the creator/author/editor of this very book, lead to the discovery that the Supreme Court of the United States frequently makes unannounced edits to its published opinions ([example](https://twitter.com/SCOTUS_servo/status/504758688494526466)). ScotusServo has been called "the most interesting SCOTUS development of the year" ((source)[https://twitter.com/kedarbhatia/status/481454638466891778]) and is used by the Supreme Court correspondent for the New York Times ([source](https://twitter.com/derekwillis/status/481602952671817728)). +In the legal world, perhaps one of the most important uses of diffing was [ScotusServo](https://twitter.com/SCOTUS_servo) ([code](https://github.com/vzvenyach/scotus-servo)). ScotusServo, which was coded by the creator/author/editor of this very book, lead to the discovery that the Supreme Court of the United States frequently makes unannounced edits to its published opinions ([example](https://twitter.com/SCOTUS_servo/status/504758688494526466)). ScotusServo has been called "the most interesting SCOTUS development of the year" ([source](https://twitter.com/kedarbhatia/status/481454638466891778)) and is used by the Supreme Court correspondent for the New York Times ([source](https://twitter.com/derekwillis/status/481602952671817728)). ## Exercise (OSX) From 29654aa268615051f1af8adeac30c091e5776c45 Mon Sep 17 00:00:00 2001 From: Alan deLevie Date: Sun, 7 Sep 2014 13:13:06 -0400 Subject: [PATCH 07/10] Added D.R.E.A.M. section to Diff --- md/diffs.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/md/diffs.md b/md/diffs.md index 880a3ec..f8e2b99 100644 --- a/md/diffs.md +++ b/md/diffs.md @@ -66,3 +66,19 @@ Output: ``` Files README.md and NEW-README.md differ ``` + +## Diffs Rule Everything Around Me: Diffing the Law + +Now that you've gotten your feet wet with diffs, this section will demonstrate a practical application for lawyers in their everyday law practice: untangling complex regulations and understanding when and how they changed. + +Let's say you need to understand what a given regulation currently is, and how it changed each time it was amended. Assuming you can access the plain text of various versions of a the Code of Federal Regulations (C.F.R.) (which you'll be able to do without trouble when you read our chapter on [Parsing XML]()), you can run `diff previous-version.txt current-version.txt`. As you might observe, running this command for each and every pair of different files can get tedious and reptitive. Thankfully, tools like git and GitHub make it easy to automatically generate histories of files (in this case, a file could represent a section of the C.F.R.). + +For example, the [adelevie/cfr-diffs](https://github.com/adelevie/cfr-diffs) GitHub repository shows the diffs of Title 47 of the C.F.R. going back several years. For example, this [page](https://github.com/adelevie/cfr-diffs/commits/master/cfr/title-47/20.19.md) displays the history of 47 C.F.R. ยง 20.19 (known as the Hearing Aid Compatibility Rules). Clicking on any of the revisions (known as "commits" in git-speak), shows the revisions for a given year. For example, you can easily see the changes to this regulation introduced in [2010](https://github.com/adelevie/cfr-diffs/commit/964e2272b95bbf7c2453839e3559be71ba0ae949). GitHub makes it even easier to view diffs of Markdown documents by displaying a "rich diff" ([example](https://github.com/adelevie/cfr-diffs/commit/964e2272b95bbf7c2453839e3559be71ba0ae949?short_path=5e27c6e#diff-5e27c6e509774e6358f3e291694f9a3f)). + +In that example, changes that might have been difficult and time-consuming to detect with the naked eye were made obvious and prominent in the diff: + +![screenshot of GitHub's rich diff](http://i.imgur.com/WgGKp0p.png) + +To a lawyer working with the Hearing Aid Compatibility Rules, it's potentially very important that the 2010 revisions introduced a change that no longer applied the rules to a device that incorporates WiFi, but instead operates within a precise frequency range defined in a well-understood standard. + + From 10d45f2e43666f476a14a34f6d36277513e199f7 Mon Sep 17 00:00:00 2001 From: Alan deLevie Date: Sun, 7 Sep 2014 13:42:57 -0400 Subject: [PATCH 08/10] added fisa court section to diff chapter --- md/diffs.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/md/diffs.md b/md/diffs.md index f8e2b99..5f2adb8 100644 --- a/md/diffs.md +++ b/md/diffs.md @@ -69,7 +69,32 @@ Files README.md and NEW-README.md differ ## Diffs Rule Everything Around Me: Diffing the Law -Now that you've gotten your feet wet with diffs, this section will demonstrate a practical application for lawyers in their everyday law practice: untangling complex regulations and understanding when and how they changed. +Now that you've gotten your feet wet with diffs, this section will demonstrate practical applications for lawyers in their everyday law practice: + +1. accessing court documents; and +2. untangling complex regulations and understanding when and how they changed. + +### Court Documents + +Following the Snowden revelations, interest in the FISA court was increasing. Though much of the court operates in secrecy, some documents were being published on the court's [website](http://www.fisc.uscourts.gov/). Unfortunately, for a long time, the site lacked a meaningful notification mechanism. This meant lawyers (and anyone else) interested in the FISC needed to manually check the site for new documents to be posted. Not only is this time-consuming, but it is error-prone. + +Around this time, [Eric Mill wrote software](https://twitter.com/FISACourt) that periodically checks the contents of the FISA court's website and, using diffs (thanks to a [code contribution from Ben Balter](https://github.com/konklone/fisacourt/pull/1)), detected the presence of new links to court filings. + +Mill [wrote](https://konklone.com/post/following-the-fisa-court-new-website-new-data): + +> The FISC's docket is a tiny piece of the action surrounding surveillance, but since the nation's only Court dedicated to surveillance first opened its ad hoc internet welcome mat in June of 2013, allowing the public a window into its work for the first time in 35 years, we've gotten to see: + +> ... + +> The Court declassifying and publishing a full justification for allowing bulk collection of phone metadata under the Fourth Amendment. + +> ... + +> The Court responding to inquiries from prominent senators by publicly describing its operations, and following up with numbers on how often they make the government revise their requests before granting them (~25% of the time). + +Though accessing these documents was certainly *possible* without diffs, diffs made such access much easier, more reliable, and more comprehensive. + +### Complex Regulations Let's say you need to understand what a given regulation currently is, and how it changed each time it was amended. Assuming you can access the plain text of various versions of a the Code of Federal Regulations (C.F.R.) (which you'll be able to do without trouble when you read our chapter on [Parsing XML]()), you can run `diff previous-version.txt current-version.txt`. As you might observe, running this command for each and every pair of different files can get tedious and reptitive. Thankfully, tools like git and GitHub make it easy to automatically generate histories of files (in this case, a file could represent a section of the C.F.R.). From 19b3135135ed77fcb4f852374a8489fcd7953ddf Mon Sep 17 00:00:00 2001 From: Rebecca Williams Date: Sun, 7 Sep 2014 14:36:44 -0400 Subject: [PATCH 09/10] Added examples and tools they could probably use descriptions too, but that's another PR --- md/diffs.md | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/md/diffs.md b/md/diffs.md index 5f2adb8..16a4949 100644 --- a/md/diffs.md +++ b/md/diffs.md @@ -106,4 +106,43 @@ In that example, changes that might have been difficult and time-consuming to de To a lawyer working with the Hearing Aid Compatibility Rules, it's potentially very important that the 2010 revisions introduced a change that no longer applied the rules to a device that incorporates WiFi, but instead operates within a precise frequency range defined in a well-understood standard. - +##More Diff Examples and Tools + +###Examples + +Including the examples mentioned above, here are examples of some legislative diffs to date to awe and inspire you. + +* [@CongressEdits](https://twitter.com/congressedits), the [code](https://github.com/edsu/anon) has been [re-used around the world](https://github.com/edsu/anon#community) +* [CFPB's e-regulations](http://www.consumerfinance.gov/eregulations/about) and [code](https://eregs.github.io/eregulations/) +* [@FISACourt](https://twitter.com/FISACourt) and [code](https://github.com/konklone/fisacourt) +* [GovTrack](https://www.govtrack.us/congress/bills/112/s1488/text) +* [LobbyPlag](http://lobbyplag.eu/) +* [ly.g0v.tw](http://ly.g0v.tw/bills/1150L15359#original-972) +* [NY Capitol Camp's Bill Diff](https://github.com/nycapitolcamp/legislative-apps#Bill) +* [The Making of a Law](http://visualisiert.net/parteiengesetz/index.en.html) +* [@ScotusServo](https://twitter.com/SCOTUS_servo), and [code](https://github.com/vzvenyach/scotus-servo) + +###Tools + +There are a variety of free software tools out there that can assist you with quick out-of-box legislative diff comparisons, provide prototype examples, and technically inspire your diff creations. + +* [Code Compare](http://www.devart.com/codecompare/) +* [DiffMerge](http://sourcegear.com/diffmerge/) +* [DiffPDF](http://www.qtrac.eu/diffpdf.html) +* [Diffuse](http://diffuse.sourceforge.net/) +* [ExamDiff](http://www.prestosoft.com/edp_examdiff.asp) +* [GitHub Diff function, example with a regulation:](https://github.com/adelevie/cfr-diffs/commit/bf2b3568273c12a94f4b40afe45ecf4093904636 ) +* [Juxta Commons](http://juxtacommons.org/shares/S7xr1e) +* [KDiff3](http://kdiff3.sourceforge.net/) +* [Meld](http://meldmerge.org/) +* [NetBeans](https://netbeans.org/) +* [Notepad++](http://notepad-plus-plus.org/) +* [Online Code Difference Comparison Tool](http://www.tareeinternet.com/scripts/comparison-tool/) +* [Pretty Diff](http://prettydiff.com/) +* [PsPad](http://www.pspad.com/) +* [Quick Diff Online Tool](http://www.quickdiff.com/) +* [Superfastmatch](http://superfastmatch.org/) +* [WinMerge](http://winmerge.org/) +* [Xcode](https://developer.apple.com/xcode/) + +* See also["25+ Useful Document and File Comparison Tools," noupe (26-11-2011)](http://www.noupe.com/tools/25-useful-document-and-file-comparison-tools.html) From 3c1a5a8e503f90bfb25d8f31438736ac7ba94623 Mon Sep 17 00:00:00 2001 From: Rebecca Williams Date: Sun, 7 Sep 2014 14:52:24 -0400 Subject: [PATCH 10/10] removed/added spaces --- md/diffs.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/md/diffs.md b/md/diffs.md index 16a4949..19b2127 100644 --- a/md/diffs.md +++ b/md/diffs.md @@ -143,6 +143,5 @@ There are a variety of free software tools out there that can assist you with qu * [Quick Diff Online Tool](http://www.quickdiff.com/) * [Superfastmatch](http://superfastmatch.org/) * [WinMerge](http://winmerge.org/) -* [Xcode](https://developer.apple.com/xcode/) - -* See also["25+ Useful Document and File Comparison Tools," noupe (26-11-2011)](http://www.noupe.com/tools/25-useful-document-and-file-comparison-tools.html) +* [Xcode](https://developer.apple.com/xcode/) +* See also ["25+ Useful Document and File Comparison Tools," noupe (26-11-2011)](http://www.noupe.com/tools/25-useful-document-and-file-comparison-tools.html)