Introduction

Owlograf draws the Dolfin projects you keep in Agrafe as an interactive graph: concepts, properties and how they connect, laid out the way Agrafe’s Graph pane shows them, with the whole window to work in.

You can explore your own projects, the ones shared with you, and public ones; preview a box’s neighbours with the lens; arrange the layout; and, once you allow it, create, rename and edit concepts and properties right on the graph.

The Dolfin language has its own documentation at www.dolfin.fr/docs. Nothing here repeats it.

What is covered

• Signing in with your Agrafe account, and allowing editing.
• Projects: your projects, shared ones, and public ones.
• Reading the graph: what boxes and arrows mean.
  • Moving around: pan, zoom, center.
  • The lens: a box and its direct neighbours in a popup.
  • Previous and Next: step through files and back through your jumps.
• Layout and snap to grid: arrange boxes and keep the arrangement.
• Editing on the graph: create, rename, edit and delete.
• Working alongside Agrafe: live updates and jumping to the source.
• Keyboard, mouse and touch: every gesture on one page.

First steps

1. Press Continue with Agrafe. See Signing in.
2. Pick a project on Your Projects.
3. Hold Shift over a box to see what it connects to.
4. Right-click a box and choose Enable editing… to change the ontology from the graph.

Conventions

• Box: a concept, property or union drawn in the graph.
• File box: the rounded frame grouping the boxes of one source file.
• Menu and button names are written exactly as they appear in the app.
• On a Mac, read ⌘ wherever this book says Ctrl.

Signing in

Owlograf has no accounts of its own: press Continue with Agrafe and sign in with your Agrafe account. No account? Follow Create one. Just looking? Browse public projects needs no account.

You come back to the page you were trying to open, or to Your Projects. Your session lasts 30 days from your last visit and renews on its own; if it ends while a page is open, Owlograf sends you through sign-in and back to the same page.

Sign out, in the top bar, ends the Owlograf session only, not your Agrafe one.

Read first, edit on request

Signing in only lets Owlograf read your projects. Editing the graph needs one more permission, asked only when you want it:

• right-click a box, an arrow or a file box and choose 🔓 Enable editing…, or
• follow Allow editing in the notice at the bottom of the graph.

Agrafe asks you to approve editing, then brings you back to the same graph with the editing menus available. With editing allowed, your layout is also saved to the project in Agrafe.

Sign-in errors

Projects

Your Projects lists the projects you own, in the same folders as in Agrafe (an empty one shows Empty folder), followed by the projects shared with you, each with its owner (by …). Click a card to open its graph.

The Sort control orders the page: Manual (your Agrafe order), Recently opened or Recently modified. The choice lasts until you leave the page.

Owlograf cannot create projects or folders: do that in Agrafe. No projects yet. Create one in Agrafe first. means there is nothing to show yet.

Public projects

Public projects, in the top bar, lists the projects their owners made public, with no sign-in needed. Their graphs are read-only: you can explore them, use the lens and arrange the layout for yourself, but not edit them.

Reading the graph

The graph fills the window below the top bar. Each source file of the project is a file box labelled with its file name; the boxes it declares sit inside. Things declared outside the project are grouped in a dashed box labelled Outside.

Boxes

A concept lists its fields as rows name: Type, followed by the cardinality in brackets when there is one.

Arrows

Several arrows between the same two boxes fan out so you can tell them apart. An arrow from a box to itself is a loop above it.

Descriptions

Hover a box, a field row or an arrow that has a description to read it in a tooltip.

Languages

When the project labels its terms in two languages or more, a selector (Display language) appears at the far left of the top-right controls. Default shows what the Dolfin compiler picked; the other options are the project’s language tags. The choice is remembered in this browser and shared with Agrafe and Pangloss.

The top-right controls

From left to right: the language selector, < and > (Previous and Next), 🔍 (the lens), and the View menu (the round magnifier) with Reset layout, Zoom in, Zoom out and Snap to grid (see Layout and Moving around).

When there is nothing to show

