From d1a2cdfc4cfdf608d3062a2eff2a76869be987df Mon Sep 17 00:00:00 2001 From: lararennie Date: Thu, 23 Mar 2017 10:05:59 +0100 Subject: [PATCH] Adding a FAQ about the metadata-lite files (#1655) Linking to FAQ from the README, and updating broken links in the two files while here. --- FAQ.md | 63 ++++++++++++++++++++++++++++++++++++------------------- README.md | 27 ++++++++++++++++-------- 2 files changed, 59 insertions(+), 31 deletions(-) diff --git a/FAQ.md b/FAQ.md index ba99a7766..8345e6eb6 100644 --- a/FAQ.md +++ b/FAQ.md @@ -23,17 +23,14 @@ indicate this to the library. To understand the behavior of functions, please refer to the documentation in the Javadoc/C++ header files. For example, see `isPossibleNumberWithReason` in -[`PhoneNumberUtil`] -(https://github.com/googlei18n/libphonenumber/blob/master/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java). +[`PhoneNumberUtil`](https://github.com/googlei18n/libphonenumber/blob/master/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java). ### Why does PhoneNumberUtil return false for valid short numbers? Short numbers are out of scope of -[`PhoneNumberUtil`] -(https://github.com/googlei18n/libphonenumber/blob/master/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java). +[`PhoneNumberUtil`](https://github.com/googlei18n/libphonenumber/blob/master/java/libphonenumber/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java). For short numbers, use -[`ShortNumberInfo`] -(https://github.com/googlei18n/libphonenumber/blob/master/java/libphonenumber/src/com/google/i18n/phonenumbers/ShortNumberInfo.java). +[`ShortNumberInfo`](https://github.com/googlei18n/libphonenumber/blob/master/java/libphonenumber/src/com/google/i18n/phonenumbers/ShortNumberInfo.java). ### What does it mean for a phone number to be valid? @@ -45,7 +42,7 @@ which numbers can be freely assigned by carriers to users. Do not rely on libphonenumber to determine whether numbers are currently assigned to a specific user and reachable. Some products (e.g. -[Google 2-step verification] (https://www.google.com/landing/2step/)) do +[Google 2-step verification](https://www.google.com/landing/2step/)) do this with a verification step e.g. by sending an SMS or placing an automated phone call with a verification code). This is not technically feasible without such a verification step given the complicated international world we live in, @@ -117,24 +114,22 @@ a number in an advert, etc. We don't think the lack of M2M support hinders any of those use-case, but we might be wrong. If you would like libphonenumber to support M2M numbers, please engage with the -developer community at [Support M2M numbers #680] -(https://github.com/googlei18n/libphonenumber/issues/680) with further -information to address our questions and concerns and please describe what kinds -of use-cases fail because M2M numbers are not supported by the library. +developer community at [Support M2M numbers #680]( +https://github.com/googlei18n/libphonenumber/issues/680) with further +information to address our questions and concerns and please describe what +kinds of use-cases fail because M2M numbers are not supported by the library. More information on this issue would be very welcomed! -Related issues: [Support M2M numbers #680] -(https://github.com/googlei18n/libphonenumber/issues/680), -[#930: JTGlobal - an MNO based in the UK] -(https://github.com/googlei18n/libphonenumber/issues/930), [#976: Norway] -(https://github.com/googlei18n/libphonenumber/issues/976), [#985: South Africa, -Vodacom](https://github.com/googlei18n/libphonenumber/issues/985), [#910: -Sweden](https://github.com/googlei18n/libphonenumber/issues/910), [#657: -Canada](https://github.com/googlei18n/libphonenumber/issues/657), [#550: -Belgium](https://github.com/googlei18n/libphonenumber/issues/550), [#351: -Norway](https://github.com/googlei18n/libphonenumber/issues/351), [#332: -Netherlands](https://github.com/googlei18n/libphonenumber/issues/332) +Related issues: [Support M2M numbers #680](https://github.com/googlei18n/libphonenumber/issues/680), +[#930: JTGlobal - an MNO based in the UK](https://github.com/googlei18n/libphonenumber/issues/930), +[#976: Norway](https://github.com/googlei18n/libphonenumber/issues/976), +[#985: South Africa, Vodacom](https://github.com/googlei18n/libphonenumber/issues/985), +[#910: Sweden](https://github.com/googlei18n/libphonenumber/issues/910), +[#657: Canada](https://github.com/googlei18n/libphonenumber/issues/657), +[#550: Belgium](https://github.com/googlei18n/libphonenumber/issues/550), +[#351: Norway](https://github.com/googlei18n/libphonenumber/issues/351), +[#332: Netherlands](https://github.com/googlei18n/libphonenumber/issues/332) ## Representation @@ -235,6 +230,30 @@ We only support a country if: ## Misc +### What is the metadatalite.js/METADATA_LITE option? + +For JavaScript, Java and C++ there is the option to use a stripped-down version +of the metadata. Currently this only removes the example number metadata, so the +savings are not a lot, but we may revisit this. + +*Impact:* + - `getExampleNumber`, `getInvalidExampleNumber`, `getExampleNumberForType`, + `getExampleNumberForNonGeoEntity` will return `null` + - Binary size (or download size for JS) will be slightly smaller + +*JS:* +Simply include metadatalite.js instead of metadata.js in your project. + +*C++:* +Set the compiler flag `USE_METADATA_LITE` to `ON` using ccmake or similar. + +*Java:* +The metadata binary files can be generated using the ant build rules +`build-phone-metadata` and `build-short-metadata` with `lite-build` set to +`true`. This can be set in the [build +file](https://github.com/googlei18n/libphonenumber/blob/master/java/build.xml) +itself. + ### How do I load libphonenumber resources in my Android app? #### System considerations diff --git a/README.md b/README.md index 109ddb6bd..734706777 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,17 @@

+ # What is it? -Google's common Java, C++ and JavaScript library for parsing, formatting, and 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). +Google's common Java, C++ and JavaScript library for parsing, formatting, and +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] (https://github.com/googlei18n/libphonenumber/blob/master/CONTRIBUTING.md) first. +If you want to report an issue, or to contribute to the project, please read +the guidelines [here](CONTRIBUTING.md) first. # Highlights of functionality * Parsing/formatting/validating phone numbers for all countries/regions of the world. @@ -26,7 +31,8 @@ If you want to report an issue, or to contribute to the project, please read the [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: +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/ @@ -34,6 +40,10 @@ http://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/ [Latest release](https://javadoc.io/doc/com.googlecode.libphonenumber/libphonenumber/) +# FAQ + +See the [FAQ](FAQ.md) for common questions and tips. + # Versioning and Announcements We generally choose the release number following these guidelines. @@ -48,8 +58,7 @@ If any of those changes *enable* clients to update their code to take advantage of new functionality, we publish a minor release. So we'd go from 7.7.3 to 7.8.0. -Otherwise, including when a release contains only [metadata] -(http://github.com/googlei18n/libphonenumber/blob/master/FAQ.md#metadata_definition) +Otherwise, including when a release contains only [metadata](FAQ.md#metadata_definition) changes, we publish a sub-minor release, e.g. 7.7.3 to 7.7.4. Sometimes we make internal changes to the code or metadata that, while not @@ -63,10 +72,10 @@ release if there were no other changes. Want to get notified of new releases? During most of the year, excepting holidays and extenuating circumstances, we release fortnightly. We update [release tags](http://github.com/googlei18n/libphonenumber/releases) and -document detailed [release notes] -(http://github.com/googlei18n/libphonenumber/blob/master/release_notes.txt). -We also send an announcement to [libphonenumber-discuss] -(http://groups.google.com/forum/#!forum/libphonenumber-discuss) for every +document detailed [release notes]( +http://github.com/googlei18n/libphonenumber/blob/master/release_notes.txt). +We also send an announcement to [libphonenumber-discuss]( +http://groups.google.com/forum/#!forum/libphonenumber-discuss) for every release. # Quick Examples