adding specification of label schema for #93

Author: vsoch

pages/docs/user-docs/docs-environment-metadata.md

@@ -9,6 +9,7 @@ folder: docs
 
 Singularity containers have two level of metadata - environment variables, and labels from the user and bootstrap process.
 
+
 ### Environment
 
 If you are importing a Docker container, the environment will be imported as well. If you want to define custom environment variables in your bootstrap recipe file `Singularity` you can do that like this
@@ -58,7 +59,26 @@ export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 ```
 
 ### Labels
-Your container stores metadata about it's build, along with Docker labels. You can see the data as follows:
+Your container stores metadata about it's build, along with Docker labels, and your custom labels that you define in a bootstrap `%labels` section. For containers that are generated with Singularity version 2.4 and later, labels are represented using the <a href="http://label-schema.org/rc1/">rc1 Label Schema</a>. For example:
+
+```
+singularity inspect dino.img
+{
+    "org.label-schema.usage.singularity.deffile.bootstrap": "docker",
+    "MAINTAINER": "Vanessasaurus",
+    "org.label-schema.usage.singularity.deffile": "Singularity.help",
+    "org.label-schema.usage": "/.singularity.d/runscript.help",
+    "org.label-schema.schema-version": "1.0",
+    "org.label-schema.usage.singularity.deffile.from": "ubuntu:latest",
+    "org.label-schema.build-date": "2017-07-28T22:59:17-04:00",
+    "org.label-schema.usage.singularity.runscript.help": "/.singularity.d/runscript.help",
+    "org.label-schema.usage.singularity.version": "2.3.1-add/label-schema.g00f040f",
+    "org.label-schema.build-size": "715MB"
+}
+```
+
+You will notice that the one label doesn't belong to the label schema, `MAINTAINER`. This was a user provided label during bootstrap. For versions earlier than 2.4, containers did not use the label schema:
+
 
 ```bash
 singularity exec centos7.img cat /.singularity.d/labels.json

pages/docs/user-docs/docs-inspect.md

@@ -6,7 +6,7 @@ toc: false
 folder: docs
 ---
 
-How can you sniff an image? We have provided the inspect command for you to easily see the runscript, test script, environment, and metadata labels. 
+How can you sniff an image? We have provided the inspect command for you to easily see the runscript, test script, environment, help, and metadata labels. 
 
 {% include toc.html %}
 
@@ -27,6 +27,7 @@ INSPECT OPTIONS:
     -t/--test        Show the test script for this image
     -e/--environment Show the environment settings for this container
     -j/--json        Print structured json instead of sections
+    -hf/--helpfile   Inspect the runscript helpfile, if exists
 
 EXAMPLES:
 
@@ -91,11 +92,12 @@ $ singularity inspect ubuntu.img
 and as outlined in the usage, you can specify to see any combination of `--labels`, `--environment`, `--runscript`, `--test`, and `--deffile`. The quick command to see everything, in json format, would be:
 
 ```
-$ singularity inspect -l -r -d -t -e -j ubuntu.img
+$ singularity inspect -l -r -d -t -e -j -hf ubuntu.img
 {
     "data": {
         "attributes": {
             "test": null,
+            "help": "This is how you run the image!\n",
             "environment": "# Custom environment shell code should follow\n\n",
             "labels": {
                 "SINGULARITY_DEFFILE_BOOTSTRAP": "docker",
@@ -159,6 +161,38 @@ $ singularity inspect -r ubuntu.img
 exec /bin/bash "$@"
 ```
 
+### Help
+The commands `--helpfile` or `-hf` will show you the runscript helpfile, if it exists. With `--json` you can also see it as such:
+
+```
+singularity inspect -hf -j dino.img
+{
+    "data": {
+        "attributes": {
+            "help": "\n\n\nHi there! This is my image help section.\n\nUsage:\n\nboobeep doo doo\n\n --arg/a arrrrg I'm a pirate!\n --boo/b eeeeeuzzz where is the honey?\n\n\n"
+        },
+        "type": "container"
+    }
+}
+```
+
+or in a human friendly, readable print to the screen, don't use `-j` or `--json`:
+
+```
+$ singularity inspect -hf dino.img
+
+
+Hi there! This is my image help section.
+
+Usage:
+
+boobeep doo doo
+
+ --arg/a arrrrg I'm a pirate!
+ --boo/b eeeeeuzzz where is the honey?
+
+```
+
 
 ### Environment
 The commands `--environment` and `-e` will show you the container's environment, again specified by the `%environment` section of a bootstrap file, and other `ENV` labels that might have come from a Docker import. You can again choose to see `--json`: