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

Documentation: workspace.open( ) with no URI #6005

Merged
merged 2 commits into from Apr 9, 2015

Conversation

Projects
None yet
3 participants
@vegar
Contributor

vegar commented Mar 17, 2015

I just learned that calling open on workspace without specifying an uri is the way to go for getting a new tab with a new document.

I can't find anything about this in either the docs or the api documentation.

Should uri be marked optional, like the options params? And should it be added a line stating that no uri opens a blank editor?

(and there's an extra a in the title..)

Documentation: workspace.open( ) with no URI
I just learned that [calling open on workspace](https://discuss.atom.io/t/how-can-we-help-you-write-packages/4268/67) without specifying an uri is the way to go for getting a new tab with a new document. 

I can't find anything about this in either the docs or the [api documentation.](https://atom.io/docs/api/v0.187.0/Workspace#instance-open)

Should `uri` be marked optional, like the `options` params? And should it be added a line stating that no uri opens a blank editor?

(and there's an extra `a` in the title..)
@izuzak

This comment has been minimized.

Show comment
Hide comment
@izuzak

izuzak Mar 18, 2015

Member

This makes sense to me. What do you think, @nathansobo -- is it 🆒 to document this behavior?

Member

izuzak commented Mar 18, 2015

This makes sense to me. What do you think, @nathansobo -- is it 🆒 to document this behavior?

@nathansobo

This comment has been minimized.

Show comment
Hide comment
@nathansobo

nathansobo Mar 19, 2015

Contributor

Yeah, documenting that would be great.

Contributor

nathansobo commented Mar 19, 2015

Yeah, documenting that would be great.

Show outdated Hide outdated src/workspace.coffee
#
# * `uri` A {String} containing a URI.
# Essential: Open a given URI in Atom asynchronously.
# If no URI is given, or URI does not resolve to an existing file,

This comment has been minimized.

@izuzak

izuzak Mar 20, 2015

Member

Perhaps instead of saying:

or URI does not resolve to an existing file,

we could say something like

or URI is not already open in an existing pane item

because URIs are used to reference and open more than files. For example, atom.workspace.open("atom://config") can be used to open the Settings View. What do you think, @vegar?

@izuzak

izuzak Mar 20, 2015

Member

Perhaps instead of saying:

or URI does not resolve to an existing file,

we could say something like

or URI is not already open in an existing pane item

because URIs are used to reference and open more than files. For example, atom.workspace.open("atom://config") can be used to open the Settings View. What do you think, @vegar?

This comment has been minimized.

@vegar

vegar Mar 20, 2015

Contributor

First: I have been looking at atom for three spare nights now. I have very little knowledge of how it works.

What I found, was that if we have atom.workspace.open("file_not_on_disk.txt"), we get a new editor/document where the filename is initalized to the URI, so if you hit save you wan't be prompted for a filename - it will just save the file in the root of the current project.
If you do not have a project open, you will still get a new document, but the document will not get the filename specified. It will get 'untitled'.

So the proposed text .., or URI does not resolve to an existingn file, ... was supposed to capture some of this behavior. Not a very clear formulation I guess.. 😳 ..but that was it's intent.

I think maybe your proposed change will document yet another behavior that I was unaware of. Maybe it should be added as a separate bullet point? (The documentation guidelines may have an opinion on how behavior should be listed?)

@vegar

vegar Mar 20, 2015

Contributor

First: I have been looking at atom for three spare nights now. I have very little knowledge of how it works.

What I found, was that if we have atom.workspace.open("file_not_on_disk.txt"), we get a new editor/document where the filename is initalized to the URI, so if you hit save you wan't be prompted for a filename - it will just save the file in the root of the current project.
If you do not have a project open, you will still get a new document, but the document will not get the filename specified. It will get 'untitled'.

So the proposed text .., or URI does not resolve to an existingn file, ... was supposed to capture some of this behavior. Not a very clear formulation I guess.. 😳 ..but that was it's intent.

I think maybe your proposed change will document yet another behavior that I was unaware of. Maybe it should be added as a separate bullet point? (The documentation guidelines may have an opinion on how behavior should be listed?)

This comment has been minimized.

@izuzak

izuzak Mar 31, 2015

Member

What I found, was that if we have atom.workspace.open("file_not_on_disk.txt"), we get a new editor/document where the filename is initalized to the URI, so if you hit save you wan't be prompted for a filename - it will just save the file in the root of the current project.
If you do not have a project open, you will still get a new document, but the document will not get the filename specified. It will get 'untitled'.

@vegar I'd skip documenting this stuff around untitled filenames for now, especially not here since you're referring to something that will happen on save, and the user might not even save the file. I think my proposed change reflects the behavior related to opening, which is the method we are documenting here. Sound good?

@izuzak

izuzak Mar 31, 2015

Member

What I found, was that if we have atom.workspace.open("file_not_on_disk.txt"), we get a new editor/document where the filename is initalized to the URI, so if you hit save you wan't be prompted for a filename - it will just save the file in the root of the current project.
If you do not have a project open, you will still get a new document, but the document will not get the filename specified. It will get 'untitled'.

@vegar I'd skip documenting this stuff around untitled filenames for now, especially not here since you're referring to something that will happen on save, and the user might not even save the file. I think my proposed change reflects the behavior related to opening, which is the method we are documenting here. Sound good?

This comment has been minimized.

@izuzak

izuzak Mar 31, 2015

Member

Also cc @nathansobo in case he has different opinions on this.

@izuzak

izuzak Mar 31, 2015

Member

Also cc @nathansobo in case he has different opinions on this.

This comment has been minimized.

@vegar

vegar Mar 31, 2015

Contributor

👍

@vegar

vegar Mar 31, 2015

Contributor

👍

This comment has been minimized.

@izuzak

izuzak Mar 31, 2015

Member

@vegar Just to make sure I understand -- does that 👍 mean that you want to update the PR to clarify the text based on my above suggestion? https://github.com/atom/atom/pull/6005/files#r26837887 I'm still in favor of making that update.

@izuzak

izuzak Mar 31, 2015

Member

@vegar Just to make sure I understand -- does that 👍 mean that you want to update the PR to clarify the text based on my above suggestion? https://github.com/atom/atom/pull/6005/files#r26837887 I'm still in favor of making that update.

This comment has been minimized.

@vegar

vegar Mar 31, 2015

Contributor

It was me agreeing to not documenting all the save-related behavior here.

About your initial suggesting: replacing

or URI does not resolve to an existing file,

with

or URI is not already open in an existing pane item

I'm not sure what's best.

Your suggestion states that if the uri is already open, it wan't open again, but is that true? Or is that dependent on how the open handler are implemented? (Cause in a small test project I have, I get multiple tabs with the same uri... ..not that I wanted to, but I can't find out how to prevent it...)

My suggestion states that if the uri is a file uri but the file doesn't exist, you will get a new text editor.

So... What about

Essential: Opens a given URI in Atom asynchronously, if it's not already open.

If no URI is given, or URI is a filepath and the file does not exist, a new empty text editor is created.

or

..., or URI is to a file that does not exist, ...

@vegar

vegar Mar 31, 2015

Contributor

It was me agreeing to not documenting all the save-related behavior here.

About your initial suggesting: replacing

or URI does not resolve to an existing file,

with

or URI is not already open in an existing pane item

I'm not sure what's best.

Your suggestion states that if the uri is already open, it wan't open again, but is that true? Or is that dependent on how the open handler are implemented? (Cause in a small test project I have, I get multiple tabs with the same uri... ..not that I wanted to, but I can't find out how to prevent it...)

My suggestion states that if the uri is a file uri but the file doesn't exist, you will get a new text editor.

So... What about

Essential: Opens a given URI in Atom asynchronously, if it's not already open.

If no URI is given, or URI is a filepath and the file does not exist, a new empty text editor is created.

or

..., or URI is to a file that does not exist, ...

This comment has been minimized.

@nathansobo

nathansobo Mar 31, 2015

Contributor

I don't have strong opinions here, as long as we're accurate. I do like ensuring our language makes clear that URIs don't always correspond to paths on disk.

@nathansobo

nathansobo Mar 31, 2015

Contributor

I don't have strong opinions here, as long as we're accurate. I do like ensuring our language makes clear that URIs don't always correspond to paths on disk.

@izuzak izuzak merged commit 4cf34cc into atom:master Apr 9, 2015

izuzak added a commit that referenced this pull request Apr 9, 2015

Merge pull request #6005 from vegar/patch-1
Documentation: workspace.open( ) with no URI
@izuzak

This comment has been minimized.

Show comment
Hide comment
@izuzak

izuzak Apr 9, 2015

Member

This is merged now, I just made a minor clarification in b8fb2f4. Thanks again for this.

Member

izuzak commented Apr 9, 2015

This is merged now, I just made a minor clarification in b8fb2f4. Thanks again for this.

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