Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/tour: instructions for running Go tour offline are malformatted #24819

Open
rpjday opened this issue Apr 12, 2018 · 14 comments

Comments

@rpjday
Copy link

commented Apr 12, 2018

There seem to be two issues with the instructions for how to run the Go tour offline here.

First, on my Fedora system, even though I have installed Go 1.10.1 from binary rpms, running go tool tour doesn't work (perhaps this requires installing a distinct Fedora package that is not mentioned):

$ go tool tour
go tool: no such tool "tour"
$

The second issue is that, before trying to run these commands:

$ go get golang.org/x/tour/gotour
$ gotour

the reader should be reminded to add ${GOPATH}/bin to their search path.

@ALTree

This comment has been minimized.

Copy link
Member

commented Apr 12, 2018

Thanks for the report. I have a comment about your first point.

First, on my Fedora system, even though I have installed Go 1.10.1 from binary rpms, running go tool tour doesn't work

The full paragraph says:

To run the tour locally first download and install Go then start the tour from the command line:
go tool tour

The two things go together: it's one sentence. The hyperlink at the "download and install Go" text points to golang.org/dl, which instructs the reader to install go from the pre-compiled binaries. It is implied that you can expect the command to work out-of-the-box only if you followed the instructions immediately above and installed go from the website.

While we could fill the docs with notes and warnings about possible different ways to do things (like installing from OS packages), I think this would make the documentation very unpleasant to read. In general, it's clearer to document a simple, happy path (especially in tutorials like the Go Tour, where it's generally a bad idea to hit the reader with too much -possibly useless- text). Users are expected to follow that path, or be ready to troubleshot their problems if they decide to deviate.

@andybons andybons changed the title Instructions for running Go tour offline are deficient x/tour: instructions for running Go tour offline are deficient Apr 12, 2018

@gopherbot gopherbot added this to the Unreleased milestone Apr 12, 2018

@agnivade

This comment has been minimized.

Copy link
Member

commented Apr 12, 2018

the reader should be reminded to add ${GOPATH}/bin to their search path.

I think that is unnecessary. Next up, people will start asking for this reminder to be added under all x/tools/ subrepos as well. And following that logic, maybe all Go repos on github as well.

We should just need one page to clearly document the installation steps. And that is very well documented at https://golang.org/doc/install.

@rpjday

This comment has been minimized.

Copy link
Author

commented Apr 12, 2018

I'm not suggesting that that advice be added everywhere, but given that it's on page three of the entire tour, I don't think it's out of place to make sure readers know how to set up properly. And the page you're referring to is not part of the tour. Why so much resistance to adding a single line to make sure readers don't run into a problem?

@agnivade

This comment has been minimized.

Copy link
Member

commented Apr 12, 2018

Not at all. My only concern was that information might get duplicated into multiple places. Otherwise I have no strong opinions on this. If it helps newcomers, I am all for it. 👍

Sorry if I was misunderstood.

@ALTree

This comment has been minimized.

Copy link
Member

commented Apr 12, 2018

I don't understand why this has been labelled as NeedsFix. Tracker guidelines says:

The path to resolution is known

That's not the case. It's not clear what exactly should be done here. This is a needsDecision, if anything. And anyway we don't really track tour improvemen suggestions here. The tour tracker is at https://github.com/golang/tour

@agnivade

This comment has been minimized.

Copy link
Member

commented May 19, 2018

ping @ianlancetaylor, @bradfitz for decision.

@bradfitz

This comment has been minimized.

Copy link
Member

commented May 23, 2018

For completeness, since I didn't see it mentioned above: even if the user is confused by both offline install options, there's always a third option: using the web-based tour that the user's already found if they're reading that page.

I don't really want to mention $GOPATH because $GOPATH might be implicit, and it might be spelled %GOPATH% on Windows, if it's set at all. Likewise, I don't want to assume bash and recommend running $(go list -f {{.Target}} golang.org/x/tour/gotour) or something gross.

If anything, we could modify the cmd/go tool to know what "tour" means on the case where the binary isn't found in the tool dir, and then it can spit out detailed, OS-specific install instructions on failure.

Then we could even remove some of the text on the tour page and only mention go tool tour.

@jschulenklopper

This comment has been minimized.

Copy link

commented Jan 4, 2019

Not sure when it started to work, but go tool tour worked fine after retrieving the package (on my macOS machine). If the instructions for an offline tour would include that command, it could be good resolution for this ticket.

(I also mentioned this in the Golang Tour tracker, so if this repository isn't for the Tour at all, as mentioned ^, it could be closed here?)

@jschulenklopper

This comment was marked as off-topic.

Copy link

commented Jan 5, 2019

@mandeepsingh-private

This comment has been minimized.

Copy link

commented Jan 8, 2019

"go tool tour" works on Mac.

@jschulenklopper

This comment has been minimized.

Copy link

commented Jan 17, 2019

"go tool tour" works on Mac.

Yes, that's what I said. Unfortunately, the instructions aren't updated yet.

@bradfitz

This comment has been minimized.

Copy link
Member

commented Jan 18, 2019

"go tool tour" is dead as of Go 1.12. Maybe that should be in the release notes (@andybons, @dmitshur, @ianlancetaylor).

But the formatting at https://tour.golang.org/welcome/3 is a mess and doesn't seem to match https://github.com/golang/tour/blob/master/content/welcome.article#L80

Let's make this bug about fixing that.

@bradfitz bradfitz changed the title x/tour: instructions for running Go tour offline are deficient x/tour: instructions for running Go tour offline are malformatted Jan 18, 2019

@bradfitz bradfitz added the NeedsFix label Jan 18, 2019

@gopherbot

This comment has been minimized.

Copy link

commented Jan 19, 2019

Change https://golang.org/cl/158618 mentions this issue: doc: note go tool tour removal in 1.12 release notes

gopherbot pushed a commit that referenced this issue Jan 30, 2019
doc: note go tool tour removal in 1.12 release notes
Note the removal of the go tool tour command in the Go 1.12 release
notes.

Updates #24819

Change-Id: I258ab9401ea2cc06a83328c67299376fcf23c980
Reviewed-on: https://go-review.googlesource.com/c/158618
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
nebulabox added a commit to nebulabox/go that referenced this issue Feb 18, 2019
doc: note go tool tour removal in 1.12 release notes
Note the removal of the go tool tour command in the Go 1.12 release
notes.

Updates golang#24819

Change-Id: I258ab9401ea2cc06a83328c67299376fcf23c980
Reviewed-on: https://go-review.googlesource.com/c/158618
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
nebulabox added a commit to nebulabox/go that referenced this issue Feb 20, 2019
doc: note go tool tour removal in 1.12 release notes
Note the removal of the go tool tour command in the Go 1.12 release
notes.

Updates golang#24819

Change-Id: I258ab9401ea2cc06a83328c67299376fcf23c980
Reviewed-on: https://go-review.googlesource.com/c/158618
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@ra1u

This comment has been minimized.

Copy link

commented Apr 29, 2019

At page https://tour.golang.org/welcome/3 it is specified that command

go get golang.org/x/tour
tour

is way to go. But looks like that first command has no effect,

It is also unclear what and where software is installed.

For example command

go get -v golang.org/x/tour

does not output anything on std-out, except it seems to return correct exit code. I cant find tour binary on my system

After some playing around with go help , my setup is now:

git clone https://github.com/golang/tour
cd tour
go build
./tour

And this seems to work for my particular debian system (your mileage may vary)

Extra:

I later found out that binary is located at $HOME/go/bin/tour, but i am not sure if package is installed from git or from go get.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
9 participants
You can’t perform that action at this time.