protoc-gen-go: add paths=source_relative option

README.md

@@ -7,7 +7,7 @@ Google's data interchange format.
 Copyright 2010 The Go Authors.
 https://github.com/golang/protobuf
 
-This package and the code it generates requires at least Go 1.4.
+This package and the code it generates requires at least Go 1.6.
 
 This software implements Go bindings for protocol buffers.  For
 information about protocol buffers themselves, see
@@ -56,13 +56,49 @@ parameter set to the directory you want to output the Go code to.
 The generated files will be suffixed .pb.go.  See the Test code below
 for an example using such a file.
 
+## Packages and input paths ##
+
+The protocol buffer language has a concept of "packages" which does not
+correspond well to the Go notion of packages. In generated Go code,
+each source `.proto` file is associated with a single Go package. The
+name and import path for this package is specified with the `go_package`
+proto option:
+
+	option go_package = "github.com/golang/protobuf/ptypes/any";
+
+The protocol buffer compiler will attempt to derive a package name and
+import path if a `go_package` option is not present, but it is
+best to always specify one explicitly.
+
+There is a one-to-one relationship between source `.proto` files and
+generated `.pb.go` files, but any number of `.pb.go` files may be
+contained in the same Go package.
+
+The output name of a generated file is produced by replacing the
+`.proto` suffix with `.pb.go` (e.g., `foo.proto` produces `foo.pb.go`).
+However, the output directory is selected in one of two ways.  Let
+us say we have `inputs/x.proto` with a `go_package` option of
+`github.com/golang/protobuf/p`. The corresponding output file may
+be:
+
+- Relative to the import path:
+
+	protoc --go_out=. inputs/x.proto
+	# writes ./github.com/golang/protobuf/p/x.pb.go
+
+  (This can work well with `--go_out=$GOPATH`.)
+
+- Relative to the input file:
+
+	protoc --go_out=paths=source_relative:. inputs/x.proto
+	# generate ./inputs/x.pb.go
+
+## Generated code ##
 
 The package comment for the proto library contains text describing
 the interface provided in Go for protocol buffers. Here is an edited
 version.
 
-==========
-
 The proto package converts data structures to and from the
 wire format of protocol buffers.  It works in concert with the
 Go source code generated for .proto files by the protocol compiler.
@@ -170,22 +206,25 @@ To create and play with a Test object from the example package,
 To pass extra parameters to the plugin, use a comma-separated
 parameter list separated from the output directory by a colon:
 
-
 	protoc --go_out=plugins=grpc,import_path=mypackage:. *.proto
 
-
-- `import_prefix=xxx` - a prefix that is added onto the beginning of
-  all imports. Useful for things like generating protos in a
-  subdirectory, or regenerating vendored protobufs in-place.
-- `import_path=foo/bar` - used as the package if no input files
-  declare `go_package`. If it contains slashes, everything up to the
-  rightmost slash is ignored.
+- `paths=(import | source_relative)` - specifies how the paths of
+  generated files are structured. See the "Packages and imports paths"
+  section above.
 - `plugins=plugin1+plugin2` - specifies the list of sub-plugins to
   load. The only plugin in this repo is `grpc`.
 - `Mfoo/bar.proto=quux/shme` - declares that foo/bar.proto is
   associated with Go package quux/shme.  This is subject to the
   import_prefix parameter.
 
+The following parameters are deprecated and should not be used:
+
+- `import_prefix=xxx` - a prefix that is added onto the beginning of
+  all imports.
+- `import_path=foo/bar` - used as the package if no input files
+  declare `go_package`. If it contains slashes, everything up to the
+  rightmost slash is ignored.
+
 ## gRPC Support ##
 
 If a proto file specifies RPC services, protoc-gen-go can be instructed to