From 278369152267b79853a9cceaa0390d6c7e1d86b9 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Sat, 4 Feb 2012 07:49:51 +1100 Subject: [PATCH] docs: replace references to gofix etc. with tool invocations R=rsc CC=golang-dev https://golang.org/cl/5630045 --- doc/effective_go.html | 5 +++- doc/effective_go.tmpl | 5 +++- doc/go1.html | 58 ++++++++++++++++++++++--------------------- doc/go1.tmpl | 58 ++++++++++++++++++++++--------------------- doc/install.html | 2 +- src/cmd/nm/doc.go | 3 +-- 6 files changed, 70 insertions(+), 61 deletions(-) diff --git a/doc/effective_go.html b/doc/effective_go.html index 4ecbe19b9f..edaffd733d 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -66,7 +66,10 @@ prescriptive style guide. With Go we take an unusual approach and let the machine take care of most formatting issues. -The gofmt tool reads a Go program +The gofmt program +(also available as go tool fmt, which +operates at the package level rather than source file level) +reads a Go program and emits the source in a standard style of indentation and vertical alignment, retaining and if necessary reformatting comments. diff --git a/doc/effective_go.tmpl b/doc/effective_go.tmpl index 782c7003e7..8875495073 100644 --- a/doc/effective_go.tmpl +++ b/doc/effective_go.tmpl @@ -62,7 +62,10 @@ prescriptive style guide. With Go we take an unusual approach and let the machine take care of most formatting issues. -The gofmt tool reads a Go program +The gofmt program +(also available as go tool fmt, which +operates at the package level rather than source file level) +reads a Go program and emits the source in a standard style of indentation and vertical alignment, retaining and if necessary reformatting comments. diff --git a/doc/go1.html b/doc/go1.html index 38a0faa398..07adb677b0 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -242,10 +242,11 @@ There is no return value. Deleting a non-existent entry is a no-op.

Updating: -Gofix will convert expressions of the form m[k] = ignored, +Running go fix will convert expressions of the form m[k] = ignored, false into delete(m, k) when it is clear that the ignored value can be safely discarded from the program and -false refers to the predefined boolean constant. Gofix +false refers to the predefined boolean constant. +The fix tool will flag other uses of the syntax for inspection by the programmer.

@@ -534,12 +535,12 @@ and template.

Updating: -Gofix will update all imports and package renames for packages that +Running go fix will update all imports and package renames for packages that remain inside the standard repository. Programs that import packages that are no longer in the standard repository will need to be edited by hand.
-TODO: gofix should warn about deletions. +TODO: go fix should warn about deletions.

The package tree exp

@@ -571,16 +572,17 @@ Also, the utf8.String type has been moved to its own package, Finally, the gotype command now resides in exp/gotype, while -ebnflint is now in exp/ebnflint +ebnflint is now in exp/ebnflint. +If they are installed, they now reside in $GOROOT/bin/tool.

Updating: Code that uses packages in exp will need to be updated by hand, or else compiled from an installation that has exp available. -Gofix or the compiler will complain about such uses. +The go fix tool or the compiler will complain about such uses.
-TODO: gofix should warn about such uses. +TODO: go fix should warn about such uses.

The package tree old

@@ -605,9 +607,9 @@ The packages in their new locations are: Updating: Code that uses packages now in old will need to be updated by hand, or else compiled from an installation that has old available. -Gofix will warn about such uses. +The go fix tool will warn about such uses.
-TODO: gofix should warn about such uses. +TODO: go fix should warn about such uses.

Deleted packages

@@ -635,7 +637,7 @@ slices directly. See Language Community Wiki for some suggestions. Code that uses the other packages (there should be almost zero) will need to be rethought.
-TODO: gofix should warn such uses. +TODO: go fix should warn such uses.

Packages moving to subrepositories

@@ -690,7 +692,7 @@ This table lists the old and new import paths:

Updating: -Gofix will update imports of these packages to use the new import paths. +Running go fix will update imports of these packages to use the new import paths. Installations that depend on these packages will need to install them using a go install command.

@@ -755,7 +757,7 @@ to turn a string into an error. It replaces the old os.NewError.

Updating: -Gofix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change. Code that defines error types with a String method will need to be updated by hand to rename the methods to Error.

@@ -774,7 +776,7 @@ that satisfies error and replaces the old os.Errno.

Updating: -Gofix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change. Regardless, most code should use the os package rather than syscall and so will be unaffected.

@@ -842,11 +844,11 @@ its representation of file time stamps.

Updating: -Gofix will update many uses of the old time package to use the new +The go fix tool will update many uses of the old time package to use the new types and methods, although it does not replace values such as 1e9 representing nanoseconds per second. Also, because of type changes in some of the values that arise, -some of the expressions rewritten by gofix may require +some of the expressions rewritten by the fix tool may require further hand editing; in such cases the rewrite will include the correct function or method for the old functionality, but may have the wrong type or require further analysis. @@ -857,7 +859,7 @@ may have the wrong type or require further analysis.

