Merge branch 'master' of https://github.com/microsoft/vcpkg into dev/philc/3425

4 files changed, 69 insertions, 10 deletions

diff --git a/docs/examples/using-sqlite.md b/docs/examples/installing-and-using-packages.md
index d12695bfb..50200c877 100644
--- a/docs/examples/using-sqlite.md
+++ b/docs/examples/installing-and-using-packages.md
@@ -1,4 +1,4 @@
-# Example: Using Sqlite
+## Installing and Using Packages Example: SQLite
 
   - [Step 1: Install](#install)
   - [Step 2: Use](#use)
@@ -10,7 +10,7 @@
 <a name="install"></a>
 ## Step 1: Install
 
-First, we need to know what name [Sqlite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output:
+First, we need to know what name [SQLite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output:
 ```no-highlight
 PS D:\src\vcpkg> .\vcpkg search sqlite
 libodb-sqlite        2.4.0            Sqlite support for the ODB ORM library
@@ -71,7 +71,7 @@ See `.\vcpkg help triplet` for all supported targets.
 <a name="msbuild"></a>
 #### VS/MSBuild Project (User-wide integration)
 
-The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwords is no longer required and the integration is configured on a per-user basis.
+The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwards is no longer required and the integration is configured on a per-user basis.
 ```no-highlight
 PS D:\src\vcpkg> .\vcpkg integrate install
 Applied user-wide integration for this vcpkg root.
@@ -82,7 +82,7 @@ Installing new libraries will make them instantly available.
 ```
 *Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.* 
 
-You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 and the library will be automatically available. For Sqlite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html).
+You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 and the library will be automatically available. For SQLite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html).
 
 To remove the integration for your user, you can use `.\vcpkg integrate remove`.
 
diff --git a/docs/examples/packaging-github-repos.md b/docs/examples/packaging-github-repos.md
new file mode 100644
index 000000000..af2e6141a
--- /dev/null
+++ b/docs/examples/packaging-github-repos.md
@@ -0,0 +1,59 @@
+## Packaging Github Repos Example: libogg

+### Create the CONTROL file

+The `CONTROL` file is a simple set of fields describing the package's metadata.

+

+*For libogg, we'll create the file `ports\libogg\CONTROL` with the following contents:*

+```no-highlight

+Source: libogg

+Version: 1.3.3

+Description: Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs.

+```

+

+### Create the portfile

+`portfile.cmake` describes how to build and install the package. First we include `vcpkg_common_functions` to give us utilities for carrying this out:

+

+```no-highlight

+include(vcpkg_common_functions)

+```

+

+Now we download the project from Github with [`vcpkg_from_github`](../maintainers/vcpkg_from_github.md):

+

+```no-highlight

+vcpkg_from_github(

+    OUT_SOURCE_PATH SOURCE_PATH

+    REPO xiph/ogg

+    REF v1.3.3

+    SHA512 0bd6095d647530d4cb1f509eb5e99965a25cc3dd9b8125b93abd6b248255c890cf20710154bdec40568478eb5c4cde724abfb2eff1f3a04e63acef0fbbc9799b

+    HEAD_REF master

+)

+```

+

+The important parts to update are `REPO` for the GitHub repository path, `REF` for a stable tag/commit to use, and `SHA512` with the checksum of the downloaded zipfile (you can get this easily by setting it to `1`, trying to install the package, and copying the checksum).

+

+Finally, we configure the project with CMake, install the package, and copy over the license file:

+

+```no-highlight

+vcpkg_configure_cmake(

+    SOURCE_PATH ${SOURCE_PATH}

+    PREFER_NINJA

+)

+vcpkg_install_cmake()

+file(INSTALL ${SOURCE_PATH}/COPYING DESTINATION ${CURRENT_PACKAGES_DIR}/share/libogg RENAME copyright)

+```

+

+Check the documentation for [`vcpkg_configure_cmake`](../maintainers/vcpkg_configure_cmake.md) and [`vcpkg_install_cmake`](../maintainers/vcpkg_install_cmake.md) if your package needs additional options. 

+

+Now you can run `vcpkg install libogg` to build and install the package.

+

+### Suggested example portfiles

+In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake.

+

+- Header only libraries

+    - rapidjson

+    - range-v3

+- MSBuild-based

+    - cppunit

+    - mpg123

+- Non-CMake, custom buildsystem

+    - openssl

+    - ffmpeg

diff --git a/docs/examples/packaging-zlib.md b/docs/examples/packaging-zipfiles.md
index ce176d451..ed63637fd 100644
--- a/docs/examples/packaging-zlib.md
+++ b/docs/examples/packaging-zipfiles.md
@@ -1,9 +1,9 @@
-## Example 2: Packaging zlib
+## Packaging Zipfiles Example: zlib
 
 ### Bootstrap with `create`
 First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors.
 
-*Looking at zlib's website, the URL http://zlib.net/zlib128.zip looks appropriate.*
+*Looking at zlib's website, the URL http://zlib.net/zlib1211.zip looks appropriate.*
 
 Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name.
 
@@ -11,7 +11,7 @@ Second, determine a suitable package name. This should be ASCII, lowercase, and
 
 Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `<packagename>-<version>.zip`.
 
-*`zlib128.zip` is a fine name, so no change needed.*
+*`zlib1211.zip` is a fine name, so no change needed.*
 
 All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports\<packagename>`.
 
@@ -21,12 +21,12 @@ PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib-1.
 ```
 
 ### Create the CONTROL file
-In addition to the generated `ports\<package>\portfile.cmake`, we also need a `ports\<package>\CONTROL` file. This file is a simply formatted set of fields describing the package's metadata.
+In addition to the generated `ports\<package>\portfile.cmake`, we also need a `ports\<package>\CONTROL` file. This file is a simple set of fields describing the package's metadata.
 
 *For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:*
 ```no-highlight
 Source: zlib2
-Version: 1.2.8
+Version: 1.2.11
 Description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library
 ```
 
diff --git a/docs/examples/patching-libpng.md b/docs/examples/patching.md
index 2337b73da..98115400e 100644
--- a/docs/examples/patching-libpng.md
+++ b/docs/examples/patching.md
@@ -1,4 +1,4 @@
-## Example 3: Patching libpng to work for x86-uwp
+## Patching Example: Patching libpng to work for x86-uwp
 
 ### Initial error logs
 First, try building: