Move repo-owned wiki pages to source tree and add quick links to main page + reorganize it (#1853)

README.md

@@ -9,41 +9,75 @@ validating international phone numbers. The Java version is optimized for
 running on smartphones, and is used by the Android framework since 4.0 (Ice
 Cream Sandwich).
 
-# Want to report an issue?
-If you want to report an issue, or to contribute to the project, please read
-the guidelines [here](CONTRIBUTING.md) first.
+# Quick links
+
+*   Reporting an issue? Want to send a pull request? See the [contribution
+    guidelines](CONTRIBUTING.md)
+*   Check the [frequently asked questions](FAQ.md)
+*   Fun! [Falsehoods Programmers Believe About Phone Numbers](FALSEHOODS.md)
+*   Look for
+    [`README`s](http://github.com/googlei18n/libphonenumber/find/master) in
+    directories relevant to the code you're interested in.
+*   For contributors and porters: [How to run the Java demo](run-java-demo.md)
+*   For porters: [How to make metadata changes](making-metadata-changes.md)
 
 # Highlights of functionality
-  * Parsing/formatting/validating phone numbers for all countries/regions of the world.
-  * ` getNumberType ` - gets the type of the number based on the number itself; able to distinguish Fixed-line, Mobile, Toll-free, Premium Rate, Shared Cost, VoIP and Personal Numbers  (whenever feasible).
-  * ` isNumberMatch ` - gets a confidence level on whether two numbers could be the same.
-  * ` getExampleNumber `/` getExampleNumberByType ` - provides valid example numbers for all countries/regions, with the option of specifying which type of example phone number is needed.
-  * ` isPossibleNumber ` - quickly guessing whether a number is a possible phonenumber by using only the length information, much faster than a full validation.
-  * ` isValidNumber ` - full validation of a phone number for a region using length and prefix information.
-  * ` AsYouTypeFormatter ` - formats phone numbers on-the-fly when users enter each digit.
-  * ` findNumbers ` - finds numbers in text input.
-  * ` PhoneNumberOfflineGeocoder ` - provides geographical information related to a phone number.
-  * ` PhoneNumberToCarrierMapper ` - provides carrier information related to a phone number.
-  * ` PhoneNumberToTimeZonesMapper ` - provides timezone information related to a phone number.
 
-# Demo (v8.6.0)
-[Java](http://libphonenumber.appspot.com/)
-
-[JavaScript](https://rawgit.com/googlei18n/libphonenumber/master/javascript/i18n/phonenumbers/demo-compiled.html)
-
-# Code
-To include the code in your application, either integrate with Maven or
-download the latest Jars from the Maven repository:
-
-http://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/
+*   Parsing, formatting, and validating phone numbers for all countries/regions
+    of the world.
+*   `getNumberType` - gets the type of the number based on the number itself;
+    able to distinguish Fixed-line, Mobile, Toll-free, Premium Rate, Shared
+    Cost, VoIP, Personal Numbers, UAN, Pager, and Voicemail (whenever feasible).
+*   `isNumberMatch` - gets a confidence level on whether two numbers could be
+    the same.
+*   `getExampleNumber` and `getExampleNumberByType` - provide valid example
+    numbers for all countries/regions, with the option of specifying which type
+    of example phone number is needed.
+*   `isPossibleNumber` - quickly guesses whether a number is a possible
+    phone number by using only the length information, much faster than a full
+    validation.
+*   `isValidNumber` - full validation of a phone number for a region using
+    length and prefix information.
+*   `AsYouTypeFormatter` - formats phone numbers on-the-fly when users enter
+    each digit.
+*   `findNumbers` - finds numbers in text.
+*   `PhoneNumberOfflineGeocoder` - provides geographical information related to
+    a phone number.
+*   `PhoneNumberToCarrierMapper` - provides carrier information related to a
+    phone number.
+*   `PhoneNumberToTimeZonesMapper` - provides timezone information related to a
+    phone number.
+
+# Demo
+
+## Java
+
+The [Java demo](http://libphonenumber.appspot.com/) is updated with a slight
+delay after the GitHub release.
+
+Last demo update: v8.6.0.
+
+If this number is lower than the [latest release's version
+number](http://github.com/googlei18n/libphonenumber/releases), we are between
+releases and the demo may be at either version.
+
+## JavaScript
+
+The [JavaScript
+demo](http://rawgit.com/googlei18n/libphonenumber/master/javascript/i18n/phonenumbers/demo-compiled.html)
+may be run at various tags; this link will take you to `master`.
+
+# Java code
+
+To include the Java code in your application, either integrate with Maven (see
+[wiki](http://github.com/googlei18n/libphonenumber/wiki)) or download the latest
+jars from the [Maven
+repository](http://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/).
 
 # Javadoc
 
-[Latest release](https://javadoc.io/doc/com.googlecode.libphonenumber/libphonenumber/)
-
-# FAQ
-
-See the [FAQ](FAQ.md) for common questions and tips.
+Javadoc is automatically updated to reflect the latest release at
+http://javadoc.io/doc/com.googlecode.libphonenumber/libphonenumber/.
 
 # Versioning and Announcements
 
@@ -82,7 +116,9 @@ http://groups.google.com/forum/#!forum/libphonenumber-discuss) for every
 release.
 
 # Quick Examples
-Let's say you have a string representing a phone number from Switzerland. This is how you parse/normalize it into a ` PhoneNumber ` object:
+
+Let's say you have a string representing a phone number from Switzerland. This
+is how you parse/normalize it into a `PhoneNumber` object:
 
 ```java
 String swissNumberStr = "044 668 18 00";
@@ -94,7 +130,8 @@ try {
 }
 ```
 
-At this point, swissNumberProto contains:
+At this point, `swissNumberProto` contains:
+
 ```json
 {
   "country_code": 41,
@@ -102,14 +139,19 @@ At this point, swissNumberProto contains:
 }
 ```
 
-` PhoneNumber ` is a class that is auto-generated from the phonenumber.proto with necessary modifications for efficiency. For details on the meaning of each field, refer to https://github.com/googlei18n/libphonenumber/blob/master/resources/phonenumber.proto
+`PhoneNumber` is a class that was originally auto-generated from
+`phonenumber.proto` with necessary modifications for efficiency. For details on
+the meaning of each field, refer to `resources/phonenumber.proto`.
 
 Now let us validate whether the number is valid:
+
 ```java
 boolean isValid = phoneUtil.isValidNumber(swissNumberProto); // returns true
 ```
 
-There are a few formats supported by the formatting method, as illustrated below:
+There are a few formats supported by the formatting method, as illustrated
+below:
+
 ```java
 // Produces "+41 44 668 18 00"
 System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.INTERNATIONAL));
@@ -119,14 +161,16 @@ System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.NATIONAL
 System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.E164));
 ```
 
-You could also choose to format the number in the way it is dialed from another country:
+You could also choose to format the number in the way it is dialed from another
+country:
 
 ```java
 // Produces "011 41 44 668 1800", the number when it is dialed in the United States.
 System.out.println(phoneUtil.formatOutOfCountryCallingNumber(swissNumberProto, "US"));
 ```
 
-### Formatting Phone Numbers 'as you type'
+## Formatting Phone Numbers 'as you type'
+
 ```java
 PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance();
 AsYouTypeFormatter formatter = phoneUtil.getAsYouTypeFormatter("US");
@@ -135,7 +179,8 @@ System.out.println(formatter.inputDigit('6'));  // Outputs "6"
 System.out.println(formatter.inputDigit('3'));  // Now outputs "650 253"
 ```
 
-### Geocoding Phone Numbers offline
+## Geocoding Phone Numbers
+
 ```java
 PhoneNumberOfflineGeocoder geocoder = PhoneNumberOfflineGeocoder.getInstance();
 // Outputs "Zurich"
@@ -146,7 +191,12 @@ System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.GER
 System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ITALIAN));
 ```
 
-### Mapping Phone Numbers to carrier
+## Mapping Phone Numbers to original carriers
+
+Caveat: We do not provide data about the current carrier of a phone number, only
+the original carrier who is assigned the corresponding range. Read about [number
+portability](FAQ.md#what-is-mobile-number-portability).
+
 ```java
 PhoneNumber swissMobileNumber =
     new PhoneNumber().setCountryCode(41).setNationalNumber(798765432L);
@@ -155,11 +205,8 @@ PhoneNumberToCarrierMapper carrierMapper = PhoneNumberToCarrierMapper.getInstanc
 System.out.println(carrierMapper.getNameForNumber(swissMobileNumber, Locale.ENGLISH));
 ```
 
-
----
-
-
-More examples on how to use the library can be found in the unittests at https://github.com/googlei18n/libphonenumber/tree/master/java/libphonenumber/test/com/google/i18n/phonenumbers
+More examples on how to use the library can be found in the [unit
+tests](http://github.com/googlei18n/libphonenumber/tree/master/java/libphonenumber/test/com/google/i18n/phonenumbers).
 
 # Third-party Ports
 
@@ -175,7 +222,7 @@ maintenance processes.
     there are several other options, including
     https://github.com/halt-hammerzeit/libphonenumber-js (a stripped-down
     rewrite, about 110 KB in size) and https://github.com/seegno/google-libphonenumber
-    (a browserify-compatible wrapper around the original unmodified library 
+    (a browserify-compatible wrapper around the original unmodified library
     installable via npm, packs Google Closure library, about 420 KB in size)
 *   Objective-c: https://github.com/iziz/libPhoneNumber-iOS
 *   PHP: https://github.com/giggsey/libphonenumber-for-php

making-metadata-changes.md

@@ -0,0 +1,86 @@
+# How to make metadata changes
+
+## Introduction
+
+These steps outline how to edit the metadata for the phone number library to fix
+problems with validation or formatting.
+
+Note that we are currently not accepting validation, formatting, or timezone
+metadata pull requests, but you may use these guidelines to create changes in
+your own fork until we fix issues upstream. Please [file a corresponding
+issue](CONTRIBUTING.md#checklist-before-filing-an-issue) with us.
+
+You can read more about the pull request [contribution
+guidelines](CONTRIBUTING.md#pull-requests).
+
+## Details
+
+### Edit the data
+
+Edit the appropriate files:
+
+*   `resources/PhoneNumberMetadata.xml` for normal validation / formatting
+    issues
+*   `resources/ShortNumberMetadata.xml` for short-code data
+*   `resources/PhoneNumberAlternateFormats.xml` for alternate patterns for phone
+    number matching
+*   `resources/geocoding/xx` for geocoding data (where `xx` is the language code
+    you wish to edit)
+*   `resources/carrier/xx` for carrier mapping data
+
+Note:
+
+*   To track provenance for your own maintenance needs, consider including
+    sources for data where appropriate
+*   If multiple countries share a country calling code, check all of them are
+    updated. Formatting rules will only be listed by the country with
+    `mainCountryForCode` set to `true`.
+*   Details on each field in the xml file can be found at the top of the file
+    and in `resources/phonemetadata.proto`.
+
+### Generate data files
+
+#### Java
+
+```
+ant -f java/build.xml junit
+```
+
+This will generate new binary files under
+`java/libphonenumber/src/com/google/i18n/phonenumbers/data`,
+`geocoder/src/com/google/i18n/phonenumbers/carrier/data`, and
+`geocoder/src/com/google/i18n/phonenumbers/geocoding/data`.
+
+#### Javascript
+
+```
+ant -f java/build.xml build-js-metadata
+```
+
+This will generate new js metadata files; you should also now compile the
+changes, as per the instructions in `javascript/README`.
+
+#### C++
+
+See the [C++
+README](http://github.com/googlei18n/libphonenumber/blob/master/cpp/README)
+instructions for how to build and run C++. You should build it with
+`USE_LITE_METADATA` set to `ON` as well as `OFF`, which will generate both a
+`metadata.cc` and a `metadata_lite.cc` file.
+
+### Test changes
+
+#### Java
+
+Build a jar:
+
+```
+ant -f java/build.xml jar
+```
+
+Then [run your own demo](run-java-demo.md) and test your changes are as
+expected.
+
+#### Javascript
+
+See `javascript/README` for how to run the demo page in your browser.

run-java-demo.md

@@ -0,0 +1,85 @@
+# How to run the Java demo
+
+## About this document
+
+This document explains how to build and run the demo of the Java version of
+libphonenumber, **from the command line** on **Linux** or **Mac**, using Google
+App Engine. By following the instructions here, you can build a demo running
+against any revision of the Java code by supplying jar files you build on your
+own, or downloading the ones from [Maven
+Central](http://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/).
+
+## Detailed steps
+
+### Install Google App Engine
+
+Download and follow [the
+instructions](http://cloud.google.com/appengine/downloads) to install the Java
+SDK of Google App Engine. This document assumes it is named as
+`appengine-java-sdk`. You may want to rename the directory after unpacking.
+
+### Check out the demo code
+
+Check out the Java code:
+
+```
+git clone https://github.com/googlei18n/libphonenumber.git
+```
+
+Create a symlink to your unpacked appengine sdk directory at the same level as
+the `java` directory. Alternatively, update `java/demo/build.xml` to point to
+the right location for the appengine sdk.
+
+### Get the phone number library jars
+
+Save the `libphonenumber`, `geocoder`, `carrier`, and `prefixmapper` jars under
+`demo/war/WEB-INF/lib/`.
+
+You can either download them from the  [Maven
+repository](http://repo1.maven.org/maven2/com/googlecode/libphonenumber/) or
+build them yourself by running:
+
+```
+git clone https://github.com/google/libphonenumber.git
+cd libphonenumber/java
+ant jar
+cp build/jar/* demo/war/WEB-INF/lib
+```
+
+### Run the demo code
+
+Start the server:
+
+```
+cd demo
+ant runserver
+```
+
+This will start a server on your localhost, and you can try it out by pointing
+your browser to http://localhost:8080/.
+
+## Troubleshooting
+
+If you get a warning from App Engine asking you to upgrade your JRE to Java 1.6
+or later, you might need to install Java 1.6 and point your `JAVA_HOME` to it.
+
+*   To see your current `JAVA_HOME`, run `echo $JAVA_HOME`.
+*   To see the list of JDKs currently installed, use `update-java-alternatives
+    -l`.
+*   To reset `JAVA_HOME`, use `export JAVA_HOME=[path to Java 1.6 SDK]/jre`.
+
+Now run `ant runserver` to start the server on your localhost.
+
+## Uploading your own demo App Engine application
+
+If you want to upload the demo to your own App Engine application, follow the
+steps to [register an application with App
+Engine](http://cloud.google.com/appengine/docs/standard/java/gettingstarted/deploying-the-application).
+
+Then run:
+
+```
+../appengine-java-sdk/bin/appcfg.sh update war
+```
+
+The demo will be uploaded to `http://application-id.appspot.com/`.