Merge lp:~mbruzek/charms/trusty/ibm-xl-fortran/readme-update into lp:~ibmcharmers/charms/trusty/ibm-xl-fortran/trunk

[Matt Bruzek]

I found the README.md file incomplete and hard to follow.

For example it must be clear this is a Power PC only charm so I added a section near the top that made this very clear.

Also the existing README.md suggested editing the config.yaml file and users can not do that if they deploy this charm from the Charm Store. So I removed that section from the deployment steps.

This merge proposal does not fix all the problems with the README.md file! Some of the configuration uses underscores (_) and some configuration options use hypens (-) as word separators. The code, config.yaml and the README.md should be fixed to normalize on one method.

Please consider this merge proposal.

[lp:~mbruzek/charms/trusty/ibm-xl-fortran/readme-update]

52. By Matt Bruzek on 2015-11-05

Fixing grammer errors in the README update.

Unmerged revisions

52. By Matt Bruzek on 2015-11-05

Fixing grammer errors in the README update.

51. By Matt Bruzek on 2015-11-05

Updating the readme to fix issues that I found in the review.

=== modified file 'README.md'
--- README.md	2015-09-30 06:58:52 +0000
+++ README.md	2015-11-05 21:19:01 +0000
@@ -1,88 +1,95 @@
-Charm for IBM XL FORTRAN for Linux 15.1.2, Evaluation
-
-
-Overview
---------
-
-
-IBM XL FORTRAN for Linux V15.1.2, Evaluation
-
-IBM XL FORTRAN for Linux, V15.1.2 is a standards-based, high-performance Fortran compiler with advanced optimization and performance-tuning features.
-
-For details on IBM XL FORTRAN, as well as information on purchasing the trial version,
-please visit: [Trial Download] [trial-xlf].
-
-To get more details about the product and useful additional resources, please visit the product page
-[Product Page] [product-page] and [IBM Knowledge Center] [ibm-xlf-info]
-
+# IBM XL Fortran
+
+IBM XL FORTRAN for Linux, V15.1.2 is a standards-based, high-performance
+Fortran compiler with advanced optimization and performance-tuning features.
+
+For details on IBM XL FORTRAN, as well as information on purchasing the trial
+version, please visit: [Trial Download][trial-xlf].
+
+To get more details about the product and useful additional resources, please
+visit the [Product Page][product-page] and [IBM Knowledge Center][ibm-xlf-info]
+
+### This charm only runs on Power architecture (ppc64le)!
 
 Usage
 -----
 
-Download your 60 day trial version for IBM XL Fortran for Linux  and upload it to your apache
-repository. To download and install the code contained in this charm you must agree to the IBM license.
-The License files (`LicenseAgreement.pdf` and `license.pdf` ) can be found under the `files/archives` folder
-after extraction of IBM Fortran compiler software is successful.
-
-Note: This charm will only work on power systems. 
-
-# Creating the repositories in Apache
-Run below steps with admin access
-
-Install the required packages
-	apt-get install dpkg-dev apache2
-
-Create a repository on Apache server under your Apache repository directory.
-    
-        cd <apache-repository-directory>
-        mkdir ibm-xlf
-
-Place the downloaded IBM XL FORTRAN for Linux packages in the above directory and Configure Apache server to allow access to the repository.
-
-Configure config.yaml with the repository url
- 
- Example : `fortran_url: "http://<server-name>/<REPOSITORY_DIR>/fortran_url"`
-
- Verify repository is set correctly otherwise charm might throw errors.
-
-
+Download your 60 day trial version for IBM XL Fortran for Linux and upload it
+to your apache repository. To download and install the code contained in this
+charm you must agree to the IBM license. The License files
+(`LicenseAgreement.pdf` and `license.pdf` ) can be found under the
+`files/archives` folder after extraction of IBM Fortran compiler software is
+successful.
+
+**Note**: This charm is specifically designed to run Power architecture
+(ppc64le) systems only.  It will not run on AMD (amd64) or Intel (x86_64) based
+systems.  Use `uname -m` to determine the architecture of your cloud instances.
+
+## Create a web repository to host the software  
+
+To deploy this charm you need to [download][trial-xlf] the IBM XL Fortran
+software and host it on a web server such as Apache.  Run the following steps
+with administrator access.
+
+Install the required packages:  
+
+    apt-get install dpkg-dev apache2
+
+Create a repository on the server under the Apache repository directory:
+
+    cd <apache-repository-directory>
+    mkdir ibm-xlf
+
+Place the downloaded IBM XL FORTRAN for Linux packages in the 'ibm-xlf'
+directory and configure Apache server to allow access to the repository.
+
+Verify the IBM XL Fortran repository URL is accessible before deploying the
+charm.  You will need the URL to the directory that contains the
+`IBM_XL_FORTRAN*.tar.gz` file to configure the ibm-xl-fortran charm.
+
+**Example**: `http://<server-name>:<port>/<REPOSITORY_DIR>/ibm-xlf`
 
 Deploy
 ------
 
