First pass documentation review

Author: acdha

CHANGELOG.md

@@ -1,9 +1,13 @@
 #### Changes in 5.0.0
-1. Complete rewrite of the library to remove bad practices and to allow for a much better design using java best practices.
-2. Removal of creating a zipped bag. There are many good zip (or other serialization) libraries in Java, please use one of them instead. Please see the examples directory for how you might use third-party libraries to do zipping (or other serialization).
-3. Removal of fetching. It is impossible to account for all the protocols possible with fetching. Please see the examples directory for how you might use third-party libraries to do fetching.
+1. Complete rewrite using Java 8 and modern Java best practices
+2. Bagging directly into a ZIP file is no longer a core feature. The examples
+   directory shows how to support the serialization format and options of
+   your choice.
+3. Integrated support for `fetch.txt` has been removed as a core feature. The
+   examples directory includes an implementation using the standard library
+   which can serve as a reference for the more advanced implementations which
+   most users will require.
 3. Allow for ignoring hidden files except if specified in manifest.
-4. Bagit now uses Java version 8 syntax, thus the minimum requirement for building and running is Java 8
 
 #### Changes in 4.10.0
 1. Fixes defect in SimpleResult.add*Message() methods.
@@ -28,15 +32,15 @@
 
 #### Changes in 4.7
 1. Handle NPE when encountering improperly formatted bag-info.txt.
-2. Added progress reports to bag fetch. 
+2. Added progress reports to bag fetch.
 
 #### Changes in 4.6
-1. Added tag file fetch-progress.txt to support progressive fetch and verification.  The file 
+1. Added tag file fetch-progress.txt to support progressive fetch and verification.  The file
         will be removed once the bag is successfully fetched.  In BagFetcher, added verification
-        of a fetched file against the checksum in the manifest file.  Added switch verify to fill 
-        holey bag and fetch remote bag command-line operations.  This option enables bag verification 
+        of a fetched file against the checksum in the manifest file.  Added switch verify to fill
+        holey bag and fetch remote bag command-line operations.  This option enables bag verification
         before the fetch is resumed.
-        
+
 #### Changes in 4.5.1
 1. Added missing braces to conditional blocks in ValidHoleyBagVerifier.  This caused false
         error message when verifying a holey bag.
@@ -46,7 +50,7 @@
 
 #### Changes in 4.4
 1. Attempt to correct for unicode normalization form in filepaths. Note: Java has
