More documentation updates.

Author: mikedarcy

README.md

@@ -37,7 +37,7 @@ An experimental Graphical User Interface (GUI) for *bdbag* can be found [here](h
 
 ### Dependencies
 
-* [Python 2.7](https://www.python.org/downloads/release/python-2711/) is the minimum Python version required.
+* [Python 2.7](https://www.python.org/downloads/release/python-27/) is the minimum Python version required.
 * The code and dependencies are also compatible with Python 3, versions 3.3 through 3.6.
 
 ### Installation
@@ -71,16 +71,17 @@ The unit tests can be run by invoking the following command from the root of the
 python setup.py test
 ```
 
-### Configuration
-
-See the [Configuration guide](./doc/config.md).
-
 ### Usage
 
 This software can be used from the command-line environment by running the **bdbag** script.  For detailed usage
 instructions, see the [CLI guide](./doc/cli.md).
 
+### Configuration
+
+Some components of the **bdbag** software can be configured via JSON-formatted configuration files.
+See the [Configuration guide](./doc/config.md) for further details.
+
 ### Application Programming Interface
 
 It is also possible to use **bdbag** from within other Python programs via an API.
-See the [API guide](./doc/api.md) for further details.
+See the [API guide](/doc/api.md) for further details.

doc/api.md

@@ -141,7 +141,7 @@ and that there are no additional files present that are not listed in either `fe
 -----
 
 <a name="make_bag"></a>
-#### make_bag(bag_path, update=False, algs=None, prune_manifests=False, metadata=None, metadata_file=None, remote_file_manifest=None, config_file=bdbag.DEFAULT_CONFIG_FILE)  ⇒ `bag`
+#### make_bag(bag_path, update=False, algs=None, prune_manifests=False, metadata=None, metadata_file=None, remote_file_manifest=None, config_file=bdbag.DEFAULT_CONFIG_FILE, ro_metadata=None, ro_metadata_file=None)  ⇒ `bag`
 Creates or updates the bag denoted by the `bag_path` argument.
 
 | Param | Type | Description |

doc/cli.md

@@ -39,18 +39,20 @@ usage: bdbag
 #### Extended arguments:
 These extended arguments are mapped directly to metadata fields in bag-info.txt:
 ```
-[--source-organization SOURCE_ORGANIZATION]
-[--organization-address ORGANIZATION_ADDRESS]
-[--contact-name CONTACT_NAME] [--contact-phone CONTACT_PHONE]
+[--bag-count BAG_COUNT]
+[--bag-group-identifier BAG_GROUP_IDENTIFIER]
+[--bag-size BAG_SIZE]
+[--bagit-profile-identifier BAGIT_PROFILE_IDENTIFIER]
 [--contact-email CONTACT_EMAIL]
+[--contact-name CONTACT_NAME]
 [--contact-orcid CONTACT_ORCID]
+[--contact-phone CONTACT_PHONE]
 [--external-description EXTERNAL_DESCRIPTION]
-[--external-identifier EXTERNAL_IDENTIFIER] [--bag-size BAG_SIZE]
-[--bag-group-identifier BAG_GROUP_IDENTIFIER]
-[--bag-count BAG_COUNT]
-[--internal-sender-identifier INTERNAL_SENDER_IDENTIFIER]
+[--external-identifier EXTERNAL_IDENTIFIER]
 [--internal-sender-description INTERNAL_SENDER_DESCRIPTION]
-[--bagit-profile-identifier BAGIT_PROFILE_IDENTIFIER]
+[--internal-sender-identifier INTERNAL_SENDER_IDENTIFIER]
+[--organization-address ORGANIZATION_ADDRESS]
+[--source-organization SOURCE_ORGANIZATION]
 ```
 ----
 
@@ -407,7 +409,6 @@ Here's an example of what a `remote-file-manifest` looks like:
     "url":"https://raw.githubusercontent.com/fair-research/bdbag/master/profiles/bdbag-profile.json",
     "length":723,
     "filename":"bdbag-profile.json",
-    "md5":"4754a1f3204f8b2de547477117f65f6d",
     "sha256":"3039ea47828e032ea2fe63679281c50760e68b5773a76f5873c4ae7acdf87951"
   },
   {
@@ -467,7 +468,6 @@ ark:/88120/r8059v       632860  data/minid_v0.1_Nov_2015.pdf
 
 [mdarcy@dev ~]$  cat test_bag/manifest-md5.txt
 
-4754a1f3204f8b2de547477117f65f6d  data/bdbag-profile.json
 dad6891eb4148dfed2d162370983d06f  data/test1.txt
 11069c18ee13a990265cf944359dbca5  data/test2.txt
 

doc/config.md

@@ -6,8 +6,8 @@ There are two global configuration files: [bdbag.json](#bdbag.json) and [keychai
 these files with simple default values are automatically created in
 the current user's home directory the first time a bag is created or opened.
 
-Additionally, two JSON-formatted configuration files can be passed as arguments to *bdbag* in order to supply input
-for certain bag creation and update functions.  These files are known as [metadata](#metadata) and
+Additionally, three JSON-formatted configuration files can be passed as arguments to *bdbag* in order to supply input
+for certain bag creation and update functions.  These files are known as [metadata](#metadata), [ro metadata](#ro_metadata) and
 [remote-file-manifest](#remote-file-manifest) configurations.
 
 <a name="bdbag.json"></a>
@@ -145,11 +145,11 @@ Below is a sample *remote-file-manifest* configuration file:
 ```
 
 <a name="metadata"></a>
-## *metadata*
-A metadata configuration file consists of a single JSON object containing a set of JSON key-value pairs that will be
-written as-is to the bag's `bag-info.txt` file.
+## *`bag-info` metadata*
+A `bag-info` metadata configuration file consists of a single JSON object containing a set of JSON key-value pairs that will be
+written as-is to the bag's `bag-info.txt` file.  NOTE: per the `bagit` specification, strings are the only supported value type in `bag-info.txt`.
 
-Below is a sample *metadata* configuration file:
+Below is a sample `bag-info` *metadata* configuration file:
 ```json
 {
     "BagIt-Profile-Identifier": "https://raw.githubusercontent.com/fair-research/bdbag/master/profiles/bdbag-profile.json",
@@ -159,10 +159,18 @@ Below is a sample *metadata* configuration file:
 ```
 
 <a name="ro_metadata"></a>
-## *ro_metadata*
-A Research Object metadata configuration file consists of a single JSON object containing a set of JSON key-object pairs where the `key` is a `/` delimited relative file path and the `object` is any aribitratily complex JSON content. This format allows `bdbag` to process all RO metadata as an aggregation which can then be serialized into individual JSON file components relative to the bag's `metadata` directory.
-
-Below is a sample *ro_metadata* configuration file:
+## *`ro` metadata*
+A Research Object metadata configuration file consists of a single JSON object containing a set of JSON key-object pairs where
+the `key` is a `/` delimited relative file path and the `object` is any aribitratily complex JSON content. This format allows
+`bdbag` to process all RO metadata as an aggregation which can then be serialized into individual JSON file components relative
+to the bag's `metadata` directory.
+
+NOTE: while this documentation refers to this configuration file a `ro` metadata file,
+the contents of this configuration file only have to conform to the [`bagit-ro`](https://github.com/ResearchObject/bagit-ro)
+conventions if `bagit-ro` compatibility is the goal. Otherwise, this mechanism can be used as a generic way to create any number of
+arbitrary JSON (or JSON-LD) metadata files as `bagit` tagfiles.
+
+Below is a sample *ro metadata* configuration file:
 ```json
 {
   "manifest.json": {

setup.py

@@ -8,13 +8,14 @@
 
 from setuptools import setup, find_packages
 
+with open('README.md') as readme_file:
+    readme = readme_file.read()
 
 setup(
     name="bdbag",
-    description="BigData Bag Utilities",
-    long_description=
-    "For more information on *bdbag*, visit: https://github.com/fair-research/bdbag/.\n\n"
-    "For more information on the GUI frontend for *bdbag*, visit: https://github.com/fair-research/bdbag_gui/.\n",
+    description="Big Data Bag Utilities",
+    long_description=readme,
+    long_description_content_type='text/markdown',
     url='https://github.com/fair-research/bdbag/',
     maintainer='USC Information Sciences Institute, Informatics Systems Research Division',
     maintainer_email='[email protected]',