-Run the following to deploy this charm:
-
-	juju deploy ibm-xl-fortran 
-
-At this point IBM XL FORTRAN install will wait for you to accept the License. To install the downloaded binaries
-you must agree to the IBM license. 
-
-If the URL and package is configured in the config.yaml:
-        
-    juju set ibm-xl-fortran accept-ibm-xlfortran-license=True 
-    
-If not,
-        
-     juju set ibm-xl-fortran accept-ibm-xlfortran-license=True fortran-url=<repository URL> xlfortran_package_name=<Installation package name> sha_fortran=<sha sum of the xlf package>
-
-This charm will deploy the IBM XL FORTRAN compiler packages. For testing purpose, when you run amulet test, it will deploy the Compiler and create a sample program for compilation.
-
-    
+Run the following command to deploy the IBM XL Fortran charm:
+
+    juju deploy ibm-xl-fortran
+
+At this point IBM XL FORTRAN charm will wait for you to accept the license.
+To install the downloaded binaries you must agree to the IBM license. To
+signify you agree set the `accept-ibm-xlfortran-license` configuration option
+to True:  
+
+    juju set ibm-xl-fortran accept-ibm-xlfortran-license=True
+
+For the charm to install you also need to set URL to the package and the
+checksum of the package to verify the software was downloaded correctly.
+
+These values can be set through configuration with the following command:  
+
+    juju set ibm-xl-fortran accept-ibm-xlfortran-license=True xlfortran_url=<repository URL> xlfortran_package_name=<Installation package name> sha_fortran=<sha sum of the xlf package>
+
+This charm will deploy the IBM XL FORTRAN compiler packages. For testing
+purpose, when you run amulet test, it will deploy the Compiler and create a
+sample program for compilation.
+
 Configuration
 -------------
 See config.yaml file for more information.
 
-`xlfortran_url`          
+`xlfortran_url`
 
-URL to download IBM XL FORTRAN packages. The url would be in this format  
-http://<server-name>/<REPOSITORY_DIR>/ibm-xlf. If not set or set incorrectly, the charm
-cannot install the IBM XL FORTRAN software.
+URL to download IBM XL FORTRAN packages. The URL would be in this format  
+http://<server-name>:<port>/<REPOSITORY_DIR>/ibm-xlf. If not set or set
+incorrectly, the charm cannot install the IBM XL FORTRAN software.
 
 `accept-ibm-xlfortran-license`
 
-The IBM XL FORTRAN software can only be used by accepting the terms and conditions for IBM 
-XL FORTRAN License. Setting this option to True indicates that you have read and accepted the
-IBM XL FORTRAN terms and conditions found in the license file.
+The IBM XL FORTRAN software can only be used by accepting the terms and
+conditions for IBM XL FORTRAN License. Setting this option to True indicates
+that you have read and accepted the IBM XL FORTRAN terms and conditions found
+in the license file.
 
 `xlfortran_package_name`
 
@@ -90,20 +97,21 @@
 
 `sha_fortran:`
 
-Checksum value to check integrity of IBM XL FORTRAN package. The Charm uses
+Checksum value to check integrity of IBM XL FORTRAN package. The charm uses
 sha1sum to check the integrity. If empty, it does not carry out the integrity check.
 The command to find the checksum is: "sha1sum <Package Name> | cut -d" " -f1"
 
 
 IBM XL FORTRAN Information
 ----------------------------
-(1) General Information
-Information on IBM XL FORTRAN available at the [IBM Knowledge Center] [ibm-xlf-info]
-
-(2) Download Information
-Information on downloading the fully functional trial for an evaluation period of 60 days is available at [Trial Download] [trial-xlf]
-
-(3) Contact Information
+#### General Information  
+Information on IBM XL FORTRAN available at the [IBM Knowledge Center][ibm-xlf-info]
+
+#### Download Information  
+Information on downloading the fully functional trial for an evaluation period
+of 60 days is available at [Trial Download][trial-xlf]
+
+#### Contact Information  
 For issues with this charm, please contact IBM Juju Support Team <[e-mail]>
 
 <!-- Links -->
@@ -113,6 +121,3 @@
 [trial-xlf]: http://www.ibm.com/developerworks/downloads/r/xlfortranlinux/
 
 [ibm-xlf-info]: http://www-01.ibm.com/support/knowledgecenter/SSAT4T_15.1.2/com.ibm.compilers.linux.doc/welcome.html
-
-
-