Fast Link

Table of contents:

When Nodes are added to a diagram they are initially linked to any previously selected node(s), and the current selection is changed to the new node. Typing “A” and pressing enter followed by “B” enter followed by “C” enter will create a chain of linked nodes A -> B -> C.

Keep in mind you can change the current selection before pressing enter to add a new node, thus ensuring it gets linked from the intended node.

Link forward >>

If you type >> instead of pressing enter, the new node is created linked as normal, but the current selection does not change to the newly created node. Typing “A»B»C»” will create A with links to both B and C instead of a chain.

Link backward <<

Similarly you can type ‘«’ instead of pressing enter to create a backward link. Typing “A«B«C” will create A with links from B and C (instead of to them).

The << and >> shortcuts can be used in any order, as they do not change the current selection.

Adding a node without linking

Pressing the escape key clears the current selection. When no nodes are currently selected, no links are created.

There is an experiemental ;; operator which will add a node without linking to current selection and will not change the current selection. It isn’t clear whether this is a good idea just yet.

Create as group }}

If you type }} instead of pressing enter, a group is created instead of a node. It will be labeled with whatever you typed beforehand, and will contain all selected nodes. The group will replace the current selection. Adding a node while a group is selected will add it to the group instead of linking it. If you do want to create a link from/to a group, you can use the << >> operators to do so.

Rationale

A little notation greatly reduces time to add nodes and relationship to a graph. Notation can be used to link nodes at creation time, instead of having to find them and connect them.

Given a node and multiple connections, we can create the nodes and edges much faster with notation:
‘Emily likes Susan, Sally, Kim and Jim’
Commonly found in a row from a table, or survey result.

Given a node we might identify parent nodes and child nodes:
‘Hate causes Anger, and is caused by Fear’
Commonly encountered while brainstorming.

Given a set of nodes we might create them in a group:
‘Parsers, Grammars, and Chess are all good fun’
Commonly encountered while enumerating objects with a shared trait or type.

Goals

1. Create connected nodes, links, and groups incrementally.
2. Easy and fast to type
3. Never reject user input

Anti-Goals

1. Avoid tricky syntax which require planning, editing, and balancing to get right
2. Avoid clashing with other user data where possible
3. Not file format (Graphviz/JSON/EDN are better file formats)
4. Not for long compound statements

Design considerations

Several tradeoffs need consideration.

No parse failures, ever

Poorly constructed expressions will be interpreted as node text. Always accepting input is better than interrupting the user. Prefer to create one or more nodes that the user can rearrange or edit to their desired state, rather than raising an error or forcing a notational decision upon the user.

Avoiding conflicts

Single character operators have a higher probability for conflicting with user input. This is addressed by using double characters (>> << [[ ;;) which are almost as fast to type. It also helps to avoid overlap with Markdown syntax, which is anticipated to be relatively common. In the rare event that you need to use these double characters as part of the text, the easiest thing to do is create the node without them first, and then edit it to add them. Alternatively, operators may be escaped by an extra character: >>> will produce a literal >> instead of creating a link. Would it be better to treat triples as notation? Or preserve them?

Personal Knowledge Graphs (such as Roam) use [[reference]] in their markdown, so there is potentially a notation overlap. It seems unlikely that this overlap would affect users in any way, but it is worth considering whether another grouping operator would be preferable. [[ has the advantage of not requiring a shift modifier to be pressed, but (( or {{ would also be logical choices.

Chaining vs relative to head

Chaining is partially achievable by pressing enter. This isn’t perfect. Consider when entering A>>B as one statement followed by >>C as another statement. Should this chain from B to C or should both A and B be linked to C? It is not clear that either make perfect sense, but probably both is more sensible than one because given A>>B>>C there is no clear good single choice. Creating unwanted links is not a huge deal as they can be deleted, but it is a little sad.

There might be a case for making >> and << be chaining operators, and provide separate relative to head operators like |> and |<. This might be more intuitive, and visually pleasing without sacrificing power. It does introduce the mental overhead of extra operators to remember. Also, the proposed operators are not double characters, making them slower to type.

What about search and auto-complete or select? (TBD)

When working on a large graph sometimes it’s hard to locate a node that you know exists in the graph. Using the browser’s built-in search feature is probably not ideal. To help people locate existing nodes, it would be helpful to have a visual search feature. When typing text into the input box it might be helpful to highlight in the diagram where that text occurs. There could be an auto-completion feature so when a match is unique it will fill with that node. It might be useful to have a select operator at that point? But maybe not if the highlighting and auto-complete is sufficient.

Compatibility with Graphviz (lack of)

Graphviz provides a superior file format. It would be easy to support -> as a synonym for >>. The downside is that it makes the grammar less specific. Adding -> should be considered if there is a desire for this from users.

Graphviz supports undirected links -- which don’t currently have meaning in Hummi. This might be a candidate for future inclusion as bidirectional linkage or undirected linkage.

Graphviz has a property notation which is currently out of scope for Hummi Grammar.

Graphviz can be used as an import/export file format. Support for import/export of other text formats (PlantUML, Mermaid, Drakon) will be added in the future.

Labelling nodes (lack of)

Groups and links can be labeled, but node labelling is currently undefined. For all intents and purposes node text is equivalent to a label. It remains to be seen if it would be useful to have node text and label be separate concepts. If they should be, then it introduces additional ambiguity into the notation. We would need to distinguish between link labels and node labels. It seems fine for the label operator to be restricted to groups and links.

Group selected (lack of)

It might be interesting to make

 [[

Groups currently selected nodes similar to how the other operators work on selected nodes and links. But maybe users should click the Group button instead.