Renaming commands

[ellisonbg]

This PR does a review of the action names in the notebook to address #532.

We sat down with @sccolbert @jasongrout and @SylvainCorlay last week and spent a day going through all the action names, and seeing what patterns and inconsistencies there were. Here are the broad rules we are using for these names:

• First pick a noun and a verb for the action. For example, if the action is "restart kernel," the verb is "restart" and the noun is "kernel".
• Omit terms like "selected" and "active" by default, so "delete-cell", rather than "delete-selected-cell". Only provide a scope like "-all-" if it is other than the default "selected" or "active" scope.
• If an action has a secondary action, separate the secondary action with "-and-", so "restart-kernel-and-clear-output".
• Don't ever use before/after as they have a temporal connotation that is confusing when used in a spatial context.
• Use above/below or previous/next to indicate spacial and sequential relationships.
• For dialogs, use a verb that indicates what the dialog will accomplish, such as "confirm-restart-kernel".

This PR also starts to use : for action groups (looking forward to phosphor) and jupyter-notebook as the default group.

[ssanderson]

👍 for having a consistent naming-style guide on these.

• Use above/below or previous/next to indicate spacial and sequential relationships.

This sentence is a bit ambiguous to me. Is the intent here equivalent to "Use above/below to indicate spacial relationships. Use previous/next to indicate sequential relationships."? Is sequential indended as a synonym for "temporally-sequential" here?

[ellisonbg]

Yeah, when to use above/below or previous/next can be a bit sutble and that difficulty is reflected in the sentence structure.

[Carreau]

Omit terms like "selected" and "active" by default, so "delete-cell", rather than "delete-selected-cell". Only provide a scope like "-all-" if it is other than the default "selected" or "active" scope.

Why that ? Especially since we have multiple selection and anchor ? I fel a lot confused when searching for an action if there is not the "selected", or "all"

[Carreau]

ipython: ?

[ellisonbg]

Opps, good catch.

[Carreau]

Actually jupyter-notebook

[ellisonbg]

@Carreau as to why omit the "selected". Initially we started with that, but it felt one-step-too-verbose, when a significant fraction of the time, the user will be applying actions to the active object.

Another thing that we talked about today. For actions that make sense on multiple (marked) cells, the simple versions of commands should apply to:

• All marked cells if any are marked (multiple selection). In this case, not the selected cell - it acts like a cursor.
• The selected cell if none are marked.

The alternative is to have 3 versions of all actions on cells:

1. -selected-
2. -marked-
3. -all-

That seems overly verbose. he approach implemented in this PR automatically provides a natural way of have actions that either the selected of mulitple marked cells.

[Carreau]

The verbosity will not be annoying for user to type once we have fuzzy-matching, but I understand your point. Though I dont' think verbosity should be scarified on action that will almost never be used through the command palette (run current cell, move cursor up or previous cell).
These are mostly for user to do write compound actions, so are probably better explicit IMHO.

I see you point though, but keep in mind that many user are not native english, and that they will be exposed to english UI, and that while english user will find some action name obvious, it will not be the case for non-english.

[ellisonbg]

@Carreau yes, I get your point about english versus non-english users. It was actually very helpful to have @SylvainCorlay doing this work with us as he had similar feedback as you. One suggestion was to use German for all of these as it is a quite formal language with more rigid and structured grammar rules. But I think paste-zelle unterhalb might be difficult to sell to our users.

[ellisonbg]

@Carreau yes, I like your idea of being able to hide some actions from the command pallete. We are pretty sure that some of them won't ever be run that way. Pinging @sccolbert @blink1073 on that idea.

[Carreau]

@Carreau yes, I like your idea of being able to hide some actions from the command pallete. We are pretty sure that some of them won't ever be run that way. Pinging @sccolbert @blink1073 on that idea.

We are all consenting adults. Hide by default action stat start with _ and show them only if user search pattern that start with _ ? (like private method completion in Python)

[sccolbert]

+1 on having a prefix to distinguish advanced commands from every-day commands. I might choose $ over _ as the prefix though, to prevent any misunderstanding that the commands are private.

[minrk]

+1 to most of this, I think it's a great improvement. Thanks for doing a thoughtful pass on the names. Only a couple of questions:

• inline comment about jupyter-notebook. Seems like notebook is enough, or possibly jupyter, but jupyter-notebook seems redundant at least once.
• is there any reasoning behind the switch from . to : that I missed? I don't care much, but have a slight preference for ..

[sccolbert]

The choice for : is because that's what Phosphor is planning to use. It's also what Atom uses to denote a package namespace.

[blink1073]

+1 for a prefix other than _, I'm fine with $.

[minrk]

Following existing convention is a good reason, thanks.

[Carreau]

I'm fine with either $ or _ , the old hackpad notes for commands is here

[Carreau]

Seem to need rebase (sorry about that)

[ellisonbg]

No problem, I figure I would have to rebase.

On Wed, Oct 14, 2015 at 2:13 PM, Matthias Bussonnier <
notifications@github.com> wrote:

