Clarify the purpose of Makefile (#232)

README.md

@@ -1,12 +1,11 @@
 # Google APIs
 
-This repository contains the original interface definitions for a
-small (but growing) set of Google APIs built on a next-generation API
-serving stack. Reading the original interface definitions can provide
-a better understanding of these APIs and help you to utilize them more
-efficiently. You can also use these interface definitions with open
-source tools to generate client libraries or other artifacts such as
-documentation.
+This repository contains the original interface definitions of public
+Google APIs that support both REST and gRPC protocols. Reading the
+original interface definitions can provide a better understanding of
+Google APIs and help you to utilize them more efficiently. You can also
+use these definitions with open source tools to generate client
+libraries, documentation, and other artifacts.
 
 For more details on all Google APIs and developer tools, see the [Google
 Developers](https://developers.google.com/products/) site.
@@ -15,21 +14,20 @@ Developers](https://developers.google.com/products/) site.
 
 Google APIs are typically deployed as API services that are hosted
 under different DNS names. One API service may implement multiple APIs
-and multiple versions of the same API, and each API contains a
-collection of API methods.
-
-By default, Google APIs use [Protocol
-Buffers](https://github.com/google/protobuf) language version 3 - aka
-proto3 - as their Interface Definition Language (IDL) to define the
-API interface and the structure of the payload messages. The same
-interface definition is used for both REST and RPC versions of the
+and multiple versions of the same API.
+
+Google APIs use [Protocol Buffers](https://github.com/google/protobuf)
+version 3 (proto3) as their Interface Definition Language (IDL) to
+define the API interface and the structure of the payload messages. The
+same interface definition is used for both REST and RPC versions of the
 API, which can be accessed over different wire protocols.
 
 There are two ways of accessing Google APIs:
 
-1.  JSON over HTTP/1.1: You can access Google APIs directly using JSON
-over HTTP/1.1, using Google-provided API or third-party API client
-libraries.
+1.  JSON over HTTP: You can access Google APIs directly using JSON
+over HTTP, using
+[Google API client libraries](https://developers.google.com/api-client-libraries)
+or third-party API client libraries.
 
 2.  Protocol Buffers over gRPC: You can access Google APIs published
 in this repository through [GRPC](https://github.com/grpc), which is
@@ -39,8 +37,8 @@ streaming.
 
 ## Discussions
 
-You may use the [Google APIs](https://groups.google.com/group/googleapis)
-mailing list for general discussions about this repository.
+Please use GitHub Issues to discuss bugs and features related to this
+repository.
 
 ## Repository Structure
 
@@ -53,19 +51,23 @@ client libraries have idiomatic namespaces in most programming
 languages. Alongside the API directories live the configuration files
 for the [GAPIC toolkit](https://github.com/googleapis/toolkit).
 
-**NOTE:** the major version of an API is used to indicate breaking
+**NOTE:** The major version of an API is used to indicate breaking
 change to the API.
 
 ## Generate gRPC Source Code
 
 To generate gRPC source code for Google APIs in this repository, you
 first need to install both Protocol Buffers and gRPC on your local
-machine. Then you can run `make all` in this directory to generate
-the code.
+machine, then you can run `make LANGUAGE=xxx all` to generate the
+source code. You need to integrated the generated source code into
+your application build system.
+
+**NOTE:** The Makefile is only intended to generate source code for the
+entire repository. It is not for generating linkable client library
+for a specific API. Please see other repositories under
+https://github.com/googleapis for generating linkable client libraries.
 
 ### Go gRPC Source Code
 It is difficult to generate Go gRPC source code from this repository,
 since Go has different directory structure.
 Please use [this repository](https://github.com/google/go-genproto) instead.
-
-**NOTE:** The Makefile needs more improvements.