proposal: doc: document $GOROOT layout

[ghost]

Not everyone new to Go is coming from a Un*x background, but, I think writing up, in the Readme.md file, the html docs, or on the wiki, of the similarity of the Go and plan9port file trees, might make the language more accessible to new Go programmers.

[ianlancetaylor]

This is not obvious to me. It seems likely that more people are familiar with Go than with plan9port. But perhaps I misunderstand. Can you give an example of the kind of docs you would like to add?

[ghost]

hardware specific sub-directories in the file tree

src, being akin to p9p's src and Plan 9's sys/src

R.C., R.P., and K.T., as Go developers worked on Plan 9

and might be eminently qualified to do a write up on the Go file tree

proposed location as a new html page linked to on the Documents page

under the References section

https://golang.org/doc/#references

References

File Tree Documentation

The documentation for the Go file tree.

[ianlancetaylor]

Thanks, but what would the documentation actually say? What would make it useful?

In my experience, directories named src, and hardware-specific subdirectories, are common in projects of this nature.

[ianlancetaylor]

If anything I think this should simply be a wiki page. Want to try writing it yourself?

[jimmyfrasche]

@forskning do you know of other projects with files like this? Some examples could help show the usefulness of the idea.

A wiki page does sound like a good start, though. It can always be added to the repo itself later.

[rsc]

