Merge pull request #27 from khos2ow/cleanup-readme

Update and cleanup README

Author: khos2ow

README.md

@@ -6,7 +6,9 @@
 
 Docker images for building Apache CloudStack RPM packages.
 
-This will give portable, immutable and reproducable mechanism to build packages for releases. A very good candidate to be used by the Jenkins slaves of the project.
+This will give portable, immutable and reproducable mechanism to build packages
+for releases. A very good candidate to be used by the Jenkins slaves of the
+project.
 
 ## Table of Contents
 
@@ -27,9 +29,9 @@ This will give portable, immutable and reproducable mechanism to build packages
 
 ## Supported tags and respective `Dockerfile` links
 
-- [`latest`, `latest-jdk8`, `centos7`, `centos7-jdk8`(centos7/Dockerfile.jdk8)](https://github.com/khos2ow/cloudstack-rpm-builder/blob/master/centos7/Dockerfile.jdk8)
-- [`latest-jdk11`, `centos7-jdk11` (centos7/Dockerfile.jdk11)](https://github.com/khos2ow/cloudstack-rpm-builder/blob/master/centos7/Dockerfile.jdk11)
-- [`centos6` (centos6/Dockerfile)](https://github.com/khos2ow/cloudstack-rpm-builder/blob/master/centos6/Dockerfile) [EOL - not supported anymore]
+- [`latest`, `latest-jdk8`, `centos7`, `centos7-jdk8`(centos7/Dockerfile.jdk8)][centos7-dockerfile]
+- [`latest-jdk11`, `centos7-jdk11` (centos7/Dockerfile.jdk11)][latest-jdk11-dockerfile]
+- [`centos6` (centos6/Dockerfile)][centos6-dockerfile] [EOL - not supported anymore]
 
 ## Packages installed in container
 
@@ -50,58 +52,83 @@ List of available packages inside the container:
 
 ## Build RPM packages
 
-Building RPM packages with the Docker container is rather easy, a few steps are required:
+Building RPM packages with the Docker container is rather easy, a few steps are
+required:
 
 ### Pull Docker images
 
-Let's assume we want to build packages for CentOS 7 on CentOS 7. We pull that image first:
+Let's assume we want to build packages for CentOS 7 on CentOS 7. We pull that
+image first:
 
-    docker pull khos2ow/cloudstack-rpm-builder:centos7-jdk11
+```bash
+docker pull khos2ow/cloudstack-rpm-builder:centos7-jdk11
+```
 
-You can replace `centos7-jdk11` tag by [one of the other tags](#supported-tags-and-respective-dockerfile-links).
+You can replace `centos7-jdk11` tag by [one of the other tags].
 
 ### Build local repository
 
-You can clone the CloudStack source code from repository locally on your machine and build packages against that.
+You can clone the CloudStack source code from repository locally on your machine
+and build packages against that.
 
 #### Clone Apache CloudStack source code
 
-The first step required is to clone the CloudStack source code somewhere on the filesystem, in `/tmp` for example:
+The first step required is to clone the CloudStack source code somewhere on the
+filesystem, in `/tmp` for example:
 
-    git clone https://github.com/apache/cloudstack.git /tmp/cloudstack
+```bash
+git clone https://github.com/apache/cloudstack.git /tmp/cloudstack
+```
 
 Now that you have done so we can continue.
 
 #### Build packages of local repository
 
-Now that we have cloned the CloudStack source code locally, we can build packages by mapping `/tmp` into `/mnt/build` in the container. (Note that the container always expects the `cloudstack` code exists in `/mnt/build` path.)
+Now that we have cloned the CloudStack source code locally, we can build packages
+by mapping `/tmp` into `/mnt/build` in the container. (Note that the container
+always expects the `cloudstack` code exists in `/mnt/build` path.)
 
-    docker run \
-        -v /tmp:/mnt/build \
-        khos2ow/cloudstack-rpm-builder:centos7-jdk11 --distribution centos7 [ARGS...]
+```bash
+docker run \
+    -v /tmp:/mnt/build \
+    khos2ow/cloudstack-rpm-builder:centos7-jdk11 --distribution centos7 [ARGS...]
+```
 
-Or if your local cloudstack folder has other name, you need to map it to `/mnt/build/cloudstack`.
+Or if your local cloudstack folder has other name, you need to map it to
+`/mnt/build/cloudstack`.
 
-    docker run \
-        -v /tmp/cloudstack-custom-name:/mnt/build/cloudstack \
-        khos2ow/cloudstack-rpm-builder:centos7-jdk11 --distribution centos7 [ARGS...]
+```bash
+docker run \
+    -v /tmp/cloudstack-custom-name:/mnt/build/cloudstack \
+    khos2ow/cloudstack-rpm-builder:centos7-jdk11 --distribution centos7 [ARGS...]
+```
 
-After the build has finished the *.rpm* packages are available in */tmp/cloudstack/dist/rpmbuild/RPMS* on the host system.
+After the build has finished the `.rpm` packages are available in
+`/tmp/cloudstack/dist/rpmbuild/RPMS` on the host system.
 
 ### Build remote repository
 
-Also you can build RPM packages of any remote repository without the need to manually clone it first. You only need to specify git remote and git ref you intend to build from.
+Also you can build RPM packages of any remote repository without the need to manually
+clone it first. You only need to specify git remote and git ref you intend to build
+from.
 
 #### Build packages of remote repository
 
-Now let's assume we want to build packages of `HEAD` of `master` branch from https://github.com/apache/cloudstack repository, we build packages by mapping `/tmp` into `/mnt/build` in the container. The container will clone the repository (defined by `--git-remote` flag) and check out the REF (defined by `--git-ref` flag) in `/mnt/build/cloudstack` inside the container and can be accessed from `/tmp/cloudstack` from the host machine.
-
-    docker run \
-        -v /tmp:/mnt/build \
-        khos2ow/cloudstack-rpm-builder:centos7-jdk11 \
-            --git-remote https://github.com/apache/cloudstack.git \
-            --git-ref master \
-            --distribution centos7 [ARGS...]
+Now let's assume we want to build packages of `HEAD` of `master` branch from
+[https://github.com/apache/cloudstack] repository, we build packages by mapping
+`/tmp` into `/mnt/build` in the container. The container will clone the repository
+(defined by `--git-remote` flag) and check out the REF (defined by `--git-ref`
+flag) in `/mnt/build/cloudstack` inside the container and can be accessed from
+`/tmp/cloudstack` from the host machine.
+
+```bash
+docker run \
+    -v /tmp:/mnt/build \
+    khos2ow/cloudstack-rpm-builder:centos7-jdk11 \
+        --git-remote https://github.com/apache/cloudstack.git \
+        --git-ref master \
+        --distribution centos7 [ARGS...]
+```
 
 Note that any valid git Refspec is acceptable, such as:
 
@@ -111,41 +138,64 @@ Note that any valid git Refspec is acceptable, such as:
 - `refs/merge-requests/<NUMBER>/head` to build specified GitLab Merge Request
 - `refs/tags/<NAME>` to build specified Tag
 
-After the build has finished the *.rpm* packages are available in */tmp/cloudstack/dist/rpmbuild/RPMS* on the host system.
+After the build has finished the `.rpm` packages are available in
+`/tmp/cloudstack/dist/rpmbuild/RPMS` on the host system.
 
 ## Building tips
 
 Check the following tips when using the builder:
 
 ### Maven cache
 
-You can provide Maven cache folder (`~/.m2`) as a volume to the container to make it run faster.
+You can provide Maven cache folder (`~/.m2`) as a volume to the container to make
+it run faster.
 
-    docker run \
-        -v /tmp:/mnt/build \
-        -v ~/.m2:/root/.m2 \
-        khos2ow/cloudstack-rpm-builder:centos7-jdk11 --distribution centos7 [ARGS...]
+```bash
+docker run \
+    -v /tmp:/mnt/build \
+    -v ~/.m2:/root/.m2 \
+    khos2ow/cloudstack-rpm-builder:centos7-jdk11 --distribution centos7 [ARGS...]
+```
 
 ### Adjust host owner permission
 
-Builder container in some cases (e.g. using `--use-timestamp` flag) may change the file and directory owner shared from host to container (through volume) and it will create `dist` directory which holds the final artifacts. You can provide `USER_ID` (mandatory) and/or `USER_GID` (optional) from host to adjust the owner from whitin the container.
+Builder container in some cases (e.g. using `--use-timestamp` flag) may change
+the file and directory owner shared from host to container (through volume) and
+it will create `dist` directory which holds the final artifacts. You can provide
+`USER_ID` (mandatory) and/or `USER_GID` (optional) from host to adjust the owner
+from whitin the container.
 
-This is specially useful if you want to use this image in Jenkins job and want to clean up the workspace afterward. By adjusting the owner, you won't need to give your Jenkins' user `sudo` privilege to clean up.
+This is specially useful if you want to use this image in Jenkins job and want to
+clean up the workspace afterward. By adjusting the owner, you won't need to give
+your Jenkins' user `sudo` privilege to clean up.
 
-    docker run \
-        -v /tmp:/mnt/build \
-        -e "USER_ID=$(id -u)" \
-        -e "USER_GID=$(id -g)" \
-        khos2ow/cloudstack-rpm-builder:centos7-jdk11 --distribution centos7 [ARGS...]
+```bash
+docker run \
+    -v /tmp:/mnt/build \
+    -e "USER_ID=$(id -u)" \
+    -e "USER_GID=$(id -g)" \
+    khos2ow/cloudstack-rpm-builder:centos7-jdk11 --distribution centos7 [ARGS...]
+```
 
 ## Builder help
 
 To see all the available options you can pass to `docker run ...` command:
 
-    docker run \
-        -v /tmp:/mnt/build \
-        khos2ow/cloudstack-rpm-builder:centos7-jdk11 --help
+```bash
+docker run \
+    -v /tmp:/mnt/build \
+    khos2ow/cloudstack-rpm-builder:centos7-jdk11 --help
+```
 
 ## License
 
-Licensed under [Apache License version 2.0](http://www.apache.org/licenses/LICENSE-2.0). Please see the [LICENSE](https://github.com/khos2ow/cloudstack-rpm-builder/blob/master/LICENSE) file included in the root directory of the source tree for extended license details.
+Licensed under [Apache License version 2.0]. Please see the [LICENSE] file
+included in the root directory of the source tree for extended license details.
+
+[centos7-dockerfile]: https://github.com/khos2ow/cloudstack-rpm-builder/blob/master/centos7/Dockerfile.jdk8
+[latest-jdk11-dockerfile]: https://github.com/khos2ow/cloudstack-rpm-builder/blob/master/centos7/Dockerfile.jdk11
+[centos6-dockerfile]: https://github.com/khos2ow/cloudstack-rpm-builder/blob/master/centos6/Dockerfile
+[one of the other tags]: #supported-tags-and-respective-dockerfile-links
+[https://github.com/apache/cloudstack]: https://github.com/apache/cloudstack
+[Apache License version 2.0]: http://www.apache.org/licenses/LICENSE-2.0
+[LICENSE]: https://github.com/khos2ow/cloudstack-rpm-builder/blob/master/LICENSE