Merge pull request #22 from infosiftr/consistency-and-fredlf

Reflow all the language stack `README-content.md` files to 80 columns and incorporate Fred's changes

Author: yosifkit

README-footer.md

@@ -4,16 +4,17 @@
 ## Issues
 
 If you have any problems with, or questions about this image, please contact us
-%%MAILING_LIST%% through a [GitHub issue](%%REPO%%/issues) or via the IRC channel
-`#docker-library` on [Freenode](https://freenode.net).
+%%MAILING_LIST%% through a [GitHub issue](%%REPO%%/issues) or via the IRC
+channel `#docker-library` on [Freenode](https://freenode.net).
 
 ## Contributing
 
-You are invited to contribute new features, fixes, or updates, large or small; we are
-always thrilled to receive pull requests, and do our best to process them as fast as
-we can.
+You are invited to contribute new features, fixes, or updates, large or small;
+we are always thrilled to receive pull requests, and do our best to process them
+as fast as we can.
 
-Before you start to code, we recommend discussing your plans %%MAILING_LIST%% through a
-[GitHub issue](%%REPO%%/issues), especially for more ambitious contributions. This gives
-other contributors a chance to point you in the right direction, give you feedback on
-your design, and help you find out if someone else is working on the same thing.
+Before you start to code, we recommend discussing your plans %%MAILING_LIST%%
+through a [GitHub issue](%%REPO%%/issues), especially for more ambitious
+contributions. This gives other contributors a chance to point you in the right
+direction, give you feedback on your design, and help you find out if someone
+else is working on the same thing.

buildpack-deps/README-content.md

@@ -1,3 +1,8 @@
-# What is buildpack-deps?
+# What is `buildpack-deps`?
 
-`buildpack-deps` is in spirit similar to [Heroku's stack images](https://github.com/heroku/stack-images/blob/master/bin/cedar.sh); it includes a huge number of "development header" packages needed by arbitrary things like Ruby Gems, PyPI modules, etc.  This makes it possible to do something like a `bundle install` in an arbitrary application directory without knowing beforehand that it needs `ssl.h` to build one of the modules depended on, for example.
+In spirit, `buildpack-deps` is similar to [Heroku's stack
+images](https://github.com/heroku/stack-images/blob/master/bin/cedar.sh). It
+includes a large number of "development header" packages needed by various
+things like Ruby Gems, PyPI modules, etc. For example, `buildpack-deps` would
+let you do a `bundle install` in an arbitrary application directory without
+knowing beforehand that `ssl.h` is required to build a dependent module.

clojure/README-content.md

@@ -1,26 +1,37 @@
-What is Clojure?
+# What is Clojure?
 
-Clojure is a dialect of the Lisp programming language created by Rich Hickey. Clojure is a general-purpose programming language with an emphasis on functional programming. It runs on the Java Virtual Machine, Common Langauge Runtime, and JavaScript engines. Like other Lisps, Clojure treats code as data and has a macro system.
+Clojure is a dialect of the Lisp programming language. It is a general-purpose
+programming language with an emphasis on functional programming. It runs on the
+Java Virtual Machine, Common Langauge Runtime, and JavaScript engines. Like
+other Lisps, Clojure treats code as data and has a macro system.
 
->[wikipedia.org/wiki/Clojure](http://en.wikipedia.org/wiki/Clojure)
+> [wikipedia.org/wiki/Clojure](http://en.wikipedia.org/wiki/Clojure)
 
 # How to use this image
 
-## Start a Lein/Clojure instance running in your app.
+## Start a Lein/Clojure instance in your app
 
-As the most common way to use Clojure is in conjunction with [lein](http://leiningen.org/), the Clojure image assumes you are doing so. The most straight-forward way of using this image is adding a Dockerfile to an already existing Lein/Clojure project.
+Since the most common way to use Clojure is in conjunction with [Leiningen
+(`lein`)](http://leiningen.org/), this image assumes that's how you'll be
+working. The most straightforward way to use this image is to add a `Dockerfile`
+to an existing Leiningen/Clojure project:
 
     FROM clojure
     COPY . /usr/src/app
     WORKDIR /usr/src/app
     CMD ["lein", "run"]
 
-Then run the commands to build and run the image.
+Then, run these commands to build and run the image:
 
     docker build -t my-clojure-app .
     docker run -it --rm --name my-running-app my-clojure-app
 
-While the above is the most straight-forward example of a Dockerfile, it has several drawbacks. The `lein run` command will download your dependencies, compile the project, and then run it. That's a lot of work being done, and it may not be that you want that done every single time you run the image. We can download the dependencies ahead of time, as well as compile the project, so that when you run your image, the startup time is significantly reduced.
+While the above is the most straightforward example of a `Dockerfile`, it does
+have some drawbacks. The `lein run` command will download your dependencies,
+compile the project, and then run it. That's a lot of work, all of which you may
+not want done every time you run the image. To get around this, you can download
+the dependencies and compile the project ahead of time. This will significantly
+reduce startup time when you run your image.
 
     FROM clojure
     RUN mkdir -p /usr/src/app
@@ -31,17 +42,19 @@ While the above is the most straight-forward example of a Dockerfile, it has sev
     RUN mv "$(lein uberjar | sed -n 's/^Created \(.*standalone\.jar\)/\1/p')" app-standalone.jar
     CMD ["java", "-jar", "app-standalone.jar"]
 
-This Dockerfile will cause the dependencies to be downloaded (and cached so that they are only redownloaded when the dependencies change, rather than everytime the image is built) and compiled into a standalone jar when it is built rather than each time it is run.
+Writing the `Dockerfile` this way will download the dependencies (and cache
+them, so they are only re-downloaded when the dependencies change) and then
+compile them into a standalone jar ahead of time rather than each time the image
+is run.
 
-Then build and run the image.
+You can then build and run the image as above.
 
-    docker build -t my-clojure-app .
-    docker run -it --rm --name my-running-app my-clojure-app
-
-## Compile your Lein/Clojure project into a jar from within the container.
+## Compile your Lein/Clojure project into a jar from within the container
 
-If you have an existing Lein/Clojure project, it's fairly straightforward to compile your project into a jar from a container.
+If you have an existing Lein/Clojure project, it's fairly straightforward to
+compile your project into a jar from a container:
 
     docker run -it --rm -v "$(pwd)":/usr/src/app -w /usr/src/app clojure lein uberjar
 
-This will build your project into a jar file located in your project's target/uberjar directory for you to use.
+This will build your project into a jar file located in your project's
+`target/uberjar` directory.

gcc/README-content.md

@@ -1,31 +1,44 @@
-# What is gcc?
-The GNU Compiler Collection (GCC) is a compiler system produced by the GNU Project supporting various programming languages. GCC is a key component of the GNU toolchain. The Free Software Foundation (FSF) distributes GCC under the GNU General Public License (GNU GPL). GCC has played an important role in the growth of free software, as both a tool and an example.
+# What is GCC?
+
+The GNU Compiler Collection (GCC) is a compiler system produced by the GNU
+Project that supports various programming languages. GCC is a key component of
+the GNU toolchain. The Free Software Foundation (FSF) distributes GCC under the
+GNU General Public License (GNU GPL). GCC has played an important role in the
+growth of free software, as both a tool and an example.
 
 > [wikipedia.org/wiki/GNU_Compiler_Collection](https://en.wikipedia.org/wiki/GNU_Compiler_Collection)
 
 # How to use this image
 
-## Start a gcc instance running your app.
+## Start a GCC instance running your app
 
-For this image, the most straight-forward use is to use a gcc container as both the build environment as well as the runtime environment. In your Dockerfile, you can do something along the lines of the following will compile and run your project.
+The most straightforward way to use this image is to use a gcc container as both
+the build and runtime environment. In your `Dockerfile`, writing something along
+the lines of the following will compile and run your project:
 
     FROM gcc:4.9
     COPY . /usr/src/myapp
     WORKDIR /usr/src/myapp
     RUN gcc -o myapp main.c
     CMD ["./myapp"]
 
-Then run the commands to build and run the docker image.
+Then, build and run the Docker image:
 
     docker build -t my-gcc-app .
     docker run -it --rm --name my-running-app my-gcc-app
 
-## Compile your app inside the docker container.
+## Compile your app inside the Docker container
 
-It is not always appropriate to run your app inside a container. In instances where you only want to compile inside the docker instance, you can do something along the lines of the following.
+There may be occasions where it is not appropriate to run your app inside a
+container. To compile, but not run your app inside the Docker instance, you can
+write something like:
 
     docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp gcc:4.9 gcc -o myapp myapp.c
 
-This will add your current directory as a volume to the container, set the working directory to the volume, and run the command `gcc -o myapp myapp.c` which will tell gcc to compile the code in myapp.c and output the executable to myapp. Alternatively, if you have a make file, you can instead run the make command inside your container.
+This will add your current directory, as a volume, to the container, set the
+working directory to the volume, and run the command `gcc -o myapp myapp.c.`
+This tells gcc to compile the code in `myapp.c` and output the executable to
+myapp. Alternatively, if you have a `Makefile`, you can instead run the `make`
+command inside your container:
 
     docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp gcc:4.9 make

gcc/README-short.txt

@@ -1 +1 @@
-The GNU Compiler Collection (GCC) is a compiler system produced by the GNU Project supporting various programming languages.
+The GNU Compiler Collection (GCC) is a compiler system produced by the GNU Project that supports various programming languages.

golang/README-content.md

@@ -1,43 +1,60 @@
 # What is Go?
-Go, also called golang, is a programming language initially developed at Google in 2007 by Robert Griesemer, Rob Pike, and Ken Thompson. It is a statically-typed language with syntax loosely derived from that of C, adding garbage collection, type safety, some dynamic-typing capabilities, additional built-in types such as variable-length arrays and key-value maps, and a large standard library.
+
+Go (a.k.a., Golang) is a programming language first developed at Google. It is a
+statically-typed language with syntax loosely derived from C, but with
+additional features such as garbage collection, type safety, some dynamic-typing
+capabilities, additional built-in types (e.g., variable-length arrays and
+key-value maps), and a large standard library.
 
 > [wikipedia.org/wiki/Go_(programming_language)](http://en.wikipedia.org/wiki/Go_(programming_language))
 
 # How to use this image
 
-## Start a go instance running in your app.
+## Start a Go instance in your app
 
-For this image, the most straight-forward use is to use a golang container as both the build environment as well as the runtime environment. In your Dockerfile, you can do something along the lines of the following will compile and run your project.
+The most straightforward way to use this image is to use a Go container as both
+the build and runtime environment. In your `Dockerfile`, writing something along
+the lines of the following will compile and run your project:
 
-    FROM golang:1.3-onbuild
+    FROM golang:1.3.1-onbuild
     CMD ["./myapp"]
 
-This image includes multiple `ONBUILD` triggers so that should be all that you need for most applications. The build will `COPY . /usr/src/app`, `RUN go get -d -v`, and `RUN go build -v`.
+This image includes multiple `ONBUILD` triggers which should cover most
+applications. The build will `COPY . /usr/src/app`, `RUN go get -d -v`, and `RUN
+go build -v`.
 
-Then run and build the docker image.
+You can then run and build the Docker image:
 
     docker build -t my-golang-app
     docker run -it --rm --name my-running-app my-golang-app
 
-## Compile your app inside the docker container.
+## Compile your app inside the Docker container
 
-It is not always appropriate to run your app inside a container. In instances where you only want to compile inside the docker instance, you can do something along the lines of the following.
+There may be occasions where it is not appropriate to run your app inside a
+container. To compile, but not run your app inside the Docker instance, you can
+write something like:
 
-    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp golang:1.3 go build -v
+    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp golang:1.3.1 go build -v
 
-This will add your current directory as a volume to the container, set the working directory to the volume, and run the command `go build` which will tell go to compile the project in the working directory and output the executable to myapp. Alternatively, if you have a make file, you can instead run the make command inside your container.
+This will add your current directory as a volume to the container, set the
+working directory to the volume, and run the command `go build` which will tell
+go to compile the project in the working directory and output the executable to
+`myapp`. Alternatively, if you have a `Makefile`, you can run the `make` command
+inside your container.
 
-    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp golang:1.3 make
+    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp golang:1.3.1 make
 
-## Cross-compile your app inside the docker container.
+## Cross-compile your app inside the Docker container
 
-If you need to compile your application for a platform other than `linux/amd64` (like `windows/386`, for example), the provided `cross` tags can be used to accomplish this with minimal friction:
+If you need to compile your application for a platform other than `linux/amd64`
+(such as `windows/386`), this can be easily accomplished with the provided
+`cross` tags:
 
-    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp -e GOOS=windows -e GOARCH=386 golang:1.3-cross go build -v
+    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp -e GOOS=windows -e GOARCH=386 golang:1.3.1-cross go build -v
 
-Alternatively, build for multiple platforms at once:
+Alternatively, you can build for multiple platforms at once:
 
-    docker run --rm -it -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp golang:1.3-cross bash
+    docker run --rm -it -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp golang:1.3.1-cross bash
     $ for GOOS in darwin linux; do
     >   for GOARCH in 386 amd64; do
     >     go build -v -o myapp-$GOOS-$GOARCH

hylang/README-content.md

@@ -1,25 +1,33 @@
-# What is hylang?
+# What is Hy?
 
-Hy (alternately, Hylang) is a dialect of the Lisp programming language designed to interoperate with Python by translating expressions into Python's abstract syntax tree (AST). Similar to Clojure's mapping of s-expressions onto the JVM, Hy is meant to operate as a transparent Lisp front end to Python's abstract syntax. Hy also allows for Python libraries (include the standard library) to be imported and accessed alongside Hy code with a compilation step, converting the data structure of both into Python's AST.
+Hy (a.k.a., Hylang) is a dialect of the Lisp programming language designed to
+interoperate with Python by translating expressions into Python's abstract
+syntax tree (AST). Similar to Clojure's mapping of s-expressions onto the JVM,
+Hy is meant to operate as a transparent Lisp front end to Python's abstract
+syntax. Hy also allows for Python libraries (including the standard library) to
+be imported and accessed alongside Hy code with a compilation step, converting
+the data structure of both into Python's AST.
 
-> [hy.readthedocs.org/en/latest/](http://hy.readthedocs.org/en/latest/)
+> [wikipedia.org/wiki/Hy](https://en.wikipedia.org/wiki/Hy)
 
 # How to use this image
 
-## Create a `Dockerfile` in your hylang project.
+## Create a `Dockerfile` in your Hy project
 
-    FROM hylang:0.10.0
+    FROM hylang:0.10
     COPY . /usr/src/myapp
     WORKDIR /usr/src/myapp
     CMD [ "hy", "./your-daemon-or-script.hy" ]
 
-Then build and run the docker image.
+You can then build and run the Docker image:
 
     docker build -t my-hylang-app
     docker run -it --rm --name my-running-app my-hylang-app
 
-## Run a single hylang script.
+## Run a single Hy script
 
-For many single file projects, it may not be convenient to write a `Dockerfile` for your project. In such cases, you can run a hylang script by using the hylang docker image directly.
+For many simple, single file projects, you may find it inconvenient to write a
+complete `Dockerfile`. In such cases, you can run a Hy script by using the Hy
+Docker image directly:
 
-    docker run -it --rm --name my-running-script -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp hylang:0.10.0 hy your-daemon-or-script.hy
+    docker run -it --rm --name my-running-script -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp hylang:0.10 hy your-daemon-or-script.hy

java/README-content.md

@@ -1,34 +1,42 @@
 # What is Java?
 
-Java is a concurrent, class-based, object-oriented language specifically designed to have as few implementation dependencies as possible. It is intended to allow application developers to "write once, run anywhere", meaning that code that runs on one platform does not need to be recompiled to run on another.
+Java is a concurrent, class-based, object-oriented language specifically
+designed to have as few implementation dependencies as possible. It is intended
+to allow application developers to "write once, run anywhere", meaning that code
+that runs on one platform does not need to be recompiled to run on another.
 
 Java is a registered trademark of Oracle and/or its affiliates.
 
 > [wikipedia.org/wiki/Java_(programming_language)](http://en.wikipedia.org/wiki/Java_(programming_language))
 
 # How to use this image
 
-## Start a java instance running your app
+## Start a Java instance in your app
 
-For this image, the most straight-forward use is to use a java container as both the build environment as well as the runtime environment. In your Dockerfile, you can do something along the lines of the following will compile and run your project.
+The most straightforward way to use this image is to use a Java container as
+both the build and runtime environment. In your `Dockerfile`, writing something
+along the lines of the following will compile and run your project:
 
     FROM java:7
     COPY . /usr/src/myapp
     WORKDIR /usr/src/myapp
     RUN javac Main.java
     CMD ["java", "Main"]
 
-Then run the commands to build and run the docker image.
+You can then run and build the Docker image:
 
     docker build -t my-java-app .
     docker run -it --rm --name my-running-app my-java-app
 
-## Compile your app inside the docker container.
+## Compile your app inside the Docker container
 
-It is not always appropriate to run your app inside a container. In instances where you only want to compile inside the docker instance, you can do something along the lines of the following.
+There may be occasions where it is not appropriate to run your app inside a
+container. To compile, but not run your app inside the Docker instance, you can
+write something like:
 
     docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp java:7 javac Main.java
 
-This will add your current directory as a volume to the container, set the working directory to the volume, and run the command `javac Main.java` which will tell java to compile the code in Main.java and output the java class file to Main.class. Alternatively, if you have a make file, you can instead run the make command inside your container.
-
-    docker run --rm -v "$(pwd)":/usr/src/myapp -w /usr/src/myapp java:7 make
+This will add your current directory as a volume to the container, set the
+working directory to the volume, and run the command `javac Main.java` which
+will tell Java to compile the code in `Main.java` and output the Java class file
+to `Main.class`.