This section describes smaller changes, such as those to less commonly used packages or that affect -few programs beyond the need to run gofix. +few programs beyond the need to run go fix. This category includes packages that are new in Go 1.

@@ -880,7 +882,7 @@ in crypto/elliptic that take an elliptic.Curve as their first argument.

-

The crypto/hmac package

+

The crypto/hmac package

In Go 1, the hash-specific functions, such as hmac.NewMD5, have @@ -890,7 +892,7 @@ a function that returns a hash.Hash, such as md5.New.

Updating: -Gofix will perform the needed changes. +Running go fix will perform the needed changes.

The crypto/x509 package

@@ -1020,7 +1022,7 @@ The previous behavior can be recreated by adding a nil argument to Existing implementations of hash.Hash will need to add a BlockSize method. Hashes that process the input one byte at a time can implement BlockSize to return 1. -Gofix will update calls to the Sum methods of the various +Running go fix will update calls to the Sum methods of the various implementations of hash.Hash.

@@ -1062,7 +1064,7 @@ historical artifact.

Updating: -Gofix will update the few programs that are affected except for +Running go fix will update the few programs that are affected except for uses of RawURL, which must be fixed by hand.

@@ -1181,7 +1183,7 @@ and

Updating: -Gofix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change.

The mime package

@@ -1227,7 +1229,7 @@ The net.ListenMulticastUDP function replaces the old

Updating: Code that uses the old methods will fail to compile and must be updated by hand. -The semantic change makes it difficult for gofix to update automatically. +The semantic change makes it difficult for the fix tool to update automatically.

The os.FileInfo type

@@ -1299,7 +1301,7 @@ of the standard interface.

Updating: -Gofix will update code that uses the old equivalent of the current os.FileInfo +Running go fix will update code that uses the old equivalent of the current os.FileInfo and os.FileMode API. Code that needs system-specific file details will need to be updated by hand.

@@ -1438,11 +1440,11 @@ for full details.

Updating: -Gofix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change.
§ Atoi persists but Atoui and Atof32 do not, so they may require -a cast that must be added by hand; gofix will warn about it. +a cast that must be added by hand; the go fix tool will warn about it.

@@ -1540,7 +1542,7 @@ added to URL.

Updating: Code that uses the old fields will fail to compile and must be updated by hand. -The semantic changes make it difficult for gofix to update automatically. +The semantic changes make it difficult for the fix tool to update automatically.

The xml package

@@ -1579,9 +1581,9 @@ of the XML element being marshaled.

Updating: -Gofix will update most uses of the package except for some calls to +Running go fix will update most uses of the package except for some calls to Unmarshal. Special care must be taken with field tags, -since gofix will not update them and if not fixed by hand they will +since the fix tool will not update them and if not fixed by hand they will misbehave silently in some cases. For example, the old "attr" is now written ",attr" while plain "attr" remains valid but with a different meaning. diff --git a/doc/go1.tmpl b/doc/go1.tmpl index 1e317446bf..3287e137f2 100644 --- a/doc/go1.tmpl +++ b/doc/go1.tmpl @@ -192,10 +192,11 @@ There is no return value. Deleting a non-existent entry is a no-op.

Updating: -Gofix will convert expressions of the form m[k] = ignored, +Running go fix will convert expressions of the form m[k] = ignored, false into delete(m, k) when it is clear that the ignored value can be safely discarded from the program and -false refers to the predefined boolean constant. Gofix +false refers to the predefined boolean constant. +The fix tool will flag other uses of the syntax for inspection by the programmer.

@@ -458,12 +459,12 @@ and template.

Updating: -Gofix will update all imports and package renames for packages that +Running go fix will update all imports and package renames for packages that remain inside the standard repository. Programs that import packages that are no longer in the standard repository will need to be edited by hand.
-TODO: gofix should warn about deletions. +TODO: go fix should warn about deletions.

The package tree exp

@@ -495,16 +496,17 @@ Also, the utf8.String type has been moved to its own package, Finally, the gotype command now resides in exp/gotype, while -ebnflint is now in exp/ebnflint +ebnflint is now in exp/ebnflint. +If they are installed, they now reside in $GOROOT/bin/tool.

Updating: Code that uses packages in exp will need to be updated by hand, or else compiled from an installation that has exp available. -Gofix or the compiler will complain about such uses. +The go fix tool or the compiler will complain about such uses.
-TODO: gofix should warn about such uses. +TODO: go fix should warn about such uses.

The package tree old

@@ -529,9 +531,9 @@ The packages in their new locations are: Updating: Code that uses packages now in old will need to be updated by hand, or else compiled from an installation that has old available. -Gofix will warn about such uses. +The go fix tool will warn about such uses.
-TODO: gofix should warn about such uses. +TODO: go fix should warn about such uses.

Deleted packages

@@ -559,7 +561,7 @@ slices directly. See Language Community Wiki for some suggestions. Code that uses the other packages (there should be almost zero) will need to be rethought.
-TODO: gofix should warn such uses. +TODO: go fix should warn such uses.

Packages moving to subrepositories

