GNU-devel ELPA - org-real

org-real

Description
Keep track of real things as org-mode links
Latest
org-real-1.0.9.0.20240505.204156.tar (.sig), 2024-May-06, 40.0 KiB
Maintainer
Amy Grinn <grinn.amy@gmail.com>
Atom feed
org-real.xml
Website
https://gitlab.com/grinn.amy/org-real
Browse ELPA's repository
CGit or Gitweb
Badge

To install this package from Emacs, use package-install or list-packages.

Full description

Keep track of real things as org-mode links.

package-install RET org-real RET

1. Usage

1.1. Inserting a link

To create a real link in org-mode, use C-c C-l real RET.

Real links are created inside-out, starting with the most specific item and working to the most general.


┌──────────────────────────────┐
│                              │
│           outside            │
│              ↑               │
│  ┌────────── ↑ ───────────┐  │
│  │           ↑            │  │
│  │           ↑            │  │
│  │           ↑            │  │
│  │  ┌─────── ↑ ────────┐  │  │
│  │  │        ↑         │  │  │
│  │  │      inside      │  │  │
│  │  │                  │  │  │
│  │  └──────────────────┘  │  │
│  │                        │  │
│  └────────────────────────┘  │
│                              │
└──────────────────────────────┘

The first prompt will be for the thing which is trying to be linked to, called the "primary thing". Then, the prompt will continue to ask if more context should be added by pressing + until the user confirms the link with RET.

insert-link.gif

1.2. Inserting a link with completion

Org real will help create links by parsing all existing links in the current buffer. When choosing an existing thing, all of the context for that thing is automatically added to the current completion.

This is only possible because of the unique inside-out completion style for inserting a link and makes it very easy to add new things to an existing container.

insert-link-with-completion.gif

1.3. Rearranging things

In order to edit a real link, place the cursor on the link and press C-c C-l. Narrow the link down beyond the context you wish to change by pressing BACKSPACE repeatedly, then + to add the new context.

edit-link.gif

If any container in the new link does not match an existing container in the buffer, org-real will prompt you to replace all occurences of that thing with the new context and relationships.

This makes it easy to keep things in sync. If any one link changes location, all links in the currnet buffer are updated accordingly.

apply-changes.gif

If a link is changed manually, use the interactive function org-real-apply with the cursor on top of the new link to apply changes from that link to the buffer.

1.4. Opening links

To open a real link, place the cursor within the link and press C-c C-o. This will display a popup buffer in Org Real mode showing the location of the link.

1.5. org-real-world

To view all real links in the current buffer in a combined diagram, use the interactive function org-real-world

Suggested keybinding:

(define-key org-mode-map (kbd "C-c r w") 'org-real-world)

1.6. Boxy mode

Once in boxy mode, you can cycle the visibility level of all children with S-TAB or use TAB to toggle the visibility of children for a single box.

Emacs movement keys will navigate by boxes rather than characters. Each box in the diagram has these keybindings:

  • RET / mouse-1 Jump to first occurrence of link
  • o Cycle occurrences of links in other window
  • M-RET Open all occurences of links by splitting the current window
  • r Jump to the box directly related to the current box
  • TAB expand/collapse children boxes

boxy-mode.gif

2. License

GPLv3

3. Development

3.1. Setup

Install eldev

3.2. Commands:

3.2.1. eldev lint

Lint the org-real.el file

3.2.2. eldev compile

Test whether ELC has any complaints

3.2.3. eldev test

Run all test files in tests/

3.2.4. eldev package

Creates a dist folder with org-real-<version>.el

3.2.5. eldev md5

Creates an md5 checksum against all files in the dist folder.

Old versions

org-real-1.0.8.0.20240503.174325.tar.lz2024-May-048.09 KiB
org-real-1.0.8.0.20240328.105118.tar.lz2024-Mar-318.09 KiB
org-real-1.0.7.0.20231024.111108.tar.lz2023-Oct-248.08 KiB
org-real-1.0.6.0.20221114.84409.tar.lz2022-Nov-148.17 KiB
org-real-1.0.5.0.20220510.111135.tar.lz2022-May-106.79 KiB
org-real-1.0.4.0.20211015.143403.tar.lz2021-Oct-1517.3 KiB
org-real-1.0.3.0.20211013.201859.tar.lz2021-Oct-1317.3 KiB
org-real-1.0.2.0.20211011.34446.tar.lz2021-Oct-1117.5 KiB
org-real-1.0.1.0.20211005.181330.tar.lz2021-Oct-0617.6 KiB