From f01741e127575b47b0535036cedab786e123c726 Mon Sep 17 00:00:00 2001
From: Tom Scavo <trscavo@internet2.edu>
Date: Sat, 22 Oct 2016 18:57:22 -0400
Subject: [PATCH] Add example to overview section

---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.md b/README.md
index 39641a5..36062b5 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,36 @@ IdP Display Name,IdP Entity ID,IdP Discovery,Registrar ID
 "Case Western Reserve University",urn:mace:incommon:case.edu,show,https://incommon.org
 ```
 
+### Example #1
+
+Consider the following URLs:
+
+```Shell
+xml_location=http://md.incommon.org/InCommon/InCommon-metadata.xml
+resource_url=https://incommon.org/federation/metadata/all_IdP_DisplayNames.csv
+```
+
+Suppose there is an automated process that transforms the SAML metadata at ``xml_location`` into the CSV file at ``resource_url``. Specifically, let's suppose the following process runs every hour on www.incommon.org:
+
+```Shell
+# the XSL script and the shell script are included in the md-transforms repository
+xsl_file=$LIB_DIR/list_all_IdP_DisplayNames_csv.xsl
+resource_file=/tmp/all_IdP_DisplayNames.csv
+$BIN_DIR/http_xsltproc.sh -F -o "$resource_file" "$xsl_file" "$xml_location"
+exit_code=$?
+if [ $exit_code -ne 0 ]; then
+	echo "ERROR: http_xsltproc.sh failed with status code: $exit_code" >&2
+	exit $exit_code
+fi
+
+# the resource_dir is the target web directory for the resource_file
+resource_dir=/home/htdocs/www.incommonfederation.org/federation/metadata/
+mv $resource_file $resource_dir
+exit 0
+```
+
+Observe that the command ``http_xsltproc.sh -F`` forces a fresh SAML metadata file. If the server responds with ``304 Not Modified``, the process terminates without updating the resource file.
+
 ## Compatibility
 
 The executable scripts are compatible with GNU/Linux and Mac OS. The library files are written in XSLT 1.0.