User Guide
===================================

One way to think of Xerblin is as a text editor that uses Joy as a macro language.

When you start the ``xerblin`` script it will present you with a ``StackViewer`` window
and a ``TextViewer`` (text editor) that contains the system log.  Instead of printing
to ``stdout`` Xerblin prints text to the log window.  This text is also written to the
``log.txt`` file in the ``~/.xerblin`` git repo and versioned.

To quit Xerblin close the log window.

Other than editing text files everything else is done by putting things onto the stack
and executing Joy commands.

You execute commands (sometimes called "words" after Forth nomenclature) by right-clicking
on them in any ``TextViewer`` window.  If the word you want isn't in any
window you can always just type it and click on it.  (There are no menus.)

The cursor or caret is set by the left mouse button, however, the selection is set by the right
mouse button.  They are independent of each other, and you can even have the cursor in one
``TextViewer`` and the selection in another.  (This is following the old Oberon OS user
interface.)  It takes a little getting used to, but then it's quite nice.

You can copy text from one place to another with just the mouse buttons.
You can also copy (or cut with the ``shift`` button held down) text to and
from the system stack.

You can middle-click on numbers to put them onto the stack.


Mouse Chords
----------------------------

These are the mouse button chords that Xerblin understands.

Actions take place when you release the buttons. To cancel a chord
click the third mouse button.

+--------+--------+------------------------------------------------+
| First  | Second | Action                                         |
+========+========+================================================+
| Left   |        | Set the insertion caret.                       |
+--------+--------+------------------------------------------------+
| Left   | Middle | Paste from top of stack to caret.              |
|        |        | Hold down shift to also pop the stack.         |
+--------+--------+------------------------------------------------+
| Left   | Right  | Copy selection to caret.                       |
|        |        | Hold down shift to also cut selection.         |
+--------+--------+------------------------------------------------+
| Middle |        | Execute command.                               |
|        |        | Paste selection (bypassing stack).             |
|        |        | Click and drag to scroll.                      |
+--------+--------+------------------------------------------------+
| Middle | Left   | Unassigned.                                    |
+--------+--------+------------------------------------------------+
| Middle | Right  | Print the documentation for a command word     |
|        |        | to the log.                                    |
+--------+--------+------------------------------------------------+
| Right  |        | Start/sweep selection.                         |
+--------+--------+------------------------------------------------+
| Right  | Middle | Copy selection to stack.                       |
|        |        | Hold down shift to also cut selection.         |
+--------+--------+------------------------------------------------+
| Right  | Left   | Copy selection to caret.                       |
|        |        | Hold down shift to also cut selection.         |
+--------+--------+------------------------------------------------+


Keyboard Shortcuts
----------------------------

There are a few built-in keyboard shortcuts.

- ``Control-Enter`` - Run the selection as Joy code, or if there's no selection the line containing the cursor.
- ``F3`` - Copy selection to stack.
- ``Shift-F3`` - Cut selection to stack.
- ``F4`` - Paste item on top of stack to insertion cursor.
- ``Shift-F4`` - Pop and paste top of stack to insertion cursor.

There are some commands bound to keys in the config file:

- ``F5`` - ``swap``
- ``F6`` - ``dup``
- ``Shift-F5`` - ``roll<``
- ``Shift-F6`` - ``roll>``
- ``F7`` - ``over``
- ``Shift-F7`` - ``tuck``
- ``F8`` - ``parse``
- ``F12`` - ``words``
- ``F1`` - ``reset_log show_log``
- ``Escape`` - ``clear reset_log show_log``
- ``Control-Delete`` - ``pop``
- ``Control-i`` - ``i``

You can edit the ``thun.config`` file to change these.


Extending Xerblin
----------------------------

You can add definitions to the current dictionary with the ``inscribe`` command.
These definitions will be forgotten when you quit Xerblin.

TODO: link to reference docs for ``inscribe`` command.

You can add definitions to the ``definitions.txt`` file to make them available
every time you run Xerblin.

TODO: double check that the ``definitions.txt`` file is actually loaded!

Last but not least, you can extend the underlying Thun system with new primitives
to provide additional functionality.


Creating New Documents
----------------------------

> TBD


Opening Documents
----------------------------

> TBD


----------------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`