@@ -614,7 +616,7 @@ This table lists the old and new import paths:

Updating: -Gofix will update imports of these packages to use the new import paths. +Running go fix will update imports of these packages to use the new import paths. Installations that depend on these packages will need to install them using a go install command.

@@ -669,7 +671,7 @@ to turn a string into an error. It replaces the old os.NewError.

Updating: -Gofix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change. Code that defines error types with a String method will need to be updated by hand to rename the methods to Error.

@@ -688,7 +690,7 @@ that satisfies error and replaces the old os.Errno.

Updating: -Gofix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change. Regardless, most code should use the os package rather than syscall and so will be unaffected.

@@ -746,11 +748,11 @@ its representation of file time stamps.

Updating: -Gofix will update many uses of the old time package to use the new +The go fix tool will update many uses of the old time package to use the new types and methods, although it does not replace values such as 1e9 representing nanoseconds per second. Also, because of type changes in some of the values that arise, -some of the expressions rewritten by gofix may require +some of the expressions rewritten by the fix tool may require further hand editing; in such cases the rewrite will include the correct function or method for the old functionality, but may have the wrong type or require further analysis. @@ -761,7 +763,7 @@ may have the wrong type or require further analysis.

This section describes smaller changes, such as those to less commonly used packages or that affect -few programs beyond the need to run gofix. +few programs beyond the need to run go fix. This category includes packages that are new in Go 1.

@@ -784,7 +786,7 @@ in crypto/elliptic that take an elliptic.Curve as their first argument.

-

The crypto/hmac package

+

The crypto/hmac package

In Go 1, the hash-specific functions, such as hmac.NewMD5, have @@ -794,7 +796,7 @@ a function that returns a hash.Hash, such as md5.New.

Updating: -Gofix will perform the needed changes. +Running go fix will perform the needed changes.

The crypto/x509 package

@@ -923,7 +925,7 @@ The previous behavior can be recreated by adding a nil argument to Existing implementations of hash.Hash will need to add a BlockSize method. Hashes that process the input one byte at a time can implement BlockSize to return 1. -Gofix will update calls to the Sum methods of the various +Running go fix will update calls to the Sum methods of the various implementations of hash.Hash.

@@ -965,7 +967,7 @@ historical artifact.

Updating: -Gofix will update the few programs that are affected except for +Running go fix will update the few programs that are affected except for uses of RawURL, which must be fixed by hand.

@@ -1084,7 +1086,7 @@ and

Updating: -Gofix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change.

The mime package

@@ -1130,7 +1132,7 @@ The net.ListenMulticastUDP function replaces the old

Updating: Code that uses the old methods will fail to compile and must be updated by hand. -The semantic change makes it difficult for gofix to update automatically. +The semantic change makes it difficult for the fix tool to update automatically.

The os.FileInfo type

@@ -1202,7 +1204,7 @@ of the standard interface.

Updating: -Gofix will update code that uses the old equivalent of the current os.FileInfo +Running go fix will update code that uses the old equivalent of the current os.FileInfo and os.FileMode API. Code that needs system-specific file details will need to be updated by hand.

@@ -1341,11 +1343,11 @@ for full details.

Updating: -Gofix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change.
§ Atoi persists but Atoui and Atof32 do not, so they may require -a cast that must be added by hand; gofix will warn about it. +a cast that must be added by hand; the go fix tool will warn about it.

@@ -1430,7 +1432,7 @@ added to URL.

Updating: Code that uses the old fields will fail to compile and must be updated by hand. -The semantic changes make it difficult for gofix to update automatically. +The semantic changes make it difficult for the fix tool to update automatically.

The xml package

@@ -1469,9 +1471,9 @@ of the XML element being marshaled.

Updating: -Gofix will update most uses of the package except for some calls to +Running go fix will update most uses of the package except for some calls to Unmarshal. Special care must be taken with field tags, -since gofix will not update them and if not fixed by hand they will +since the fix tool will not update them and if not fixed by hand they will misbehave silently in some cases. For example, the old "attr" is now written ",attr" while plain "attr" remains valid but with a different meaning. diff --git a/doc/install.html b/doc/install.html index 61a90dad12..e462f1cce7 100644 --- a/doc/install.html +++ b/doc/install.html @@ -350,7 +350,7 @@ to override the defaults. The root of the Go tree, often $HOME/go. This defaults to the parent of the directory where all.bash is run. If you choose not to set $GOROOT, you must - run gomake instead of make or gmake + run go tool make instead of make or gmake when developing Go programs using the conventional makefiles. diff --git a/src/cmd/nm/doc.go b/src/cmd/nm/doc.go index 2a37dd8351..5e216b9223 100644 --- a/src/cmd/nm/doc.go +++ b/src/cmd/nm/doc.go @@ -14,8 +14,7 @@ Plan 9 C compiler. This implementation adds the flag -S, which prints each symbol's size in decimal after its address. -For reasons of disambiguation it is installed as 6nm although it also serves -as an 8nm and a 5nm. +It is installed as go tool nm and is architecture-independent. */ package documentation -- 2.52.0