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

proposal: doc: document $GOROOT layout #22041

Closed
forskning opened this Issue Sep 26, 2017 · 20 comments

Comments

Projects
None yet
8 participants
@forskning
Copy link

forskning commented Sep 26, 2017

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.

@gopherbot gopherbot added this to the Proposal milestone Sep 26, 2017

@gopherbot gopherbot added the Proposal label Sep 26, 2017

@ianlancetaylor

This comment has been minimized.

Copy link
Contributor

ianlancetaylor commented Sep 26, 2017

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?

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Sep 27, 2017

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

This comment has been minimized.

Copy link
Contributor

ianlancetaylor commented Sep 27, 2017

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

This comment has been minimized.

Copy link
Contributor

ianlancetaylor commented Sep 27, 2017

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

@jimmyfrasche

This comment has been minimized.

Copy link
Member

jimmyfrasche commented Sep 27, 2017

@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 rsc changed the title proposal: add info on file tree proposal: doc: document $GOROOT layout Oct 2, 2017

@rsc

This comment has been minimized.

Copy link
Contributor

rsc commented Oct 2, 2017

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.

@rsc rsc modified the milestones: Proposal, Unreleased Oct 2, 2017

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Oct 3, 2017

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

This comment has been minimized.

Copy link
Member

jimmyfrasche commented Oct 4, 2017

@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.

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Oct 4, 2017

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

This comment has been minimized.

Copy link
Member

mvdan commented Oct 4, 2017

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

@ianlancetaylor

This comment has been minimized.

Copy link
Contributor

ianlancetaylor commented Oct 4, 2017

@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.

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Oct 4, 2017

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.

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Oct 5, 2017

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

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Oct 5, 2017

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

This comment has been minimized.

Copy link
Contributor

as commented Oct 5, 2017

@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

This comment has been minimized.

Copy link
Member

jimmyfrasche commented Oct 5, 2017

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

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Oct 6, 2017

@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)

hubfs

http://9front.org/extra/

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

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Oct 7, 2017

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".

lynxfriend

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".

mothraenhanced

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Oct 9, 2017

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

a somewhat clipped version with tree format added

@forskning

This comment has been minimized.

Copy link
Author

forskning commented Nov 5, 2017

@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?

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.