I think you're right that there's nothing explaining what's in $GOROOT and where. I don't think that saying "it's like Plan 9" or "it's like plan9port" is going to help much, though (I'm not sure there is really very much similarity at all). Probably it should just be documented from scratch.

The $GOROOT/README.md is about much more high-level concerns so that's probably not the right place.

Maybe on the Wiki? If the wiki page is a success we might consider copying it into $GOROOT, maybe as something like $GOROOT/HACKING.md (to match src/runtime/HACKING.md and maybe others), but we should probably start on the wiki.

[ghost]

I fully understand the rewrite by R.C. of the current up for discussion issue, maybe I had been on a wrong tack here, one should probably introduce the Go language based on its content, rather than presumptions on what coding background a newcomer to the language may have had, and, neither would my approach allocate for the circumstance where Go may factually be the first language the coder learns.

Nominally #21792 (comment) may have some bearing on the current issue, the comment of I.L.T. on "other places we should document godoc.", but introducing shell variables in the README.md is probably not the best location to do so, and, whereas in #21792 (comment) I pointed out that https://go.googlesource.com/go appears to be the source of the content of the README.md, and both contain a link to a wiki page, probably a link to an additional document or wiki page therein, where the Go file tree would be explained, "what's in $GOROOT and where", might be an approach, cognisant that if one adds a "Reading the Docs" section to https://go.googlesource.com/go and README.md, one might need to explain the Go file tree.

[jimmyfrasche]

@forskning do you want to create a FileTreeDocumentation page on the wiki? You have access and permission.

If you don't have time, I could take a swing at it. I've bumbled around the project enough to know what most of the directories are for, though I might have to ask some questions here.

[ghost]

https://docs.google.com/document/d/1Bz5-UB7g2uPBdOx-rw5t9MxJwkfpx90cqG9AFL0JAYo/edit

Any opinion about the layout for a tree as appears in the example on page 2 of above link?

[mvdan]

Assuming "source tree" and "GOROOT" mean the same, I believe this is mostly a duplicate of #21034.

[ianlancetaylor]

@forskning That doc is describing the layout of a sample GOPATH. It's true that the src subdirectory of GOROOT is laid out like a GOPATH, but that doesn't help you with the other GOROOT directories.

[ghost]

Talking about the design of a wiki page, its too early for me to respond to the comments of @jimmyfrasche, the layout cited appears different than for example what would render if one ran from a Windows Command Prompt the TREE built-in, or TREE with the Ascii option.

Thank you @mvdan very much for the provision of the reference to the other thread, where the man in opening that thread mentioned the api/README file, useful in research for writing a wiki page as envisaged pursuant to this current thread.

[ghost]

My browser's too old to work on the wiki.

@rsc Maybe the following deserves a new thread.

Incidentally, both the Go source and wiki have some links which redirect.

At some point it might be pursued to make an assessment as to which of those (possibly not all) might be changed so they don't redirect.

If a link is discovered in the Go source (and designated for change), the wiki at that time might be checked for the presence of that same link, and the change in the source then reflected as a change of that same link in the wiki.

As an example of a link which probably should be updated (it's compiled into the go executable) would be that link appearing on line 419 of the Go development version file vcs.go.

https://github.com/golang/go/blob/master/src/cmd/go/internal/get/vcs.go

https://golang.org/s/gogetcmd

redirects to

https://github.com/golang/go/wiki/GoGetTools

[ghost]

I think the layout of the tree in the link provided in #22041 (comment) would render favourably in mothra and/or text-browsers.

https://www.youtube.com/watch?v=LR8fQiskYII
https://www.youtube.com/watch?v=NvWTnIoQZj4

If comparison with other languages' file trees would be relevant, Haskell and Java (on my Slackware machine) have likewise top level directories as sub-directories of /usr/lib.

@jimmyfrasche to respond to your comments

do you know of other projects with files like this?

yes - Java might have hardware specific sub-directories
no - not with a src/cmd directory

If you don't have time, I could take a swing at it

Sounds good!

[as]

@forskning
I like the tree format, but not the vertical pipes in particular. I would just go with plain old tabs. How exactly are you posting here if you can't edit the wiki? Is there a github API or has Mothra grown a new pair of wings since I last used it?

[jimmyfrasche]

I couldn't use the tree format and have links so I just went with a list of lists.

I'm sure I made some silly mistakes and there were a few directories I had to leave blank for utter want of understanding or at least insufficient understanding to comment.

PTAL: https://github.com/golang/go/wiki/FileTreeDocumentation

[ghost]

@as

vertical pipes

I thought the vertical pipes might get mixed reviews.

How exactly are you posting here if you can't edit the wiki?

Posting (not editing) works in the following.

Mozilla Firefox 15.0.1 (Slackware-14.0)
Google Chrome 49.0.2623.75 (MS® XP)

new pair of wings

A screenshot of a recent port of Mothra to plan9port (KDE 4.8.5)

http://9front.org/extra/

...
mothra.black.tgz
mothra.mono.tgz
mothra.p.tgz
mothra.white.tgz

[ghost]

FWIW, if a tree format would be implemented on other wiki pages.

% tree -d -L 2 /usr/lib/go1.9.2 | head
/usr/lib/go1.9.2
`-- go
    |-- api
    |-- bin
    |-- doc
    |-- lib
    |-- misc
    |-- pkg
    |-- src
    `-- test
% 

% tree $GOROOT/lib | head -n 5
/usr/lib/go1.9.2/go/lib
`-- time
    |-- README
    |-- update.bash
    `-- zoneinfo.zip
% 

% tree -d -L 1 $GOROOT/misc | head -n 12
/usr/lib/go1.9.2/go/misc
|-- android
|-- arm
|-- cgo
|-- chrome
|-- git
|-- ios
|-- linkcheck
|-- nacl
|-- sortac
|-- swig
`-- trace
% 

% tree -d -L 1 $GOROOT/pkg | head -n 7
/usr/lib/go1.9.2/go/pkg
|-- bootstrap
|-- include
|-- linux_386
|-- linux_386_dynlink
|-- obj
`-- tool
%

It's not likely the Go Wiki ever would get "Enhanced for Lynx" (a.k.a. Lynx Friendly), or "Enhanced for Mothra".

The Plan 9 Wiki maintainers having considered for the wikifs(4) replacing the "...very small set of cues" when generating HTML, "... with something better, like Markdown".

[ghost]

http://nurmi-labs.blogspot.com/p/filetreedoc.html

a somewhat clipped version with tree format added

[ghost]

@jimmyfrasche I added a bit of content to the FileTreeDoc blog Page

Would you be interested to utilise any of that for your wiki page?