Assigned #598 #598 to @ellisonbg
https://github.com/ellisonbg.

—
Reply to this email directly or view it on GitHub
#598 (comment).

Brian E. Granger
Associate Professor of Physics and Data Science
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger@calpoly.edu and ellisonbg@gmail.com

[ellisonbg]

Rebased

@minrk On the verbose jupyter-notebook namespace. A few reasons why more verbose. First, users should eventually never see this unlike the Python package which uses conda/pip install. Second, because the browser doesn't have any way to enforce global name uniqueness, we have to worry about someone, somewhere, someday calling something notebook other than us.

But maybe a bigger question. I would like us to start using a unique prefix approach for CSS, etc. Alot of this will start to be scoped at the level of our JS npm packages. For example, it would be great if the command and CSS namespace for the notebook component could be something like j-notebook or jupyter-notebook, etc.

What global name prefix to people like? jp? jpy?

@sccolbert @blink1073 @minrk @Carreau @jdfreder @dwillmer @jasongrout @SylvainCorlay

[jdfreder]

I prefer jpy-

[SylvainCorlay]

And a notebook file format would be .jpynb ?

[ellisonbg]

OK I have rebased, and I think fixed the tests. I think we should wait to add the command hiding in a separate PR. I like the idea of using $, but also want to make sure we don't want to express that as a separate key in the command structure.

Remaining things to solve for this:

• Which command prefix to use?
• Any other command name changes?

[ellisonbg]

OK I have addressed most comments. I talked more with Chris, Jason and Sylvain about the action name prefix naming.

• In the long run, if needed, we can provide a end-user-human-readable version of the command namespace for usage in UI elements.
• For this PR, I mostly want to get the programmatic one right.
• The feeling here is that the command namespaces should roughly follow JS package names. From this perspective, the notebook package will be jupyter-js-notebook so the command prefix would make sense as jupyter-notebook.
• Also feeling here like they should be verbose (more verbose than CSS) and developer-human-readable, so jp-notebook is too opaque.
• These will be scoped at the level of major components in the UI (what we are calling plugins on the phosphor side of things). When all is said and done, there will tons of plugins, many of which we don't develop. Because of this, I think it will be very useful to have the extra jupyter- in the namespace to group our components together:

jupyter-texteditor
jupyter-terminal
jupyter-debugger
jupyter-filebrowser
etc.

Based on these discussions, the current state of the PR is to use jupyter-notebook.

As an aside, I think it would be helpful to use a different name (maybe the shorter jp-notebook) for our CSS prefix to more easily allow searching through our codebase for developers.

Thoughts?

[Carreau]

jupyter-js-notebook

I'm still unconvinced about -js- in the name.

• Because it is/will be written in TS,
• because no other package in JS world do.
• we don't have jupyter-py-notebook.
  (- I want to punch TS in the face even more each time I have a package with - or _ in it and it fails in even weirder way than usual, but that's unrelated. )

The fact that the toolbar is not in env is weird, and yes env =! of Jupyter because env is not and should not be global.

[ellisonbg]

Yeah, I am not thrilled about the -js- in the middle of all our JS repo names. But the only way I see around this would be for us to start a new jupyterjs GitHub org for all of our JS packages. Also, because everything gets compiled down to JS and people use the libraries from JS, I think it should be JS (it is pohsphorjs, not phosphorts).

[Carreau]

Maybe fair enough for notebook, but really why not just jupyter-input-area, jupyter-output-are, jupyter-services, jupyter-cell ?

[ellisonbg]

We could, but in the long run we are going to end up with separate JS and
Python packages for the same thing. That gets tough to avoid our own name
collisions or even name confusions. It gets tough for folks to navigate and
understand the difference between "notebook" and "jupyter-notebook" and
"jupyter-notebook-plugin"...

It might not be so bad though...

On Tue, Oct 20, 2015 at 11:42 AM, Matthias Bussonnier <
notifications@github.com> wrote:

Maybe fair enough for notebook, but really why not just jupyter-input-area,
jupyter-output-are, jupyter-services, jupyter-cell ?

—
Reply to this email directly or view it on GitHub
#598 (comment).

Brian E. Granger
Associate Professor of Physics and Data Science
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger@calpoly.edu and ellisonbg@gmail.com

[Carreau]

jp-notebook here, you are using jupyter-notebook everywhere else.

[Carreau]

Can you check the pager, click on x does not close the pager for me anymore.

[Carreau]

And let's merge once the jp-notebook is fixed, and iterate.

[ellisonbg]

OK, after Travis is happy, this is ready to merge. I have also figured out why the pager is broken, but it is also broken in master so I will submit another PR to fix...

[Carreau]

I have also figured out why the pager is broken, but it is also broken in master so I will submit another PR to fix...

Seem fair enough.

Traavis is happy, rereading one last time and I'll press the GB.

[coveralls]

Changes Unknown when pulling dab9765 on ellisonbg:action-names into ** on jupyter:master**.