-    problems dealing with differences in unicode normalization form 
+    problems dealing with differences in unicode normalization form
     (http://www.unicode.org/reports/tr15/tr15-23.html) in filepaths.
     In particular, it is sometimes the case that a java.io.File is that produced
     by java.io.File.listFiles() will fail java.io.File.exists(). This attempts to
@@ -57,7 +61,7 @@
         is now to copy (instead of writing the stream exposed by BagFile).  Added support
         for specifying move in CommandLineBagDriver (--move).
 4. Added setUsername()/setPassword() interfaces to all bag fetchers to support
-        concurrent clients; each client's credentials will be local to each instance of bag fetcher.    
+        concurrent clients; each client's credentials will be local to each instance of bag fetcher.
 
 #### Changes in 4.3.1
 1. Changes to pom for maven 3.
@@ -87,7 +91,7 @@
 2. Removes Commons VFS.
 3. Deprecates support for reading/writing tar, tar bz2, and tar gz.
 4. Deprecates support for transferring SWORD and BOB.
-5. Added close() method to Bag for closing IO resources. 
+5. Added close() method to Bag for closing IO resources.
 6. Clarified logging messages for CompleteVerifier and ValidVerifier.
 7. Changed so that bagging-in-place throws an exception if a prebag contains a data directory and tag directories
         for pre-0.97 bags.
@@ -164,7 +168,7 @@
 3. Changed socket timeout from infinity to 20 seconds for http fetches.
 4. Made adding data to payload progress monitorable and cancellable (AddFilesToPayloadOperation)
 5. Made whitespace used in creating manifests configurable.
-6. Smarter handling of relative paths in manifests. 
+6. Smarter handling of relative paths in manifests.
 
 #### Changes in 3.2
 1. Fixed handling of bag-info.txt with colons in the value.
@@ -218,4 +222,4 @@
 3. Made bag-info.txt labels case-insensitive.
 4. Added additional bag-info.txt methods for Bagging-Date, Bag-Count, Bag-Size, and Payload-Oxum.
 5. Changed to only include the tar-related classes from Ant, rather than the entire dependency.
-6. Added version-aware handling of filepath delimiters. 
+6. Added version-aware handling of filepath delimiters.

README.md

@@ -10,7 +10,7 @@
 [//]: # (see https://github.com/moznion/javadocio-badges for automatic javadoc)
 
 ## Description
-The BAGIT LIBRARY is a software library intended to support the creation, 
+The BAGIT LIBRARY is a software library intended to support the creation,
 manipulation, and validation of bags. Its current version is 0.97. It is version aware with the earliest
 supported version being 0.93.
 
@@ -25,49 +25,73 @@ supported version being 0.93.
 4. If you would like to contribute, please submit a [pull request](https://help.github.com/articles/creating-a-pull-request/)
 
 ## Major differences between version 5 and 4.*
-##### Commandline
-The 4.x versions of the bagit command line are still available for [download](https://github.com/LibraryOfCongress/bagit-java/releases/download/v4.12.1/bagit-4.12.1.zip). However, starting with the 5.x versions we will not longer be creating a java command line application. If you would like to use a currently supported command line application please see our [bagit-python implementation](https://github.com/LibraryOfCongress/bagit-python)
+##### Command Line Interface
+
+The 5.x versions do not include a command-line interface.
+Users who need a command-line utility can continue to use the latest 4.x release
+([download 4.12.1](https://github.com/LibraryOfCongress/bagit-java/releases/download/v4.12.1/bagit-4.12.1.zip)
+or switch to an alternative implementation such as
+[bagit-python](https://github.com/LibraryOfCongress/bagit-python) or
+[BagIt for Ruby](https://github.com/tipr/bagit).
 
 ##### Serialization
-Starting with the 5.x versions we no longer support directly serializing a bag. Check out the [zip](https://github.com/LibraryOfCongress/bagit-java/blob/master/src/test/java/gov/loc/repository/bagit/examples/serialization/CreateZipBagExample.java) or [tar](https://github.com/LibraryOfCongress/bagit-java/blob/master/src/test/java/gov/loc/repository/bagit/examples/serialization/CreateTarBagExample.java) examples for implementing it yourself.
+Starting with the 5.x versions bagit-java no longer supports directly
+serializing a bag to an archive file. The examples show how to implement a
+custom serializer for the
+[zip](https://github.com/LibraryOfCongress/bagit-java/blob/master/src/test/java/gov/loc/repository/bagit/examples/serialization/CreateZipBagExample.java)
+and
+[tar](https://github.com/LibraryOfCongress/bagit-java/blob/master/src/test/java/gov/loc/repository/bagit/examples/serialization/CreateTarBagExample.java)
+formats.
 
 ##### Fetching
-Starting with the 5.x versions we no longer support fetching. Check out the [standard java library](https://github.com/LibraryOfCongress/bagit-java/blob/master/src/test/java/gov/loc/repository/bagit/examples/fetching/FetchHttpFileExample.java) example as one way you could implement it yourself. 
+The 5.x versions do not include a core `fetch.txt` implementation. If you need
+this functionality, the
+[`FetchHttpFileExample` example](https://github.com/LibraryOfCongress/bagit-java/blob/master/src/test/java/gov/loc/repository/bagit/examples/fetching/FetchHttpFileExample.java)
+demonstrates how you can implement this feature with your additional application
+and workflow requirements.
 
 ##### New Interfaces
-The 5.x version is a complete rewrite of the bagit-java library. Because we were rewriting it, we decided it would be a good time to update the interface to be more intuitive. As such, there are some breaking changes and code will need to be migrated.
+
+The 5.x version is a complete rewrite of the bagit-java library which attempts
+to follow modern Java practices and will require some changes to existing code:
 
 ### Examples of using the new bagit-java library
+
 ##### Create a bag from a folder using version 0.97
 ```java
 Path folder = Paths.get("FolderYouWantToBag");
 StandardSupportedAlgorithms algorithm = StandardSupportedAlgorithms.MD5;
 boolean includeHiddenFiles = false;
 Bag bag = BagCreator.bagInPlace(folder, algorithm, includeHiddenFiles);
 ```
+
 ##### Read an existing bag (version 0.93 and higher)
 ```java
 Path rootDir = Paths.get("RootDirectoryOfExistingBag");
 BagReader reader = new BagReader();
 Bag bag = reader.read(rootDir);
 ```
+
 ##### Write a Bag object to disk
 ```java
 Path outputDir = Paths.get("WhereYouWantToWriteTheBagTo");
 BagWriter.write(bag, outputDir); //where bag is a Bag object
 ```
+
 ##### Verify Complete
 ```java
 boolean ignoreHiddenFiles = true;
 BagVerifier verifier = new BagVerifier();
 verifier.isComplete(bag, ignoreHiddenFiles);
 ```
+
 ##### Verify Valid
 ```java
 boolean ignoreHiddenFiles = true;
 BagVerifier verifier = new BagVerifier();
 verifier.isValid(bag, ignoreHiddenFiles);
 ```
+
 ##### Quickly verify by payload-oxum
 ```java
 boolean ignoreHiddenFiles = true;
@@ -77,8 +101,11 @@ if(verifier.canQuickVerify(bag)){
   verifier.quicklyVerify(bag, ignoreHiddenFiles);
 }
 ```
+
 ##### Add other checksum algorithms
-You only need to implement 2 interfaces
+
+You only need to implement 2 interfaces:
+
 ```java
 public class MyNewSupportedAlgorithm implements SupportedAlgorithm {
   @Override
@@ -97,22 +124,30 @@ public class MyNewNameMapping implements BagitAlgorithmNameToSupportedAlgorithmM
     if("sha3256".equals(bagitAlgorithmName)){
       return new MyNewSupportedAlgorithm();
     }
-    
+
     return StandardSupportedAlgorithms.valueOf(bagitAlgorithmName.toUpperCase());
   }
 }
 ```
-and then add the implemented BagitAlgorithmNameToSupportedAlgorithmMapping class to your BagReader or bagVerifier object before using their methods
+
+and then add the implemented `BagitAlgorithmNameToSupportedAlgorithmMapping`
+class to your `BagReader` or `bagVerifier` object before using their methods.
 
 #### Check for potential problems
-The BagIt format is extremely flexible, and allows for many different implementations. While something may technically be correct there are known issues that can be avoided. That is why we created a Bag Linter, which checks for very well known issues that can occur. Here is an example where we check for all known issues:
+
+The BagIt format is extremely flexible and allows for some conditions which are
+technically allowed but should be avoided to minimize confusion and maximize
+portability. The `BagLinter` class allows you to easily check a bag for
+warnings:
+
 ```java
 Path rootDir = Paths.get("RootDirectoryOfExistingBag");
 BagLinter linter = new BagLinter();
 List<BagitWarning> warnings = linter.lintBag(rootDir, Collections.emptyList());
 ```
 
-You can also ignore any of the warnings by passing them into the list like so:
+You can provide a list of specific warnings to ignore:
+
 ```java
 dependencycheckth rootDir = Paths.get("RootDirectoryOfExistingBag");
 BagLinter linter = new BagLinter();
@@ -127,8 +162,8 @@ Inside the bagit-java root directory, run `gradle check`.
 1. Follow their guides
   1. http://central.sonatype.org/pages/releasing-the-deployment.html
   2. https://issues.sonatype.org/secure/Dashboard.jspa
-2. Once you have access, to create an office release and upload it you should specify the version by running `gradle -Pversion=<VERSION> uploadArchives` 
-  1. *Don't forget to tag the repository!* 
+2. Once you have access, to create an office release and upload it you should specify the version by running `gradle -Pversion=<VERSION> uploadArchives`
+  1. *Don't forget to tag the repository!*
 
 ### Note if using with Eclipse
 Simply run `gradle eclipse` and it will automatically create a eclipse project for you that you can import.