• Loading graph… while Agrafe compiles the project.
• This project has no concepts yet.
• Project not found. The project was deleted, or is no longer shared with you.
• The project’s sources don’t compile: … Fix the errors in Agrafe; the graph appears once they are gone (see Working alongside Agrafe).

Moving around

Pan

Drag the background, with the mouse or one finger. A drag keeps going if the pointer leaves the graph.

Zoom

• Mouse wheel: zooms toward the pointer.
• Zoom in / Zoom out, in the View menu: one step around the center of the view. The menu stays open so you can press again.
• Rectangle zoom: hold Ctrl and drag a rectangle (blue); the view zooms into it. Add Shift (orange rectangle) to zoom out: the current view shrinks into the rectangle.
• Ctrl+click without dragging zooms one step in; Ctrl+Shift+click one step out.
• On a touch screen, pinch with two fingers.

The pointer shows what a click will do: a magnifier with Ctrl held, a question mark with Shift (the lens), a hand over the background, a move cursor over boxes.

Center a box

Right-click a box and choose ◎ Center in view. The view glides to the box, keeping your zoom level. On an arrow, it centers the middle of the arrow.

Start over

Reset layout, in the View menu, puts every box back where Agrafe laid it out and fits the whole graph in the window. See Layout.

Find a box

Hold Shift over a box and click a neighbour in the lens to jump to it, or step file by file with Previous and Next.

The lens

The lens shows one box and the boxes it links to directly, in a small popup next to the pointer. Use it to see what a concept connects to without losing your place in a big graph.

Opening it

• Hold Shift while pointing at a box. While you hold Shift the lens stays put, so you can move the pointer into it.
• Or press 🔍 at the top right (it turns blue), then point at a box, or tap it on a touch screen. The lens stays open while you move across empty graph toward it.

While the lens is open the rest of the graph fades.

What it shows

• The box you pointed at, with a yellow ring.
• Up to 12 neighbours. More collapse into a +N more box.
• Neighbours from the same file in the middle: boxes pointing to it above, boxes it points to below.
• Neighbours from other files on the sides, grouped by file: on the left those that mostly point to it, on the right those it mostly points to.
• Only the field rows that point to the box you are looking at, so each neighbour stays small.

Jumping

Click a box in the lens to center the main graph on it, with a yellow ring around it. The lens closes, unless you still hold Shift, so you can keep hopping from neighbour to neighbour. Each jump is recorded: < takes you back (see Previous and Next).

Closing it

Release Shift, move out of both the graph and the lens, or press 🔍 again.

The lens works on public projects too.

Previous and Next

< and >, at the top right, also on Alt+[ and Alt+], move the view from box to box.

Back through your jumps

After you jump with the lens, < goes back to where you were and > forward again, like a browser’s history. Jumping somewhere new from the middle of the history drops what was ahead.

File by file

When there is no jump to go back or forward to, the buttons step through the files instead: each press goes to the first box of the next (or previous) file, wrapping around at the end. Use it to tour a project file by file.

Each step centers the box and marks it with a yellow ring. Escape clears the ring.

The buttons are greyed out when there is nowhere to go: no history in that direction and at most one file.

Layout and snap to grid

Arranging boxes

• Drag a box to move it.
• Drag the background of a file box to move the whole file at once.

New boxes, such as a concept just created in Agrafe, are placed in free space inside their file box, or just below it when it is full.

Where your layout is kept

Positions and the current view are saved after every move, pan or zoom:

Signed in read-only, the first move shows This layout is saved in this browser only. To share it with Agrafe, allow editing. Follow the link to allow editing.

When you open a graph, an editor gets the project’s layout first; a reader gets the copy from this browser first.

Reset layout

Reset layout, in the View menu, puts every box back where Agrafe’s automatic layout puts it and fits the graph in the window. The reset is saved like any other change: with editing allowed, it resets the shared layout too.

Snap to grid

Snap to grid lines dragged boxes up on a grid the height of one field row. Turn it on or off in the View menu or in any right-click menu; a ✓ shows when it is on, and a faint grid is drawn behind the graph.

Dragging a whole file snaps the box you grabbed by and moves the others with it. Boxes already placed are not re-snapped when you turn it on.

It is off by default, and the choice is remembered in this browser for every project.

Editing on the graph

Once you have allowed editing, right-click menus change the project’s Dolfin source in Agrafe. Each change is saved in Agrafe straight away and the graph redraws. You need edit rights on the project: owner or editor.

Public projects cannot be edited from Owlograf.

Right-click menus

On a concept

• ✏ Edit…: edit its declaration as text.
• 🔤 Rename
• ➕ New sub-concept…
• ↗ Add property…: add a field.
• 🗑 Delete…

On a property: Edit…, Rename, ➕ New sub-property…, Delete…

On a field arrow (thin solid arrow): the same as on a property, for that field: Edit…, Rename, New sub-property…, Delete…

On a file box: ➕ Add concept… and ↗ Add property…, declared in that file.

Every menu also has ◎ Center in view (boxes and arrows) and Snap to grid. Unions and boxes in Outside cannot be edited from the graph.

Drawing properties

Drag to connect: drag the round handle on a box’s right edge onto another box, name the property, and press Enter. Drop it on empty canvas instead to create a new concept there too: name both. On touch, tap a box first to show its handle.

Domain and range: click an arrow’s end, or a union, intersection or complement square, to edit that end’s type as text, with and, or, not and ( ) buttons and concept names suggested as you type. Apply writes it, e.g. ((A or B) and not C).

Combine: Shift+click classes (Shift+drag on the background, or long-press on touch) to select them, then and, or or not beside the View button draws a draft square. Drag a connection from it, or insert it from the domain/range editor: it is written to the source only then. ✕ discards selected drafts. Drafts are lost on reload.

The dialogs

New sub-property… on a field arrow fills Domain and Range with the two concepts the arrow joins.

Enter confirms; in the Edit… source box, Ctrl+Enter. Escape, Cancel or a click outside closes the dialog. If Agrafe refuses the change, the dialog stays open with the reason, so you lose nothing.

Deleting

Delete… asks Remove name from file? and lists the arrows in the graph that point to it and will no longer resolve. Only arrows drawn in the graph are counted: rules, facts and mappings that use the name are not. Check the Problems panel in Agrafe afterwards.

Renaming

Rename turns the box title (or the arrow label) into a text field with the name selected. Enter applies, Escape or a click elsewhere cancels. If Agrafe could not rename every use, a notice at the bottom of the graph says which files it skipped.

Notices

Errors and warnings show at the bottom of the graph. × dismisses them.

Working alongside Agrafe

Owlograf reads the project from Agrafe; Agrafe stays the place where it is written.

Live updates

While a graph is open, Owlograf checks the project every 10 seconds. When someone changes it in Agrafe, or in another Owlograf, the graph redraws with the change, keeping your view and the positions of the boxes already there. It pauses while a dialog or a rename is open, and while the browser tab is hidden.

Jump to definition

Hover a box: ⌖ appears at the right of its title (Jump to definition (line N)). Click it to open Agrafe’s editor in a new tab, at the line that declares it. On a public project it opens the project in Agrafe, read-only.

When the project does not compile

The graph cannot be drawn while the project has errors: the page shows The project’s sources don’t compile: with Agrafe’s message. Fix them in Agrafe; the graph appears on the next check.

Shared settings

The theme (top bar) and the display language are shared with Agrafe and Pangloss. With editing allowed, the layout is shared with Agrafe’s Graph pane.

Other apps

The Apps menu in the top bar switches to the other Dolfin apps, including Pangloss, which shows the same project as a glossary.

Feedback and updates

The Feedback tab on the left edge sends a message to the Dolfin team with a screenshot you can crop. When Owlograf is updated while you have it open, a banner offers Reload.

Keyboard, mouse and touch

Mouse

Keyboard

Graph shortcuts are ignored while you type in a field.

Touch