Commit ed2659f386
Verified · cmc
Layout: unified · split
favicon.svg added +1
| @@ -0,0 +1 @@ | ||
| 1 | <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path fill="#4a7bd0" d="M16 2l3.9 9.1 9.9.9-7.5 6.5 2.3 9.7L16 23.1 7.4 28.2l2.3-9.7L2.2 12l9.9-.9z"/></svg> | |
guide/01-files-and-folders.html added +322
| @@ -0,0 +1,322 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Files, folders and buffers · Orgstar</title> | |
| 7 | <meta name="description" content="Adding folders, opening files, working with buffers, searching, saving, and how Orgstar handles changes made outside it."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Files, folders and buffers</h1> | |
| 24 | <p class="lede">Orgstar works on folders of files you add to its sidebar, keeps each open file in a buffer, saves on its own, and merges changes other programs make to the same files.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#the-window">The window</a> | |
| 29 | <ul> | |
| 30 | <li><a href="#menus-and-the-command-palette">Menus and the command palette</a></li> | |
| 31 | <li><a href="#showing-and-hiding-panes">Showing and hiding panes</a></li> | |
| 32 | </ul></li> | |
| 33 | <li><a href="#folders">Folders</a> | |
| 34 | <ul> | |
| 35 | <li><a href="#adding-a-folder">Adding a folder</a></li> | |
| 36 | <li><a href="#removing-a-folder">Removing a folder</a></li> | |
| 37 | <li><a href="#what-the-sidebar-lists">What the sidebar lists</a></li> | |
| 38 | <li><a href="#creating-renaming-and-trashing-files">Creating, renaming and trashing files</a></li> | |
| 39 | </ul></li> | |
| 40 | <li><a href="#opening-files">Opening files</a> | |
| 41 | <ul> | |
| 42 | <li><a href="#files-that-aren-t-org">Files that aren't org</a></li> | |
| 43 | </ul></li> | |
| 44 | <li><a href="#buffers">Buffers</a> | |
| 45 | <ul> | |
| 46 | <li><a href="#buffer-commands">Buffer commands</a></li> | |
| 47 | <li><a href="#buffer-names">Buffer names</a></li> | |
| 48 | <li><a href="#the-tab-bar">The tab bar</a></li> | |
| 49 | </ul></li> | |
| 50 | <li><a href="#searching-your-notes">Searching your notes</a></li> | |
| 51 | <li><a href="#the-outline-pane">The outline pane</a> | |
| 52 | <ul> | |
| 53 | <li><a href="#backlinks">Backlinks</a></li> | |
| 54 | <li><a href="#inspector">Inspector</a></li> | |
| 55 | </ul></li> | |
| 56 | <li><a href="#saving">Saving</a> | |
| 57 | <ul> | |
| 58 | <li><a href="#how-a-save-works">How a save works</a></li> | |
| 59 | </ul></li> | |
| 60 | <li><a href="#external-changes">External changes</a> | |
| 61 | <ul> | |
| 62 | <li><a href="#conflicts">Conflicts</a></li> | |
| 63 | <li><a href="#syncthing-conflict-copies">Syncthing conflict copies</a></li> | |
| 64 | <li><a href="#recovery-versions">Recovery versions</a></li> | |
| 65 | <li><a href="#icloud">iCloud</a></li> | |
| 66 | </ul></li> | |
| 67 | <li><a href="#encodings-and-line-endings">Encodings and line endings</a></li> | |
| 68 | <li><a href="#on-ios">On iOS</a></li> | |
| 69 | </ul> | |
| 70 | </nav> | |
| 71 | <h2 id="the-window">The window</h2> | |
| 72 | <p>Orgstar has one main window, titled with the name of the buffer it shows. From left to right it holds:</p> | |
| 73 | <ul> | |
| 74 | <li>the <strong>sidebar</strong>, listing the folders you added and the files in them;</li> | |
| 75 | <li>the <strong>outline pane</strong>, listing the headings of the open file, with the <strong>backlinks pane</strong> under it;</li> | |
| 76 | <li>the <strong>editor</strong>, with the optional tab bar above it and the modeline and echo area below it;</li> | |
| 77 | <li>the <strong>inspector</strong>, hidden by default, showing column view and clocked time.</li> | |
| 78 | </ul> | |
| 79 | <p>The toolbar holds a button that shows or hides the outline pane, a progress indicator while Orgstar indexes your folders, the running clock (see <a href="06-dates-and-clocking.html">Dates and clocking</a>), a <code class="verbatim">Conflict</code> button when the open file has a conflict (see <em>Conflicts</em> below), and the search field.</p> | |
| 80 | <p>The window title is the buffer name (see <em>Buffer names</em> below). When the open file is not UTF-8, the subtitle reads <code class="verbatim">Read-only: not UTF-8</code>. The close button shows the unsaved-changes dot while any open buffer has unsaved edits.</p> | |
| 81 | <p>With no folders added, the editor area reads "Add a folder of org files". With folders but no open file, it reads "Choose a file" and suggests <code class="verbatim">⌘P</code>.</p> | |
| 82 | <p>The Agenda, Board, Clock Report and Capture windows are separate; they are covered in <a href="07-agenda.html">Agenda</a>, <a href="06-dates-and-clocking.html">Dates and clocking</a> and <a href="08-capture.html">Capture</a>. Closing the main window quits Orgstar when no other window is open.</p> | |
| 83 | <h3 id="menus-and-the-command-palette">Menus and the command palette</h3> | |
| 84 | <p>Most commands are in the menu bar. The <code class="verbatim">Org</code> menu lists every org command, each with the keys that run it in the current keymap; it is disabled when no file is open.</p> | |
| 85 | <p>File ▸ Command Palette… (<code class="verbatim">⇧⌘P</code>; <code class="verbatim">M-x</code> in the Emacs and Doom presets; <code class="verbatim">SPC :</code> in Doom normal state) lists every command by title with its keys. Type to filter (characters match in order, as in Quick Open), then press <code class="verbatim">Return</code> to run the top match or click one. <code class="verbatim">Escape</code> closes it. Text movement and editing commands (forward character, kill line and so on) are not listed; they are only on keys.</p> | |
| 86 | <p>Several commands in this chapter are only in the palette, not in a menu: Close Other Buffers, Close All Buffers, Last Buffer, Show or Hide Tab Bar, Revert to File on Disk, Resolve Sync Conflicts… and Recovery Versions….</p> | |
| 87 | <h3 id="showing-and-hiding-panes">Showing and hiding panes</h3> | |
| 88 | <table> | |
| 89 | <thead> | |
| 90 | <tr><th>Menu item</th><th>Shortcut</th><th>Palette title</th></tr> | |
| 91 | </thead> | |
| 92 | <tbody> | |
| 93 | <tr><td>View ▸ Show or Hide Outline</td><td><code class="verbatim">⌥⌘O</code></td><td>Show or Hide Outline</td></tr> | |
| 94 | <tr><td>View ▸ Show or Hide Backlinks</td><td></td><td>Show or Hide Backlinks</td></tr> | |
| 95 | <tr><td>View ▸ Show or Hide Columns and Clock</td><td><code class="verbatim">⌥⌘I</code></td><td>Show or Hide Columns and Clock</td></tr> | |
| 96 | <tr><td>View ▸ Show Tab Bar</td><td></td><td>Show or Hide Tab Bar</td></tr> | |
| 97 | </tbody> | |
| 98 | </table> | |
| 99 | <p>The toolbar's outline button does the same as View ▸ Show or Hide Outline. The sidebar is shown and hidden with the standard View menu command.</p> | |
| 100 | <p>Orgstar remembers whether the outline, backlinks and inspector are shown. The outline pane's visibility is remembered for org files only: for other files it starts hidden each time you open one. Drag the divider on the outline pane's right edge to resize it (160 to 400 points; 220 by default).</p> | |
| 101 | <h2 id="folders">Folders</h2> | |
| 102 | <p>Orgstar does not open a single folder like a project. You add any number of folders, called roots, and each appears as a section of the sidebar. Orgstar indexes every org file in them for search, the agenda, refiling, backlinks and IDs.</p> | |
| 103 | <h3 id="adding-a-folder">Adding a folder</h3> | |
| 104 | <p>Choose File ▸ Add Folder… (<code class="verbatim">⇧⌘O</code>), or click <code class="verbatim">+</code> at the bottom of the sidebar, and pick a folder. Orgstar indexes it in the background; the toolbar shows a progress indicator while it works.</p> | |
| 105 | <p>Orgstar keeps a bookmark to each folder, so a folder you move or rename in Finder is followed. If a folder can't be found at launch, Orgstar reports <code class="verbatim">Can't find the folder PATH.</code> Adding a folder that is already in the sidebar does nothing.</p> | |
| 106 | <p>Orgstar keeps the list of folders, the index and recovery versions in <code class="verbatim">~/Library/Application Support/Orgstar</code>.</p> | |
| 107 | <h3 id="removing-a-folder">Removing a folder</h3> | |
| 108 | <p>Click <code class="verbatim">−</code> at the bottom of the sidebar and choose the folder, or right-click the folder's header and choose Remove from Sidebar…. Confirm with <code class="verbatim">Remove</code>. The folder and its files stay on disk; only Orgstar's index entries for them are removed.</p> | |
| 109 | <h3 id="what-the-sidebar-lists">What the sidebar lists</h3> | |
| 110 | <p>Each root is a collapsible section headed by the folder's name; hover over the name to see its full path. Roots are sorted by path. Inside a root, subfolders come first, then files, each sorted by name the way Finder sorts them. Orgstar remembers which roots you collapsed.</p> | |
| 111 | <p>The sidebar lists every file in the folder, not only org files, with an icon for its kind:</p> | |
| 112 | <table> | |
| 113 | <thead> | |
| 114 | <tr><th>Icon</th><th>File</th></tr> | |
| 115 | </thead> | |
| 116 | <tbody> | |
| 117 | <tr><td>document</td><td><code class="verbatim">.org</code></td></tr> | |
| 118 | <tr><td>archive box</td><td><code class="verbatim">.org_archive</code></td></tr> | |
| 119 | <tr><td>orange warning sign</td><td>a Syncthing conflict copy (see <em>Syncthing conflict copies</em> below)</td></tr> | |
| 120 | <tr><td>photo</td><td>an image</td></tr> | |
| 121 | <tr><td>rich document</td><td>a PDF</td></tr> | |
| 122 | <tr><td>play button</td><td>audio or video</td></tr> | |
| 123 | <tr><td><code class="verbatim"></></code></td><td>source code or a script</td></tr> | |
| 124 | <tr><td>plain document</td><td>other text</td></tr> | |
| 125 | <tr><td>cloud with arrow</td><td>an iCloud file still downloading (see <em>iCloud</em> below)</td></tr> | |
| 126 | </tbody> | |
| 127 | </table> | |
| 128 | <p>Some files are never listed or indexed:</p> | |
| 129 | <ul> | |
| 130 | <li>Emacs backups (names ending in <code class="verbatim">~</code>), auto-save files (names starting with <code class="verbatim">#</code>) and lock files (<code class="verbatim">.#name</code>);</li> | |
| 131 | <li>Syncthing's temporary files (<code class="verbatim">.syncthing.*</code>);</li> | |
| 132 | <li>Orgstar's own temporary files (names containing <code class="verbatim">.orgstar-</code>);</li> | |
| 133 | <li><code class="verbatim">.DS_Store</code> and <code class="verbatim">.localized</code>;</li> | |
| 134 | <li>anything inside these folders: <code class="verbatim">.git</code>, <code class="verbatim">.hg</code>, <code class="verbatim">.svn</code>, <code class="verbatim">.jj</code>, <code class="verbatim">.bzr</code>, <code class="verbatim">.stfolder</code>, <code class="verbatim">.stversions</code>, <code class="verbatim">.Trash</code>, <code class="verbatim">.Spotlight-V100</code>, <code class="verbatim">.fseventsd</code>, <code class="verbatim">.build</code>, <code class="verbatim">.venv</code>, <code class="verbatim">.cache</code>, <code class="verbatim">.tox</code>, <code class="verbatim">.mypy_cache</code>, <code class="verbatim">.pytest_cache</code>, <code class="verbatim">.gradle</code>, <code class="verbatim">.next</code>, <code class="verbatim">.terraform</code> and <code class="verbatim">node_modules</code>.</li> | |
| 135 | </ul> | |
| 136 | <p>Other dotfiles and dot folders are listed unless you turn off Settings ▸ General ▸ Show hidden files and folders (on by default). To change the list of ignored folders, set <code class="verbatim">ignored-folders</code> in <code class="verbatim">config.toml</code> to folder names separated by spaces; there is no control for it in Settings. See <a href="13-configuration.html">Configuration</a>.</p> | |
| 137 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">orgstar</span><span class="punctuation definition table toml">]</span> | |
| 138 | <span class="variable other key toml">show-hidden-files</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span> | |
| 139 | <span class="variable other key toml">ignored-folders</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>.git .hg node_modules build<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 140 | <p>Only org files (<code class="verbatim">.org</code> and <code class="verbatim">.org_archive</code>) are read by the index. Other files are listed and can be opened, but their contents are not searched.</p> | |
| 141 | <h3 id="creating-renaming-and-trashing-files">Creating, renaming and trashing files</h3> | |
| 142 | <p>Right-click a file or folder in the sidebar for:</p> | |
| 143 | <ul> | |
| 144 | <li>New File… — creates a file in that folder (for a file, in the folder holding it). A name without an extension gets <code class="verbatim">.org</code>. A name like <code class="verbatim">projects/house</code> creates the <code class="verbatim">projects</code> folder too. Names can't start with <code class="verbatim">/</code> or contain <code class="verbatim">..</code>. The new file opens.</li> | |
| 145 | <li>Rename… — renames the file or folder in place. The new name can't contain <code class="verbatim">/</code>. Open buffers of the file, or of files inside the folder, are saved first (in explicit save mode you are asked) and reopened under the new path.</li> | |
| 146 | <li>Show in Finder.</li> | |
| 147 | <li>Move to Trash… — moves the file or folder to the Trash after you confirm. Open buffers of it close without saving; the confirmation warns you when the file, or an open file inside the folder, has unsaved changes. You can put it back from the Trash in Finder.</li> | |
| 148 | </ul> | |
| 149 | <p>Right-click a root's header for New File…, Expand or Collapse, Show in Finder and Remove from Sidebar….</p> | |
| 150 | <h2 id="opening-files">Opening files</h2> | |
| 151 | <p>Click a file in the sidebar to open it. Other ways:</p> | |
| 152 | <ul> | |
| 153 | <li><strong>Quick Open</strong>: File ▸ Quick Open… (<code class="verbatim">⌘P</code>; <code class="verbatim">C-x C-f</code> in the Emacs and Doom presets; <code class="verbatim">SPC SPC</code>, <code class="verbatim">SPC .</code> or <code class="verbatim">SPC f f</code> in Doom normal state). Type part of a file's path below its root. Characters match in order, not necessarily next to each other; matches at the start of a word and runs of consecutive characters rank higher, and shorter paths win ties. Up to 50 matches show, with each file's name and path. The top match is selected; <code class="verbatim">↑</code> and <code class="verbatim">↓</code>, or <code class="verbatim">C-p</code> and <code class="verbatim">C-n</code>, move the selection. Press <code class="verbatim">Return</code> to open the selected match or click any match; <code class="verbatim">Escape</code> closes the list. Syncthing conflict copies are left out.</li> | |
| 154 | <li><strong>Finder</strong>: open an org file from Finder, with <code class="verbatim">open file.org</code> in Terminal, or by dropping it on Orgstar's Dock icon. Orgstar registers as the default app for org files and as an alternative editor for plain text. Each file opens as a buffer.</li> | |
| 155 | <li><strong>Links</strong>: following a <code class="verbatim">file:</code> link or an ID link opens the target file; see <a href="09-links.html">Links</a>.</li> | |
| 156 | <li><strong>Doom ex command</strong>: <code class="verbatim">:e FILE</code> opens <code class="verbatim">FILE</code>, relative to the current file's folder; <code class="verbatim">~</code> is expanded. A file that doesn't exist is reported as <code class="verbatim">No file FILE</code>.</li> | |
| 157 | </ul> | |
| 158 | <p>A file opened from Finder or by a link does not have to be inside one of your folders. Such a file is edited and saved normally, but it isn't listed in the sidebar, isn't indexed for search or the agenda, and isn't watched for outside changes (Orgstar still merges outside changes when it saves; see <em>Saving</em> below).</p> | |
| 159 | <p>Orgstar has no Open Recent menu. Instead, it reopens the buffers that were open when you quit, in the same order, with the same file showing and each caret where you left it. Files that no longer exist are skipped.</p> | |
| 160 | <h3 id="files-that-aren-t-org">Files that aren't org</h3> | |
| 161 | <p>How a file opens depends on what it is:</p> | |
| 162 | <ul> | |
| 163 | <li><strong>Org files</strong> (<code class="verbatim">.org</code>, <code class="verbatim">.org_archive</code>) open in the editor with org editing.</li> | |
| 164 | <li><strong>Text files</strong> open in the same editor as plain text. A file counts as text when macOS knows its type as text, or, for unknown types, when its first 8 KB are valid UTF-8 with no NUL bytes. Org commands report <code class="verbatim">Not an org file</code>, and the outline pane shows "No outline" when you turn it on. Files in these languages get syntax highlighting: shell (<code class="verbatim">.sh</code>, <code class="verbatim">.bash</code>, <code class="verbatim">.zsh</code>, <code class="verbatim">.zshrc</code>, <code class="verbatim">.bashrc</code>, <code class="verbatim">.profile</code>), Python, Emacs Lisp, C, C++, R, JavaScript, Java, Scheme, Clojure, Haskell, Rust, Go, Ruby, JSON, YAML, TOML and Lua.</li> | |
| 165 | <li><strong>Everything else</strong> (images, PDFs, audio, video, archives, binary files) shows a Quick Look preview in place of the editor, with <code class="verbatim">Open with Default App</code> and <code class="verbatim">Show in Finder</code> buttons below it. The preview is not a buffer.</li> | |
| 166 | </ul> | |
| 167 | <p>Text files from Finder use Orgstar only if you choose it with Open With, since Orgstar is not their default app.</p> | |
| 168 | <h2 id="buffers">Buffers</h2> | |
| 169 | <p>Each open file is a buffer, as in Emacs. A buffer keeps its text, caret, folds, undo history and unsaved edits while another buffer is showing. Opening a file that already has a buffer shows that buffer. Two paths to the same file (through a symbolic link, for example) share one buffer, as <code class="verbatim">find-buffer-visiting</code> does.</p> | |
| 170 | <p>A new buffer is placed after the current one in the buffer order. Next and Previous Buffer follow that order and wrap around. Switch to Buffer and Last Buffer follow the order in which you last showed buffers.</p> | |
| 171 | <h3 id="buffer-commands">Buffer commands</h3> | |
| 172 | <table> | |
| 173 | <thead> | |
| 174 | <tr><th>Command</th><th>Menu, or palette</th><th>Mac</th><th>Emacs preset</th><th>Doom (normal state)</th></tr> | |
| 175 | </thead> | |
| 176 | <tbody> | |
| 177 | <tr><td>Switch to Buffer…</td><td>Window ▸ Switch to Buffer…</td><td></td><td><code class="verbatim">C-x b</code>, <code class="verbatim">C-x C-b</code></td><td><code class="verbatim">SPC b b</code>, <code class="verbatim">SPC b B</code>, <code class="verbatim">SPC ,</code>, <code class="verbatim">:b</code>, <code class="verbatim">:ls</code></td></tr> | |
| 178 | <tr><td>Next Buffer</td><td>Window ▸ Next Buffer</td><td><code class="verbatim">⇧⌘]</code>, <code class="verbatim">⌃Tab</code></td><td><code class="verbatim">⇧⌘]</code>, <code class="verbatim">C-x <right></code></td><td><code class="verbatim">SPC b n</code>, <code class="verbatim">SPC b ]</code>, <code class="verbatim">] b</code>, <code class="verbatim">:bn</code></td></tr> | |
| 179 | <tr><td>Previous Buffer</td><td>Window ▸ Previous Buffer</td><td><code class="verbatim">⇧⌘[</code>, <code class="verbatim">⌃⇧Tab</code></td><td><code class="verbatim">⇧⌘[</code>, <code class="verbatim">C-x <left></code></td><td><code class="verbatim">SPC b p</code>, <code class="verbatim">SPC b [</code>, <code class="verbatim">[ b</code>, <code class="verbatim">:bp</code></td></tr> | |
| 180 | <tr><td>Last Buffer</td><td>palette</td><td></td><td></td><td><code class="verbatim">SPC `</code></td></tr> | |
| 181 | <tr><td>Close Buffer</td><td>File ▸ Close Buffer</td><td><code class="verbatim">⌘W</code></td><td><code class="verbatim">⌘W</code>, <code class="verbatim">C-x k</code></td><td><code class="verbatim">SPC b k</code>, <code class="verbatim">SPC b d</code>, <code class="verbatim">:bd</code></td></tr> | |
| 182 | <tr><td>Close Other Buffers</td><td>palette</td><td></td><td></td><td><code class="verbatim">SPC b O</code></td></tr> | |
| 183 | <tr><td>Close All Buffers</td><td>palette</td><td></td><td></td><td><code class="verbatim">SPC b K</code></td></tr> | |
| 184 | </tbody> | |
| 185 | </table> | |
| 186 | <p>Menu shortcuts (<code class="verbatim">⇧⌘]</code>, <code class="verbatim">⌘W</code> and the others) work in every preset. The Doom preset also has the Emacs preset's <code class="verbatim">C-x</code> keys in every state. The Mac preset's <code class="verbatim">⌃Tab</code> and <code class="verbatim">⌃⇧Tab</code> are in addition to the menu shortcuts.</p> | |
| 187 | <p>Switch to Buffer asks in the echo area. The choices are the open buffers, most recently shown first, with the current buffer last. Type to narrow them, <code class="verbatim">Tab</code> to complete the top choice, <code class="verbatim">Return</code> to switch, <code class="verbatim">Escape</code> to cancel.</p> | |
| 188 | <p>Close Buffer closes the current buffer and shows the buffer you showed before it. With no buffer open, <code class="verbatim">⌘W</code> closes the window. In other windows (Agenda, Board and so on) <code class="verbatim">⌘W</code> closes that window. File ▸ Close Window (<code class="verbatim">⇧⌘W</code>) closes the window in front.</p> | |
| 189 | <p>When you close buffers with unsaved edits, what happens depends on the save mode (see <em>Saving</em> below): in automatic mode they are saved first; in explicit mode Orgstar asks <code class="verbatim">Save</code>, <code class="verbatim">Don't Save</code> or <code class="verbatim">Cancel</code> (<code class="verbatim">Save All</code> for several files). A buffer whose save fails or conflicts stays open.</p> | |
| 190 | <h3 id="buffer-names">Buffer names</h3> | |
| 191 | <p>A buffer is named after its file. When two open files have the same name, each name gets as many of its folders as it takes to tell them apart, in angle brackets, as Emacs's uniquify does with <code class="verbatim">post-forward-angle-brackets</code>:</p> | |
| 192 | <pre><code class="language-text">notes.org<work> | |
| 193 | notes.org<home> | |
| 194 | notes.org<archive/2024></code></pre> | |
| 195 | <p>These names show in the window title, the tab bar and Switch to Buffer.</p> | |
| 196 | <h3 id="the-tab-bar">The tab bar</h3> | |
| 197 | <p>View ▸ Show Tab Bar shows a row of tabs above the editor, one per open buffer, in buffer order. It is off by default; the setting is <code class="verbatim">tab-bar</code> in <code class="verbatim">config.toml</code>.</p> | |
| 198 | <ul> | |
| 199 | <li>Click a tab to show its buffer. Hover to see the file's full path.</li> | |
| 200 | <li>Click <code class="verbatim">×</code> to close a buffer. A dot replaces the <code class="verbatim">×</code> while the buffer has unsaved edits; clicking it also closes the buffer, with the same unsaved-changes handling as Close Buffer.</li> | |
| 201 | </ul> | |
| 202 | <h2 id="searching-your-notes">Searching your notes</h2> | |
| 203 | <p>The search field in the toolbar searches every org file in your folders. Click it or choose Edit ▸ Search Notes (<code class="verbatim">⇧⌘F</code>; <code class="verbatim">SPC /</code> or <code class="verbatim">SPC s p</code> in Doom normal state) and type.</p> | |
| 204 | <p>While the field holds text, the outline pane shows the results in place of the outline. Each result is a heading, with its file's name below it. Click a result to open the file at that heading. Clear the field to get the outline back.</p> | |
| 205 | <p>How matching works:</p> | |
| 206 | <ul> | |
| 207 | <li>Orgstar searches heading titles and the text under each heading, in <code class="verbatim">.org</code> and <code class="verbatim">.org_archive</code> files. Text before the first heading and files that aren't org are not searched. Syncthing conflict copies are not searched.</li> | |
| 208 | <li>Each word you type matches words that start with it: <code class="verbatim">proj</code> finds <code class="verbatim">project</code> and <code class="verbatim">projection</code>.</li> | |
| 209 | <li>Every word must match within the same heading.</li> | |
| 210 | <li>Up to 50 results show, best matches first.</li> | |
| 211 | <li>Open buffers with unsaved edits are searched as they are in the buffer, not as they are on disk.</li> | |
| 212 | </ul> | |
| 213 | <p>To find text inside the open file, use Edit ▸ Find (see <a href="02-the-editor.html">The editor</a>).</p> | |
| 214 | <h2 id="the-outline-pane">The outline pane</h2> | |
| 215 | <p>The outline pane lists the headings of the open org file, indented by level. Headings without a title show as <code class="verbatim">(untitled)</code>. Click a heading to move the caret to it; folded headings around it unfold. A file without headings shows "No headings"; a file that isn't org shows "No outline".</p> | |
| 216 | <p>The outline follows your edits after a short pause in typing.</p> | |
| 217 | <h3 id="backlinks">Backlinks</h3> | |
| 218 | <p>Under the outline, the backlinks pane lists headings in your folders that link to the current file (a link before a file's first heading is listed under the file's name) (<code class="verbatim">Links to this file</code>) and to the heading at the caret (<code class="verbatim">Links to</code> followed by the heading's title). It updates as you move the caret. Click an entry to open it. Turn the pane off with View ▸ Show or Hide Backlinks. Which links count is covered in <a href="09-links.html">Links</a>.</p> | |
| 219 | <h3 id="inspector">Inspector</h3> | |
| 220 | <p>View ▸ Show or Hide Columns and Clock (<code class="verbatim">⌥⌘I</code>) opens a pane on the right with column view and clocked time for the file or the current subtree. See <a href="04-outlines.html">Outlines</a> and <a href="06-dates-and-clocking.html">Dates and clocking</a>.</p> | |
| 221 | <h2 id="saving">Saving</h2> | |
| 222 | <p>Settings ▸ General ▸ Save files has two modes; the <code class="verbatim">config.toml</code> setting is <code class="verbatim">save</code> in <code class="verbatim">[orgstar]</code>.</p> | |
| 223 | <ul> | |
| 224 | <li><strong>Automatically, when typing stops</strong> (<code class="verbatim">automatic</code>, the default). Each buffer saves one second after its last change, including buffers that are not showing. Quitting and closing buffers save without asking.</li> | |
| 225 | <li><strong>Only with File ▸ Save (⌘S)</strong> (<code class="verbatim">explicit</code>). Nothing is written until you save. Closing a buffer or quitting with unsaved edits asks first.</li> | |
| 226 | </ul> | |
| 227 | <table> | |
| 228 | <thead> | |
| 229 | <tr><th>Command</th><th>Menu</th><th>Shortcut</th><th>Emacs preset</th><th>Doom</th></tr> | |
| 230 | </thead> | |
| 231 | <tbody> | |
| 232 | <tr><td>Save</td><td>File ▸ Save</td><td><code class="verbatim">⌘S</code></td><td><code class="verbatim">C-x C-s</code></td><td><code class="verbatim">SPC f s</code>, <code class="verbatim">SPC b s</code>, <code class="verbatim">:w</code>; <code class="verbatim">:wq</code> and <code class="verbatim">:x</code> save and close the window</td></tr> | |
| 233 | <tr><td>Save All</td><td>File ▸ Save All</td><td><code class="verbatim">⌥⌘S</code></td><td><code class="verbatim">C-x s</code></td><td><code class="verbatim">SPC b S</code></td></tr> | |
| 234 | </tbody> | |
| 235 | </table> | |
| 236 | <p>Save is disabled for a read-only file. Save All is disabled when nothing is unsaved.</p> | |
| 237 | <p>The modeline shows a dot while the current buffer has unsaved edits. Buffers with unsaved edits show a dot in the tab bar.</p> | |
| 238 | <h3 id="how-a-save-works">How a save works</h3> | |
| 239 | <p>Orgstar does not assume it is the only program writing your files. Emacs, Syncthing, iCloud and Git may change them too. Each save:</p> | |
| 240 | <ol> | |
| 241 | <li>Reads the file on disk. If it has changed since Orgstar last read or wrote it, Orgstar merges those changes into the buffer first (see <em>External changes</em> below). If they conflict with yours, nothing is written and the buffer has a conflict.</li> | |
| 242 | <li>Checks the file again, then writes the buffer to a temporary file in the same folder and replaces the original with it, so the file is never half-written.</li> | |
| 243 | <li>Reads the file back. If another program wrote it at the same moment, the version that lost goes to recovery and the other program's changes are merged where possible.</li> | |
| 244 | </ol> | |
| 245 | <p>Every version a save displaces goes to recovery first (see <em>Recovery versions</em> below). Reads and writes go through macOS file coordination, so iCloud and other coordinating programs see a consistent file.</p> | |
| 246 | <p>A save keeps the file's encoding details: a UTF-8 byte order mark stays, and text you didn't change keeps its exact bytes, including CRLF line endings. Lines you add end in LF.</p> | |
| 247 | <h2 id="external-changes">External changes</h2> | |
| 248 | <p>Orgstar watches the files in your folders. When a file with an open buffer changes on disk:</p> | |
| 249 | <ul> | |
| 250 | <li>If the buffer has no unsaved edits, it reloads. The caret and folds stay where they were, mapped through the change.</li> | |
| 251 | <li>If the buffer has unsaved edits, Orgstar merges the change into the buffer line by line, against the version both started from. Lines changed on one side take that side; lines changed the same way on both sides are taken once. The merged buffer still has unsaved edits and saves as usual.</li> | |
| 252 | <li>If both sides changed the same lines differently, the buffer has a conflict.</li> | |
| 253 | </ul> | |
| 254 | <p>Reloading or merging clears the buffer's undo history.</p> | |
| 255 | <p>If an open file is deleted on disk, its buffer stays open with its text. Saving it writes the file again.</p> | |
| 256 | <p>To throw away your unsaved edits and load the file as it is on disk, run Revert to File on Disk from the palette (<code class="verbatim">:e</code> in Doom). Your edits go to recovery.</p> | |
| 257 | <h3 id="conflicts">Conflicts</h3> | |
| 258 | <p>When a buffer conflicts with its file, automatic saving stops for that buffer, the <code class="verbatim">Conflict</code> button appears in the toolbar, and the conflict sheet opens. The sheet shows the differences: lines marked <code class="verbatim">-</code> are on disk, lines marked <code class="verbatim">+</code> are in your version, with three lines of context around each change. Choose:</p> | |
| 259 | <table> | |
| 260 | <thead> | |
| 261 | <tr><th>Button</th><th>What it does</th></tr> | |
| 262 | </thead> | |
| 263 | <tbody> | |
| 264 | <tr><td>Keep Mine</td><td>Writes your version over the file. The disk version goes to recovery. This is the default button.</td></tr> | |
| 265 | <tr><td>Use Disk Version</td><td>Loads the file as it is on disk. Your version goes to recovery.</td></tr> | |
| 266 | <tr><td>Merge with Markers</td><td>Puts both sets of changes in the buffer, as <code class="verbatim">git merge</code> leaves a conflict: non-conflicting changes merged, conflicting lines between markers. Your version as it was goes to recovery.</td></tr> | |
| 267 | <tr><td>Decide Later</td><td>Closes the sheet. The conflict stays; click <code class="verbatim">Conflict</code> in the toolbar to reopen it.</td></tr> | |
| 268 | </tbody> | |
| 269 | </table> | |
| 270 | <p>After Merge with Markers the buffer holds blocks like this, which you edit and save:</p> | |
| 271 | <pre><code class="language-text"><<<<<<< yours | |
| 272 | - [ ] Call the plumber on Monday | |
| 273 | ======= | |
| 274 | - [X] Call the plumber | |
| 275 | >>>>>>> disk</code></pre> | |
| 276 | <p>While a conflict is unresolved, saving that buffer does nothing except reopen the sheet.</p> | |
| 277 | <h3 id="syncthing-conflict-copies">Syncthing conflict copies</h3> | |
| 278 | <p>When two devices change a file before Syncthing syncs them, Syncthing keeps one version as a conflict copy beside the file, named like <code class="verbatim">notes.sync-conflict-20260301-142233-ABCDEF7.org</code>. Orgstar lists these in the sidebar in orange with a warning icon, and leaves them out of search, the agenda, ID lookup and Quick Open.</p> | |
| 279 | <p>When you open a file that has conflict copies, the echo area says how many there are. Run Resolve Sync Conflicts… from the palette to compare them. Pick a copy from the menu at the top; lines marked <code class="verbatim">-</code> are in the file (as the buffer holds it) and lines marked <code class="verbatim">+</code> are in the copy. Then choose:</p> | |
| 280 | <table> | |
| 281 | <thead> | |
| 282 | <tr><th>Button</th><th>What it does</th></tr> | |
| 283 | </thead> | |
| 284 | <tbody> | |
| 285 | <tr><td>Keep File</td><td>Leaves the buffer as it is.</td></tr> | |
| 286 | <tr><td>Use Copy</td><td>Replaces the buffer's text with the copy's.</td></tr> | |
| 287 | <tr><td>Merge with Markers</td><td>Puts every difference between the buffer and the copy between conflict markers, labelled with the two file names. There is no common base to merge against, so every difference is marked.</td></tr> | |
| 288 | </tbody> | |
| 289 | </table> | |
| 290 | <p>Each choice moves the copy to recovery and deletes it from the folder. The buffer changes as an edit you can undo, and is saved according to your save mode. When no copies are left the sheet closes.</p> | |
| 291 | <h3 id="recovery-versions">Recovery versions</h3> | |
| 292 | <p>Whenever Orgstar replaces a version of a file, it keeps a copy: your buffer when you take the disk version, the disk version when you keep yours, a version another program wrote while Orgstar saved, and resolved Syncthing copies. Orgstar keeps the last 20 versions per file in <code class="verbatim">~/Library/Application Support/Orgstar/Recovery</code>.</p> | |
| 293 | <p>Run Recovery Versions… from the palette to see the open file's versions, newest first, each with its date and why it was kept:</p> | |
| 294 | <table> | |
| 295 | <thead> | |
| 296 | <tr><th>Label</th><th>Meaning</th></tr> | |
| 297 | </thead> | |
| 298 | <tbody> | |
| 299 | <tr><td>Your version, replaced</td><td>Your buffer, before it was replaced</td></tr> | |
| 300 | <tr><td>Disk version, replaced</td><td>The file on disk, before Orgstar wrote over it</td></tr> | |
| 301 | <tr><td>Sync conflict copy</td><td>A Syncthing conflict copy you resolved</td></tr> | |
| 302 | </tbody> | |
| 303 | </table> | |
| 304 | <p>Select a version to see how it differs from the buffer (<code class="verbatim">-</code> in the buffer, <code class="verbatim">+</code> in the kept version). <code class="verbatim">Restore</code> puts the kept version's text in the buffer as one edit, which undo reverses; the buffer as it was goes to recovery first. <code class="verbatim">Show in Finder</code> reveals the kept file.</p> | |
| 305 | <h3 id="icloud">iCloud</h3> | |
| 306 | <p>Files in iCloud Drive that aren't downloaded to the Mac show in the sidebar with a cloud icon and grey text, with the tooltip "Downloading from iCloud". Orgstar asks iCloud to download them, and indexes them and lets you open them when they arrive. Files iCloud removes from the Mac to save space keep their index entries until they are back, so search and the agenda still find them.</p> | |
| 307 | <h2 id="encodings-and-line-endings">Encodings and line endings</h2> | |
| 308 | <p>Orgstar edits UTF-8 files, with or without a byte order mark.</p> | |
| 309 | <ul> | |
| 310 | <li>A file that is not valid UTF-8 opens read-only. Its text shows with replacement characters where bytes don't decode, the window subtitle reads <code class="verbatim">Read-only: not UTF-8</code>, the modeline shows <code class="verbatim">Read-only</code>, and commands that would change it report <code class="verbatim">This file is read-only.</code> Orgstar never writes such a file, and refiling or archiving into it is refused.</li> | |
| 311 | <li>A file with a UTF-8 byte order mark keeps it when saved; the modeline shows <code class="verbatim">BOM</code>.</li> | |
| 312 | <li>A file containing CRLF line endings shows <code class="verbatim">CRLF</code> in the modeline. Existing line endings are kept.</li> | |
| 313 | </ul> | |
| 314 | <p>Orgstar does not convert between encodings or line endings.</p> | |
| 315 | <h2 id="on-ios">On iOS</h2> | |
| 316 | <p>The iOS app adds folders from its Folders screen and lists only org files there. Conflicts, Syncthing copies and recovery versions are in the editor's menu. Files are watched through file presenters rather than FSEvents. See <a href="14-ios.html">iOS</a>.</p> | |
| 317 | </main> | |
| 318 | <footer class="site"> | |
| 319 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 320 | </footer> | |
| 321 | </body> | |
| 322 | </html> | |
| \ No newline at end of file | ||
guide/02-the-editor.html added +351
| @@ -0,0 +1,351 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>The editor · Orgstar</title> | |
| 7 | <meta name="description" content="How the editor displays org text, folds it, reports state in the modeline and echo area, completes, checks spelling, pairs brackets, wraps lines and…"> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>The editor</h1> | |
| 24 | <p class="lede">The editor shows an org file as plain text with its markup styled or hidden, folds headings, drawers and blocks the way Org does, and reports position and state in a modeline and echo area below the text.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#what-the-editor-shows">What the editor shows</a> | |
| 29 | <ul> | |
| 30 | <li><a href="#markup">Markup</a></li> | |
| 31 | <li><a href="#styling">Styling</a></li> | |
| 32 | <li><a href="#indentation-and-stars">Indentation and stars</a></li> | |
| 33 | <li><a href="#entities">Entities</a></li> | |
| 34 | <li><a href="#inline-images">Inline images</a></li> | |
| 35 | <li><a href="#what-isn-t-rendered">What isn't rendered</a></li> | |
| 36 | </ul></li> | |
| 37 | <li><a href="#folding">Folding</a> | |
| 38 | <ul> | |
| 39 | <li><a href="#cycling">Cycling</a></li> | |
| 40 | <li><a href="#folding-when-a-file-opens">Folding when a file opens</a></li> | |
| 41 | </ul></li> | |
| 42 | <li><a href="#the-modeline">The modeline</a></li> | |
| 43 | <li><a href="#the-echo-area">The echo area</a> | |
| 44 | <ul> | |
| 45 | <li><a href="#prompts">Prompts</a></li> | |
| 46 | </ul></li> | |
| 47 | <li><a href="#completion">Completion</a></li> | |
| 48 | <li><a href="#electric-pairs">Electric pairs</a></li> | |
| 49 | <li><a href="#spell-checking">Spell checking</a></li> | |
| 50 | <li><a href="#wrapping-and-filling">Wrapping and filling</a></li> | |
| 51 | <li><a href="#view-toggles">View toggles</a> | |
| 52 | <ul> | |
| 53 | <li><a href="#line-numbers">Line numbers</a></li> | |
| 54 | </ul></li> | |
| 55 | <li><a href="#themes">Themes</a></li> | |
| 56 | <li><a href="#undo">Undo</a></li> | |
| 57 | <li><a href="#finding-text-in-a-file">Finding text in a file</a></li> | |
| 58 | <li><a href="#accessibility">Accessibility</a></li> | |
| 59 | </ul> | |
| 60 | </nav> | |
| 61 | <h2 id="what-the-editor-shows">What the editor shows</h2> | |
| 62 | <p>The editor holds the file's text exactly as it is on disk. Styling, hidden markup, indentation and images are display only; none of them change the file.</p> | |
| 63 | <p>Org files open with the caret at the start of the file, as in Emacs. Buffers you had open when you quit reopen with the caret where you left it.</p> | |
| 64 | <h3 id="markup">Markup</h3> | |
| 65 | <p>View ▸ Show Markup (<code class="verbatim">⇧⌘M</code>; palette: Show or Hide Markup) is off by default. While it is off:</p> | |
| 66 | <ul> | |
| 67 | <li>Link brackets and targets are hidden, so <code class="verbatim">[[https://orgmode.org][Org]]</code> shows as an underlined <code class="verbatim">Org</code>, as with <code class="verbatim">org-link-descriptive</code>.</li> | |
| 68 | <li>Emphasis markers (the <code class="verbatim">*</code> of bold, the <code class="verbatim">=</code> of verbatim and so on) are hidden when <code class="verbatim">org-hide-emphasis-markers</code> is on, which is the default.</li> | |
| 69 | <li>Entities and sub- and superscripts are drawn as characters when <code class="verbatim">org-pretty-entities</code> is on, which is the default (see <em>Entities</em> below).</li> | |
| 70 | </ul> | |
| 71 | <p>The line with the caret always shows its markup, so you can edit it. Moving to another line hides it again. Turn Show Markup on to see all markup everywhere. The <code class="verbatim">config.toml</code> setting is <code class="verbatim">show-markup</code> in <code class="verbatim">[orgstar]</code>.</p> | |
| 72 | <p>The two Org options are in Settings ▸ Editing as "Emacs hides emphasis markers (org-hide-emphasis-markers)" and "Emacs shows entities as characters (org-pretty-entities)", and in <code class="verbatim">config.toml</code> as <code class="verbatim">org-hide-emphasis-markers</code> and <code class="verbatim">org-pretty-entities</code>. They also tell Orgstar how wide your Emacs displays text, so tag alignment, table alignment and <code class="verbatim">M-q</code> produce the same file Emacs would. Set them to match your Emacs.</p> | |
| 73 | <h3 id="styling">Styling</h3> | |
| 74 | <ul> | |
| 75 | <li>Headings are bold and coloured by level (eight colours, as <code class="verbatim">org-level-1</code> to <code class="verbatim">org-level-8</code>). Levels 1 to 3 are larger than body text: each level is a step larger than the one below it, and level 4 and deeper are body size. The step is Settings ▸ Appearance ▸ "Headings grow by N pt a level" (1 pt by default, 0 to 8).</li> | |
| 76 | <li>TODO and DONE keywords are bold, in the TODO or DONE colour, or a colour you set for that keyword.</li> | |
| 77 | <li>Priorities, tags, timestamps, comments, keywords (<code class="verbatim">#+TITLE:</code> and the like), planning lines and drawers, block delimiters and tables each have a colour; footnotes, targets, macros and LaTeX share one.</li> | |
| 78 | <li>Bold, italic, underline and strike-through are drawn as such; verbatim and code get their own colour and background.</li> | |
| 79 | <li>Links are underlined.</li> | |
| 80 | <li>Blocks (<code class="verbatim">#+BEGIN_…</code> to <code class="verbatim">#+END_…</code>), dynamic blocks and fixed-width lines are drawn on a shaded band across the whole width of the editor, as Emacs extends the <code class="verbatim">org-block</code> face. Code in src blocks is highlighted for its language (see <a href="11-code-blocks.html">Code blocks</a>).</li> | |
| 81 | <li>A folded heading shows an ellipsis after its line.</li> | |
| 82 | </ul> | |
| 83 | <p>Colours come from the theme and follow the system's light or dark appearance. The font, size and line spacing are in Settings ▸ Appearance; colours are set in <code class="verbatim">config.toml</code>. See <a href="13-configuration.html">Configuration</a>. Use a monospaced font: tags and tables line up by columns.</p> | |
| 84 | <h3 id="indentation-and-stars">Indentation and stars</h3> | |
| 85 | <p>Org files display as <code class="verbatim">org-indent-mode</code> shows them, by default: each heading's body is indented to start one column past its stars, all stars but the last are hidden, and a wrapped heading title continues under the title. The indentation is display only; the file keeps its text at the left margin.</p> | |
| 86 | <p>Body lines that wrap continue under their own text: past leading spaces, and past a list item's bullet and checkbox, as <code class="verbatim">adaptive-wrap</code> does.</p> | |
| 87 | <table> | |
| 88 | <thead> | |
| 89 | <tr><th>Setting</th><th>Default</th><th>What it does</th></tr> | |
| 90 | </thead> | |
| 91 | <tbody> | |
| 92 | <tr><td><code class="verbatim">org-startup-indented</code></td><td>on</td><td>Indent bodies under their headings. <code class="verbatim">#+STARTUP: indent</code> or <code class="verbatim">noindent</code> overrides it per file.</td></tr> | |
| 93 | <tr><td><code class="verbatim">org-hide-leading-stars</code></td><td>off</td><td>Without indentation, show only a heading's last star. <code class="verbatim">#+STARTUP: hidestars</code> or <code class="verbatim">showstars</code> overrides it.</td></tr> | |
| 94 | </tbody> | |
| 95 | </table> | |
| 96 | <p>With both off, headings show all their stars and bodies start at the left margin. Both settings are in <code class="verbatim">config.toml</code> only, and are read when a file opens.</p> | |
| 97 | <h3 id="entities">Entities</h3> | |
| 98 | <p>When <code class="verbatim">org-pretty-entities</code> is on and Show Markup is off:</p> | |
| 99 | <ul> | |
| 100 | <li>An entity such as <code class="verbatim">\alpha</code> or <code class="verbatim">\to</code> is drawn as its character (<code class="verbatim">α</code>, <code class="verbatim">→</code>), taking one column.</li> | |
| 101 | <li><code class="verbatim">x_{1}</code> and <code class="verbatim">x^{2}</code> are drawn lowered and raised, without their markers. Braces are required: <code class="verbatim">x_1</code> is left as typed.</li> | |
| 102 | </ul> | |
| 103 | <p>Entities are left as typed on the caret's line, in comment lines and inside blocks. Sub- and superscripts are left as typed inside emphasis, links and keywords.</p> | |
| 104 | <h3 id="inline-images">Inline images</h3> | |
| 105 | <p>Org ▸ Show or Hide Inline Images (<code class="verbatim">C-c C-x C-v</code> in the Emacs and Doom presets), as <code class="verbatim">org-toggle-inline-images</code> does, draws images in place of their links. The echo area reports how many images it displayed.</p> | |
| 106 | <p>A line shows as an image when it holds nothing but a link to an image file with no description:</p> | |
| 107 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+ATTR_ORG:</span><span class="string unquoted org"> :width 400</span> | |
| 108 | <span class="punctuation definition link org">[[</span><span class="markup underline link org">file:images/diagram.png</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">]</span></span></code></pre> | |
| 109 | <ul> | |
| 110 | <li>Recognised extensions: <code class="verbatim">png</code>, <code class="verbatim">jpg</code>, <code class="verbatim">jpeg</code>, <code class="verbatim">gif</code>, <code class="verbatim">svg</code>, <code class="verbatim">webp</code>, <code class="verbatim">tif</code>, <code class="verbatim">tiff</code>, <code class="verbatim">bmp</code>, <code class="verbatim">heic</code>, <code class="verbatim">avif</code>.</li> | |
| 111 | <li>Paths are relative to the file's folder; <code class="verbatim">~</code> is expanded. Remote URLs are not displayed.</li> | |
| 112 | <li><code class="verbatim">#+ATTR_ORG: :width N</code> sets the width in points. Images are never wider than the editor.</li> | |
| 113 | <li>The link text is hidden while its image shows, except on the caret's line.</li> | |
| 114 | </ul> | |
| 115 | <p>To show images when a file opens, add <code class="verbatim">#+STARTUP: inlineimages</code> to the file, or set <code class="verbatim">org-startup-with-inline-images = true</code> in <code class="verbatim">config.toml</code>. <code class="verbatim">#+STARTUP: noinlineimages</code> turns it off for one file.</p> | |
| 116 | <h3 id="what-isn-t-rendered">What isn't rendered</h3> | |
| 117 | <p>LaTeX fragments and environments are coloured but not rendered as formulas. Images in links that have a description, and images on lines with other text, show as links.</p> | |
| 118 | <h2 id="folding">Folding</h2> | |
| 119 | <p>Headings, drawers and blocks fold as in Org. Folding is display only and isn't saved in the file.</p> | |
| 120 | <h3 id="cycling">Cycling</h3> | |
| 121 | <table> | |
| 122 | <thead> | |
| 123 | <tr><th>Action</th><th>Emacs and Mac presets</th><th>Doom</th><th>Org command</th></tr> | |
| 124 | </thead> | |
| 125 | <tbody> | |
| 126 | <tr><td>Cycle the heading or element at the caret</td><td><code class="verbatim">TAB</code></td><td><code class="verbatim">TAB</code> in normal and visual state</td><td><code class="verbatim">org-cycle</code></td></tr> | |
| 127 | <tr><td>Cycle the whole file</td><td><code class="verbatim">S-TAB</code></td><td><code class="verbatim">S-TAB</code>, <code class="verbatim">z A</code> in normal state; <code class="verbatim">S-TAB</code> in visual state</td><td><code class="verbatim">org-global-cycle</code></td></tr> | |
| 128 | <tr><td>Open or fold the heading</td><td></td><td><code class="verbatim">z a</code> in normal state</td><td><code class="verbatim">+org/toggle-fold</code></td></tr> | |
| 129 | <tr><td>Open the heading one level</td><td></td><td><code class="verbatim">z o</code> in normal state</td><td><code class="verbatim">+org/open-fold</code></td></tr> | |
| 130 | <tr><td>Fold the subtree the caret is in</td><td></td><td><code class="verbatim">z c</code> in normal state</td><td><code class="verbatim">outline-hide-subtree</code></td></tr> | |
| 131 | </tbody> | |
| 132 | </table> | |
| 133 | <p>The titles in the palette and the Org menu are Cycle Visibility, Cycle Global Visibility, Toggle Fold, Open Fold and Close Fold.</p> | |
| 134 | <p>Toggle Fold and Open Fold act on a heading line: a folded heading opens one level, showing its body and its child headings, each folded. On an open heading, Toggle Fold folds it and Open Fold does nothing. Close Fold folds the subtree of the heading the caret is under, from anywhere in it.</p> | |
| 135 | <p><code class="verbatim">TAB</code> on a heading line cycles that heading: folded, then its children, then the whole subtree, then folded again. A heading without children goes straight from folded to open. <code class="verbatim">TAB</code> on the first or last line of a drawer or block folds or opens it; drawer and block folds are kept apart from heading folds, so cycling a heading leaves them as they are. Elsewhere <code class="verbatim">TAB</code> does what it otherwise would: in a table it moves to the next field, and in plain text it inserts a tab.</p> | |
| 136 | <p>In Doom's insert state, <code class="verbatim">TAB</code> and <code class="verbatim">S-TAB</code> on a heading demote and promote it, and on a list item indent and outdent it, as Doom's <code class="verbatim">+org-indent-maybe-h</code> does. Use normal state to fold.</p> | |
| 137 | <p><code class="verbatim">S-TAB</code> cycles the whole file through three states, starting at the first:</p> | |
| 138 | <ol> | |
| 139 | <li>Overview: top-level headings only.</li> | |
| 140 | <li>Contents: every heading, no bodies.</li> | |
| 141 | <li>Show all: everything, with blocks opened. Drawers stay folded.</li> | |
| 142 | </ol> | |
| 143 | <p>Overview and contents also fold drawers before the first heading.</p> | |
| 144 | <p>Clicking a heading's stars cycles that heading, as <code class="verbatim">TAB</code> does on it.</p> | |
| 145 | <p>The caret can't rest in folded text: moving forward into a fold jumps past it, and moving back into one goes to the end of the heading line. Going to a location from the outline pane, search, a link or the agenda opens whatever folds hide it.</p> | |
| 146 | <h3 id="folding-when-a-file-opens">Folding when a file opens</h3> | |
| 147 | <p>With no <code class="verbatim">#+STARTUP</code> visibility option, a file opens with every heading shown. Drawers start folded (<code class="verbatim">org-cycle-hide-drawer-startup</code>, on by default); blocks start open (<code class="verbatim">org-cycle-hide-block-startup</code>, off by default). Both settings are in <code class="verbatim">config.toml</code>.</p> | |
| 148 | <p><code class="verbatim">#+STARTUP</code> options a file can set:</p> | |
| 149 | <table> | |
| 150 | <thead> | |
| 151 | <tr><th>Option</th><th>Effect when the file opens</th></tr> | |
| 152 | </thead> | |
| 153 | <tbody> | |
| 154 | <tr><td><code class="verbatim">overview</code>, <code class="verbatim">fold</code></td><td>Top-level headings only</td></tr> | |
| 155 | <tr><td><code class="verbatim">content</code></td><td>Every heading, no bodies</td></tr> | |
| 156 | <tr><td><code class="verbatim">showall</code>, <code class="verbatim">nofold</code></td><td>Everything</td></tr> | |
| 157 | <tr><td><code class="verbatim">show2levels</code>, <code class="verbatim">show3levels</code>, …</td><td>Headings down to that level, no bodies</td></tr> | |
| 158 | <tr><td><code class="verbatim">showeverything</code></td><td>Everything, including drawers and blocks; <code class="verbatim">VISIBILITY</code> properties are ignored</td></tr> | |
| 159 | <tr><td><code class="verbatim">hidedrawers</code>, <code class="verbatim">nohidedrawers</code></td><td>Fold or open drawers</td></tr> | |
| 160 | <tr><td><code class="verbatim">hideblocks</code>, <code class="verbatim">nohideblocks</code></td><td>Fold or open blocks</td></tr> | |
| 161 | <tr><td><code class="verbatim">indent</code>, <code class="verbatim">noindent</code></td><td>Indent bodies under headings, or not</td></tr> | |
| 162 | <tr><td><code class="verbatim">hidestars</code>, <code class="verbatim">showstars</code></td><td>Hide all stars but the last, or not</td></tr> | |
| 163 | <tr><td><code class="verbatim">inlineimages</code>, <code class="verbatim">noinlineimages</code></td><td>Show image links as images, or not</td></tr> | |
| 164 | <tr><td><code class="verbatim">align</code>, <code class="verbatim">noalign</code></td><td>Align every table, or not (<code class="verbatim">org-startup-align-all-tables</code>)</td></tr> | |
| 165 | <tr><td><code class="verbatim">shrink</code></td><td>Narrow table columns that have width cookies</td></tr> | |
| 166 | </tbody> | |
| 167 | </table> | |
| 168 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+STARTUP:</span><span class="string unquoted org"> content hideblocks</span></span></code></pre> | |
| 169 | <p>When the file sets a visibility (<code class="verbatim">overview</code>, <code class="verbatim">content</code>, <code class="verbatim">showall</code>, <code class="verbatim">showNlevels</code> and the like, but not <code class="verbatim">showeverything</code>), Orgstar then applies each heading's <code class="verbatim">VISIBILITY</code> property and folds subtrees tagged <code class="verbatim">ARCHIVE</code>, as <code class="verbatim">org-cycle-set-visibility-according-to-property</code> and <code class="verbatim">org-cycle-hide-archived-subtrees</code> do. <code class="verbatim">VISIBILITY</code> takes <code class="verbatim">folded</code>, <code class="verbatim">children</code>, <code class="verbatim">content</code> or <code class="verbatim">all</code>:</p> | |
| 170 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Reference | |
| 171 | </span>:PROPERTIES: | |
| 172 | :VISIBILITY: folded | |
| 173 | :END:</span></code></pre> | |
| 174 | <p><code class="verbatim">#+STARTUP</code> options are read from the file and from any <code class="verbatim">#+SETUPFILE</code> it names, and take effect when the file opens. To apply changed options to an open file, close its buffer and open it again.</p> | |
| 175 | <p>Narrowing to a subtree or block, and sparse trees, also hide text; see <a href="04-outlines.html">Outlines</a>.</p> | |
| 176 | <h2 id="the-modeline">The modeline</h2> | |
| 177 | <p>The line under the editor shows, from the left:</p> | |
| 178 | <table> | |
| 179 | <thead> | |
| 180 | <tr><th>Item</th><th>Shown when</th><th>What it shows</th></tr> | |
| 181 | </thead> | |
| 182 | <tbody> | |
| 183 | <tr><td>Evil state</td><td>Doom preset</td><td><code class="verbatim">NORMAL</code>, <code class="verbatim">INSERT</code>, <code class="verbatim">VISUAL</code>, <code class="verbatim">V-LINE</code> or <code class="verbatim">V-BLOCK</code>, on a coloured tag</td></tr> | |
| 184 | <tr><td>Unsaved dot</td><td>the buffer has unsaved edits</td><td>a small dot</td></tr> | |
| 185 | <tr><td>Outline path</td><td>the caret is under a heading</td><td>the headings containing the caret, outermost first, as <code class="verbatim">Projects › House › Roof</code></td></tr> | |
| 186 | <tr><td>Running clock</td><td>a clock is running</td><td>elapsed time and the clocked heading; click for Clock Out, Cancel Clock and Go to Clocked Entry</td></tr> | |
| 187 | <tr><td>Selection counts</td><td>text is selected</td><td>lines, words and characters in the selection, as <code class="verbatim">count-words-region</code></td></tr> | |
| 188 | <tr><td>Line and column</td><td>always</td><td><code class="verbatim">LINE:COLUMN</code> of the caret (the end of the selection)</td></tr> | |
| 189 | <tr><td>Word count</td><td>always</td><td>words in the whole file, as <code class="verbatim">count-words</code></td></tr> | |
| 190 | <tr><td>Encoding notes</td><td>the file differs from UTF-8 with LF</td><td><code class="verbatim">Read-only</code>, <code class="verbatim">BOM</code> and <code class="verbatim">CRLF</code>, in orange</td></tr> | |
| 191 | <tr><td>Git branch</td><td>the file is in a Git repository</td><td>the checked-out branch, or the first 7 characters of the commit when detached</td></tr> | |
| 192 | </tbody> | |
| 193 | </table> | |
| 194 | <p>Lines count from 1. Columns count from 0, as Emacs's <code class="verbatim">column-number-mode</code> does: a tab advances to the next multiple of 8, and wide characters such as CJK count as two columns. Hover over an item for a description.</p> | |
| 195 | <p>The word count follows edits after a pause. The Git branch is read from the repository's <code class="verbatim">HEAD</code> file without running <code class="verbatim">git</code>, and checked again every 5 seconds; worktrees and submodules are followed.</p> | |
| 196 | <p>The running clock is covered in <a href="06-dates-and-clocking.html">Dates and clocking</a>; the evil states in <a href="03-keys.html">Keys and commands</a>.</p> | |
| 197 | <h2 id="the-echo-area">The echo area</h2> | |
| 198 | <p>The line under the modeline is the echo area, as Emacs's minibuffer. It shows:</p> | |
| 199 | <ul> | |
| 200 | <li><strong>Messages</strong> from commands, such as <code class="verbatim">Stored: …</code> or <code class="verbatim">Not an org file</code>. A message stays for 4 seconds.</li> | |
| 201 | <li><strong>A pending key prefix</strong>. After <code class="verbatim">C-c</code> it shows <code class="verbatim">C-c-</code>. If you pause for about 0.6 seconds, a grid of the keys that can follow appears, each with the command it would run at the caret, or <code class="verbatim">+prefix</code> for a further prefix, as <code class="verbatim">which-key</code> shows them. <code class="verbatim">C-g</code> cancels the prefix and shows <code class="verbatim">Quit</code>. A sequence that isn't bound shows, for example, <code class="verbatim">C-c z is undefined</code>, and does nothing; in the Doom preset this includes sequences after <code class="verbatim">SPC</code>.</li> | |
| 202 | <li><strong>Prompts</strong>, when a command asks a question.</li> | |
| 203 | </ul> | |
| 204 | <h3 id="prompts">Prompts</h3> | |
| 205 | <p>A prompt shows its question and a text field, which takes the keyboard.</p> | |
| 206 | <ul> | |
| 207 | <li>Type an answer and press <code class="verbatim">Return</code>.</li> | |
| 208 | <li>When the prompt has choices (buffers, refile targets, tags), up to 12 of them list above the field, filtered as you type: characters match in order, and the best match is listed first. <code class="verbatim">Tab</code> completes the field to the first match. <code class="verbatim">Return</code> accepts the first match when the prompt requires one of its choices, and the typed text otherwise. Clicking a choice accepts it.</li> | |
| 209 | <li>Prompts that take several values, such as tags separated by colons, complete only the part after the last separator.</li> | |
| 210 | <li><code class="verbatim">Escape</code> cancels the prompt; the command reports <code class="verbatim">Quit</code>.</li> | |
| 211 | </ul> | |
| 212 | <p>Date prompts also show a date picker, and <code class="verbatim">S-<left></code>, <code class="verbatim">S-<right></code>, <code class="verbatim">S-<up></code> and <code class="verbatim">S-<down></code> move the date by a day or a week; see <a href="06-dates-and-clocking.html">Dates and clocking</a>. TODO keywords and tags with fast-selection keys show a key menu instead of a text field; see <a href="05-todos-and-tags.html">TODOs and tags</a>.</p> | |
| 213 | <p>When a prompt closes, the keyboard goes back to the editor.</p> | |
| 214 | <h2 id="completion">Completion</h2> | |
| 215 | <p>Complete at Point (<code class="verbatim">completion-at-point</code>) completes the word before the caret from what Org knows at that position.</p> | |
| 216 | <table> | |
| 217 | <thead> | |
| 218 | <tr><th>Preset</th><th>Key</th></tr> | |
| 219 | </thead> | |
| 220 | <tbody> | |
| 221 | <tr><td>Emacs</td><td><code class="verbatim">C-M-i</code></td></tr> | |
| 222 | <tr><td>Doom</td><td><code class="verbatim">C-SPC</code> or <code class="verbatim">C-@</code> in insert state; the list also opens by itself after you type two characters and pause for 0.4 seconds, as Doom's corfu does</td></tr> | |
| 223 | <tr><td>Mac</td><td>no key; run Complete at Point from the palette, or bind one in <code class="verbatim">keymap.toml</code></td></tr> | |
| 224 | </tbody> | |
| 225 | </table> | |
| 226 | <p>With one candidate, it is inserted. With several, a list opens under the caret, showing up to 16 rows. Nothing is selected until you pick a row.</p> | |
| 227 | <table> | |
| 228 | <thead> | |
| 229 | <tr><th>Key</th><th>In the list</th></tr> | |
| 230 | </thead> | |
| 231 | <tbody> | |
| 232 | <tr><td><code class="verbatim">C-n</code>, <code class="verbatim"><down></code>, <code class="verbatim">C-j</code></td><td>Next candidate; past the last one the selection goes back to what you typed</td></tr> | |
| 233 | <tr><td><code class="verbatim">C-p</code>, <code class="verbatim"><up></code>, <code class="verbatim">C-k</code></td><td>Previous candidate</td></tr> | |
| 234 | <tr><td><code class="verbatim">TAB</code></td><td>Insert the selected candidate; with none selected, insert the part all candidates share</td></tr> | |
| 235 | <tr><td><code class="verbatim">RET</code></td><td>Insert the selected candidate; with none selected, close the list and insert a newline</td></tr> | |
| 236 | <tr><td><code class="verbatim">ESC</code></td><td>Close the list; the key then does what it otherwise would</td></tr> | |
| 237 | <tr><td><code class="verbatim">C-g</code></td><td>Close the list</td></tr> | |
| 238 | </tbody> | |
| 239 | </table> | |
| 240 | <p>The list follows what you type and closes when nothing matches. Candidates are those that start with what you typed.</p> | |
| 241 | <p>What is completed, by position:</p> | |
| 242 | <table> | |
| 243 | <thead> | |
| 244 | <tr><th>Where</th><th>Candidates</th></tr> | |
| 245 | </thead> | |
| 246 | <tbody> | |
| 247 | <tr><td><code class="verbatim">#+</code> at the start of a line</td><td>keyword names (<code class="verbatim">TITLE</code>, <code class="verbatim">STARTUP</code>, <code class="verbatim">OPTIONS</code>, …), in upper and lower case</td></tr> | |
| 248 | <tr><td>After <code class="verbatim">#+STARTUP:</code></td><td>startup options</td></tr> | |
| 249 | <tr><td>After <code class="verbatim">#+OPTIONS:</code></td><td>export options</td></tr> | |
| 250 | <tr><td>After <code class="verbatim">#+DATE:</code></td><td>today's date as a timestamp</td></tr> | |
| 251 | <tr><td>After <code class="verbatim">#+EXCLUDE_TAGS:</code>, <code class="verbatim">#+SELECT_TAGS:</code>, <code class="verbatim">#+LANGUAGE:</code>, <code class="verbatim">#+PRIORITIES:</code></td><td>the usual values</td></tr> | |
| 252 | <tr><td><code class="verbatim"><</code> and a letter at the start of a line</td><td>structure templates (<code class="verbatim"><s</code> for a src block and so on); see <a href="11-code-blocks.html">Code blocks</a></td></tr> | |
| 253 | <tr><td>After <code class="verbatim">#+BEGIN_SRC</code></td><td>languages, then header arguments</td></tr> | |
| 254 | <tr><td>After <code class="verbatim">#+BEGIN: clocktable</code></td><td>clock table options</td></tr> | |
| 255 | <tr><td>After <code class="verbatim">[[</code></td><td>link types and the file's link abbreviations</td></tr> | |
| 256 | <tr><td>After <code class="verbatim">[[*</code></td><td>heading titles in the file</td></tr> | |
| 257 | <tr><td>After <code class="verbatim">\</code></td><td>entity names</td></tr> | |
| 258 | <tr><td>After <code class="verbatim">:</code> at the end of a heading</td><td>tags: those in <code class="verbatim">#+TAGS</code>, or else tags used in the file and across your folders</td></tr> | |
| 259 | <tr><td>After the stars of an empty heading</td><td>TODO keywords</td></tr> | |
| 260 | <tr><td><code class="verbatim">:</code> at the start of a line in a property drawer</td><td>property names the entry doesn't have yet</td></tr> | |
| 261 | <tr><td><code class="verbatim">:</code> at the start of a line elsewhere</td><td>drawer names</td></tr> | |
| 262 | </tbody> | |
| 263 | </table> | |
| 264 | <p>Elsewhere, Complete at Point reports <code class="verbatim">No match</code>. Completion is for org files only.</p> | |
| 265 | <h2 id="electric-pairs">Electric pairs</h2> | |
| 266 | <p>Typing an opening bracket inserts its closing partner, as <code class="verbatim">electric-pair-mode</code> does. The pairs are <code class="verbatim">()</code>, <code class="verbatim">[]</code>, <code class="verbatim">{}</code>, <code class="verbatim"><></code> and a pair of double quotes.</p> | |
| 267 | <ul> | |
| 268 | <li>Typing a closing character in front of the same closer moves over it instead of inserting another, skipping whitespace before it.</li> | |
| 269 | <li><code class="verbatim">DEL</code> between an empty pair deletes both.</li> | |
| 270 | <li><code class="verbatim">RET</code> between a pair opens a blank line between them.</li> | |
| 271 | <li>With text selected, typing an opening or closing character, or a double quote, wraps the selection.</li> | |
| 272 | <li>No pair is inserted where it would leave the brackets unbalanced (<code class="verbatim">electric-pair-preserve-balance</code>).</li> | |
| 273 | </ul> | |
| 274 | <p>Electric pairs are on by default and work in org files only. Set <code class="verbatim">electric-pair-mode = false</code> in <code class="verbatim">config.toml</code> to turn them off. Plain Emacs has them off; Doom pairs with smartparens.</p> | |
| 275 | <h2 id="spell-checking">Spell checking</h2> | |
| 276 | <p>Spell checking is off by default. Turn it on for the current buffer with Check Spelling While Typing from the palette (<code class="verbatim">SPC t s</code> in Doom normal state); the echo area says whether it is now on or off. To have it on in every file, set <code class="verbatim">spell-check = true</code> in <code class="verbatim">config.toml</code>.</p> | |
| 277 | <p>Misspelt words are underlined, using the macOS spelling dictionary. In org files, Orgstar doesn't mark words where spell-fu skips them: code, verbatim, links, timestamps, tags, TODO keywords, priorities, list bullets, checkboxes, keywords and affiliated keywords, planning and clock lines, property drawers, the first and last lines of drawers and blocks, the whole of src, example, export and comment blocks, LaTeX, entities, macros, targets, footnote references, citations, table formulas and fixed-width lines.</p> | |
| 278 | <p>Orgstar never corrects spelling on its own; automatic spelling correction, text replacement and smart quotes and dashes are off.</p> | |
| 279 | <p>On iOS, spell checking follows <code class="verbatim">spell-check</code> in the synced <code class="verbatim">config.toml</code>, and is off by default.</p> | |
| 280 | <h2 id="wrapping-and-filling">Wrapping and filling</h2> | |
| 281 | <p>Long lines wrap at the edge of the editor by default. View ▸ Truncate or Wrap Long Lines (<code class="verbatim">toggle-truncate-lines</code>) switches the current buffer to long lines that run off the right edge, with a horizontal scroll bar, and back. The echo area says which is now in effect.</p> | |
| 282 | <table> | |
| 283 | <thead> | |
| 284 | <tr><th>Preset</th><th>Key</th></tr> | |
| 285 | </thead> | |
| 286 | <tbody> | |
| 287 | <tr><td>Emacs</td><td><code class="verbatim">C-x x t</code></td></tr> | |
| 288 | <tr><td>Doom</td><td><code class="verbatim">SPC t w</code> in normal state</td></tr> | |
| 289 | <tr><td>Mac</td><td>menu or palette only</td></tr> | |
| 290 | </tbody> | |
| 291 | </table> | |
| 292 | <p>To truncate lines in every file, turn on Settings ▸ Editing ▸ "Long lines run off the edge instead of wrapping", or set <code class="verbatim">org-startup-truncated = true</code> in <code class="verbatim">config.toml</code>. The default is to wrap, as Doom does; Emacs's own default is to truncate.</p> | |
| 293 | <p>Wrapping is display only. To rewrap the text of a paragraph, use Org ▸ Fill Paragraph (<code class="verbatim">org-fill-paragraph</code>), which breaks the paragraph's lines at the fill column: <code class="verbatim">M-q</code> in the Emacs preset and in every Doom state, <code class="verbatim">⌃⌘P</code> in the Mac preset. With a selection, it fills every paragraph the selection touches. In Doom's normal and visual states, <code class="verbatim">gq</code> and <code class="verbatim">gw</code> with a motion fill the paragraphs in the lines it covers (<code class="verbatim">gqq</code> and <code class="verbatim">gww</code> for the current lines); <code class="verbatim">gq</code> leaves the caret on the last line, <code class="verbatim">gw</code> where it was. Unlike Fill Paragraph, <code class="verbatim">gq</code> and <code class="verbatim">gw</code> keep extra spaces between words and at the ends of lines, as Doom does. See <a href="03-keys.html">Keys and commands</a>. The fill column is Settings ▸ Editing ▸ "M-q fills to column N" (80 by default, 40 to 200), or <code class="verbatim">fill-column</code> in <code class="verbatim">config.toml</code>. Orgstar has no auto-fill: lines are not broken as you type.</p> | |
| 294 | <h2 id="view-toggles">View toggles</h2> | |
| 295 | <table> | |
| 296 | <thead> | |
| 297 | <tr><th>Toggle</th><th>Menu</th><th>Keys</th><th>Default</th><th><code class="verbatim">config.toml</code></th><th>Scope</th></tr> | |
| 298 | </thead> | |
| 299 | <tbody> | |
| 300 | <tr><td>Show Markup</td><td>View ▸ Show Markup</td><td><code class="verbatim">⇧⌘M</code></td><td>off</td><td><code class="verbatim">show-markup</code></td><td>every buffer</td></tr> | |
| 301 | <tr><td>Show Line Numbers</td><td>View ▸ Show Line Numbers</td><td><code class="verbatim">⇧⌘L</code></td><td>on</td><td><code class="verbatim">display-line-numbers-type</code></td><td>every buffer</td></tr> | |
| 302 | <tr><td>Inline images</td><td>Org ▸ Show or Hide Inline Images</td><td><code class="verbatim">C-c C-x C-v</code> (Emacs, Doom)</td><td>off</td><td><code class="verbatim">org-startup-with-inline-images</code></td><td>current buffer</td></tr> | |
| 303 | <tr><td>Spell checking</td><td>palette</td><td><code class="verbatim">SPC t s</code> (Doom)</td><td>off</td><td><code class="verbatim">spell-check</code></td><td>current buffer</td></tr> | |
| 304 | <tr><td>Truncate long lines</td><td>View ▸ Truncate or Wrap Long Lines</td><td><code class="verbatim">C-x x t</code> (Emacs), <code class="verbatim">SPC t w</code> (Doom)</td><td>off</td><td><code class="verbatim">org-startup-truncated</code></td><td>current buffer</td></tr> | |
| 305 | </tbody> | |
| 306 | </table> | |
| 307 | <p>Toggles that apply to the current buffer last until it closes; the <code class="verbatim">config.toml</code> setting decides how each file starts. Changing those settings, and <code class="verbatim">org-startup-indented</code> and <code class="verbatim">org-hide-leading-stars</code>, affects files opened afterwards, not buffers already open.</p> | |
| 308 | <h3 id="line-numbers">Line numbers</h3> | |
| 309 | <p>Line numbers show in a margin left of the text, as <code class="verbatim">display-line-numbers-mode</code> shows them: one number per line of the file, so wrapped lines are numbered once and folded lines are skipped. The caret's line number is brighter. Line numbers are on by default.</p> | |
| 310 | <h2 id="themes">Themes</h2> | |
| 311 | <p>The editor's font, size, line spacing and heading sizes are in Settings ▸ Appearance. Colours for the editor, the sidebar, the modeline, line numbers, the selection and the caret come from <code class="verbatim">config.toml</code>, under <code class="verbatim">[theme]</code> for both appearances, <code class="verbatim">[theme.light]</code> and <code class="verbatim">[theme.dark]</code> for one, and <code class="verbatim">[theme.todo]</code> for colours of TODO keywords. Settings ▸ Appearance ▸ Show Default Theme opens <code class="verbatim">default-theme.toml</code>, which lists every colour with its default value. Changes apply while Orgstar runs. See <a href="13-configuration.html">Configuration</a>.</p> | |
| 312 | <p>The iOS editor uses the same theme and display settings, read from the synced <code class="verbatim">config.toml</code>; see <a href="14-ios.html">iPhone and iPad</a>.</p> | |
| 313 | <h2 id="undo">Undo</h2> | |
| 314 | <p>Each buffer has its own undo history, kept while other buffers show.</p> | |
| 315 | <table> | |
| 316 | <thead> | |
| 317 | <tr><th>Action</th><th>Menu</th><th>Mac</th><th>Emacs preset</th><th>Doom (normal state)</th></tr> | |
| 318 | </thead> | |
| 319 | <tbody> | |
| 320 | <tr><td>Undo</td><td>Edit ▸ Undo</td><td><code class="verbatim">⌘Z</code></td><td><code class="verbatim">⌘Z</code>, <code class="verbatim">C-/</code>, <code class="verbatim">C-_</code>, <code class="verbatim">C-x u</code></td><td><code class="verbatim">u</code></td></tr> | |
| 321 | <tr><td>Redo</td><td>Edit ▸ Redo</td><td><code class="verbatim">⇧⌘Z</code></td><td><code class="verbatim">⇧⌘Z</code></td><td><code class="verbatim">C-r</code></td></tr> | |
| 322 | </tbody> | |
| 323 | </table> | |
| 324 | <p>A command's whole change undoes in one step, separately from the typing around it. Restoring a recovery version and resolving a Syncthing conflict copy can be undone too.</p> | |
| 325 | <p>The undo history is cleared when the buffer reloads or merges changes from disk, and when you take the disk version or merge with markers to settle a conflict; see <a href="01-files-and-folders.html">Files, folders and buffers</a>. The Emacs preset has no redo key other than <code class="verbatim">⇧⌘Z</code>, and undo is linear, not Emacs's undo tree.</p> | |
| 326 | <h2 id="finding-text-in-a-file">Finding text in a file</h2> | |
| 327 | <p>Edit ▸ Find opens the find bar above the text.</p> | |
| 328 | <table> | |
| 329 | <thead> | |
| 330 | <tr><th>Menu item</th><th>Shortcut</th><th>Emacs preset</th><th>Doom</th></tr> | |
| 331 | </thead> | |
| 332 | <tbody> | |
| 333 | <tr><td>Edit ▸ Find ▸ Find…</td><td><code class="verbatim">⌘F</code></td><td><code class="verbatim">C-s</code>, <code class="verbatim">C-r</code></td><td><code class="verbatim">SPC s s</code></td></tr> | |
| 334 | <tr><td>Edit ▸ Find ▸ Find and Replace…</td><td><code class="verbatim">⌥⌘F</code></td><td><code class="verbatim">M-%</code></td><td></td></tr> | |
| 335 | <tr><td>Edit ▸ Find ▸ Find Next</td><td><code class="verbatim">⌘G</code></td><td></td><td></td></tr> | |
| 336 | <tr><td>Edit ▸ Find ▸ Find Previous</td><td><code class="verbatim">⇧⌘G</code></td><td></td><td></td></tr> | |
| 337 | <tr><td>Edit ▸ Find ▸ Use Selection for Find</td><td><code class="verbatim">⌘E</code></td><td></td><td></td></tr> | |
| 338 | </tbody> | |
| 339 | </table> | |
| 340 | <p>In the Emacs preset <code class="verbatim">C-s</code> and <code class="verbatim">C-r</code> open the find bar; they are not incremental search. In Doom, <code class="verbatim">:s/PATTERN/REPLACEMENT/</code> and <code class="verbatim">:%s/…/…/</code> with the <code class="verbatim">g</code> and <code class="verbatim">i</code> flags substitute with regular expressions on the current line or in the whole file.</p> | |
| 341 | <p>To search all your files, use the toolbar's search field; see <a href="01-files-and-folders.html">Files, folders and buffers</a>.</p> | |
| 342 | <h2 id="accessibility">Accessibility</h2> | |
| 343 | <p>The editor works with VoiceOver. VoiceOver reads the text as it is shown rather than as stored: hidden link brackets and targets, hidden emphasis markers and hidden stars are skipped, entities are read as the characters drawn for them, and narrowed table columns are read as drawn. Folded text is still read, so the whole file is available. Lines, the caret position and the selection are reported in terms of the shown text.</p> | |
| 344 | <p>Other parts of the window are labelled: tabs in the tab bar are buttons, with the current one marked selected, and each close button names its buffer and says whether it is unsaved; the modeline's unsaved dot reads "Unsaved changes", and the Doom state tag reads, for example, "Normal state".</p> | |
| 345 | <p>The editor keeps the system's keyboard navigation and text editing; the presets only add bindings. See <a href="03-keys.html">Keys and commands</a>.</p> | |
| 346 | </main> | |
| 347 | <footer class="site"> | |
| 348 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 349 | </footer> | |
| 350 | </body> | |
| 351 | </html> | |
| \ No newline at end of file | ||
guide/03-keys.html added +1116
| @@ -0,0 +1,1116 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Keys and commands · Orgstar</title> | |
| 7 | <meta name="description" content="The three key presets, prefix keys and key hints, the echo area, the command palette, Option as Meta, keymap.toml, Vim editing in the Doom preset,…"> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Keys and commands</h1> | |
| 24 | <p class="lede">Every action in Orgstar is a named command; a keymap preset decides which keys run which commands, and keymap.toml lets you change that.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#commands-and-keymaps">Commands and keymaps</a></li> | |
| 29 | <li><a href="#choosing-a-preset">Choosing a preset</a></li> | |
| 30 | <li><a href="#option-as-meta">Option as Meta</a></li> | |
| 31 | <li><a href="#how-keys-reach-commands">How keys reach commands</a> | |
| 32 | <ul> | |
| 33 | <li><a href="#contexts">Contexts</a></li> | |
| 34 | <li><a href="#prefix-keys-and-key-hints">Prefix keys and key hints</a></li> | |
| 35 | </ul></li> | |
| 36 | <li><a href="#the-echo-area">The echo area</a></li> | |
| 37 | <li><a href="#the-command-palette">The command palette</a></li> | |
| 38 | <li><a href="#menu-shortcuts">Menu shortcuts</a></li> | |
| 39 | <li><a href="#speed-keys">Speed keys</a></li> | |
| 40 | <li><a href="#customizing-keys-keymap-toml">Customizing keys: keymap.toml</a> | |
| 41 | <ul> | |
| 42 | <li><a href="#format">Format</a></li> | |
| 43 | <li><a href="#key-notation">Key notation</a></li> | |
| 44 | <li><a href="#priority">Priority</a></li> | |
| 45 | <li><a href="#unbinding">Unbinding</a></li> | |
| 46 | <li><a href="#doom-states">Doom states</a></li> | |
| 47 | <li><a href="#more-examples">More examples</a></li> | |
| 48 | <li><a href="#reloading-and-errors">Reloading and errors</a></li> | |
| 49 | <li><a href="#importing-from-emacs">Importing from Emacs</a></li> | |
| 50 | </ul></li> | |
| 51 | <li><a href="#vim-editing-doom-preset">Vim editing (Doom preset)</a> | |
| 52 | <ul> | |
| 53 | <li><a href="#how-keys-are-handled">How keys are handled</a></li> | |
| 54 | <li><a href="#states">States</a></li> | |
| 55 | <li><a href="#motions">Motions</a></li> | |
| 56 | <li><a href="#operators">Operators</a></li> | |
| 57 | <li><a href="#text-objects">Text objects</a></li> | |
| 58 | <li><a href="#counts-and-registers">Counts and registers</a></li> | |
| 59 | <li><a href="#repeat">Repeat</a></li> | |
| 60 | <li><a href="#macros">Macros</a></li> | |
| 61 | <li><a href="#marks-and-jumps">Marks and jumps</a></li> | |
| 62 | <li><a href="#visual-states">Visual states</a></li> | |
| 63 | <li><a href="#surround">Surround</a></li> | |
| 64 | <li><a href="#commenting">Commenting</a></li> | |
| 65 | <li><a href="#org-keys-in-normal-state">Org keys in normal state</a></li> | |
| 66 | <li><a href="#the-leader">The leader</a></li> | |
| 67 | <li><a href="#ex-commands">Ex commands</a></li> | |
| 68 | <li><a href="#not-available">Not available</a></li> | |
| 69 | </ul></li> | |
| 70 | <li><a href="#keys-in-other-windows">Keys in other windows</a></li> | |
| 71 | <li><a href="#ios-and-ipados">iOS and iPadOS</a></li> | |
| 72 | <li><a href="#key-reference">Key reference</a> | |
| 73 | <ul> | |
| 74 | <li><a href="#movement-and-the-region">Movement and the region</a></li> | |
| 75 | <li><a href="#editing">Editing</a></li> | |
| 76 | <li><a href="#outline-visibility-and-narrowing">Outline: visibility and narrowing</a></li> | |
| 77 | <li><a href="#outline-headings-and-subtrees">Outline: headings and subtrees</a></li> | |
| 78 | <li><a href="#lists-and-checkboxes">Lists and checkboxes</a></li> | |
| 79 | <li><a href="#todo-priority-and-tags">TODO, priority and tags</a></li> | |
| 80 | <li><a href="#properties-and-column-view">Properties and column view</a></li> | |
| 81 | <li><a href="#dates-and-clocking">Dates and clocking</a></li> | |
| 82 | <li><a href="#tables">Tables</a></li> | |
| 83 | <li><a href="#links-and-footnotes">Links and footnotes</a></li> | |
| 84 | <li><a href="#code-blocks-and-c-c-c-c">Code blocks and C-c C-c</a></li> | |
| 85 | <li><a href="#agenda-and-capture">Agenda and capture</a></li> | |
| 86 | <li><a href="#export">Export</a></li> | |
| 87 | <li><a href="#files-buffers-and-the-app">Files, buffers and the app</a></li> | |
| 88 | <li><a href="#unbound-commands">Unbound commands</a></li> | |
| 89 | <li><a href="#speed-keys-reference">Speed keys reference</a></li> | |
| 90 | </ul></li> | |
| 91 | </ul> | |
| 92 | </nav> | |
| 93 | <h2 id="commands-and-keymaps">Commands and keymaps</h2> | |
| 94 | <p>Each action has a command id such as <code class="verbatim">org.todo.cycle</code> and a title such as <em>Cycle TODO State</em>. Keys, the Org menu, the command palette and the iOS key bar all run commands by id. A keymap maps key sequences to command ids. Orgstar ships three keymaps, called presets, and reads your own bindings from <code class="verbatim">keymap.toml</code> on top of the one you choose.</p> | |
| 95 | <p>Ids starting with <code class="verbatim">org.</code> are Org commands and run only in Org files. Ids starting with <code class="verbatim">edit.</code> are text-system actions (movement, killing, find). Ids starting with <code class="verbatim">app.</code> are carried out by the app: saving, buffers, windows, export. <code class="verbatim">editor.</code> ids change how the editor behaves. The <a href="#key-reference">key reference</a> at the end of this chapter lists every bound command with its keys in each preset.</p> | |
| 96 | <h2 id="choosing-a-preset">Choosing a preset</h2> | |
| 97 | <p>Choose a preset in Settings ▸ General ▸ Keys, or with <code class="verbatim">keymap</code> in the <code class="verbatim">[orgstar]</code> table of <code class="verbatim">config.toml</code> (see <a href="13-configuration.html">Configuration</a>). The change applies at once.</p> | |
| 98 | <table> | |
| 99 | <thead> | |
| 100 | <tr><th>Preset</th><th><code class="verbatim">config.toml</code> value</th><th>What it is</th></tr> | |
| 101 | </thead> | |
| 102 | <tbody> | |
| 103 | <tr><td>Emacs</td><td><code class="verbatim">"emacs"</code></td><td>Emacs and Org keys: <code class="verbatim">C-f</code>, <code class="verbatim">C-k</code>, <code class="verbatim">C-x C-s</code>, <code class="verbatim">C-c C-t</code>, <code class="verbatim">M-RET</code>, <code class="verbatim">M-<left></code>. The default.</td></tr> | |
| 104 | <tr><td>Mac</td><td><code class="verbatim">"mac"</code></td><td>Standard macOS text keys stay as they are. Org commands use Control-Command chords (<code class="verbatim">⌃⌘T</code>, <code class="verbatim">⌃⌘←</code>), which macOS text editing leaves free.</td></tr> | |
| 105 | <tr><td>Doom (Vim keys)</td><td><code class="verbatim">"doom"</code></td><td>Modal editing as in Doom Emacs with evil and evil-org: normal, insert and visual states, the <code class="verbatim">SPC</code> leader and <code class="verbatim">SPC m</code> local leader, plus the Emacs preset's Org keys in every state.</td></tr> | |
| 106 | </tbody> | |
| 107 | </table> | |
| 108 | <p>The Mac preset binds fewer commands than the others. <code class="verbatim">⌃⌘X</code> is its <code class="verbatim">C-c C-c</code>, <code class="verbatim">⌘K</code> inserts a link and <code class="verbatim">⇧⌘E</code> opens the export sheet; the <a href="#key-reference">key reference</a> lists the rest. It has no keys for agenda, capture or the single export formats. Run those from the Org menu, from the command palette (<code class="verbatim">⇧⌘P</code>), from a menu shortcut (Agenda <code class="verbatim">⇧⌘A</code>, Capture <code class="verbatim">⇧⌘N</code>), or bind them yourself in <code class="verbatim">keymap.toml</code>.</p> | |
| 109 | <p>In the Emacs and Mac presets, and in Doom's insert state, macOS's own text keys keep working where the preset does not bind the key: <code class="verbatim">⌥←</code>, <code class="verbatim">⌘←</code>, <code class="verbatim">⇧</code> with arrows to select, and the Control keys the macOS text system provides (<code class="verbatim">⌃A</code>, <code class="verbatim">⌃E</code>, <code class="verbatim">⌃K</code> and so on). Menu shortcuts such as <code class="verbatim">⌘S</code> and <code class="verbatim">⌘F</code> work in every preset; see <a href="#menu-shortcuts">Menu shortcuts</a>.</p> | |
| 110 | <h2 id="option-as-meta">Option as Meta</h2> | |
| 111 | <p>Emacs notation writes Meta as <code class="verbatim">M-</code>. On a Mac keyboard Meta is the Option key, but Option also types characters such as <code class="verbatim">é</code> and <code class="verbatim">ø</code>. Settings ▸ General ▸ Option as Meta picks which Option keys act as Meta:</p> | |
| 112 | <table> | |
| 113 | <thead> | |
| 114 | <tr><th>Choice</th><th><code class="verbatim">config.toml</code> (<code class="verbatim">option-as-meta</code> in <code class="verbatim">[orgstar]</code>)</th><th>Effect</th></tr> | |
| 115 | </thead> | |
| 116 | <tbody> | |
| 117 | <tr><td>Left Option</td><td><code class="verbatim">"left"</code></td><td>The left Option key is Meta; the right one types characters. The default.</td></tr> | |
| 118 | <tr><td>Right Option</td><td><code class="verbatim">"right"</code></td><td>The right Option key is Meta.</td></tr> | |
| 119 | <tr><td>Both</td><td><code class="verbatim">"both"</code></td><td>Both are Meta; Option no longer types special characters in the editor.</td></tr> | |
| 120 | <tr><td>Neither</td><td><code class="verbatim">"none"</code></td><td>Option always types characters. Plain <code class="verbatim">M-</code> keys such as <code class="verbatim">M-f</code> cannot be typed; chords that also use Control or Command still work.</td></tr> | |
| 121 | </tbody> | |
| 122 | </table> | |
| 123 | <p>Option pressed together with Control or Command always counts as Meta, whatever this setting says, so chords such as <code class="verbatim">C-M-i</code> (<code class="verbatim">⌃⌥I</code>) and the Mac preset's <code class="verbatim">⌃⌥⌘←</code> always work.</p> | |
| 124 | <h2 id="how-keys-reach-commands">How keys reach commands</h2> | |
| 125 | <h3 id="contexts">Contexts</h3> | |
| 126 | <p>One key can run different commands depending on where the caret is. In the Emacs preset <code class="verbatim">M-<right></code> demotes a heading, indents a list item and moves a table column right. Each binding can name a context, and Orgstar tries the bindings for a key from the highest priority down. The first one whose context holds and whose command can run at the caret wins.</p> | |
| 127 | <table> | |
| 128 | <thead> | |
| 129 | <tr><th>Context</th><th>Holds when</th></tr> | |
| 130 | </thead> | |
| 131 | <tbody> | |
| 132 | <tr><td><code class="verbatim">heading</code></td><td>The caret is on a heading line.</td></tr> | |
| 133 | <tr><td><code class="verbatim">item</code></td><td>The caret is inside a list item.</td></tr> | |
| 134 | <tr><td><code class="verbatim">table</code></td><td>The caret is inside a table.</td></tr> | |
| 135 | <tr><td><code class="verbatim">tblfm</code></td><td>The caret is on a <code class="verbatim">#+TBLFM:</code> line.</td></tr> | |
| 136 | <tr><td><code class="verbatim">timestamp</code></td><td>The caret is on a timestamp.</td></tr> | |
| 137 | <tr><td><code class="verbatim">property</code></td><td>The caret is on a property line in a property drawer.</td></tr> | |
| 138 | <tr><td><code class="verbatim">src</code></td><td>The caret is inside a src block.</td></tr> | |
| 139 | <tr><td><code class="verbatim">dblock</code></td><td>The caret is on the <code class="verbatim">#+BEGIN:</code> line of a dynamic block.</td></tr> | |
| 140 | <tr><td><code class="verbatim">fold-line</code></td><td>The caret is on the first or last line of a drawer or block, where <code class="verbatim">TAB</code> folds it.</td></tr> | |
| 141 | <tr><td><code class="verbatim">region</code></td><td>Text is selected.</td></tr> | |
| 142 | <tr><td><code class="verbatim">speed</code></td><td>Speed keys are on, nothing is selected, and the caret is at the very start of a heading line. See <a href="04-outlines.html#speed-keys">Speed keys</a>.</td></tr> | |
| 143 | </tbody> | |
| 144 | </table> | |
| 145 | <p>When no binding for a key applies:</p> | |
| 146 | <ul> | |
| 147 | <li>In the Emacs and Mac presets, a single key goes to the text system and does what it normally does. <code class="verbatim">TAB</code> outside a heading, drawer edge or table types a tab; <code class="verbatim">S-<right></code> on plain text extends the selection.</li> | |
| 148 | <li>A key sequence of two or more keys runs its highest-priority command anyway, so you see that command's message (for example "Not on a heading").</li> | |
| 149 | <li>In the Doom preset the keys go on to the Vim engine (see <a href="#vim-editing-doom-preset">Vim editing</a>).</li> | |
| 150 | </ul> | |
| 151 | <p>In a file that is not an Org file, <code class="verbatim">org.</code> commands never apply, so their keys fall through as above.</p> | |
| 152 | <h3 id="prefix-keys-and-key-hints">Prefix keys and key hints</h3> | |
| 153 | <p>A prefix is a key that starts longer sequences, such as <code class="verbatim">C-c</code>, <code class="verbatim">C-c C-x</code>, <code class="verbatim">C-x n</code> or, in the Doom preset, <code class="verbatim">SPC</code> and <code class="verbatim">SPC m</code>. After a prefix, Orgstar waits for the next key and shows the keys typed so far in the echo area, followed by a dash: <code class="verbatim">C-c C-x-</code>.</p> | |
| 154 | <p>If you pause on a prefix for 0.6 seconds, a panel of key hints opens above the echo area. It lists each key that can follow, sorted by key, with the title of the command it runs, or <code class="verbatim">+prefix</code> when it leads to a longer sequence. This is Orgstar's version of <code class="verbatim">which-key</code>. The hints follow the current keymap, including your <code class="verbatim">keymap.toml</code>, and in the Doom preset the current evil state. When a key has several contexts (<code class="verbatim">C-c C-c</code> is the common case), the hint shows the command that would run at the caret; where none of them applies, it shows the highest-priority one.</p> | |
| 155 | <p><code class="verbatim">C-g</code> during a prefix cancels it; in the Emacs and Mac presets the echo area shows <code class="verbatim">Quit</code>. A sequence that nothing binds shows, for example, <code class="verbatim">C-c z is undefined</code> and does nothing. In the Doom preset this holds for sequences that start with <code class="verbatim">SPC</code> or with a Control or Meta key; see <a href="#how-keys-are-handled">How keys are handled</a> for the others.</p> | |
| 156 | <p>A key bound by itself cannot also be a prefix. When a keymap binds both <code class="verbatim">C-c</code> and <code class="verbatim">C-c C-t</code>, <code class="verbatim">C-c</code> always waits for the next key, so the binding for <code class="verbatim">C-c</code> alone never runs.</p> | |
| 157 | <h2 id="the-echo-area">The echo area</h2> | |
| 158 | <p>The echo area is the line at the bottom of the window, below the modeline. It shows, in order of priority:</p> | |
| 159 | <ul> | |
| 160 | <li>A question a command is asking, with a text field: a refile target, a date, a property value, a sparse-tree match, a Vim search or ex command. <code class="verbatim">Return</code> answers, <code class="verbatim">Esc</code> cancels. When the question has choices, they are listed above the field and filtered as you type with fuzzy matching; <code class="verbatim">Tab</code> completes the best match. Date questions show a calendar, and <code class="verbatim">S-<left></code>, <code class="verbatim">S-<right></code>, <code class="verbatim">S-<up></code> and <code class="verbatim">S-<down></code> move the date by a day or a week, as in <code class="verbatim">org-read-date</code>.</li> | |
| 161 | <li>Fast selection for TODO keywords and tags when the file defines keys for them (see <a href="05-todos-and-tags.html">TODOs and tags</a>).</li> | |
| 162 | <li>The pending prefix, such as <code class="verbatim">C-c C-x-</code>.</li> | |
| 163 | <li>The last message from a command or from the keymap, for four seconds.</li> | |
| 164 | </ul> | |
| 165 | <p>In the Doom preset the modeline shows the evil state as a tag: <code class="verbatim">NORMAL</code>, <code class="verbatim">INSERT</code>, <code class="verbatim">VISUAL</code>, <code class="verbatim">V-LINE</code> or <code class="verbatim">V-BLOCK</code>. See <a href="02-the-editor.html">The editor</a> for the rest of the modeline.</p> | |
| 166 | <h2 id="the-command-palette">The command palette</h2> | |
| 167 | <p>The palette lists every command by title with its keys in the current keymap. Open it with:</p> | |
| 168 | <ul> | |
| 169 | <li><code class="verbatim">⇧⌘P</code> or File ▸ Command Palette… in every preset,</li> | |
| 170 | <li><code class="verbatim">M-x</code> in the Emacs and Doom presets (<code class="verbatim">execute-extended-command</code>),</li> | |
| 171 | <li><code class="verbatim">SPC :</code> in Doom normal state.</li> | |
| 172 | </ul> | |
| 173 | <p>Type part of a title; matching is fuzzy and the best matches come first. <code class="verbatim">Return</code> runs the top match, a click runs any row, and <code class="verbatim">Esc</code> closes the palette. Each row shows up to two key sequences; in the Doom preset these are normal-state keys first, then insert-state keys.</p> | |
| 174 | <p>The palette leaves out text-system movement and editing commands (Forward Character, Kill Line, Set Mark and the like), which only make sense from keys. Every other command is in it, including the ones no preset binds, such as Show or Hide Backlinks, Import Table from File…, Recovery Versions… and Delete Property…. Commands that cannot run at the caret show a message instead.</p> | |
| 175 | <p>The Org menu in the menu bar lists every <code class="verbatim">org.</code> command with its keys in the current keymap, and is a way to find a key without the palette. Its Clock submenu lists the clock commands the same way, followed by the recently clocked entries.</p> | |
| 176 | <h2 id="menu-shortcuts">Menu shortcuts</h2> | |
| 177 | <p>These come from the menu bar and work in every preset. In the Doom preset, keys with <code class="verbatim">⌘</code> always go to the menus.</p> | |
| 178 | <table> | |
| 179 | <thead> | |
| 180 | <tr><th>Menu</th><th>Item</th><th>Key</th></tr> | |
| 181 | </thead> | |
| 182 | <tbody> | |
| 183 | <tr><td>Orgstar</td><td>Settings…</td><td><code class="verbatim">⌘,</code></td></tr> | |
| 184 | <tr><td>Orgstar</td><td>Edit Config File</td><td><code class="verbatim">⌥⌘,</code></td></tr> | |
| 185 | <tr><td>File</td><td>Add Folder…</td><td><code class="verbatim">⇧⌘O</code></td></tr> | |
| 186 | <tr><td>File</td><td>Quick Open…</td><td><code class="verbatim">⌘P</code></td></tr> | |
| 187 | <tr><td>File</td><td>Command Palette…</td><td><code class="verbatim">⇧⌘P</code></td></tr> | |
| 188 | <tr><td>File</td><td>Capture…</td><td><code class="verbatim">⇧⌘N</code></td></tr> | |
| 189 | <tr><td>File</td><td>Close Buffer (closes other windows themselves)</td><td><code class="verbatim">⌘W</code></td></tr> | |
| 190 | <tr><td>File</td><td>Close Window</td><td><code class="verbatim">⇧⌘W</code></td></tr> | |
| 191 | <tr><td>File</td><td>Save</td><td><code class="verbatim">⌘S</code></td></tr> | |
| 192 | <tr><td>File</td><td>Save All</td><td><code class="verbatim">⌥⌘S</code></td></tr> | |
| 193 | <tr><td>Edit ▸ Find</td><td>Find…</td><td><code class="verbatim">⌘F</code></td></tr> | |
| 194 | <tr><td>Edit ▸ Find</td><td>Find and Replace…</td><td><code class="verbatim">⌥⌘F</code></td></tr> | |
| 195 | <tr><td>Edit ▸ Find</td><td>Find Next</td><td><code class="verbatim">⌘G</code></td></tr> | |
| 196 | <tr><td>Edit ▸ Find</td><td>Find Previous</td><td><code class="verbatim">⇧⌘G</code></td></tr> | |
| 197 | <tr><td>Edit ▸ Find</td><td>Use Selection for Find</td><td><code class="verbatim">⌘E</code></td></tr> | |
| 198 | <tr><td>Edit</td><td>Cancel Running Task</td><td><code class="verbatim">⌘.</code></td></tr> | |
| 199 | <tr><td>Edit</td><td>Search Notes</td><td><code class="verbatim">⇧⌘F</code></td></tr> | |
| 200 | <tr><td>View</td><td>Show Markup</td><td><code class="verbatim">⇧⌘M</code></td></tr> | |
| 201 | <tr><td>View</td><td>Show Line Numbers</td><td><code class="verbatim">⇧⌘L</code></td></tr> | |
| 202 | <tr><td>View</td><td>Show or Hide Outline</td><td><code class="verbatim">⌥⌘O</code></td></tr> | |
| 203 | <tr><td>View</td><td>Show or Hide Columns and Clock</td><td><code class="verbatim">⌥⌘I</code></td></tr> | |
| 204 | <tr><td>Window</td><td>Agenda</td><td><code class="verbatim">⇧⌘A</code></td></tr> | |
| 205 | <tr><td>Window</td><td>Board</td><td><code class="verbatim">⇧⌘B</code></td></tr> | |
| 206 | <tr><td>Window</td><td>Next Buffer</td><td><code class="verbatim">⇧⌘]</code></td></tr> | |
| 207 | <tr><td>Window</td><td>Previous Buffer</td><td><code class="verbatim">⇧⌘[</code></td></tr> | |
| 208 | </tbody> | |
| 209 | </table> | |
| 210 | <p>View ▸ Show or Hide Backlinks and Show Tab Bar, Window ▸ Switch to Buffer…, and the items of File ▸ Export have no shortcut.</p> | |
| 211 | <p>With Settings ▸ Capture ▸ "⌃⌥Space opens Capture from any app" on (the default), <code class="verbatim">⌃⌥Space</code> opens the Capture window from any application (see <a href="08-capture.html">Capture</a>).</p> | |
| 212 | <h2 id="speed-keys">Speed keys</h2> | |
| 213 | <p>With <code class="verbatim">org-use-speed-commands</code> set to <code class="verbatim">true</code> in <code class="verbatim">config.toml</code>, single letters typed at the very start of a heading line, before the stars, run commands instead of inserting text (<code class="verbatim">org-speed-commands</code>). Anywhere else the letters type as usual. The setting is off by default and has no checkbox in Settings.</p> | |
| 214 | <p>Speed keys work in the Emacs and Mac presets, and in the Doom preset in insert state. The full list is in the <a href="#speed-keys-reference">speed keys reference</a>.</p> | |
| 215 | <h2 id="customizing-keys-keymap-toml">Customizing keys: keymap.toml</h2> | |
| 216 | <p>Your own bindings go in <code class="verbatim">keymap.toml</code> in the configuration folder: <code class="verbatim">$XDG_CONFIG_HOME/orgstar/keymap.toml</code> when <code class="verbatim">XDG_CONFIG_HOME</code> is set, otherwise <code class="verbatim">~/.config/orgstar/keymap.toml</code>. Settings ▸ General shows the path under the Keys picker. The file does not exist until you create it. If you used an earlier version that kept it in <code class="verbatim">~/Library/Application Support/Orgstar/</code>, that copy is read, and reloaded when you save it, until one exists in the configuration folder.</p> | |
| 217 | <p>The bindings in the file are layered on top of the chosen preset. They apply to whichever preset is chosen, so a file written for the Emacs preset does nothing useful under Doom unless its bindings name a <code class="verbatim">mode</code>.</p> | |
| 218 | <h3 id="format">Format</h3> | |
| 219 | <p>The file is a list of <code class="verbatim">[[bind]]</code> tables, one per binding:</p> | |
| 220 | <pre><code class="language-toml highlight"><span class="source toml"><span class="comment line number-sign toml"><span class="punctuation definition comment toml">#</span> C-c t cycles the TODO keyword. | |
| 221 | </span><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 222 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-c t<span class="punctuation definition string end toml">"</span></span> | |
| 223 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>org.todo.cycle<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 224 | <table> | |
| 225 | <thead> | |
| 226 | <tr><th>Field</th><th>Required</th><th>Meaning</th></tr> | |
| 227 | </thead> | |
| 228 | <tbody> | |
| 229 | <tr><td><code class="verbatim">keys</code></td><td>yes</td><td>The key sequence, in Emacs notation, chords separated by spaces.</td></tr> | |
| 230 | <tr><td><code class="verbatim">command</code></td><td>yes</td><td>A command id, or <code class="verbatim">"none"</code> to unbind.</td></tr> | |
| 231 | <tr><td><code class="verbatim">when</code></td><td>no</td><td>A context from the table in <a href="#contexts">Contexts</a>. Without it the binding holds everywhere.</td></tr> | |
| 232 | <tr><td><code class="verbatim">mode</code></td><td>no</td><td>An evil state for the Doom preset: <code class="verbatim">"normal"</code>, <code class="verbatim">"insert"</code> or <code class="verbatim">"visual"</code>.</td></tr> | |
| 233 | </tbody> | |
| 234 | </table> | |
| 235 | <p>The <a href="#key-reference">key reference</a> gives each command's id after its title. Commands no preset binds are listed under <a href="#unbound-commands">Unbound commands</a>. A binding whose command id Orgstar does not know is skipped and reported when the file loads (see <a href="#reloading-and-errors">Reloading and errors</a>).</p> | |
| 236 | <p>Orgstar reads a subset of TOML: <code class="verbatim">[[bind]]</code> headers, <code class="verbatim">key = value</code> lines, basic <code class="verbatim">"..."</code> and literal <code class="verbatim">'...'</code> strings, <code class="verbatim">true</code> and <code class="verbatim">false</code>, integers, and <code class="verbatim">#</code> comments. Arrays, inline tables and multi-line strings are not supported.</p> | |
| 237 | <h3 id="key-notation">Key notation</h3> | |
| 238 | <table> | |
| 239 | <thead> | |
| 240 | <tr><th>Notation</th><th>Key</th></tr> | |
| 241 | </thead> | |
| 242 | <tbody> | |
| 243 | <tr><td><code class="verbatim">C-</code></td><td>Control (<code class="verbatim">⌃</code>)</td></tr> | |
| 244 | <tr><td><code class="verbatim">M-</code></td><td>Meta: Option (<code class="verbatim">⌥</code>), as set in <a href="#option-as-meta">Option as Meta</a></td></tr> | |
| 245 | <tr><td><code class="verbatim">S-</code></td><td>Shift (<code class="verbatim">⇧</code>)</td></tr> | |
| 246 | <tr><td><code class="verbatim">s-</code></td><td>Command (<code class="verbatim">⌘</code>)</td></tr> | |
| 247 | <tr><td><code class="verbatim">a</code>, <code class="verbatim">%</code>, <code class="verbatim">/</code></td><td>A single character</td></tr> | |
| 248 | <tr><td><code class="verbatim">TAB</code>, <code class="verbatim">RET</code>, <code class="verbatim">SPC</code>, <code class="verbatim">ESC</code>, <code class="verbatim">DEL</code></td><td>Tab, Return, Space, Escape, Delete (backspace)</td></tr> | |
| 249 | <tr><td><code class="verbatim"><left></code>, <code class="verbatim"><right></code>, <code class="verbatim"><up></code>, <code class="verbatim"><down></code></td><td>Arrow keys</td></tr> | |
| 250 | <tr><td><code class="verbatim"><home></code>, <code class="verbatim"><end></code>, <code class="verbatim"><prior></code>, <code class="verbatim"><next></code></td><td>Home, End, Page Up, Page Down</td></tr> | |
| 251 | <tr><td><code class="verbatim"><delete></code></td><td>Forward delete (<code class="verbatim">⌦</code>)</td></tr> | |
| 252 | <tr><td><code class="verbatim"><f1></code> to <code class="verbatim"><f12></code></td><td>Function keys</td></tr> | |
| 253 | </tbody> | |
| 254 | </table> | |
| 255 | <p>Modifiers combine: <code class="verbatim">C-M-s-<left></code> is <code class="verbatim">⌃⌥⌘←</code>. <code class="verbatim"><tab></code>, <code class="verbatim"><return></code>, <code class="verbatim"><escape></code> and <code class="verbatim"><backspace></code> are accepted as other names for <code class="verbatim">TAB</code>, <code class="verbatim">RET</code>, <code class="verbatim">ESC</code> and <code class="verbatim">DEL</code>, and <code class="verbatim"><backtab></code> for <code class="verbatim">S-TAB</code>.</p> | |
| 256 | <p>Shift with a letter is written as the capital letter: <code class="verbatim">S-a</code> and <code class="verbatim">A</code> are the same key, and so are <code class="verbatim">C-S-h</code> and <code class="verbatim">C-H</code>. With other keys Shift stays a modifier: <code class="verbatim">S-TAB</code>, <code class="verbatim">S-<up></code>, <code class="verbatim">M-S-RET</code>.</p> | |
| 257 | <p>A backslash in a basic string must be doubled. These two lines are the same key, <code class="verbatim">⌃⌘\</code>:</p> | |
| 258 | <pre><code class="language-toml highlight"><span class="source toml"><span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-s-<span class="constant character escape toml">\\</span><span class="punctuation definition string end toml">"</span></span> | |
| 259 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted single toml"><span class="punctuation definition string begin toml">'</span>C-s-\<span class="punctuation definition string end toml">'</span></span></span></code></pre> | |
| 260 | <h3 id="priority">Priority</h3> | |
| 261 | <p>Bindings are read in order: the preset first, then your file from top to bottom. When several bindings have the same keys, later ones are tried first. A binding in your file without <code class="verbatim">when</code> therefore takes its keys everywhere, hiding every context-specific preset binding for them. A binding with <code class="verbatim">when</code> is tried first only in its context; elsewhere the preset's bindings still apply.</p> | |
| 262 | <pre><code class="language-toml highlight"><span class="source toml"><span class="comment line number-sign toml"><span class="punctuation definition comment toml">#</span> M-RET in a table inserts a row; on headings and items it does what the preset says. | |
| 263 | </span><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 264 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>M-RET<span class="punctuation definition string end toml">"</span></span> | |
| 265 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>org.table.insert-row<span class="punctuation definition string end toml">"</span></span> | |
| 266 | <span class="variable other key toml">when</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>table<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 267 | <h3 id="unbinding">Unbinding</h3> | |
| 268 | <p>Set <code class="verbatim">command</code> to <code class="verbatim">"none"</code> to remove a key. A <code class="verbatim">"none"</code> binding without <code class="verbatim">when</code> hides every earlier binding of exactly those keys, so the key goes to the text system (or, in the Doom preset, to Vim):</p> | |
| 269 | <pre><code class="language-toml highlight"><span class="source toml"><span class="comment line number-sign toml"><span class="punctuation definition comment toml">#</span> Leave C-t to macOS's transpose and C-k to its kill. | |
| 270 | </span><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 271 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-t<span class="punctuation definition string end toml">"</span></span> | |
| 272 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>none<span class="punctuation definition string end toml">"</span></span> | |
| 273 | <span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 274 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-k<span class="punctuation definition string end toml">"</span></span> | |
| 275 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>none<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 276 | <p>Limitations:</p> | |
| 277 | <ul> | |
| 278 | <li>A <code class="verbatim">"none"</code> binding with <code class="verbatim">when</code> has no effect. You cannot unbind a key in one context only; bind it to another command in that context instead.</li> | |
| 279 | <li>Unbinding a prefix does not remove the longer sequences under it. Unbinding <code class="verbatim">C-c C-x</code> leaves <code class="verbatim">C-c C-x C-i</code> and the rest working. Unbind each sequence you want gone.</li> | |
| 280 | </ul> | |
| 281 | <h3 id="doom-states">Doom states</h3> | |
| 282 | <p>In the Doom preset every binding belongs to a state. A binding without <code class="verbatim">mode</code> never runs in the Doom preset, and a binding with <code class="verbatim">mode</code> never runs in the Emacs or Mac preset. <code class="verbatim">mode = "visual"</code> covers visual, visual-line and visual-block. To bind a key in more than one state, write one table per state:</p> | |
| 283 | <pre><code class="language-toml highlight"><span class="source toml"><span class="comment line number-sign toml"><span class="punctuation definition comment toml">#</span> SPC n a opens the agenda. | |
| 284 | </span><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 285 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>SPC n a<span class="punctuation definition string end toml">"</span></span> | |
| 286 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>app.agenda<span class="punctuation definition string end toml">"</span></span> | |
| 287 | <span class="variable other key toml">mode</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>normal<span class="punctuation definition string end toml">"</span></span> | |
| 288 | ||
| 289 | <span class="comment line number-sign toml"><span class="punctuation definition comment toml">#</span> C-c n inserts a heading in normal and insert state. | |
| 290 | </span><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 291 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-c n<span class="punctuation definition string end toml">"</span></span> | |
| 292 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>org.heading.insert<span class="punctuation definition string end toml">"</span></span> | |
| 293 | <span class="variable other key toml">mode</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>normal<span class="punctuation definition string end toml">"</span></span> | |
| 294 | <span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 295 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-c n<span class="punctuation definition string end toml">"</span></span> | |
| 296 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>org.heading.insert<span class="punctuation definition string end toml">"</span></span> | |
| 297 | <span class="variable other key toml">mode</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>insert<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 298 | <p>A <code class="verbatim">mode</code> other than <code class="verbatim">normal</code>, <code class="verbatim">insert</code> or <code class="verbatim">visual</code> (including <code class="verbatim">visual-line</code>) is reported when the file loads, and the binding is skipped.</p> | |
| 299 | <h3 id="more-examples">More examples</h3> | |
| 300 | <pre><code class="language-toml highlight"><span class="source toml"><span class="comment line number-sign toml"><span class="punctuation definition comment toml">#</span> Mac preset: ⌃⌘U goes up to the parent heading, ⌃⌘R opens column view, ⌃⌘; toggles COMMENT. | |
| 301 | </span><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 302 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-s-u<span class="punctuation definition string end toml">"</span></span> | |
| 303 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>org.heading.up<span class="punctuation definition string end toml">"</span></span> | |
| 304 | <span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 305 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-s-r<span class="punctuation definition string end toml">"</span></span> | |
| 306 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>org.columns<span class="punctuation definition string end toml">"</span></span> | |
| 307 | <span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 308 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-s-;<span class="punctuation definition string end toml">"</span></span> | |
| 309 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>org.heading.toggle-comment<span class="punctuation definition string end toml">"</span></span> | |
| 310 | ||
| 311 | <span class="comment line number-sign toml"><span class="punctuation definition comment toml">#</span> Emacs preset: C-c b opens the board, C-c r reloads this file. | |
| 312 | </span><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 313 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-c b<span class="punctuation definition string end toml">"</span></span> | |
| 314 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>app.board<span class="punctuation definition string end toml">"</span></span> | |
| 315 | <span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 316 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-c r<span class="punctuation definition string end toml">"</span></span> | |
| 317 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>app.reload-keymap<span class="punctuation definition string end toml">"</span></span> | |
| 318 | </span></code></pre> | |
| 319 | <h3 id="reloading-and-errors">Reloading and errors</h3> | |
| 320 | <p>Orgstar watches the configuration folder and reloads <code class="verbatim">keymap.toml</code> when you save it. It also reloads when you change the preset, and when you run Reload Keymap (<code class="verbatim">app.reload-keymap</code>, in the palette, and <code class="verbatim">SPC h r r</code> in Doom normal state), which shows <code class="verbatim">Keymap reloaded</code>.</p> | |
| 321 | <p>Problems are reported in the echo area with the line number, for example <code class="verbatim">keymap.toml: line 12: unknown context tabel (and 1 more)</code>. A binding with bad or missing <code class="verbatim">keys</code>, a missing <code class="verbatim">command</code>, a command id Orgstar does not know, an unknown <code class="verbatim">when</code> or <code class="verbatim">mode</code>, or a table other than <code class="verbatim">[[bind]]</code> is skipped; the rest of the file still applies. A file that is not valid TOML is ignored as a whole and the error is shown; the preset alone applies until you fix it.</p> | |
| 322 | <h3 id="importing-from-emacs">Importing from Emacs</h3> | |
| 323 | <p>Settings ▸ General ▸ Import from Emacs… reads your Emacs or Doom configuration and offers, among other things, the key bindings it finds: <code class="verbatim">global-set-key</code>, <code class="verbatim">keymap-global-set</code>, <code class="verbatim">define-key</code>, <code class="verbatim">keymap-set</code>, <code class="verbatim">evil-define-key</code> and Doom's <code class="verbatim">map!</code> with <code class="verbatim">:leader</code>, <code class="verbatim">:localleader</code>, state keywords and <code class="verbatim">:prefix</code>. Bindings to commands Orgstar has are appended to <code class="verbatim">keymap.toml</code> under a <code class="verbatim"># Imported from Emacs.</code> comment, leaving out bindings the file already has. Keys written as vectors, such as <code class="verbatim">[f5]</code>, are skipped. See <a href="15-alongside-emacs.html">Alongside Emacs</a>.</p> | |
| 324 | <h2 id="vim-editing-doom-preset">Vim editing (Doom preset)</h2> | |
| 325 | <p>The Doom preset edits modally, as Doom Emacs does with <code class="verbatim">evil</code>, <code class="verbatim">evil-org</code>, <code class="verbatim">evil-surround</code>, <code class="verbatim">evil-snipe</code> and <code class="verbatim">evil-nerd-commenter</code>. Orgstar implements these itself; none of them are Emacs packages running inside it. The caret is a block in normal and visual states and a bar in insert state, and the modeline shows the state.</p> | |
| 326 | <h3 id="how-keys-are-handled">How keys are handled</h3> | |
| 327 | <p>Each key goes first to the keymap for the current state, then to the Vim engine:</p> | |
| 328 | <ol> | |
| 329 | <li>Keys with <code class="verbatim">⌘</code> go to the menus.</li> | |
| 330 | <li>If a Vim command is half typed (after <code class="verbatim">d</code>, <code class="verbatim">"a</code>, <code class="verbatim">3</code> and so on), the key goes to Vim.</li> | |
| 331 | <li>Otherwise the keymap gets the key. A prefix such as <code class="verbatim">SPC</code>, <code class="verbatim">g</code>, <code class="verbatim">z</code>, <code class="verbatim">[</code>, <code class="verbatim">]</code>, <code class="verbatim">C-c</code> or <code class="verbatim">C-x</code> waits for the next key, with key hints as described above. A complete sequence runs its command if the binding's context holds and the command can run at the caret.</li> | |
| 332 | <li>Anything the keymap does not take goes to Vim, as typed. In insert state, keys Vim does not handle are typed as text.</li> | |
| 333 | </ol> | |
| 334 | <p>Two consequences:</p> | |
| 335 | <ul> | |
| 336 | <li>Keymap commands do not take counts or registers. Once you type a count or a register, the following keys go straight to Vim.</li> | |
| 337 | <li>A sequence the keymap does not complete after <code class="verbatim">SPC</code>, <code class="verbatim">C-c</code>, <code class="verbatim">C-x</code> or another Control or Meta prefix is undefined: the echo area shows, for example, <code class="verbatim">SPC j is undefined</code>, and nothing runs. After <code class="verbatim">g</code>, <code class="verbatim">z</code>, <code class="verbatim">[</code> or <code class="verbatim">]</code>, which are Vim prefixes too, the keys are replayed into Vim, so <code class="verbatim">gu</code> and <code class="verbatim">gq</code> reach the Vim engine although the keymap binds other <code class="verbatim">g</code> keys.</li> | |
| 338 | </ul> | |
| 339 | <h3 id="states">States</h3> | |
| 340 | <table> | |
| 341 | <thead> | |
| 342 | <tr><th>State</th><th>Enter with</th><th>Leave with</th></tr> | |
| 343 | </thead> | |
| 344 | <tbody> | |
| 345 | <tr><td>Normal</td><td><code class="verbatim">ESC</code>, <code class="verbatim">C-[</code> or <code class="verbatim">C-g</code> from insert state; <code class="verbatim">ESC</code> from visual</td><td>—</td></tr> | |
| 346 | <tr><td>Insert</td><td><code class="verbatim">i</code>, <code class="verbatim">a</code>, <code class="verbatim">I</code>, <code class="verbatim">A</code>, <code class="verbatim">o</code>, <code class="verbatim">O</code>, <code class="verbatim">c</code> commands, <code class="verbatim">cc</code>, <code class="verbatim">C</code>, block <code class="verbatim">I</code>, <code class="verbatim">A</code>, <code class="verbatim">c</code></td><td><code class="verbatim">ESC</code>, <code class="verbatim">C-[</code>, <code class="verbatim">C-g</code></td></tr> | |
| 347 | <tr><td>Visual</td><td><code class="verbatim">v</code></td><td><code class="verbatim">v</code>, <code class="verbatim">ESC</code></td></tr> | |
| 348 | <tr><td>Visual line</td><td><code class="verbatim">V</code></td><td><code class="verbatim">V</code>, <code class="verbatim">ESC</code></td></tr> | |
| 349 | <tr><td>Visual block</td><td><code class="verbatim">C-v</code></td><td><code class="verbatim">C-v</code>, <code class="verbatim">ESC</code></td></tr> | |
| 350 | </tbody> | |
| 351 | </table> | |
| 352 | <p>Leaving insert state moves the caret back one character, as in Vim. A mouse click leaves visual state. In the keymap, <code class="verbatim">"visual"</code> is the state name for all three visual states.</p> | |
| 353 | <p>In insert state, <code class="verbatim">C-w</code> deletes the word before the caret and <code class="verbatim">C-u</code> deletes back to the line's indentation (or to the start of the line when the caret is already there). The rest of insert state is the Emacs preset's Org keys, the Doom insert-state keys in the reference (<code class="verbatim">TAB</code> and <code class="verbatim">S-TAB</code> on headings, items and tables, <code class="verbatim">C-t</code> and <code class="verbatim">C-d</code>, <code class="verbatim">C-S-h/j/k/l</code>, <code class="verbatim">C-SPC</code> for completion) and ordinary typing.</p> | |
| 354 | <h3 id="motions">Motions</h3> | |
| 355 | <p>Motions move the caret in normal state, extend the selection in visual states, and give the range for an operator. A count before a motion repeats it.</p> | |
| 356 | <table> | |
| 357 | <thead> | |
| 358 | <tr><th>Keys</th><th>Moves</th></tr> | |
| 359 | </thead> | |
| 360 | <tbody> | |
| 361 | <tr><td><code class="verbatim">h</code>, <code class="verbatim">l</code>, <code class="verbatim"><left></code>, <code class="verbatim"><right></code>, <code class="verbatim">DEL</code></td><td>Left, right; <code class="verbatim">DEL</code> is <code class="verbatim">h</code>. Stays on the line.</td></tr> | |
| 362 | <tr><td><code class="verbatim">j</code>, <code class="verbatim">k</code>, <code class="verbatim"><down></code>, <code class="verbatim"><up></code></td><td>Down, up, keeping the column.</td></tr> | |
| 363 | <tr><td><code class="verbatim">gj</code>, <code class="verbatim">gk</code></td><td>In Org files, to the next or previous Org element (<code class="verbatim">org-forward-element</code>, <code class="verbatim">org-backward-element</code>, as evil-org binds them); counts are ignored. On a heading, <code class="verbatim">gj</code> goes to the next heading after the subtree and <code class="verbatim">gk</code> to the previous heading at the same level or higher. In other files, down and up by screen lines in wrapped text.</td></tr> | |
| 364 | <tr><td><code class="verbatim">+</code>, <code class="verbatim">-</code>, <code class="verbatim">RET</code></td><td>First non-blank of the next or previous line. In Org files <code class="verbatim">RET</code> runs Act at Point instead.</td></tr> | |
| 365 | <tr><td><code class="verbatim">w</code>, <code class="verbatim">b</code>, <code class="verbatim">e</code>, <code class="verbatim">ge</code></td><td>Next word start, previous word start, word end, previous word end.</td></tr> | |
| 366 | <tr><td><code class="verbatim">W</code>, <code class="verbatim">B</code>, <code class="verbatim">E</code>, <code class="verbatim">gE</code></td><td>The same for blank-separated WORDs.</td></tr> | |
| 367 | <tr><td><code class="verbatim">0</code>, <code class="verbatim"><home></code></td><td>Start of the line.</td></tr> | |
| 368 | <tr><td><code class="verbatim">$</code>, <code class="verbatim"><end></code></td><td>End of the line; with a count, of the line count − 1 lines down.</td></tr> | |
| 369 | <tr><td><code class="verbatim">g_</code></td><td>Last non-blank of the line.</td></tr> | |
| 370 | <tr><td><code class="verbatim">gg</code>, <code class="verbatim">G</code></td><td>First line, last line; with a count, that line. The column is kept (<code class="verbatim">evil-start-of-line</code> nil).</td></tr> | |
| 371 | <tr><td><code class="verbatim">f</code> <em>x</em>, <code class="verbatim">F</code> <em>x</em>, <code class="verbatim">t</code> <em>x</em>, <code class="verbatim">T</code> <em>x</em></td><td>To, or to just before, the next or previous <em>x</em> on the line. These are one-character snipes, as Doom's <code class="verbatim">evil-snipe-override-mode</code> makes them. <em>x</em> also matches its accented and other variants, as Doom's <code class="verbatim">evil-snipe-char-fold</code> makes it: <code class="verbatim">a</code> matches <code class="verbatim">à</code>, <code class="verbatim">À</code>, <code class="verbatim">ª</code> and <code class="verbatim">a</code>. A lowercase <em>x</em> matches either case, a capital only capitals; <code class="verbatim">t</code> and <code class="verbatim">T</code> skip a match right next to the caret; <code class="verbatim">f SPC</code> and <code class="verbatim">t SPC</code> skip a run of blanks after the caret and stop at the last blank before the next word, or just before it.</td></tr> | |
| 372 | <tr><td><code class="verbatim">;</code>, <code class="verbatim">,</code></td><td>Repeats the last snipe (<code class="verbatim">s</code>, <code class="verbatim">S</code>, <code class="verbatim">f</code>, <code class="verbatim">F</code>, <code class="verbatim">t</code> or <code class="verbatim">T</code>), forward or reversed. A repeat searches all the text the window shows, so it can go past the caret's line (<code class="verbatim">evil-snipe-repeat-scope</code>, as Doom sets it). Right after a snipe, its own key repeats it: <code class="verbatim">f</code> goes on in the same direction and <code class="verbatim">F</code> reverses, and the same for <code class="verbatim">t</code> and <code class="verbatim">T</code> and for <code class="verbatim">s</code> and <code class="verbatim">S</code>. A count typed right after a snipe ends this: the key after the count starts a new snipe with that count, so <code class="verbatim">f a 2 f a</code> goes to the next <em>a</em>, then to the second <em>a</em> after it.</td></tr> | |
| 373 | <tr><td><code class="verbatim">s</code> <em>xy</em>, <code class="verbatim">S</code> <em>xy</em></td><td>evil-snipe: to the next or previous <em>xy</em> on the line. Each character matches its variants as for <code class="verbatim">f</code>, and <em>xy</em> without a capital matches case-insensitively. <code class="verbatim">SPC</code> and <code class="verbatim">TAB</code> are read as a space and a tab. Not available after an operator.</td></tr> | |
| 374 | <tr><td><code class="verbatim">%</code></td><td>The bracket matching the next <code class="verbatim">()</code>, <code class="verbatim">[]</code> or <code class="verbatim">{}</code> on the line.</td></tr> | |
| 375 | <tr><td><code class="verbatim">{</code>, <code class="verbatim">}</code></td><td>Previous, next blank line.</td></tr> | |
| 376 | <tr><td><code class="verbatim">/</code>, <code class="verbatim">?</code></td><td>Asks in the echo area for a regular expression and searches forward or backward, wrapping around the file.</td></tr> | |
| 377 | <tr><td><code class="verbatim">n</code>, <code class="verbatim">N</code></td><td>Repeats the last search in the same or the opposite direction.</td></tr> | |
| 378 | <tr><td><code class="verbatim">*</code>, <code class="verbatim">#</code></td><td>Searches forward or backward for the whole word under the caret.</td></tr> | |
| 379 | <tr><td><code class="verbatim">C-d</code>, <code class="verbatim">C-u</code></td><td>Down, up half the window's height; with a count, that many lines.</td></tr> | |
| 380 | <tr><td><code class="verbatim">H</code>, <code class="verbatim">M</code>, <code class="verbatim">L</code></td><td>First non-blank of the top, middle or bottom line the window shows. With a count, <code class="verbatim">H</code> goes to that line from the top and <code class="verbatim">L</code> from the bottom. Lines are text lines, not wrapped screen lines. Linewise after an operator.</td></tr> | |
| 381 | <tr><td><code class="verbatim">'</code> <em>a</em>, <code class="verbatim">`</code> <em>a</em></td><td>To mark <em>a</em>: its line's first non-blank, or its exact position. See <a href="#marks-and-jumps">Marks and jumps</a>.</td></tr> | |
| 382 | </tbody> | |
| 383 | </table> | |
| 384 | <p>Search patterns are ICU regular expressions as macOS uses them, close to PCRE; Emacs and Vim regexp syntax such as <code class="verbatim">\(...\)</code> or <code class="verbatim">\<</code> does not work. <code class="verbatim">:noh</code> is accepted and does nothing; searches are not highlighted.</p> | |
| 385 | <h3 id="operators">Operators</h3> | |
| 386 | <table> | |
| 387 | <thead> | |
| 388 | <tr><th>Keys</th><th>Does</th></tr> | |
| 389 | </thead> | |
| 390 | <tbody> | |
| 391 | <tr><td><code class="verbatim">d</code> <em>motion</em></td><td>Deletes. <code class="verbatim">dd</code> deletes lines.</td></tr> | |
| 392 | <tr><td><code class="verbatim">c</code> <em>motion</em></td><td>Deletes and enters insert state. <code class="verbatim">cc</code> keeps the line's indentation; <code class="verbatim">cw</code> changes to the end of the word, as <code class="verbatim">ce</code>.</td></tr> | |
| 393 | <tr><td><code class="verbatim">y</code> <em>motion</em></td><td>Yanks (copies). <code class="verbatim">yy</code> yanks lines.</td></tr> | |
| 394 | <tr><td><code class="verbatim">></code> <em>motion</em>, <code class="verbatim"><</code> <em>motion</em></td><td>Indents or outdents lines by 8 spaces (<code class="verbatim">evil-shift-width</code>, which Doom sets to Org's <code class="verbatim">tab-width</code>). <code class="verbatim">>></code> and <code class="verbatim"><<</code> act on lines.</td></tr> | |
| 395 | <tr><td><code class="verbatim">g~</code> <em>motion</em>, <code class="verbatim">gu</code> <em>motion</em>, <code class="verbatim">gU</code> <em>motion</em></td><td>Toggles case, lowercases, uppercases. <code class="verbatim">g~~</code>, <code class="verbatim">guu</code>, <code class="verbatim">gUU</code> act on lines.</td></tr> | |
| 396 | <tr><td><code class="verbatim">gc</code> <em>motion</em></td><td>Comments or uncomments lines with <code class="verbatim">#</code> (<code class="verbatim">evilnc-comment-operator</code>). <code class="verbatim">gcc</code> acts on lines. See <a href="#commenting">Commenting</a>.</td></tr> | |
| 397 | <tr><td><code class="verbatim">gq</code> <em>motion</em>, <code class="verbatim">gw</code> <em>motion</em></td><td>Fills the paragraphs in the motion's lines to the fill column, as Fill Paragraph does; other elements in the lines are left alone. <code class="verbatim">gq</code> leaves the caret on the first non-blank of the last line, <code class="verbatim">gw</code> where it was. Extra spaces between words and at the ends of lines are kept, as Doom fills without squeezing them. <code class="verbatim">gqq</code> and <code class="verbatim">gww</code> act on lines.</td></tr> | |
| 398 | </tbody> | |
| 399 | </table> | |
| 400 | <p><code class="verbatim">M-q</code> runs Fill Paragraph in normal, insert and visual state. In visual and visual-line state it fills every paragraph the selection touches and leaves the caret where it was. In visual-block state it fills the paragraph at the caret, as evil does with <code class="verbatim">transient-mark-mode</code> off. In each, if the text changed, the editor returns to normal state, otherwise the selection stays.</p> | |
| 401 | <p>Counts multiply: <code class="verbatim">2d3w</code> deletes six words. Doubling an operator with a count acts on that many lines: <code class="verbatim">3dd</code>.</p> | |
| 402 | <p>Single-key changes:</p> | |
| 403 | <table> | |
| 404 | <thead> | |
| 405 | <tr><th>Keys</th><th>Does</th></tr> | |
| 406 | </thead> | |
| 407 | <tbody> | |
| 408 | <tr><td><code class="verbatim">x</code>, <code class="verbatim"><delete></code></td><td>Deletes the character under the caret (count: that many, within the line).</td></tr> | |
| 409 | <tr><td><code class="verbatim">X</code></td><td>Deletes the character before the caret.</td></tr> | |
| 410 | <tr><td><code class="verbatim">D</code>, <code class="verbatim">C</code></td><td>Deletes, or changes, to the end of the line.</td></tr> | |
| 411 | <tr><td><code class="verbatim">Y</code></td><td>Yanks to the end of the line (<code class="verbatim">evil-want-Y-yank-to-eol</code>, as Doom sets it).</td></tr> | |
| 412 | <tr><td><code class="verbatim">p</code>, <code class="verbatim">P</code></td><td>Pastes after or before the caret; whole lines go below or above the current line. A count pastes that many times.</td></tr> | |
| 413 | <tr><td><code class="verbatim">J</code></td><td>Joins the next line (count: that many lines) with one space.</td></tr> | |
| 414 | <tr><td><code class="verbatim">~</code></td><td>Toggles the case of the character under the caret and moves right.</td></tr> | |
| 415 | <tr><td><code class="verbatim">r</code> <em>x</em></td><td>Replaces the character under the caret (count: that many) with <em>x</em>; <code class="verbatim">r RET</code> splits the line.</td></tr> | |
| 416 | <tr><td><code class="verbatim">u</code>, <code class="verbatim">C-r</code></td><td>Undo, redo, with counts.</td></tr> | |
| 417 | <tr><td><code class="verbatim">.</code></td><td>Repeats the last change.</td></tr> | |
| 418 | <tr><td><code class="verbatim">ZZ</code></td><td>Saves the file and closes the window, as <code class="verbatim">:wq</code>.</td></tr> | |
| 419 | <tr><td><code class="verbatim">ZQ</code></td><td>Closes the window, as <code class="verbatim">:q!</code>.</td></tr> | |
| 420 | </tbody> | |
| 421 | </table> | |
| 422 | <p><code class="verbatim">o</code> and <code class="verbatim">O</code> open a line below or above with Org's indentation: under a list item, aligned with the item's text; under a heading, none; otherwise the line's own indentation.</p> | |
| 423 | <h3 id="text-objects">Text objects</h3> | |
| 424 | <p>After an operator, or in visual state to select, <code class="verbatim">i</code> takes the inner object and <code class="verbatim">a</code> the object with its surrounding space or delimiters.</p> | |
| 425 | <table> | |
| 426 | <thead> | |
| 427 | <tr><th>Keys</th><th>Object</th></tr> | |
| 428 | </thead> | |
| 429 | <tbody> | |
| 430 | <tr><td><code class="verbatim">iw</code>, <code class="verbatim">aw</code>, <code class="verbatim">iW</code>, <code class="verbatim">aW</code></td><td>Word, WORD.</td></tr> | |
| 431 | <tr><td><code class="verbatim">i"</code>, <code class="verbatim">a"</code>, <code class="verbatim">i'</code>, <code class="verbatim">a'</code>, <code class="verbatim">i`</code>, <code class="verbatim">a`</code></td><td>Quoted text on the line.</td></tr> | |
| 432 | <tr><td><code class="verbatim">i(</code>, <code class="verbatim">a(</code>, <code class="verbatim">i)</code>, <code class="verbatim">a)</code>, <code class="verbatim">ib</code>, <code class="verbatim">ab</code></td><td>Parentheses.</td></tr> | |
| 433 | <tr><td><code class="verbatim">i[</code>, <code class="verbatim">a[</code>, <code class="verbatim">i]</code>, <code class="verbatim">a]</code></td><td>Square brackets.</td></tr> | |
| 434 | <tr><td><code class="verbatim">i{</code>, <code class="verbatim">a{</code>, <code class="verbatim">i}</code>, <code class="verbatim">a}</code>, <code class="verbatim">iB</code>, <code class="verbatim">aB</code></td><td>Braces.</td></tr> | |
| 435 | <tr><td><code class="verbatim">i<</code>, <code class="verbatim">a<</code>, <code class="verbatim">i></code>, <code class="verbatim">a></code></td><td>Angle brackets.</td></tr> | |
| 436 | <tr><td><code class="verbatim">ip</code>, <code class="verbatim">ap</code></td><td>Paragraph: lines up to a blank line.</td></tr> | |
| 437 | <tr><td><code class="verbatim">ie</code>, <code class="verbatim">ae</code></td><td>Org object at the caret: emphasis, a link, a timestamp, a footnote reference, an entity, a macro and the like (<code class="verbatim">evil-org-inner-object</code>, <code class="verbatim">evil-org-an-object</code>). <code class="verbatim">ie</code> on emphasis takes the text inside the markers, on a link its description. With no object at the caret, the element.</td></tr> | |
| 438 | <tr><td><code class="verbatim">iE</code>, <code class="verbatim">aE</code></td><td>Org element: a paragraph, a list, a table, a block, a drawer (<code class="verbatim">evil-org-inner-element</code>, <code class="verbatim">evil-org-an-element</code>).</td></tr> | |
| 439 | <tr><td><code class="verbatim">ir</code>, <code class="verbatim">ar</code></td><td>Org greater element: the list, table, drawer, block or section that contains the element (<code class="verbatim">evil-org-inner-greater-element</code>, <code class="verbatim">evil-org-a-greater-element</code>).</td></tr> | |
| 440 | <tr><td><code class="verbatim">iR</code>, <code class="verbatim">aR</code></td><td>Org subtree: <code class="verbatim">aR</code> is the heading and its subtree, <code class="verbatim">iR</code> its contents without the heading line (<code class="verbatim">evil-org-inner-subtree</code>, <code class="verbatim">evil-org-a-subtree</code>).</td></tr> | |
| 441 | </tbody> | |
| 442 | </table> | |
| 443 | <p>Tag objects (<code class="verbatim">it</code>, <code class="verbatim">at</code>) and sentence objects (<code class="verbatim">is</code>, <code class="verbatim">as</code>) are not available.</p> | |
| 444 | <h3 id="counts-and-registers">Counts and registers</h3> | |
| 445 | <p>A count is digits before a command; <code class="verbatim">0</code> only counts after another digit. A register is <code class="verbatim">"</code> and a name before the count and command: <code class="verbatim">"ayy</code>, <code class="verbatim">"a3dd</code>, <code class="verbatim">"ap</code>.</p> | |
| 446 | <table> | |
| 447 | <thead> | |
| 448 | <tr><th>Register</th><th>Holds</th></tr> | |
| 449 | </thead> | |
| 450 | <tbody> | |
| 451 | <tr><td><code class="verbatim">"a</code> to <code class="verbatim">"z</code></td><td>Named registers. Yanking or deleting into <code class="verbatim">A</code> to <code class="verbatim">Z</code> appends to the lowercase one. Writing to a named register leaves the clipboard alone.</td></tr> | |
| 452 | <tr><td><code class="verbatim">"0</code></td><td>The last yank.</td></tr> | |
| 453 | <tr><td><code class="verbatim">""</code>, <code class="verbatim">"+</code>, <code class="verbatim">"*</code></td><td>The system clipboard. This is the unnamed register: every yank, delete and change without a register goes to the clipboard, and <code class="verbatim">p</code> without a register pastes from it.</td></tr> | |
| 454 | <tr><td><code class="verbatim">"_</code></td><td>The black hole: deletes without saving the text.</td></tr> | |
| 455 | </tbody> | |
| 456 | </table> | |
| 457 | <p>Pasting from the clipboard is linewise when its text is what the last linewise yank or delete put there; text copied in another app pastes as characters. Numbered registers <code class="verbatim">"1</code> to <code class="verbatim">"9</code>, and the read-only registers such as <code class="verbatim">"%</code>, are not available.</p> | |
| 458 | <p>Registers and macros are shared by every buffer, as in evil: a yank into <code class="verbatim">"a</code> in one file pastes with <code class="verbatim">"ap</code> in another. Lowercase marks and the jump list belong to the buffer and are gone when it closes. Nothing is kept when Orgstar quits.</p> | |
| 459 | <h3 id="repeat">Repeat</h3> | |
| 460 | <p><code class="verbatim">.</code> repeats the last change made in normal state, including text typed in insert state that the change began: <code class="verbatim">ciwfoo ESC</code> then <code class="verbatim">.</code> changes the next word to <code class="verbatim">foo</code>. A count before <code class="verbatim">.</code> replaces the original count.</p> | |
| 461 | <p>Changes made from visual or visual-block state, visual <code class="verbatim">S</code> surrounds, and keymap commands (such as <code class="verbatim">M-l</code> or <code class="verbatim">SPC m t</code>) are not repeated by <code class="verbatim">.</code>.</p> | |
| 462 | <h3 id="macros">Macros</h3> | |
| 463 | <table> | |
| 464 | <thead> | |
| 465 | <tr><th>Keys</th><th>Does</th></tr> | |
| 466 | </thead> | |
| 467 | <tbody> | |
| 468 | <tr><td><code class="verbatim">q</code> <em>a</em></td><td>Starts recording keys into macro register <em>a</em> (a letter or digit). The echo area shows <code class="verbatim">Defining keyboard macro…</code>.</td></tr> | |
| 469 | <tr><td><code class="verbatim">q</code></td><td>Stops recording: <code class="verbatim">Keyboard macro defined</code>.</td></tr> | |
| 470 | <tr><td><code class="verbatim">@</code> <em>a</em></td><td>Plays macro <em>a</em>. A count plays it that many times.</td></tr> | |
| 471 | <tr><td><code class="verbatim">@@</code></td><td>Plays the last macro played.</td></tr> | |
| 472 | </tbody> | |
| 473 | </table> | |
| 474 | <p>A macro replays the keys you typed, including keymap commands, leader keys and insert-state typing. Keys with <code class="verbatim">⌘</code> are not recorded. Macros are kept apart from text registers: <code class="verbatim">"ap</code> does not paste a macro, and <code class="verbatim">"ay</code> does not change one. Macros can call macros up to 20 deep.</p> | |
| 475 | <h3 id="marks-and-jumps">Marks and jumps</h3> | |
| 476 | <p><code class="verbatim">m</code> <em>a</em> sets mark <em>a</em> (any letter) at the caret. Marks move with the text as you edit. <code class="verbatim">'</code> <em>a</em> goes to the first non-blank of the mark's line, <code class="verbatim">`</code> <em>a</em> to its exact position. <code class="verbatim">''</code> and <code class="verbatim">``</code> go back to where the last jump started.</p> | |
| 477 | <p>Jumps are <code class="verbatim">G</code>, <code class="verbatim">gg</code>, <code class="verbatim">%</code>, <code class="verbatim">{</code>, <code class="verbatim">}</code>, <code class="verbatim">n</code>, <code class="verbatim">N</code>, <code class="verbatim">*</code>, <code class="verbatim">#</code>, <code class="verbatim">'</code>, <code class="verbatim">`</code>, <code class="verbatim">H</code>, <code class="verbatim">M</code>, <code class="verbatim">L</code>, the snipes <code class="verbatim">s</code>, <code class="verbatim">S</code>, <code class="verbatim">f</code>, <code class="verbatim">F</code>, <code class="verbatim">t</code> and <code class="verbatim">T</code>, and searches with <code class="verbatim">/</code> and <code class="verbatim">?</code>. Each jump adds its starting point to the jump list, which keeps the last 100. <code class="verbatim">C-o</code> goes back through the list and <code class="verbatim">C-i</code> forward again. A new jump after <code class="verbatim">C-o</code> drops the places you went back past.</p> | |
| 478 | <p>Lowercase marks belong to the buffer, and so do <code class="verbatim">C-o</code> and <code class="verbatim">C-i</code>. Uppercase marks (<code class="verbatim">mA</code> to <code class="verbatim">mZ</code>) are file marks, shared by every buffer: <code class="verbatim">'A</code> or <code class="verbatim">`A</code> in another buffer shows the buffer the mark was set in, at the mark. A file mark goes away when its buffer closes.</p> | |
| 479 | <h3 id="visual-states">Visual states</h3> | |
| 480 | <p><code class="verbatim">v</code> selects characters, <code class="verbatim">V</code> whole lines, <code class="verbatim">C-v</code> a rectangular block. Motions and text objects extend the selection; <code class="verbatim">o</code> moves the caret to the other end. <code class="verbatim">gv</code> in normal state selects the last visual selection again.</p> | |
| 481 | <p>In visual and visual-line state:</p> | |
| 482 | <table> | |
| 483 | <thead> | |
| 484 | <tr><th>Keys</th><th>Does</th></tr> | |
| 485 | </thead> | |
| 486 | <tbody> | |
| 487 | <tr><td><code class="verbatim">d</code>, <code class="verbatim">x</code></td><td>Deletes the selection.</td></tr> | |
| 488 | <tr><td><code class="verbatim">c</code></td><td>Deletes it and enters insert state.</td></tr> | |
| 489 | <tr><td><code class="verbatim">y</code></td><td>Yanks it.</td></tr> | |
| 490 | <tr><td><code class="verbatim">></code>, <code class="verbatim"><</code></td><td>Indents or outdents its lines.</td></tr> | |
| 491 | <tr><td><code class="verbatim">~</code>, <code class="verbatim">u</code>, <code class="verbatim">U</code>, <code class="verbatim">g~</code>, <code class="verbatim">gu</code>, <code class="verbatim">gU</code></td><td>Toggles case, lowercases, uppercases.</td></tr> | |
| 492 | <tr><td><code class="verbatim">gc</code></td><td>Comments or uncomments its lines.</td></tr> | |
| 493 | <tr><td><code class="verbatim">gq</code>, <code class="verbatim">gw</code></td><td>Fills the paragraphs in its lines.</td></tr> | |
| 494 | <tr><td><code class="verbatim">J</code></td><td>Joins its lines.</td></tr> | |
| 495 | <tr><td><code class="verbatim">p</code>, <code class="verbatim">P</code></td><td>Replaces it with the clipboard or a register; the replaced text goes to the clipboard.</td></tr> | |
| 496 | <tr><td><code class="verbatim">S</code> <em>x</em></td><td>Surrounds it with <em>x</em> (see below). Linewise selections get the delimiters on lines of their own.</td></tr> | |
| 497 | <tr><td><code class="verbatim">v</code>, <code class="verbatim">V</code>, <code class="verbatim">C-v</code></td><td>Switches to another visual state, or leaves when it is the current one.</td></tr> | |
| 498 | <tr><td><code class="verbatim">TAB</code>, <code class="verbatim">S-TAB</code></td><td>Cycles visibility, as in normal state.</td></tr> | |
| 499 | </tbody> | |
| 500 | </table> | |
| 501 | <p>The Emacs preset's Org keys (<code class="verbatim">C-c ...</code>, <code class="verbatim">M-h/j/k/l</code>, <code class="verbatim">M-<left></code> and so on) also work in visual state.</p> | |
| 502 | <p>In visual-block state:</p> | |
| 503 | <table> | |
| 504 | <thead> | |
| 505 | <tr><th>Keys</th><th>Does</th></tr> | |
| 506 | </thead> | |
| 507 | <tbody> | |
| 508 | <tr><td>Motions, <code class="verbatim">o</code>, <code class="verbatim">O</code></td><td>Change the block; <code class="verbatim">o</code> and <code class="verbatim">O</code> move the caret to the opposite corner.</td></tr> | |
| 509 | <tr><td><code class="verbatim">d</code>, <code class="verbatim">x</code></td><td>Deletes the block.</td></tr> | |
| 510 | <tr><td><code class="verbatim">y</code></td><td>Yanks the block's lines, joined by newlines.</td></tr> | |
| 511 | <tr><td><code class="verbatim">c</code></td><td>Deletes the block and enters insert state; what you type is copied to every line when you press <code class="verbatim">ESC</code>.</td></tr> | |
| 512 | <tr><td><code class="verbatim">I</code>, <code class="verbatim">A</code></td><td>Inserts before or after the block on every line. <code class="verbatim">A</code> pads short lines with spaces; after <code class="verbatim">$</code>, it appends at each line's end.</td></tr> | |
| 513 | <tr><td><code class="verbatim">r</code> <em>x</em></td><td>Replaces every character of the block with <em>x</em>.</td></tr> | |
| 514 | <tr><td><code class="verbatim">~</code>, <code class="verbatim">u</code>, <code class="verbatim">U</code></td><td>Toggles case, lowercases, uppercases the block.</td></tr> | |
| 515 | <tr><td><code class="verbatim">></code>, <code class="verbatim"><</code></td><td>Indents or outdents the block's lines.</td></tr> | |
| 516 | <tr><td><code class="verbatim">v</code>, <code class="verbatim">V</code></td><td>Switches to visual or visual-line state.</td></tr> | |
| 517 | </tbody> | |
| 518 | </table> | |
| 519 | <p>Block <code class="verbatim">I</code>, <code class="verbatim">A</code> and <code class="verbatim">c</code> copy the typed text to the other lines only when it contains no newline. A yanked block pastes as ordinary lines, not as a block.</p> | |
| 520 | <h3 id="surround">Surround</h3> | |
| 521 | <p>As <code class="verbatim">evil-surround</code>:</p> | |
| 522 | <table> | |
| 523 | <thead> | |
| 524 | <tr><th>Keys</th><th>Does</th></tr> | |
| 525 | </thead> | |
| 526 | <tbody> | |
| 527 | <tr><td><code class="verbatim">ys</code> <em>motion</em> <em>x</em></td><td>Surrounds the motion's text with <em>x</em>: <code class="verbatim">ys$*</code> makes the rest of the line bold. Trailing blanks stay outside.</td></tr> | |
| 528 | <tr><td><code class="verbatim">ys</code> <code class="verbatim">i</code> <em>obj</em> <em>x</em>, <code class="verbatim">ys</code> <code class="verbatim">a</code> <em>obj</em> <em>x</em></td><td>Surrounds a text object: <code>ysiw=</code> wraps the word in <code>=</code> for verbatim.</td></tr> | |
| 529 | <tr><td><code class="verbatim">yss</code> <em>x</em></td><td>Surrounds the line, from its first non-blank.</td></tr> | |
| 530 | <tr><td><code class="verbatim">ds</code> <em>x</em></td><td>Deletes the surrounding <em>x</em>. With an opening bracket, the blanks inside go too.</td></tr> | |
| 531 | <tr><td><code class="verbatim">cs</code> <em>x</em> <em>y</em></td><td>Changes the surrounding <em>x</em> to <em>y</em>.</td></tr> | |
| 532 | <tr><td><code class="verbatim">S</code> <em>x</em> (visual)</td><td>Surrounds the selection.</td></tr> | |
| 533 | </tbody> | |
| 534 | </table> | |
| 535 | <table> | |
| 536 | <thead> | |
| 537 | <tr><th><em>x</em></th><th>Delimiters</th></tr> | |
| 538 | </thead> | |
| 539 | <tbody> | |
| 540 | <tr><td><code class="verbatim">(</code>, <code class="verbatim">[</code>, <code class="verbatim">{</code>, <code class="verbatim"><</code></td><td>The pair with a space inside each: <code class="verbatim">( text )</code>.</td></tr> | |
| 541 | <tr><td><code class="verbatim">)</code>, <code class="verbatim">b</code></td><td><code class="verbatim">(text)</code></td></tr> | |
| 542 | <tr><td><code class="verbatim">]</code>, <code class="verbatim">r</code></td><td><code class="verbatim">[text]</code></td></tr> | |
| 543 | <tr><td><code class="verbatim">}</code>, <code class="verbatim">B</code></td><td><code class="verbatim">{text}</code></td></tr> | |
| 544 | <tr><td><code class="verbatim">></code>, <code class="verbatim">a</code></td><td><code class="verbatim"><text></code></td></tr> | |
| 545 | <tr><td><code class="verbatim">SPC</code></td><td>A space on each side.</td></tr> | |
| 546 | <tr><td>Any other character</td><td>That character on both sides: <code class="verbatim">*</code>, <code class="verbatim">/</code>, <code class="verbatim">_</code>, <code class="verbatim">+</code>, <code>=</code>, <code class="verbatim">~</code>, <code class="verbatim">"</code>, <code class="verbatim">'</code>.</td></tr> | |
| 547 | </tbody> | |
| 548 | </table> | |
| 549 | <p>For <code class="verbatim">ds</code> and <code class="verbatim">cs</code>, brackets are found across lines; any other character is matched on the caret's line. Tags (<code class="verbatim">t</code>) and functions (<code class="verbatim">f</code>) are not supported.</p> | |
| 550 | <h3 id="commenting">Commenting</h3> | |
| 551 | <p><code class="verbatim">gc</code> with a motion or text object, <code class="verbatim">gcc</code> for lines, and <code class="verbatim">gc</code> in visual state toggle Org comments. Lines get <code class="verbatim">#</code> followed by a space at the shallowest indentation among them; blank lines are left alone. When every non-blank line is already a comment, the comments are removed instead. This is <code class="verbatim">comment-or-uncomment-region</code> in Org, as <code class="verbatim">evilnc-comment-operator</code> runs it.</p> | |
| 552 | <h3 id="org-keys-in-normal-state">Org keys in normal state</h3> | |
| 553 | <p>Besides the leader, the preset binds these evil-org and Doom keys in normal state. <code class="verbatim">TAB</code>, <code class="verbatim">S-TAB</code> and <code class="verbatim">RET</code> in normal state, and the Emacs preset's Org keys in every state, are listed in the <a href="#key-reference">key reference</a>. <code class="verbatim">gj</code> and <code class="verbatim">gk</code> move by Org element; see <a href="#motions">Motions</a>.</p> | |
| 554 | <table> | |
| 555 | <thead> | |
| 556 | <tr><th>Keys</th><th>Command</th></tr> | |
| 557 | </thead> | |
| 558 | <tbody> | |
| 559 | <tr><td><code class="verbatim">TAB</code></td><td>Cycle Visibility (<code class="verbatim">org-cycle</code>). Also in visual state.</td></tr> | |
| 560 | <tr><td><code class="verbatim">S-TAB</code></td><td>Cycle Global Visibility. Also in visual and insert state.</td></tr> | |
| 561 | <tr><td><code class="verbatim">RET</code></td><td>Act at Point (<code class="verbatim">+org/dwim-at-point</code>).</td></tr> | |
| 562 | <tr><td><code class="verbatim">z a</code></td><td>Toggle Fold (<code class="verbatim">+org/toggle-fold</code>). On a heading line: a folded heading opens one level, showing its body and its child headings folded; an open one folds.</td></tr> | |
| 563 | <tr><td><code class="verbatim">z o</code></td><td>Open Fold (<code class="verbatim">+org/open-fold</code>). On a heading line, a folded heading opens one level; an open one stays as it is.</td></tr> | |
| 564 | <tr><td><code class="verbatim">z c</code></td><td>Close Fold (<code class="verbatim">outline-hide-subtree</code>). Folds the subtree the caret is in, from anywhere inside it.</td></tr> | |
| 565 | <tr><td><code class="verbatim">z A</code></td><td>Cycle Global Visibility.</td></tr> | |
| 566 | <tr><td><code class="verbatim">g h</code></td><td>Up to Parent Heading.</td></tr> | |
| 567 | <tr><td><code class="verbatim">] h</code>, <code class="verbatim">[ h</code></td><td>Next or previous heading at the same level.</td></tr> | |
| 568 | <tr><td><code class="verbatim">] b</code>, <code class="verbatim">[ b</code></td><td>Next or previous buffer.</td></tr> | |
| 569 | <tr><td><code class="verbatim">M-h</code>, <code class="verbatim">M-j</code>, <code class="verbatim">M-k</code>, <code class="verbatim">M-l</code></td><td><code class="verbatim">M-<left></code>, <code class="verbatim">M-<down></code>, <code class="verbatim">M-<up></code>, <code class="verbatim">M-<right></code>: promote, move down, move up, demote on headings; the same for items; move columns and rows in tables. Also in insert and visual state.</td></tr> | |
| 570 | <tr><td><code class="verbatim">M-H</code>, <code class="verbatim">M-J</code>, <code class="verbatim">M-K</code>, <code class="verbatim">M-L</code></td><td>The <code class="verbatim">M-S-</code> arrow forms: subtree promote and demote, table row and column insert and delete. Also in insert and visual state.</td></tr> | |
| 571 | <tr><td><code class="verbatim">C-S-h</code>, <code class="verbatim">C-S-j</code>, <code class="verbatim">C-S-k</code>, <code class="verbatim">C-S-l</code></td><td>The <code class="verbatim">S-</code> arrow forms: TODO keyword, priority, timestamp and property value changes. Also in insert state.</td></tr> | |
| 572 | </tbody> | |
| 573 | </table> | |
| 574 | <h3 id="the-leader">The leader</h3> | |
| 575 | <p><code class="verbatim">SPC</code> in normal state is Doom's leader and <code class="verbatim">SPC m</code> its local leader for Org. Pause after <code class="verbatim">SPC</code> to see the key hints.</p> | |
| 576 | <table> | |
| 577 | <thead> | |
| 578 | <tr><th>Keys</th><th>Command</th></tr> | |
| 579 | </thead> | |
| 580 | <tbody> | |
| 581 | <tr><td><code class="verbatim">SPC ,</code></td><td>Switch to Buffer… (<code class="verbatim">app.buffer.switch</code>)</td></tr> | |
| 582 | <tr><td><code class="verbatim">SPC .</code></td><td>Quick Open… (<code class="verbatim">app.quick-open</code>)</td></tr> | |
| 583 | <tr><td><code class="verbatim">SPC /</code></td><td>Search Notes (<code class="verbatim">app.search</code>)</td></tr> | |
| 584 | <tr><td><code class="verbatim">SPC :</code></td><td>Command Palette… (<code class="verbatim">app.palette</code>)</td></tr> | |
| 585 | <tr><td><code class="verbatim">SPC `</code></td><td>Last Buffer (<code class="verbatim">app.buffer.last</code>)</td></tr> | |
| 586 | <tr><td><code class="verbatim">SPC b B</code></td><td>Switch to Buffer… (<code class="verbatim">app.buffer.switch</code>)</td></tr> | |
| 587 | <tr><td><code class="verbatim">SPC b K</code></td><td>Close All Buffers (<code class="verbatim">app.buffer.kill-all</code>)</td></tr> | |
| 588 | <tr><td><code class="verbatim">SPC b O</code></td><td>Close Other Buffers (<code class="verbatim">app.buffer.kill-others</code>)</td></tr> | |
| 589 | <tr><td><code class="verbatim">SPC b S</code></td><td>Save All Buffers (<code class="verbatim">app.save-all</code>)</td></tr> | |
| 590 | <tr><td><code class="verbatim">SPC b [</code></td><td>Previous Buffer (<code class="verbatim">app.buffer.previous</code>)</td></tr> | |
| 591 | <tr><td><code class="verbatim">SPC b ]</code></td><td>Next Buffer (<code class="verbatim">app.buffer.next</code>)</td></tr> | |
| 592 | <tr><td><code class="verbatim">SPC b b</code></td><td>Switch to Buffer… (<code class="verbatim">app.buffer.switch</code>)</td></tr> | |
| 593 | <tr><td><code class="verbatim">SPC b d</code></td><td>Close Buffer (<code class="verbatim">app.buffer.kill</code>)</td></tr> | |
| 594 | <tr><td><code class="verbatim">SPC b k</code></td><td>Close Buffer (<code class="verbatim">app.buffer.kill</code>)</td></tr> | |
| 595 | <tr><td><code class="verbatim">SPC b n</code></td><td>Next Buffer (<code class="verbatim">app.buffer.next</code>)</td></tr> | |
| 596 | <tr><td><code class="verbatim">SPC b p</code></td><td>Previous Buffer (<code class="verbatim">app.buffer.previous</code>)</td></tr> | |
| 597 | <tr><td><code class="verbatim">SPC b s</code></td><td>Save (<code class="verbatim">app.save</code>)</td></tr> | |
| 598 | <tr><td><code class="verbatim">SPC f f</code></td><td>Quick Open… (<code class="verbatim">app.quick-open</code>)</td></tr> | |
| 599 | <tr><td><code class="verbatim">SPC f s</code></td><td>Save (<code class="verbatim">app.save</code>)</td></tr> | |
| 600 | <tr><td><code class="verbatim">SPC h r r</code></td><td>Reload Keymap (<code class="verbatim">app.reload-keymap</code>)</td></tr> | |
| 601 | <tr><td><code class="verbatim">SPC n l</code></td><td>Store Link (<code class="verbatim">org.link.store</code>)</td></tr> | |
| 602 | <tr><td><code class="verbatim">SPC o a</code></td><td>Agenda (<code class="verbatim">app.agenda</code>)</td></tr> | |
| 603 | <tr><td><code class="verbatim">SPC q q</code></td><td>Quit Orgstar (<code class="verbatim">app.quit</code>)</td></tr> | |
| 604 | <tr><td><code class="verbatim">SPC s p</code></td><td>Search Notes (<code class="verbatim">app.search</code>)</td></tr> | |
| 605 | <tr><td><code class="verbatim">SPC s s</code></td><td>Find (<code class="verbatim">edit.find</code>)</td></tr> | |
| 606 | <tr><td><code class="verbatim">SPC SPC</code></td><td>Quick Open… (<code class="verbatim">app.quick-open</code>)</td></tr> | |
| 607 | <tr><td><code class="verbatim">SPC t s</code></td><td>Check Spelling While Typing (<code class="verbatim">editor.toggle-spell-check</code>)</td></tr> | |
| 608 | <tr><td><code class="verbatim">SPC t w</code></td><td>Truncate or Wrap Long Lines (<code class="verbatim">editor.toggle-truncate-lines</code>)</td></tr> | |
| 609 | <tr><td><code class="verbatim">SPC X</code></td><td>Capture… (<code class="verbatim">app.capture</code>)</td></tr> | |
| 610 | <tr><td><code class="verbatim">SPC z t</code></td><td>Clock Report (<code class="verbatim">app.clock.report</code>)</td></tr> | |
| 611 | <tr><td><code class="verbatim">SPC m '</code></td><td>Edit Block (<code class="verbatim">org.edit-special</code>)</td></tr> | |
| 612 | <tr><td><code class="verbatim">SPC m .</code></td><td>Go to Heading… (<code class="verbatim">org.goto</code>)</td></tr> | |
| 613 | <tr><td><code class="verbatim">SPC m A</code></td><td>Archive Subtree (<code class="verbatim">app.archive</code>)</td></tr> | |
| 614 | <tr><td><code class="verbatim">SPC m b -</code></td><td>Insert Table Rule (<code class="verbatim">org.table.insert-hline</code>)</td></tr> | |
| 615 | <tr><td><code class="verbatim">SPC m b a</code></td><td>Align Table (<code class="verbatim">org.table.align</code>)</td></tr> | |
| 616 | <tr><td><code class="verbatim">SPC m b d c</code></td><td>Delete Table Column (<code class="verbatim">org.table.delete-column</code>)</td></tr> | |
| 617 | <tr><td><code class="verbatim">SPC m b d r</code></td><td>Delete Table Row (<code class="verbatim">org.table.kill-row</code>)</td></tr> | |
| 618 | <tr><td><code class="verbatim">SPC m b i c</code></td><td>Insert Table Column (<code class="verbatim">org.table.insert-column</code>)</td></tr> | |
| 619 | <tr><td><code class="verbatim">SPC m b i h</code></td><td>Insert Table Rule (<code class="verbatim">org.table.insert-hline</code>)</td></tr> | |
| 620 | <tr><td><code class="verbatim">SPC m b i r</code></td><td>Insert Table Row (<code class="verbatim">org.table.insert-row</code>)</td></tr> | |
| 621 | <tr><td><code class="verbatim">SPC m b r</code></td><td>Recalculate Table (<code class="verbatim">org.table.recalc-all</code>)</td></tr> | |
| 622 | <tr><td><code class="verbatim">SPC m c E</code></td><td>Set Effort (<code class="verbatim">org.effort.set</code>)</td></tr> | |
| 623 | <tr><td><code class="verbatim">SPC m c G</code></td><td>Go to Recent Clocked Entry… (<code class="verbatim">app.clock.goto-recent</code>)</td></tr> | |
| 624 | <tr><td><code class="verbatim">SPC m c I</code></td><td>Clock In to Last Entry (<code class="verbatim">app.clock.in-last</code>)</td></tr> | |
| 625 | <tr><td><code class="verbatim">SPC m c R</code></td><td>Clock Report (<code class="verbatim">app.clock.report</code>)</td></tr> | |
| 626 | <tr><td><code class="verbatim">SPC m c c</code></td><td>Cancel Clock (<code class="verbatim">app.clock.cancel</code>)</td></tr> | |
| 627 | <tr><td><code class="verbatim">SPC m c d</code></td><td>Mark as Default Clock Task (<code class="verbatim">app.clock.default</code>)</td></tr> | |
| 628 | <tr><td><code class="verbatim">SPC m c g</code></td><td>Go to Clocked Entry (<code class="verbatim">app.clock.goto</code>)</td></tr> | |
| 629 | <tr><td><code class="verbatim">SPC m c i</code></td><td>Clock In (<code class="verbatim">app.clock.in</code>)</td></tr> | |
| 630 | <tr><td><code class="verbatim">SPC m c o</code></td><td>Clock Out (<code class="verbatim">app.clock.out</code>)</td></tr> | |
| 631 | <tr><td><code class="verbatim">SPC m c r</code></td><td>Resolve Open Clocks… (<code class="verbatim">app.clock.resolve</code>)</td></tr> | |
| 632 | <tr><td><code class="verbatim">SPC m d T</code></td><td>Insert Inactive Timestamp (<code class="verbatim">org.timestamp.inactive</code>)</td></tr> | |
| 633 | <tr><td><code class="verbatim">SPC m d d</code></td><td>Set Deadline (<code class="verbatim">org.deadline</code>)</td></tr> | |
| 634 | <tr><td><code class="verbatim">SPC m d s</code></td><td>Schedule (<code class="verbatim">org.schedule</code>)</td></tr> | |
| 635 | <tr><td><code class="verbatim">SPC m d t</code></td><td>Insert Timestamp (<code class="verbatim">org.timestamp.active</code>)</td></tr> | |
| 636 | <tr><td><code class="verbatim">SPC m e h h</code></td><td>Export to HTML (<code class="verbatim">app.export.html</code>)</td></tr> | |
| 637 | <tr><td><code class="verbatim">SPC m e h o</code></td><td>Export to HTML and Open (<code class="verbatim">app.export.html-open</code>)</td></tr> | |
| 638 | <tr><td><code class="verbatim">SPC m e l p</code></td><td>Export to PDF with Emacs (<code class="verbatim">app.export.pdf</code>)</td></tr> | |
| 639 | <tr><td><code class="verbatim">SPC m e m m</code></td><td>Export to Markdown (<code class="verbatim">app.export.markdown</code>)</td></tr> | |
| 640 | <tr><td><code class="verbatim">SPC m h</code></td><td>Toggle Heading (<code class="verbatim">org.heading.toggle</code>)</td></tr> | |
| 641 | <tr><td><code class="verbatim">SPC m i</code></td><td>Toggle Item (<code class="verbatim">org.item.toggle</code>)</td></tr> | |
| 642 | <tr><td><code class="verbatim">SPC m l i</code></td><td>Store ID Link (<code class="verbatim">org.id.store-link</code>)</td></tr> | |
| 643 | <tr><td><code class="verbatim">SPC m l l</code></td><td>Insert Link… (<code class="verbatim">org.link.insert</code>)</td></tr> | |
| 644 | <tr><td><code class="verbatim">SPC m l s</code></td><td>Store Link (<code class="verbatim">org.link.store</code>)</td></tr> | |
| 645 | <tr><td><code class="verbatim">SPC m o</code></td><td>Set Property… (<code class="verbatim">org.property.read-and-set</code>)</td></tr> | |
| 646 | <tr><td><code class="verbatim">SPC m p d</code></td><td>Lower Priority (<code class="verbatim">org.priority.down</code>)</td></tr> | |
| 647 | <tr><td><code class="verbatim">SPC m p p</code></td><td>Set Priority… (<code class="verbatim">org.priority.set</code>)</td></tr> | |
| 648 | <tr><td><code class="verbatim">SPC m p u</code></td><td>Raise Priority (<code class="verbatim">org.priority.up</code>)</td></tr> | |
| 649 | <tr><td><code class="verbatim">SPC m q</code></td><td>Set Tags (<code class="verbatim">org.tags.set</code>)</td></tr> | |
| 650 | <tr><td><code class="verbatim">SPC m r r</code></td><td>Refile… (<code class="verbatim">app.refile</code>)</td></tr> | |
| 651 | <tr><td><code class="verbatim">SPC m s A</code></td><td>Archive Subtree (<code class="verbatim">app.archive</code>)</td></tr> | |
| 652 | <tr><td><code class="verbatim">SPC m s N</code></td><td>Widen (<code class="verbatim">org.widen</code>)</td></tr> | |
| 653 | <tr><td><code class="verbatim">SPC m s S</code></td><td>Sort Entries (<code class="verbatim">org.sort</code>)</td></tr> | |
| 654 | <tr><td><code class="verbatim">SPC m s a</code></td><td>Toggle ARCHIVE Tag (<code class="verbatim">org.archive.toggle-tag</code>)</td></tr> | |
| 655 | <tr><td><code class="verbatim">SPC m s c</code></td><td>Clone Subtree with Time Shift (<code class="verbatim">org.subtree.clone</code>)</td></tr> | |
| 656 | <tr><td><code class="verbatim">SPC m s d</code></td><td>Cut Subtree (<code class="verbatim">org.subtree.cut</code>)</td></tr> | |
| 657 | <tr><td><code class="verbatim">SPC m s h</code></td><td>Promote Subtree (<code class="verbatim">org.subtree.promote</code>)</td></tr> | |
| 658 | <tr><td><code class="verbatim">SPC m s j</code></td><td>Move Subtree Down (<code class="verbatim">org.subtree.down</code>)</td></tr> | |
| 659 | <tr><td><code class="verbatim">SPC m s k</code></td><td>Move Subtree Up (<code class="verbatim">org.subtree.up</code>)</td></tr> | |
| 660 | <tr><td><code class="verbatim">SPC m s l</code></td><td>Demote Subtree (<code class="verbatim">org.subtree.demote</code>)</td></tr> | |
| 661 | <tr><td><code class="verbatim">SPC m s n</code></td><td>Narrow to Subtree (<code class="verbatim">org.narrow.subtree</code>)</td></tr> | |
| 662 | <tr><td><code class="verbatim">SPC m s r</code></td><td>Refile… (<code class="verbatim">app.refile</code>)</td></tr> | |
| 663 | <tr><td><code class="verbatim">SPC m s s</code></td><td>Sparse Tree… (<code class="verbatim">org.sparse-tree</code>)</td></tr> | |
| 664 | <tr><td><code class="verbatim">SPC m t</code></td><td>Cycle TODO State (<code class="verbatim">org.todo.cycle</code>)</td></tr> | |
| 665 | <tr><td><code class="verbatim">SPC m x</code></td><td>Toggle Checkbox (<code class="verbatim">org.checkbox.toggle</code>)</td></tr> | |
| 666 | </tbody> | |
| 667 | </table> | |
| 668 | <h3 id="ex-commands">Ex commands</h3> | |
| 669 | <p><code class="verbatim">:</code> opens a prompt in the echo area. Orgstar understands these:</p> | |
| 670 | <table> | |
| 671 | <thead> | |
| 672 | <tr><th>Command</th><th>Does</th></tr> | |
| 673 | </thead> | |
| 674 | <tbody> | |
| 675 | <tr><td><code class="verbatim">:w</code>, <code class="verbatim">:write</code></td><td>Saves the file.</td></tr> | |
| 676 | <tr><td><code class="verbatim">:q</code>, <code class="verbatim">:quit</code>, <code class="verbatim">:q!</code></td><td>Closes the window. Closing the last window quits Orgstar, which asks about unsaved changes as usual.</td></tr> | |
| 677 | <tr><td><code class="verbatim">:wq</code>, <code class="verbatim">:wq!</code>, <code class="verbatim">:x</code></td><td>Saves, then closes the window.</td></tr> | |
| 678 | <tr><td><code class="verbatim">:e</code> <em>file</em>, <code class="verbatim">:edit</code> <em>file</em></td><td>Opens <em>file</em>, relative to the current file's folder; <code class="verbatim">~</code> is expanded.</td></tr> | |
| 679 | <tr><td><code class="verbatim">:e</code>, <code class="verbatim">:e!</code>, <code class="verbatim">:edit</code>, <code class="verbatim">:edit!</code></td><td>Reloads the file from disk; unsaved changes go to the recovery versions.</td></tr> | |
| 680 | <tr><td><code class="verbatim">:bn</code>, <code class="verbatim">:bnext</code></td><td>Next buffer.</td></tr> | |
| 681 | <tr><td><code class="verbatim">:bp</code>, <code class="verbatim">:bprevious</code>, <code class="verbatim">:bN</code>, <code class="verbatim">:bNext</code></td><td>Previous buffer.</td></tr> | |
| 682 | <tr><td><code class="verbatim">:bd</code>, <code class="verbatim">:bdelete</code>, <code class="verbatim">:bd!</code>, <code class="verbatim">:bw</code>, <code class="verbatim">:bwipeout</code></td><td>Closes the buffer.</td></tr> | |
| 683 | <tr><td><code class="verbatim">:b</code>, <code class="verbatim">:buffer</code>, <code class="verbatim">:ls</code>, <code class="verbatim">:buffers</code>, <code class="verbatim">:files</code></td><td>Asks for a buffer to switch to.</td></tr> | |
| 684 | <tr><td><code class="verbatim">:</code> <em>N</em></td><td>Goes to line <em>N</em>.</td></tr> | |
| 685 | <tr><td><code class="verbatim">:s/</code> <em>pattern</em> <code class="verbatim">/</code> <em>replacement</em> <code class="verbatim">/</code> <em>flags</em></td><td>Replaces on the current line. Flags: <code class="verbatim">g</code> for every match on the line, <code class="verbatim">i</code> to ignore case. <code class="verbatim">\1</code> in the replacement is the first group.</td></tr> | |
| 686 | <tr><td><code class="verbatim">:%s/</code> <em>pattern</em> <code class="verbatim">/</code> <em>replacement</em> <code class="verbatim">/</code> <em>flags</em></td><td>The same on every line.</td></tr> | |
| 687 | <tr><td><code class="verbatim">:noh</code>, <code class="verbatim">:nohlsearch</code></td><td>Accepted; does nothing.</td></tr> | |
| 688 | </tbody> | |
| 689 | </table> | |
| 690 | <p>Anything else shows <code class="verbatim">Not an editor command</code>. Ranges other than <code class="verbatim">%</code>, the <code class="verbatim">c</code> flag, <code class="verbatim">:g</code>, <code class="verbatim">:normal</code> and <code class="verbatim">:set</code> are not available, and <code class="verbatim">:</code> does not work in visual state.</p> | |
| 691 | <h3 id="not-available">Not available</h3> | |
| 692 | <p>Things evil users may reach for that Orgstar does not have: <code class="verbatim">zz</code>, <code class="verbatim">zt</code> and the other scroll and fold <code class="verbatim">z</code> commands except <code class="verbatim">za</code>, <code class="verbatim">zc</code>, <code class="verbatim">zo</code> and <code class="verbatim">zA</code>; <code class="verbatim">C-a</code> and <code class="verbatim">C-x</code> to increment numbers; <code class="verbatim">gi</code>, <code class="verbatim">g;</code>, <code class="verbatim">gJ</code>; replace state (<code class="verbatim">R</code>); <code class="verbatim">&</code>; <code class="verbatim">q:</code>; the numbered and read-only registers; tag and sentence text objects.</p> | |
| 693 | <h2 id="keys-in-other-windows">Keys in other windows</h2> | |
| 694 | <p>The block editor, opened by Edit Block (<code class="verbatim">C-c '</code>) or Edit Table Field (<code class="verbatim">C-c `</code>), is a plain editor with its own two bindings in every preset: <code class="verbatim">C-c '</code> or <code class="verbatim">⌘↩</code> saves and returns, <code class="verbatim">Esc</code> or <code class="verbatim">C-c C-k</code> leaves without saving. It does not use the Doom preset's Vim editing or your <code class="verbatim">keymap.toml</code>. See <a href="11-code-blocks.html">Code blocks</a>.</p> | |
| 695 | <p>The Agenda window has its own keys, modelled on <code class="verbatim">org-agenda-mode</code>, which <code class="verbatim">keymap.toml</code> does not change:</p> | |
| 696 | <table> | |
| 697 | <thead> | |
| 698 | <tr><th>Key</th><th>Does</th></tr> | |
| 699 | </thead> | |
| 700 | <tbody> | |
| 701 | <tr><td><code class="verbatim">RET</code></td><td>Opens the selected entry.</td></tr> | |
| 702 | <tr><td><code class="verbatim">f</code>, <code class="verbatim">b</code></td><td>Next or previous span (agenda views).</td></tr> | |
| 703 | <tr><td><code class="verbatim">.</code></td><td>Back to today (agenda views).</td></tr> | |
| 704 | <tr><td><code class="verbatim">\</code></td><td>Tag filter (<code class="verbatim">+tag-tag</code>).</td></tr> | |
| 705 | <tr><td><code>=</code></td><td>Regexp filter (<code class="verbatim">-re</code> drops matches).</td></tr> | |
| 706 | <tr><td><code class="verbatim"><</code></td><td>Filter to the selected entry's category, or clear the category filter.</td></tr> | |
| 707 | <tr><td>|</td><td>Removes every filter.</td></tr> | |
| 708 | <tr><td><code class="verbatim">l</code></td><td>Log mode on or off (agenda views).</td></tr> | |
| 709 | <tr><td><code class="verbatim">g</code>, <code class="verbatim">r</code></td><td>Rebuilds the views.</td></tr> | |
| 710 | <tr><td><code class="verbatim">t</code></td><td>Cycle TODO State.</td></tr> | |
| 711 | <tr><td><code class="verbatim">+</code>, <code class="verbatim">-</code></td><td>Raise or lower priority.</td></tr> | |
| 712 | <tr><td><code class="verbatim">:</code></td><td>Set tags.</td></tr> | |
| 713 | <tr><td><code class="verbatim">S-<right></code>, <code class="verbatim">S-<left></code></td><td>Moves the entry's timestamp a day later or earlier.</td></tr> | |
| 714 | <tr><td><code class="verbatim">I</code>, <code class="verbatim">O</code>, <code class="verbatim">X</code></td><td>Clock in, clock out, cancel the clock.</td></tr> | |
| 715 | <tr><td><code class="verbatim">m</code>, <code class="verbatim">u</code>, <code class="verbatim">U</code></td><td>Marks, unmarks, unmarks all entries for bulk actions.</td></tr> | |
| 716 | <tr><td><code class="verbatim">B</code></td><td>Bulk action on the marked entries.</td></tr> | |
| 717 | <tr><td><code class="verbatim">C-c C-t</code></td><td>Cycle TODO State.</td></tr> | |
| 718 | <tr><td><code class="verbatim">C-c C-s</code>, <code class="verbatim">C-c C-d</code></td><td>Schedule, set deadline.</td></tr> | |
| 719 | <tr><td><code class="verbatim">C-c C-q</code></td><td>Set tags.</td></tr> | |
| 720 | <tr><td><code class="verbatim">C-c C-w</code></td><td>Refile.</td></tr> | |
| 721 | <tr><td><code class="verbatim">C-c $</code>, <code class="verbatim">C-c C-x C-s</code></td><td>Archive.</td></tr> | |
| 722 | </tbody> | |
| 723 | </table> | |
| 724 | <p>See <a href="07-agenda.html">Agenda</a> for what these do. In the Capture window, typing a template's key picks it, <code class="verbatim">⌘↩</code> files the entry and <code class="verbatim">Esc</code> cancels; see <a href="08-capture.html">Capture</a>.</p> | |
| 725 | <h2 id="ios-and-ipados">iOS and iPadOS</h2> | |
| 726 | <p>With a hardware keyboard, the iOS app runs the Emacs preset's bindings, whatever preset the Mac uses. It does not read <code class="verbatim">keymap.toml</code> and has no Vim editing.</p> | |
| 727 | <ul> | |
| 728 | <li>Option acts as Meta when the key starts a binding (<code class="verbatim">M-RET</code>, <code class="verbatim">M-<left></code>); otherwise Option types characters as usual.</li> | |
| 729 | <li>Keys with <code class="verbatim">⌘</code> are left to iOS.</li> | |
| 730 | <li>Movement and editing keys bound to <code class="verbatim">edit.</code> commands (<code class="verbatim">C-a</code>, <code class="verbatim">C-e</code>, <code class="verbatim">C-k</code> and so on) are left to the iOS text system, except undo.</li> | |
| 731 | <li>Of the <code class="verbatim">app.</code> commands only the clock commands run from keys: <code class="verbatim">C-c C-x C-i</code>, <code class="verbatim">C-c C-x C-o</code>, <code class="verbatim">C-c C-x C-q</code>, <code class="verbatim">C-c C-x C-j</code>, <code class="verbatim">C-c C-x C-x</code> and <code class="verbatim">C-c C-x C-z</code>. Other <code class="verbatim">app.</code> keys, and editor commands such as narrowing, show <code class="verbatim">Not available on iOS yet</code>.</li> | |
| 732 | <li>A sequence of two or more keys whose command cannot run at the caret runs it anyway and shows its message, as on the Mac (for example <code class="verbatim">Not on a heading</code>).</li> | |
| 733 | <li>A pending prefix shows as a message, without key hints.</li> | |
| 734 | </ul> | |
| 735 | <p>The on-screen key bar's buttons run what their Emacs keys run at the caret (Fold is <code class="verbatim">TAB</code>, Promote is <code class="verbatim">M-<left></code>, TODO is <code class="verbatim">C-c C-t</code>). See <a href="14-ios.html">iOS</a>.</p> | |
| 736 | <h2 id="key-reference">Key reference</h2> | |
| 737 | <p>Every binding in the three presets, generated from the presets themselves. Each command's id, for <code class="verbatim">keymap.toml</code>, follows its title.</p> | |
| 738 | <ul> | |
| 739 | <li><strong>Emacs</strong> lists the Emacs preset's keys.</li> | |
| 740 | <li><strong>Mac</strong> lists the Mac preset's keys, with macOS symbols. <code class="verbatim">⇥</code> is Tab and <code class="verbatim">↩</code> Return.</li> | |
| 741 | <li><strong>Doom</strong> lists the keys the Doom preset adds. Every Emacs-preset key that starts with <code class="verbatim">C-c</code> or <code class="verbatim">C-x</code>, the <code class="verbatim">M-</code> and <code class="verbatim">S-</code> arrow keys, <code class="verbatim">M-RET</code>, <code class="verbatim">M-S-RET</code>, <code class="verbatim">C-RET</code>, <code class="verbatim">M-x</code> and <code class="verbatim">M-q</code> also work in the Doom preset, in normal, insert and visual states, so they are not repeated in the Doom column. Doom keys marked (N), (I) or (V) work only in normal, insert or visual state; unmarked ones work in all three.</li> | |
| 742 | </ul> | |
| 743 | <p>When a key appears in several rows, it runs the command whose condition holds at the caret: for example <code class="verbatim">M-<right></code> demotes a heading, indents a list item and moves a table column. The descriptions say where each one applies. Movement and text editing in the Doom preset are the Vim keys above, so the Doom column is empty for those rows.</p> | |
| 744 | <h3 id="movement-and-the-region">Movement and the region</h3> | |
| 745 | <table> | |
| 746 | <thead> | |
| 747 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 748 | </thead> | |
| 749 | <tbody> | |
| 750 | <tr><td>Forward Character (<code class="verbatim">edit.forward-char</code>)</td><td><code class="verbatim">C-f</code></td><td>—</td><td>—</td><td>Moves forward one character (<code class="verbatim">forward-char</code>).</td></tr> | |
| 751 | <tr><td>Backward Character (<code class="verbatim">edit.backward-char</code>)</td><td><code class="verbatim">C-b</code></td><td>—</td><td>—</td><td>Moves back one character (<code class="verbatim">backward-char</code>).</td></tr> | |
| 752 | <tr><td>Next Line (<code class="verbatim">edit.next-line</code>)</td><td><code class="verbatim">C-n</code></td><td>—</td><td>—</td><td>Moves down one line (<code class="verbatim">next-line</code>).</td></tr> | |
| 753 | <tr><td>Previous Line (<code class="verbatim">edit.previous-line</code>)</td><td><code class="verbatim">C-p</code></td><td>—</td><td>—</td><td>Moves up one line (<code class="verbatim">previous-line</code>).</td></tr> | |
| 754 | <tr><td>Beginning of Line (<code class="verbatim">edit.beginning-of-line</code>)</td><td><code class="verbatim">C-a</code></td><td>—</td><td>—</td><td>Moves to the start of the line (<code class="verbatim">move-beginning-of-line</code>).</td></tr> | |
| 755 | <tr><td>End of Line (<code class="verbatim">edit.end-of-line</code>)</td><td><code class="verbatim">C-e</code></td><td>—</td><td>—</td><td>Moves to the end of the line (<code class="verbatim">move-end-of-line</code>).</td></tr> | |
| 756 | <tr><td>Forward Word (<code class="verbatim">edit.forward-word</code>)</td><td><code class="verbatim">M-f</code></td><td>—</td><td>—</td><td>Moves forward one word (<code class="verbatim">forward-word</code>).</td></tr> | |
| 757 | <tr><td>Backward Word (<code class="verbatim">edit.backward-word</code>)</td><td><code class="verbatim">M-b</code></td><td>—</td><td>—</td><td>Moves back one word (<code class="verbatim">backward-word</code>).</td></tr> | |
| 758 | <tr><td>Beginning of Buffer (<code class="verbatim">edit.beginning-of-buffer</code>)</td><td><code class="verbatim">M-<</code></td><td>—</td><td>—</td><td>Moves to the start of the file (<code class="verbatim">beginning-of-buffer</code>).</td></tr> | |
| 759 | <tr><td>End of Buffer (<code class="verbatim">edit.end-of-buffer</code>)</td><td><code class="verbatim">M-></code></td><td>—</td><td>—</td><td>Moves to the end of the file (<code class="verbatim">end-of-buffer</code>).</td></tr> | |
| 760 | <tr><td>Scroll Up (<code class="verbatim">edit.scroll-up</code>)</td><td><code class="verbatim">C-v</code></td><td>—</td><td>—</td><td>Scrolls down one screen (<code class="verbatim">scroll-up-command</code>).</td></tr> | |
| 761 | <tr><td>Scroll Down (<code class="verbatim">edit.scroll-down</code>)</td><td><code class="verbatim">M-v</code></td><td>—</td><td>—</td><td>Scrolls up one screen (<code class="verbatim">scroll-down-command</code>).</td></tr> | |
| 762 | <tr><td>Recenter (<code class="verbatim">edit.recenter</code>)</td><td><code class="verbatim">C-l</code></td><td>—</td><td>—</td><td>Scrolls so the caret's line is in the middle of the window (<code class="verbatim">recenter-top-bottom</code>, without the cycling).</td></tr> | |
| 763 | <tr><td>Set Mark (<code class="verbatim">edit.set-mark</code>)</td><td><code class="verbatim">C-SPC</code></td><td>—</td><td>—</td><td>Sets the mark at the caret. Until the next command that is not a movement, movement keys extend the selection (<code class="verbatim">set-mark-command</code>).</td></tr> | |
| 764 | <tr><td>Quit (<code class="verbatim">edit.keyboard-quit</code>)</td><td><code class="verbatim">C-g</code></td><td>—</td><td>—</td><td>Drops the mark and the selection, and shows <code class="verbatim">Quit</code> (<code class="verbatim">keyboard-quit</code>).</td></tr> | |
| 765 | <tr><td>Select All (<code class="verbatim">edit.select-all</code>)</td><td><code class="verbatim">C-x h</code></td><td>—</td><td>—</td><td>Selects the whole file (<code class="verbatim">mark-whole-buffer</code>).</td></tr> | |
| 766 | </tbody> | |
| 767 | </table> | |
| 768 | <h3 id="editing">Editing</h3> | |
| 769 | <table> | |
| 770 | <thead> | |
| 771 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 772 | </thead> | |
| 773 | <tbody> | |
| 774 | <tr><td>Delete Character (<code class="verbatim">edit.delete-char</code>)</td><td><code class="verbatim">C-d</code></td><td>—</td><td>—</td><td>Deletes the character after the caret (<code class="verbatim">delete-char</code>).</td></tr> | |
| 775 | <tr><td>Kill Word (<code class="verbatim">edit.kill-word</code>)</td><td><code class="verbatim">M-d</code></td><td>—</td><td>—</td><td>Deletes to the end of the word (<code class="verbatim">kill-word</code>).</td></tr> | |
| 776 | <tr><td>Kill Word Backward (<code class="verbatim">edit.backward-kill-word</code>)</td><td><code class="verbatim">M-DEL</code></td><td>—</td><td>—</td><td>Deletes to the start of the word (<code class="verbatim">backward-kill-word</code>).</td></tr> | |
| 777 | <tr><td>Kill Line (<code class="verbatim">edit.kill-line</code>)</td><td><code class="verbatim">C-k</code></td><td>—</td><td>—</td><td>Deletes to the end of the line, or the newline at its end, into the macOS kill buffer (<code class="verbatim">kill-line</code>).</td></tr> | |
| 778 | <tr><td>Kill Region (<code class="verbatim">edit.kill-region</code>)</td><td><code class="verbatim">C-w</code></td><td>—</td><td>—</td><td>Cuts the selection to the clipboard (<code class="verbatim">kill-region</code>).</td></tr> | |
| 779 | <tr><td>Copy Region (<code class="verbatim">edit.copy-region</code>)</td><td><code class="verbatim">M-w</code></td><td>—</td><td>—</td><td>Copies the selection to the clipboard (<code class="verbatim">kill-ring-save</code>).</td></tr> | |
| 780 | <tr><td>Yank (<code class="verbatim">edit.yank</code>)</td><td><code class="verbatim">C-y</code></td><td>—</td><td>—</td><td>Inserts the text last deleted with Kill Line, from the macOS kill buffer, not the clipboard (<code class="verbatim">yank</code>). There is no kill ring.</td></tr> | |
| 781 | <tr><td>Undo (<code class="verbatim">edit.undo</code>)</td><td><code class="verbatim">C-/</code>, <code class="verbatim">C-_</code>, <code class="verbatim">C-x u</code></td><td>—</td><td>—</td><td>Undoes the last change (<code class="verbatim">undo</code>).</td></tr> | |
| 782 | <tr><td>Transpose Characters (<code class="verbatim">edit.transpose-chars</code>)</td><td><code class="verbatim">C-t</code></td><td>—</td><td>—</td><td>Swaps the characters around the caret (<code class="verbatim">transpose-chars</code>).</td></tr> | |
| 783 | <tr><td>Find (<code class="verbatim">edit.find</code>)</td><td><code class="verbatim">C-s</code>, <code class="verbatim">C-r</code></td><td>—</td><td><code class="verbatim">SPC s s</code> (N)</td><td>Opens the find bar. <code class="verbatim">C-s</code> and <code class="verbatim">C-r</code> both open it; there is no incremental search (<code class="verbatim">isearch-forward</code>).</td></tr> | |
| 784 | <tr><td>Find and Replace (<code class="verbatim">edit.replace</code>)</td><td><code class="verbatim">M-%</code></td><td>—</td><td>—</td><td>Opens the find bar with replace (<code class="verbatim">query-replace</code>).</td></tr> | |
| 785 | <tr><td>Find Next (<code class="verbatim">edit.find-next</code>)</td><td>—</td><td>—</td><td>—</td><td>Goes to the next match of the find bar's text.</td></tr> | |
| 786 | <tr><td>Find Previous (<code class="verbatim">edit.find-previous</code>)</td><td>—</td><td>—</td><td>—</td><td>Goes to the previous match.</td></tr> | |
| 787 | <tr><td>Use Selection for Find (<code class="verbatim">edit.use-selection-for-find</code>)</td><td>—</td><td>—</td><td>—</td><td>Puts the selection in the find bar.</td></tr> | |
| 788 | <tr><td>Complete at Point (<code class="verbatim">editor.complete</code>)</td><td><code class="verbatim">C-M-i</code></td><td>—</td><td><code class="verbatim">C-SPC</code> (I), <code class="verbatim">C-@</code> (I)</td><td>Completes what is typed at the caret: <code class="verbatim">#+</code> keywords and their values, link types, entities, tags, TODO keywords, headings, drawers, properties, src languages and header arguments, and <code class="verbatim"><s</code>-style templates (<code class="verbatim">completion-at-point</code>). One candidate is inserted; several open a list.</td></tr> | |
| 789 | <tr><td>Fill Paragraph (<code class="verbatim">org.fill-paragraph</code>)</td><td><code class="verbatim">M-q</code></td><td><code class="verbatim">⌃⌘P</code></td><td>—</td><td>Refills the paragraph or list item to the fill column (<code class="verbatim">org-fill-paragraph</code>); with a selection, every paragraph it touches. In the Doom preset, <code class="verbatim">gq</code> and <code class="verbatim">gw</code> fill the lines a motion covers; see <a href="#operators">Operators</a>.</td></tr> | |
| 790 | </tbody> | |
| 791 | </table> | |
| 792 | <h3 id="outline-visibility-and-narrowing">Outline: visibility and narrowing</h3> | |
| 793 | <table> | |
| 794 | <thead> | |
| 795 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 796 | </thead> | |
| 797 | <tbody> | |
| 798 | <tr><td>Cycle Visibility (<code class="verbatim">org.cycle</code>)</td><td><code class="verbatim">TAB</code></td><td><code class="verbatim">⇥</code></td><td><code class="verbatim">TAB</code> (N, V)</td><td>On a heading, cycles its subtree through folded, children and everything; on the first or last line of a drawer or block, folds or unfolds it (<code class="verbatim">org-cycle</code>). Elsewhere, <code class="verbatim">TAB</code> types a tab in the Emacs and Mac presets.</td></tr> | |
| 799 | <tr><td>Toggle Fold (<code class="verbatim">org.fold.toggle</code>)</td><td>—</td><td>—</td><td><code class="verbatim">z a</code> (N)</td><td>On a heading line, opens a folded heading one level or folds an open one (<code class="verbatim">+org/toggle-fold</code>).</td></tr> | |
| 800 | <tr><td>Open Fold (<code class="verbatim">org.fold.open</code>)</td><td>—</td><td>—</td><td><code class="verbatim">z o</code> (N)</td><td>On a heading line, opens a folded heading one level (<code class="verbatim">+org/open-fold</code>).</td></tr> | |
| 801 | <tr><td>Close Fold (<code class="verbatim">org.fold.close</code>)</td><td>—</td><td>—</td><td><code class="verbatim">z c</code> (N)</td><td>Folds the subtree the caret is in (<code class="verbatim">outline-hide-subtree</code>).</td></tr> | |
| 802 | <tr><td>Cycle Global Visibility (<code class="verbatim">org.cycle-global</code>)</td><td><code class="verbatim">S-TAB</code></td><td><code class="verbatim">⇧⇥</code></td><td><code class="verbatim">S-TAB</code>, <code class="verbatim">z A</code> (N)</td><td>Cycles the whole file through overview, contents and everything (<code class="verbatim">org-global-cycle</code>).</td></tr> | |
| 803 | <tr><td>Narrow to Subtree (<code class="verbatim">org.narrow.subtree</code>)</td><td><code class="verbatim">C-x n s</code></td><td>—</td><td><code class="verbatim">SPC m s n</code> (N)</td><td>Shows only the current subtree (<code class="verbatim">org-narrow-to-subtree</code>).</td></tr> | |
| 804 | <tr><td>Narrow to Block (<code class="verbatim">org.narrow.block</code>)</td><td><code class="verbatim">C-x n b</code></td><td>—</td><td>—</td><td>Shows only the current block (<code class="verbatim">org-narrow-to-block</code>).</td></tr> | |
| 805 | <tr><td>Widen (<code class="verbatim">org.widen</code>)</td><td><code class="verbatim">C-x n w</code></td><td>—</td><td><code class="verbatim">SPC m s N</code> (N)</td><td>Shows the whole file again (<code class="verbatim">widen</code>).</td></tr> | |
| 806 | <tr><td>Narrow to Subtree or Widen (<code class="verbatim">org.narrow.toggle</code>)</td><td>—</td><td><code class="verbatim">⌃⌘N</code></td><td>—</td><td>Narrows to the subtree, or widens when already narrowed (<code class="verbatim">org-toggle-narrow-to-subtree</code>).</td></tr> | |
| 807 | <tr><td>Sparse Tree… (<code class="verbatim">org.sparse-tree</code>)</td><td><code class="verbatim">C-c /</code></td><td>—</td><td><code class="verbatim">SPC m s s</code> (N)</td><td>Asks for a match and shows only the matching entries and their context (<code class="verbatim">org-sparse-tree</code>). <code class="verbatim">C-c C-c</code> clears the highlights.</td></tr> | |
| 808 | <tr><td>Show or Hide Inline Images (<code class="verbatim">org.toggle-inline-images</code>)</td><td><code class="verbatim">C-c C-x C-v</code></td><td>—</td><td>—</td><td>Shows or hides image links as images (<code class="verbatim">org-toggle-inline-images</code>).</td></tr> | |
| 809 | </tbody> | |
| 810 | </table> | |
| 811 | <h3 id="outline-headings-and-subtrees">Outline: headings and subtrees</h3> | |
| 812 | <table> | |
| 813 | <thead> | |
| 814 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 815 | </thead> | |
| 816 | <tbody> | |
| 817 | <tr><td>Next Heading (<code class="verbatim">org.heading.next</code>)</td><td><code class="verbatim">C-c C-n</code></td><td><code class="verbatim">⌥⌘↓</code></td><td>—</td><td>Moves to the next heading (<code class="verbatim">org-next-visible-heading</code>).</td></tr> | |
| 818 | <tr><td>Previous Heading (<code class="verbatim">org.heading.previous</code>)</td><td><code class="verbatim">C-c C-p</code></td><td><code class="verbatim">⌥⌘↑</code></td><td>—</td><td>Moves to the previous heading (<code class="verbatim">org-previous-visible-heading</code>).</td></tr> | |
| 819 | <tr><td>Next Heading at Same Level (<code class="verbatim">org.heading.forward-same-level</code>)</td><td><code class="verbatim">C-c C-f</code></td><td><code class="verbatim">⌥⇧⌘↓</code></td><td><code class="verbatim">] h</code> (N)</td><td>Moves to the next heading at the same level (<code class="verbatim">org-forward-heading-same-level</code>).</td></tr> | |
| 820 | <tr><td>Previous Heading at Same Level (<code class="verbatim">org.heading.backward-same-level</code>)</td><td><code class="verbatim">C-c C-b</code></td><td><code class="verbatim">⌥⇧⌘↑</code></td><td><code class="verbatim">[ h</code> (N)</td><td>Moves to the previous heading at the same level (<code class="verbatim">org-backward-heading-same-level</code>).</td></tr> | |
| 821 | <tr><td>Up to Parent Heading (<code class="verbatim">org.heading.up</code>)</td><td><code class="verbatim">C-c C-u</code></td><td>—</td><td><code class="verbatim">g h</code> (N)</td><td>Moves to the parent heading (<code class="verbatim">outline-up-heading</code>).</td></tr> | |
| 822 | <tr><td>Go to Heading… (<code class="verbatim">org.goto</code>)</td><td><code class="verbatim">C-c C-j</code></td><td>—</td><td><code class="verbatim">SPC m .</code> (N)</td><td>Asks for a heading of this file by its outline path and jumps to it (<code class="verbatim">org-goto</code>).</td></tr> | |
| 823 | <tr><td>Insert Heading (<code class="verbatim">org.heading.insert</code>)</td><td><code class="verbatim">M-RET</code></td><td><code class="verbatim">⌘↩</code></td><td>—</td><td>Inserts a heading at the current level; on a list item, see Insert Item (<code class="verbatim">org-meta-return</code>, <code class="verbatim">org-insert-heading</code>).</td></tr> | |
| 824 | <tr><td>Insert Heading After Subtree (<code class="verbatim">org.heading.insert-after-subtree</code>)</td><td><code class="verbatim">C-RET</code></td><td><code class="verbatim">⌃⌘↩</code></td><td>—</td><td>Inserts a heading after the current subtree (<code class="verbatim">org-insert-heading-respect-content</code>).</td></tr> | |
| 825 | <tr><td>Insert TODO Heading (<code class="verbatim">org.heading.insert-todo</code>)</td><td><code class="verbatim">M-S-RET</code></td><td><code class="verbatim">⇧⌘↩</code></td><td>—</td><td>Inserts a heading with the first TODO keyword (<code class="verbatim">org-insert-todo-heading</code>).</td></tr> | |
| 826 | <tr><td>Promote Heading (<code class="verbatim">org.heading.promote</code>)</td><td><code class="verbatim">M-<left></code></td><td><code class="verbatim">⌃⌘←</code></td><td><code class="verbatim">M-h</code>, <code class="verbatim">C-d</code> (I), <code class="verbatim">S-TAB</code> (I)</td><td>On a heading, raises it one level (<code class="verbatim">org-do-promote</code>).</td></tr> | |
| 827 | <tr><td>Demote Heading (<code class="verbatim">org.heading.demote</code>)</td><td><code class="verbatim">M-<right></code></td><td><code class="verbatim">⌃⌘→</code></td><td><code class="verbatim">M-l</code>, <code class="verbatim">C-t</code> (I), <code class="verbatim">TAB</code> (I)</td><td>On a heading, lowers it one level (<code class="verbatim">org-do-demote</code>).</td></tr> | |
| 828 | <tr><td>Promote Subtree (<code class="verbatim">org.subtree.promote</code>)</td><td><code class="verbatim">M-S-<left></code></td><td><code class="verbatim">⌃⌥⌘←</code></td><td><code class="verbatim">M-H</code>, <code class="verbatim">SPC m s h</code> (N)</td><td>On a heading, raises it and its subtree (<code class="verbatim">org-promote-subtree</code>).</td></tr> | |
| 829 | <tr><td>Demote Subtree (<code class="verbatim">org.subtree.demote</code>)</td><td><code class="verbatim">M-S-<right></code></td><td><code class="verbatim">⌃⌥⌘→</code></td><td><code class="verbatim">M-L</code>, <code class="verbatim">SPC m s l</code> (N)</td><td>On a heading, lowers it and its subtree (<code class="verbatim">org-demote-subtree</code>).</td></tr> | |
| 830 | <tr><td>Move Subtree Up (<code class="verbatim">org.subtree.up</code>)</td><td><code class="verbatim">M-<up></code></td><td><code class="verbatim">⌃⌥⌘↑</code></td><td><code class="verbatim">M-k</code>, <code class="verbatim">SPC m s k</code> (N)</td><td>On a heading, swaps the subtree with the one above (<code class="verbatim">org-move-subtree-up</code>).</td></tr> | |
| 831 | <tr><td>Move Subtree Down (<code class="verbatim">org.subtree.down</code>)</td><td><code class="verbatim">M-<down></code></td><td><code class="verbatim">⌃⌥⌘↓</code></td><td><code class="verbatim">M-j</code>, <code class="verbatim">SPC m s j</code> (N)</td><td>On a heading, swaps the subtree with the one below (<code class="verbatim">org-move-subtree-down</code>).</td></tr> | |
| 832 | <tr><td>Mark Subtree (<code class="verbatim">org.subtree.mark</code>)</td><td><code class="verbatim">C-c @</code></td><td>—</td><td>—</td><td>Selects the current subtree (<code class="verbatim">org-mark-subtree</code>).</td></tr> | |
| 833 | <tr><td>Cut Subtree (<code class="verbatim">org.subtree.cut</code>)</td><td><code class="verbatim">C-c C-x C-w</code></td><td>—</td><td><code class="verbatim">SPC m s d</code> (N)</td><td>Cuts the subtree to the clipboard (<code class="verbatim">org-cut-subtree</code>).</td></tr> | |
| 834 | <tr><td>Copy Subtree (<code class="verbatim">org.subtree.copy</code>)</td><td><code class="verbatim">C-c C-x M-w</code></td><td>—</td><td>—</td><td>Copies the subtree to the clipboard (<code class="verbatim">org-copy-subtree</code>).</td></tr> | |
| 835 | <tr><td>Paste Subtree (<code class="verbatim">org.subtree.paste</code>)</td><td><code class="verbatim">C-c C-x C-y</code></td><td>—</td><td>—</td><td>Pastes a subtree from the clipboard, its levels adjusted to fit (<code class="verbatim">org-paste-subtree</code>).</td></tr> | |
| 836 | <tr><td>Clone Subtree with Time Shift (<code class="verbatim">org.subtree.clone</code>)</td><td><code class="verbatim">C-c C-x c</code></td><td>—</td><td><code class="verbatim">SPC m s c</code> (N)</td><td>Asks for a count and a time shift, then inserts shifted copies of the subtree (<code class="verbatim">org-clone-subtree-with-time-shift</code>).</td></tr> | |
| 837 | <tr><td>Sort Entries (<code class="verbatim">org.sort</code>)</td><td><code class="verbatim">C-c ^</code></td><td><code class="verbatim">⌃⇧⌘S</code></td><td><code class="verbatim">SPC m s S</code> (N)</td><td>Sorts by a key you pick: the lines of a table in a table, the list on an item, otherwise the children of the current heading (<code class="verbatim">org-sort</code>).</td></tr> | |
| 838 | <tr><td>Toggle Heading (<code class="verbatim">org.heading.toggle</code>)</td><td><code class="verbatim">C-c *</code></td><td>—</td><td><code class="verbatim">SPC m h</code> (N)</td><td>Outside a table, turns headings into text and lines or items into headings (<code class="verbatim">org-toggle-heading</code>).</td></tr> | |
| 839 | <tr><td>Toggle COMMENT (<code class="verbatim">org.heading.toggle-comment</code>)</td><td><code class="verbatim">C-c ;</code></td><td>—</td><td>—</td><td>Adds or removes the <code class="verbatim">COMMENT</code> keyword (<code class="verbatim">org-toggle-comment</code>).</td></tr> | |
| 840 | <tr><td>Refile… (<code class="verbatim">app.refile</code>)</td><td><code class="verbatim">C-c C-w</code></td><td><code class="verbatim">⌃⌘W</code></td><td><code class="verbatim">SPC m r r</code> (N), <code class="verbatim">SPC m s r</code> (N)</td><td>Asks for a target heading in your folders and moves the subtree there (<code class="verbatim">org-refile</code>).</td></tr> | |
| 841 | <tr><td>Archive Subtree (<code class="verbatim">app.archive</code>)</td><td><code class="verbatim">C-c C-x C-s</code>, <code class="verbatim">C-c $</code></td><td><code class="verbatim">⌃⌘A</code></td><td><code class="verbatim">SPC m A</code> (N), <code class="verbatim">SPC m s A</code> (N)</td><td>Moves the subtree to the archive file (<code class="verbatim">org-archive-subtree</code>).</td></tr> | |
| 842 | <tr><td>Toggle ARCHIVE Tag (<code class="verbatim">org.archive.toggle-tag</code>)</td><td><code class="verbatim">C-c C-x a</code></td><td>—</td><td><code class="verbatim">SPC m s a</code> (N)</td><td>Adds or removes the <code class="verbatim">ARCHIVE</code> tag (<code class="verbatim">org-toggle-archive-tag</code>).</td></tr> | |
| 843 | <tr><td>Archive to Archive Sibling (<code class="verbatim">org.archive.to-sibling</code>)</td><td><code class="verbatim">C-c C-x A</code></td><td>—</td><td>—</td><td>Moves the subtree under an <code class="verbatim">Archive</code> sibling heading (<code class="verbatim">org-archive-to-archive-sibling</code>).</td></tr> | |
| 844 | </tbody> | |
| 845 | </table> | |
| 846 | <h3 id="lists-and-checkboxes">Lists and checkboxes</h3> | |
| 847 | <table> | |
| 848 | <thead> | |
| 849 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 850 | </thead> | |
| 851 | <tbody> | |
| 852 | <tr><td>Insert Item (<code class="verbatim">org.item.insert</code>)</td><td><code class="verbatim">M-RET</code></td><td><code class="verbatim">⌘↩</code></td><td>—</td><td>In a list, inserts a new item (<code class="verbatim">org-insert-item</code>).</td></tr> | |
| 853 | <tr><td>Insert Checkbox Item (<code class="verbatim">org.item.insert-checkbox</code>)</td><td><code class="verbatim">M-S-RET</code></td><td><code class="verbatim">⇧⌘↩</code></td><td>—</td><td>In a list, inserts a new item with a checkbox.</td></tr> | |
| 854 | <tr><td>Indent Item (<code class="verbatim">org.item.indent</code>)</td><td><code class="verbatim">M-<right></code></td><td><code class="verbatim">⌃⌘→</code></td><td><code class="verbatim">M-l</code>, <code class="verbatim">C-t</code> (I)</td><td>In a list, indents the item (<code class="verbatim">org-indent-item</code>).</td></tr> | |
| 855 | <tr><td>Outdent Item (<code class="verbatim">org.item.outdent</code>)</td><td><code class="verbatim">M-<left></code></td><td><code class="verbatim">⌃⌘←</code></td><td><code class="verbatim">M-h</code>, <code class="verbatim">C-d</code> (I)</td><td>In a list, outdents the item (<code class="verbatim">org-outdent-item</code>).</td></tr> | |
| 856 | <tr><td>Indent Item and Children (<code class="verbatim">org.item.indent-tree</code>)</td><td><code class="verbatim">M-S-<right></code></td><td><code class="verbatim">⌃⌥⌘→</code></td><td><code class="verbatim">M-L</code>, <code class="verbatim">TAB</code> (I)</td><td>In a list, indents the item and its children (<code class="verbatim">org-indent-item-tree</code>).</td></tr> | |
| 857 | <tr><td>Outdent Item and Children (<code class="verbatim">org.item.outdent-tree</code>)</td><td><code class="verbatim">M-S-<left></code></td><td><code class="verbatim">⌃⌥⌘←</code></td><td><code class="verbatim">M-H</code>, <code class="verbatim">S-TAB</code> (I)</td><td>In a list, outdents the item and its children (<code class="verbatim">org-outdent-item-tree</code>).</td></tr> | |
| 858 | <tr><td>Move Item Up (<code class="verbatim">org.item.up</code>)</td><td><code class="verbatim">M-<up></code></td><td><code class="verbatim">⌃⌥⌘↑</code></td><td><code class="verbatim">M-k</code></td><td>In a list, swaps the item with the one above (<code class="verbatim">org-move-item-up</code>).</td></tr> | |
| 859 | <tr><td>Move Item Down (<code class="verbatim">org.item.down</code>)</td><td><code class="verbatim">M-<down></code></td><td><code class="verbatim">⌃⌥⌘↓</code></td><td><code class="verbatim">M-j</code></td><td>In a list, swaps the item with the one below (<code class="verbatim">org-move-item-down</code>).</td></tr> | |
| 860 | <tr><td>Toggle Checkbox (<code class="verbatim">org.checkbox.toggle</code>)</td><td><code class="verbatim">C-c C-x C-b</code></td><td><code class="verbatim">⌃⌘C</code></td><td><code class="verbatim">SPC m x</code> (N)</td><td>Checks or unchecks the item's checkbox (<code class="verbatim">org-toggle-checkbox</code>).</td></tr> | |
| 861 | <tr><td>Toggle Item (<code class="verbatim">org.item.toggle</code>)</td><td><code class="verbatim">C-c -</code></td><td>—</td><td><code class="verbatim">SPC m i</code> (N)</td><td>Outside a table: on an item, cycles the list's bullet style; elsewhere turns lines into items and items into text (<code class="verbatim">org-ctrl-c-minus</code>).</td></tr> | |
| 862 | </tbody> | |
| 863 | </table> | |
| 864 | <h3 id="todo-priority-and-tags">TODO, priority and tags</h3> | |
| 865 | <table> | |
| 866 | <thead> | |
| 867 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 868 | </thead> | |
| 869 | <tbody> | |
| 870 | <tr><td>Cycle TODO State (<code class="verbatim">org.todo.cycle</code>)</td><td><code class="verbatim">C-c C-t</code></td><td><code class="verbatim">⌃⌘T</code></td><td><code class="verbatim">SPC m t</code> (N)</td><td>Cycles the TODO keyword; with fast-selection keys in <code class="verbatim">#+TODO</code>, asks for one (<code class="verbatim">org-todo</code>).</td></tr> | |
| 871 | <tr><td>Next TODO Keyword (<code class="verbatim">org.todo.next</code>)</td><td><code class="verbatim">S-<right></code></td><td><code class="verbatim">⌃⇧⌘→</code></td><td><code class="verbatim">C-S-l</code> (N, I)</td><td>On a heading, sets the next keyword across all sequences (<code class="verbatim">org-shiftright</code>).</td></tr> | |
| 872 | <tr><td>Previous TODO Keyword (<code class="verbatim">org.todo.previous</code>)</td><td><code class="verbatim">S-<left></code></td><td><code class="verbatim">⌃⇧⌘←</code></td><td><code class="verbatim">C-S-h</code> (N, I)</td><td>On a heading, sets the previous keyword (<code class="verbatim">org-shiftleft</code>).</td></tr> | |
| 873 | <tr><td>Raise Priority (<code class="verbatim">org.priority.up</code>)</td><td><code class="verbatim">S-<up></code></td><td><code class="verbatim">⌃⌘↑</code></td><td><code class="verbatim">C-S-k</code> (N, I), <code class="verbatim">SPC m p u</code> (N)</td><td>On a heading, raises the priority (<code class="verbatim">org-priority-up</code>).</td></tr> | |
| 874 | <tr><td>Lower Priority (<code class="verbatim">org.priority.down</code>)</td><td><code class="verbatim">S-<down></code></td><td><code class="verbatim">⌃⌘↓</code></td><td><code class="verbatim">C-S-j</code> (N, I), <code class="verbatim">SPC m p d</code> (N)</td><td>On a heading, lowers the priority (<code class="verbatim">org-priority-down</code>).</td></tr> | |
| 875 | <tr><td>Set Priority… (<code class="verbatim">org.priority.set</code>)</td><td><code class="verbatim">C-c ,</code></td><td><code class="verbatim">⌃⌘,</code></td><td><code class="verbatim">SPC m p p</code> (N)</td><td>Asks for a priority; <code class="verbatim">SPC</code> removes it (<code class="verbatim">org-priority</code>).</td></tr> | |
| 876 | <tr><td>Set Priority A (<code class="verbatim">org.priority.set-a</code>)</td><td>—</td><td>—</td><td>—</td><td>Sets priority A. Bound only as a speed key.</td></tr> | |
| 877 | <tr><td>Set Priority B (<code class="verbatim">org.priority.set-b</code>)</td><td>—</td><td>—</td><td>—</td><td>Sets priority B. Bound only as a speed key.</td></tr> | |
| 878 | <tr><td>Set Priority C (<code class="verbatim">org.priority.set-c</code>)</td><td>—</td><td>—</td><td>—</td><td>Sets priority C. Bound only as a speed key.</td></tr> | |
| 879 | <tr><td>Remove Priority (<code class="verbatim">org.priority.remove</code>)</td><td>—</td><td>—</td><td>—</td><td>Removes the priority. Bound only as a speed key.</td></tr> | |
| 880 | <tr><td>Set Tags (<code class="verbatim">org.tags.set</code>)</td><td><code class="verbatim">C-c C-q</code></td><td><code class="verbatim">⌃⌘G</code></td><td><code class="verbatim">SPC m q</code> (N)</td><td>Sets the heading's tags, with fast selection when <code class="verbatim">#+TAGS</code> has keys (<code class="verbatim">org-set-tags-command</code>).</td></tr> | |
| 881 | </tbody> | |
| 882 | </table> | |
| 883 | <h3 id="properties-and-column-view">Properties and column view</h3> | |
| 884 | <table> | |
| 885 | <thead> | |
| 886 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 887 | </thead> | |
| 888 | <tbody> | |
| 889 | <tr><td>Set Property… (<code class="verbatim">org.property.read-and-set</code>)</td><td><code class="verbatim">C-c C-x p</code></td><td><code class="verbatim">⌃⇧⌘P</code></td><td><code class="verbatim">SPC m o</code> (N)</td><td>Asks for a property and a value and sets it (<code class="verbatim">org-set-property</code>).</td></tr> | |
| 890 | <tr><td>Next Allowed Value (<code class="verbatim">org.property.next-value</code>)</td><td><code class="verbatim">S-<right></code></td><td><code class="verbatim">⌃⇧⌘→</code></td><td><code class="verbatim">C-S-l</code> (N, I)</td><td>On a property line, sets the next allowed value (<code class="verbatim">org-property-next-allowed-value</code>).</td></tr> | |
| 891 | <tr><td>Previous Allowed Value (<code class="verbatim">org.property.previous-value</code>)</td><td><code class="verbatim">S-<left></code></td><td><code class="verbatim">⌃⇧⌘←</code></td><td><code class="verbatim">C-S-h</code> (N, I)</td><td>On a property line, sets the previous allowed value (<code class="verbatim">org-property-previous-allowed-value</code>).</td></tr> | |
| 892 | <tr><td>Set Effort (<code class="verbatim">org.effort.set</code>)</td><td><code class="verbatim">C-c C-x e</code></td><td><code class="verbatim">⌃⇧⌘E</code></td><td><code class="verbatim">SPC m c E</code> (N)</td><td>Sets the <code class="verbatim">Effort</code> property, offering <code class="verbatim">Effort_ALL</code> values (<code class="verbatim">org-set-effort</code>).</td></tr> | |
| 893 | <tr><td>Column View (<code class="verbatim">org.columns</code>)</td><td><code class="verbatim">C-c C-x C-c</code></td><td>—</td><td>—</td><td>Shows the column view of the entries, read-only (<code class="verbatim">org-columns</code>).</td></tr> | |
| 894 | <tr><td>Insert Column View Table (<code class="verbatim">org.columns.insert-dblock</code>)</td><td><code class="verbatim">C-c C-x i</code></td><td>—</td><td>—</td><td>Inserts a <code class="verbatim">columnview</code> dynamic block (<code class="verbatim">org-columns-insert-dblock</code>).</td></tr> | |
| 895 | <tr><td>Update Dynamic Block (<code class="verbatim">org.dblock.update</code>)</td><td><code class="verbatim">C-c C-x C-u</code>, <code class="verbatim">C-c C-c</code></td><td><code class="verbatim">⌃⌘X</code></td><td>—</td><td>Updates the dynamic block at point, such as a clock table; <code class="verbatim">C-c C-c</code> and <code class="verbatim">⌃⌘X</code> do it on the block's <code class="verbatim">#+BEGIN</code> line (<code class="verbatim">org-update-dblock</code>).</td></tr> | |
| 896 | </tbody> | |
| 897 | </table> | |
| 898 | <h3 id="dates-and-clocking">Dates and clocking</h3> | |
| 899 | <table> | |
| 900 | <thead> | |
| 901 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 902 | </thead> | |
| 903 | <tbody> | |
| 904 | <tr><td>Insert Timestamp (<code class="verbatim">org.timestamp.active</code>)</td><td><code class="verbatim">C-c .</code></td><td><code class="verbatim">⌃⌘.</code></td><td><code class="verbatim">SPC m d t</code> (N)</td><td>Asks for a date and inserts an active timestamp, or changes the one at point (<code class="verbatim">org-timestamp</code>).</td></tr> | |
| 905 | <tr><td>Insert Inactive Timestamp (<code class="verbatim">org.timestamp.inactive</code>)</td><td><code class="verbatim">C-c !</code></td><td><code class="verbatim">⌃⌥⌘.</code></td><td><code class="verbatim">SPC m d T</code> (N)</td><td>Same, inactive (<code class="verbatim">org-timestamp-inactive</code>).</td></tr> | |
| 906 | <tr><td>Schedule (<code class="verbatim">org.schedule</code>)</td><td><code class="verbatim">C-c C-s</code></td><td><code class="verbatim">⌃⌘S</code></td><td><code class="verbatim">SPC m d s</code> (N)</td><td>Asks for a date and sets <code class="verbatim">SCHEDULED</code> (<code class="verbatim">org-schedule</code>).</td></tr> | |
| 907 | <tr><td>Set Deadline (<code class="verbatim">org.deadline</code>)</td><td><code class="verbatim">C-c C-d</code></td><td><code class="verbatim">⌃⌘E</code></td><td><code class="verbatim">SPC m d d</code> (N)</td><td>Asks for a date and sets <code class="verbatim">DEADLINE</code> (<code class="verbatim">org-deadline</code>).</td></tr> | |
| 908 | <tr><td>Increase Timestamp Part (<code class="verbatim">org.timestamp.up</code>)</td><td><code class="verbatim">S-<up></code></td><td><code class="verbatim">⌃⌘↑</code></td><td><code class="verbatim">C-S-k</code> (N, I)</td><td>On a timestamp, increases the part under the caret: year, month, day, hour or minute (<code class="verbatim">org-timestamp-up</code>).</td></tr> | |
| 909 | <tr><td>Decrease Timestamp Part (<code class="verbatim">org.timestamp.down</code>)</td><td><code class="verbatim">S-<down></code></td><td><code class="verbatim">⌃⌘↓</code></td><td><code class="verbatim">C-S-j</code> (N, I)</td><td>On a timestamp, decreases the part under the caret (<code class="verbatim">org-timestamp-down</code>).</td></tr> | |
| 910 | <tr><td>Timestamp One Day Later (<code class="verbatim">org.timestamp.day-later</code>)</td><td><code class="verbatim">S-<right></code></td><td><code class="verbatim">⌃⌘→</code></td><td><code class="verbatim">C-S-l</code> (N, I)</td><td>On a timestamp, moves it one day later (<code class="verbatim">org-timestamp-up-day</code>).</td></tr> | |
| 911 | <tr><td>Timestamp One Day Earlier (<code class="verbatim">org.timestamp.day-earlier</code>)</td><td><code class="verbatim">S-<left></code></td><td><code class="verbatim">⌃⌘←</code></td><td><code class="verbatim">C-S-h</code> (N, I)</td><td>On a timestamp, moves it one day earlier (<code class="verbatim">org-timestamp-down-day</code>).</td></tr> | |
| 912 | <tr><td>Evaluate Time Range (<code class="verbatim">org.timestamp.evaluate-range</code>)</td><td><code class="verbatim">C-c C-y</code></td><td>—</td><td>—</td><td>Shows how long the time range lasts, or updates a clock line (<code class="verbatim">org-evaluate-time-range</code>).</td></tr> | |
| 913 | <tr><td>Clock In (<code class="verbatim">app.clock.in</code>)</td><td><code class="verbatim">C-c C-x C-i</code></td><td><code class="verbatim">⌃⌘I</code></td><td><code class="verbatim">SPC m c i</code> (N)</td><td>Starts the clock on the current entry (<code class="verbatim">org-clock-in</code>).</td></tr> | |
| 914 | <tr><td>Clock In to Recent Entry… (<code class="verbatim">app.clock.in-recent</code>)</td><td>—</td><td><code class="verbatim">⌃⌥⌘I</code></td><td>—</td><td>Asks for an entry from the clock history and clocks in to it (<code class="verbatim">org-clock-in</code> with <code class="verbatim">C-u</code>).</td></tr> | |
| 915 | <tr><td>Clock In to Last Entry (<code class="verbatim">app.clock.in-last</code>)</td><td><code class="verbatim">C-c C-x C-x</code></td><td>—</td><td><code class="verbatim">SPC m c I</code> (N)</td><td>Clocks in to the most recently clocked entry (<code class="verbatim">org-clock-in-last</code>).</td></tr> | |
| 916 | <tr><td>Clock Out (<code class="verbatim">app.clock.out</code>)</td><td><code class="verbatim">C-c C-x C-o</code></td><td><code class="verbatim">⌃⇧⌘I</code></td><td><code class="verbatim">SPC m c o</code> (N)</td><td>Stops the clock (<code class="verbatim">org-clock-out</code>).</td></tr> | |
| 917 | <tr><td>Cancel Clock (<code class="verbatim">app.clock.cancel</code>)</td><td><code class="verbatim">C-c C-x C-q</code></td><td><code class="verbatim">⌃⌘K</code></td><td><code class="verbatim">SPC m c c</code> (N)</td><td>Stops the clock and removes the running clock line (<code class="verbatim">org-clock-cancel</code>).</td></tr> | |
| 918 | <tr><td>Go to Clocked Entry (<code class="verbatim">app.clock.goto</code>)</td><td><code class="verbatim">C-c C-x C-j</code></td><td><code class="verbatim">⌃⌘J</code></td><td><code class="verbatim">SPC m c g</code> (N)</td><td>Opens the entry the clock is running on, or the most recently clocked one (<code class="verbatim">org-clock-goto</code>).</td></tr> | |
| 919 | <tr><td>Go to Recent Clocked Entry… (<code class="verbatim">app.clock.goto-recent</code>)</td><td>—</td><td><code class="verbatim">⌃⌥⌘J</code></td><td><code class="verbatim">SPC m c G</code> (N)</td><td>Asks for an entry from the clock history and opens it (<code class="verbatim">org-clock-goto</code> with <code class="verbatim">C-u</code>).</td></tr> | |
| 920 | <tr><td>Mark as Default Clock Task (<code class="verbatim">app.clock.default</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC m c d</code> (N)</td><td>Makes the current entry the default task, <code class="verbatim">d</code> in the clock selection (<code class="verbatim">org-clock-mark-default-task</code>).</td></tr> | |
| 921 | <tr><td>Resolve Open Clocks… (<code class="verbatim">app.clock.resolve</code>)</td><td><code class="verbatim">C-c C-x C-z</code></td><td>—</td><td><code class="verbatim">SPC m c r</code> (N)</td><td>Asks what to do with each open <code class="verbatim">CLOCK:</code> line in your folders (<code class="verbatim">org-resolve-clocks</code>).</td></tr> | |
| 922 | <tr><td>Clock Report (<code class="verbatim">app.clock.report</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC z t</code> (N), <code class="verbatim">SPC m c R</code> (N)</td><td>Opens the Clock Report window.</td></tr> | |
| 923 | <tr><td>Insert or Update Clock Table (<code class="verbatim">org.clock.report</code>)</td><td><code class="verbatim">C-c C-x C-r</code></td><td>—</td><td>—</td><td>Inserts a clock table, or updates the one at point (<code class="verbatim">org-clock-report</code>).</td></tr> | |
| 924 | </tbody> | |
| 925 | </table> | |
| 926 | <h3 id="tables">Tables</h3> | |
| 927 | <table> | |
| 928 | <thead> | |
| 929 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 930 | </thead> | |
| 931 | <tbody> | |
| 932 | <tr><td>Create Table (<code class="verbatim">org.table.create</code>)</td><td><code class="verbatim">C-c</code> |</td><td><code class="verbatim">⌃⌘\</code></td><td>—</td><td>Asks for a size and inserts an empty table (<code class="verbatim">org-table-create</code>).</td></tr> | |
| 933 | <tr><td>Next Table Field (<code class="verbatim">org.table.next-field</code>)</td><td><code class="verbatim">TAB</code></td><td><code class="verbatim">⇥</code></td><td><code class="verbatim">TAB</code> (I)</td><td>In a table, aligns it and moves to the next field, adding a row at the end (<code class="verbatim">org-table-next-field</code>).</td></tr> | |
| 934 | <tr><td>Previous Table Field (<code class="verbatim">org.table.previous-field</code>)</td><td><code class="verbatim">S-TAB</code></td><td><code class="verbatim">⇧⇥</code></td><td><code class="verbatim">S-TAB</code> (I)</td><td>In a table, moves to the previous field (<code class="verbatim">org-table-previous-field</code>).</td></tr> | |
| 935 | <tr><td>Next Table Row (<code class="verbatim">org.table.next-row</code>)</td><td><code class="verbatim">RET</code></td><td><code class="verbatim">↩</code></td><td><code class="verbatim">RET</code> (I)</td><td>In a table, moves to the same field in the next row, adding a row at the end (<code class="verbatim">org-table-next-row</code>).</td></tr> | |
| 936 | <tr><td>Align Table (<code class="verbatim">org.table.align</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC m b a</code> (N)</td><td>In a table, aligns it (<code class="verbatim">org-table-align</code>). <code class="verbatim">C-c C-c</code> in a table also aligns it; see Act at Point.</td></tr> | |
| 937 | <tr><td>Move Table Row Up (<code class="verbatim">org.table.row-up</code>)</td><td><code class="verbatim">M-<up></code></td><td><code class="verbatim">⌃⌘↑</code></td><td><code class="verbatim">M-k</code></td><td>In a table, moves the row up (<code class="verbatim">org-table-move-row-up</code>).</td></tr> | |
| 938 | <tr><td>Move Table Row Down (<code class="verbatim">org.table.row-down</code>)</td><td><code class="verbatim">M-<down></code></td><td><code class="verbatim">⌃⌘↓</code></td><td><code class="verbatim">M-j</code></td><td>In a table, moves the row down (<code class="verbatim">org-table-move-row-down</code>).</td></tr> | |
| 939 | <tr><td>Move Table Column Left (<code class="verbatim">org.table.column-left</code>)</td><td><code class="verbatim">M-<left></code></td><td><code class="verbatim">⌃⌘←</code></td><td><code class="verbatim">M-h</code>, <code class="verbatim">C-d</code> (I)</td><td>In a table, moves the column left (<code class="verbatim">org-table-move-column-left</code>).</td></tr> | |
| 940 | <tr><td>Move Table Column Right (<code class="verbatim">org.table.column-right</code>)</td><td><code class="verbatim">M-<right></code></td><td><code class="verbatim">⌃⌘→</code></td><td><code class="verbatim">M-l</code>, <code class="verbatim">C-t</code> (I)</td><td>In a table, moves the column right (<code class="verbatim">org-table-move-column-right</code>).</td></tr> | |
| 941 | <tr><td>Insert Table Column (<code class="verbatim">org.table.insert-column</code>)</td><td><code class="verbatim">M-S-<right></code></td><td><code class="verbatim">⌃⌥⌘→</code></td><td><code class="verbatim">M-L</code>, <code class="verbatim">SPC m b i c</code> (N)</td><td>In a table, inserts a column (<code class="verbatim">org-table-insert-column</code>).</td></tr> | |
| 942 | <tr><td>Delete Table Column (<code class="verbatim">org.table.delete-column</code>)</td><td><code class="verbatim">M-S-<left></code></td><td><code class="verbatim">⌃⌥⌘←</code></td><td><code class="verbatim">M-H</code>, <code class="verbatim">SPC m b d c</code> (N)</td><td>In a table, deletes the column (<code class="verbatim">org-table-delete-column</code>).</td></tr> | |
| 943 | <tr><td>Insert Table Row (<code class="verbatim">org.table.insert-row</code>)</td><td><code class="verbatim">M-S-<down></code></td><td><code class="verbatim">⌃⌥⌘↓</code></td><td><code class="verbatim">M-J</code>, <code class="verbatim">SPC m b i r</code> (N)</td><td>In a table, inserts a row (<code class="verbatim">org-table-insert-row</code>).</td></tr> | |
| 944 | <tr><td>Delete Table Row (<code class="verbatim">org.table.kill-row</code>)</td><td><code class="verbatim">M-S-<up></code></td><td><code class="verbatim">⌃⌥⌘↑</code></td><td><code class="verbatim">M-K</code>, <code class="verbatim">SPC m b d r</code> (N)</td><td>In a table, deletes the row (<code class="verbatim">org-table-kill-row</code>).</td></tr> | |
| 945 | <tr><td>Insert Table Rule (<code class="verbatim">org.table.insert-hline</code>)</td><td><code class="verbatim">C-c -</code></td><td><code class="verbatim">⌃⌘-</code></td><td><code class="verbatim">SPC m b -</code> (N), <code class="verbatim">SPC m b i h</code> (N)</td><td>In a table, inserts a horizontal rule (<code class="verbatim">org-table-insert-hline</code>).</td></tr> | |
| 946 | <tr><td>Recalculate Table Row (<code class="verbatim">org.table.recalc</code>)</td><td><code class="verbatim">C-c *</code></td><td><code class="verbatim">⌃⌘*</code></td><td>—</td><td>In a table, recalculates the current row (<code class="verbatim">org-table-recalculate</code>). On a US keyboard, <code class="verbatim">⌃⌘*</code> is typed <code class="verbatim">⌃⇧⌘8</code>.</td></tr> | |
| 947 | <tr><td>Recalculate Table (<code class="verbatim">org.table.recalc-all</code>)</td><td><code class="verbatim">C-c C-c</code></td><td><code class="verbatim">⌃⌘X</code></td><td><code class="verbatim">SPC m b r</code> (N)</td><td>Recalculates the whole table; <code class="verbatim">C-c C-c</code> and <code class="verbatim">⌃⌘X</code> run it on a <code class="verbatim">#+TBLFM</code> line (<code class="verbatim">org-table-recalculate</code> with <code class="verbatim">C-u</code>).</td></tr> | |
| 948 | <tr><td>Set Column Formula (<code class="verbatim">org.table.column-formula</code>)</td><td><code>C-c =</code></td><td>—</td><td>—</td><td>Asks for the column's formula, offering the stored one (<code class="verbatim">org-table-eval-formula</code>).</td></tr> | |
| 949 | <tr><td>Edit Table Field (<code class="verbatim">org.table.edit-field</code>)</td><td><code class="verbatim">C-c `</code></td><td>—</td><td>—</td><td>In a table, edits the field in a separate editor (<code class="verbatim">org-table-edit-field</code>).</td></tr> | |
| 950 | <tr><td>Shrink or Expand Table Column (<code class="verbatim">org.table.toggle-column-width</code>)</td><td><code class="verbatim">C-c TAB</code></td><td>—</td><td>—</td><td>In a table, shrinks or expands the column (<code class="verbatim">org-table-toggle-column-width</code>).</td></tr> | |
| 951 | </tbody> | |
| 952 | </table> | |
| 953 | <h3 id="links-and-footnotes">Links and footnotes</h3> | |
| 954 | <table> | |
| 955 | <thead> | |
| 956 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 957 | </thead> | |
| 958 | <tbody> | |
| 959 | <tr><td>Open Link (<code class="verbatim">org.link.open</code>)</td><td><code class="verbatim">C-c C-o</code></td><td><code class="verbatim">⌃⌘O</code></td><td>—</td><td>Follows the link or timestamp at the caret (<code class="verbatim">org-open-at-point</code>).</td></tr> | |
| 960 | <tr><td>Insert Link… (<code class="verbatim">org.link.insert</code>)</td><td><code class="verbatim">C-c C-l</code></td><td><code class="verbatim">⌘K</code></td><td><code class="verbatim">SPC m l l</code> (N)</td><td>Asks for a link and description and inserts it, offering stored links (<code class="verbatim">org-insert-link</code>).</td></tr> | |
| 961 | <tr><td>Store Link (<code class="verbatim">org.link.store</code>)</td><td><code class="verbatim">C-c l</code></td><td><code class="verbatim">⌃⌘L</code></td><td><code class="verbatim">SPC m l s</code> (N), <code class="verbatim">SPC n l</code> (N)</td><td>Stores a link to the current entry for a later Insert Link (<code class="verbatim">org-store-link</code>).</td></tr> | |
| 962 | <tr><td>Store ID Link (<code class="verbatim">org.id.store-link</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC m l i</code> (N)</td><td>Gives the entry an <code class="verbatim">ID</code> if needed and stores an <code class="verbatim">id:</code> link to it (<code class="verbatim">org-id-store-link</code>).</td></tr> | |
| 963 | <tr><td>Footnote Action (<code class="verbatim">org.footnote.action</code>)</td><td><code class="verbatim">C-c C-x f</code></td><td><code class="verbatim">⌃⇧⌘F</code></td><td>—</td><td>On a reference, goes to its definition; on a definition, back to a reference; elsewhere inserts a footnote (<code class="verbatim">org-footnote-action</code>).</td></tr> | |
| 964 | </tbody> | |
| 965 | </table> | |
| 966 | <h3 id="code-blocks-and-c-c-c-c">Code blocks and C-c C-c</h3> | |
| 967 | <table> | |
| 968 | <thead> | |
| 969 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 970 | </thead> | |
| 971 | <tbody> | |
| 972 | <tr><td>Act at Point (C-c C-c) (<code class="verbatim">org.ctrl-c-ctrl-c</code>)</td><td><code class="verbatim">C-c C-c</code></td><td><code class="verbatim">⌃⌘X</code></td><td>—</td><td>Does what fits the context: sets tags on a heading, toggles an item's checkbox, follows a footnote, offers the property menu in a property drawer, updates a clock line, statistics cookie or timestamp, runs a <code class="verbatim">#+CALL:</code> line, inline <code class="verbatim">call_</code> or inline <code class="verbatim">src_</code> block, and refreshes the setup on a <code class="verbatim">#+</code> keyword line (<code class="verbatim">org-ctrl-c-ctrl-c</code>). In a table it evaluates a formula typed in the field (starting with <code>=</code> or <code>:=</code>), then recalculates the row when it is marked <code class="verbatim">#</code> and otherwise aligns the table; at the table's first character it recalculates the whole table. After a sparse tree, the first <code class="verbatim">C-c C-c</code> only clears the highlights. More specific bindings take <code class="verbatim">C-c C-c</code> and <code class="verbatim">⌃⌘X</code> in src blocks, <code class="verbatim">#+TBLFM</code> lines and dynamic blocks.</td></tr> | |
| 973 | <tr><td>Act at Point (<code class="verbatim">org.dwim</code>)</td><td>—</td><td>—</td><td><code class="verbatim">RET</code> (N)</td><td>Doom's <code class="verbatim">+org/dwim-at-point</code>: follows a link, runs a src block, recalculates or aligns a table, toggles a checkbox, or switches a heading between TODO and done.</td></tr> | |
| 974 | <tr><td>Run Source Block (<code class="verbatim">org.babel.execute</code>)</td><td><code class="verbatim">C-c C-c</code></td><td><code class="verbatim">⌃⌘X</code></td><td>—</td><td>In a src block, runs it and inserts the results (<code class="verbatim">org-babel-execute-src-block</code>).</td></tr> | |
| 975 | <tr><td>Tangle File (<code class="verbatim">org.babel.tangle</code>)</td><td><code class="verbatim">C-c C-v t</code>, <code class="verbatim">C-c C-v C-t</code></td><td><code class="verbatim">⌃⌘V</code></td><td>—</td><td>Writes the file's src blocks to their tangle targets (<code class="verbatim">org-babel-tangle</code>).</td></tr> | |
| 976 | <tr><td>Tangle Block (<code class="verbatim">org.babel.tangle-block</code>)</td><td>—</td><td><code class="verbatim">⌃⇧⌘V</code></td><td>—</td><td>Tangles only the src block at point (<code class="verbatim">org-babel-tangle</code> with <code class="verbatim">C-u</code>).</td></tr> | |
| 977 | <tr><td>Tangle Block's Target (<code class="verbatim">org.babel.tangle-target</code>)</td><td>—</td><td><code class="verbatim">⌃⌥⌘V</code></td><td>—</td><td>Tangles every block that writes to the same file as the block at point (<code class="verbatim">org-babel-tangle</code> with <code class="verbatim">C-u C-u</code>).</td></tr> | |
| 978 | <tr><td>Insert Structure Template (<code class="verbatim">org.structure-template</code>)</td><td><code class="verbatim">C-c C-,</code></td><td>—</td><td>—</td><td>Asks for a block type and inserts the block, or wraps the selection (<code class="verbatim">org-insert-structure-template</code>).</td></tr> | |
| 979 | <tr><td>Edit Block (<code class="verbatim">org.edit-special</code>)</td><td><code class="verbatim">C-c '</code></td><td><code class="verbatim">⌃⌘'</code></td><td><code class="verbatim">SPC m '</code> (N)</td><td>Edits the src, example or export block at point in a separate editor (<code class="verbatim">org-edit-special</code>).</td></tr> | |
| 980 | </tbody> | |
| 981 | </table> | |
| 982 | <h3 id="agenda-and-capture">Agenda and capture</h3> | |
| 983 | <table> | |
| 984 | <thead> | |
| 985 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 986 | </thead> | |
| 987 | <tbody> | |
| 988 | <tr><td>Agenda (<code class="verbatim">app.agenda</code>)</td><td><code class="verbatim">C-c a</code></td><td>—</td><td><code class="verbatim">SPC o a</code> (N)</td><td>Opens the Agenda window (<code class="verbatim">org-agenda</code>).</td></tr> | |
| 989 | <tr><td>Capture… (<code class="verbatim">app.capture</code>)</td><td><code class="verbatim">C-c c</code></td><td>—</td><td><code class="verbatim">SPC X</code> (N)</td><td>Opens the Capture window (<code class="verbatim">org-capture</code>).</td></tr> | |
| 990 | </tbody> | |
| 991 | </table> | |
| 992 | <h3 id="export">Export</h3> | |
| 993 | <table> | |
| 994 | <thead> | |
| 995 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 996 | </thead> | |
| 997 | <tbody> | |
| 998 | <tr><td>Export… (<code class="verbatim">app.export-dialog</code>)</td><td>—</td><td><code class="verbatim">⇧⌘E</code></td><td>—</td><td>Opens the export sheet. In the Emacs and Doom presets <code class="verbatim">C-c C-e</code> is a prefix for the export keys only; pausing after it lists them in the key hints.</td></tr> | |
| 999 | <tr><td>Export to HTML (<code class="verbatim">app.export.html</code>)</td><td><code class="verbatim">C-c C-e h h</code></td><td>—</td><td><code class="verbatim">SPC m e h h</code> (N)</td><td>Exports to HTML (<code class="verbatim">org-html-export-to-html</code>).</td></tr> | |
| 1000 | <tr><td>Export to HTML and Open (<code class="verbatim">app.export.html-open</code>)</td><td><code class="verbatim">C-c C-e h o</code></td><td>—</td><td><code class="verbatim">SPC m e h o</code> (N)</td><td>Exports to HTML and opens the result.</td></tr> | |
| 1001 | <tr><td>Export to Markdown (<code class="verbatim">app.export.markdown</code>)</td><td><code class="verbatim">C-c C-e m m</code></td><td>—</td><td><code class="verbatim">SPC m e m m</code> (N)</td><td>Exports to Markdown (<code class="verbatim">org-md-export-to-markdown</code>).</td></tr> | |
| 1002 | <tr><td>Export to PDF with Emacs (<code class="verbatim">app.export.pdf</code>)</td><td><code class="verbatim">C-c C-e l p</code></td><td>—</td><td><code class="verbatim">SPC m e l p</code> (N)</td><td>Exports to PDF through Emacs (<code class="verbatim">org-latex-export-to-pdf</code>).</td></tr> | |
| 1003 | <tr><td>Export to LaTeX with Emacs (<code class="verbatim">app.export.latex</code>)</td><td><code class="verbatim">C-c C-e l l</code></td><td>—</td><td>—</td><td>Exports to LaTeX through Emacs (<code class="verbatim">org-latex-export-to-latex</code>).</td></tr> | |
| 1004 | <tr><td>Export to ODT with Emacs (<code class="verbatim">app.export.odt</code>)</td><td><code class="verbatim">C-c C-e o o</code></td><td>—</td><td>—</td><td>Exports to ODT through Emacs (<code class="verbatim">org-odt-export-to-odt</code>).</td></tr> | |
| 1005 | <tr><td>Export to Plain Text with Emacs (<code class="verbatim">app.export.text</code>)</td><td><code class="verbatim">C-c C-e t u</code></td><td>—</td><td>—</td><td>Exports to plain text through Emacs (<code class="verbatim">org-ascii-export-to-ascii</code>).</td></tr> | |
| 1006 | </tbody> | |
| 1007 | </table> | |
| 1008 | <h3 id="files-buffers-and-the-app">Files, buffers and the app</h3> | |
| 1009 | <table> | |
| 1010 | <thead> | |
| 1011 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th><th>What it does</th></tr> | |
| 1012 | </thead> | |
| 1013 | <tbody> | |
| 1014 | <tr><td>Save (<code class="verbatim">app.save</code>)</td><td><code class="verbatim">C-x C-s</code></td><td>—</td><td><code class="verbatim">SPC f s</code> (N), <code class="verbatim">SPC b s</code> (N)</td><td>Saves the file (<code class="verbatim">save-buffer</code>).</td></tr> | |
| 1015 | <tr><td>Save All Buffers (<code class="verbatim">app.save-all</code>)</td><td><code class="verbatim">C-x s</code></td><td>—</td><td><code class="verbatim">SPC b S</code> (N)</td><td>Saves every open buffer (<code class="verbatim">save-some-buffers</code>).</td></tr> | |
| 1016 | <tr><td>Quick Open… (<code class="verbatim">app.quick-open</code>)</td><td><code class="verbatim">C-x C-f</code></td><td>—</td><td><code class="verbatim">SPC SPC</code> (N), <code class="verbatim">SPC .</code> (N), <code class="verbatim">SPC f f</code> (N)</td><td>Opens a file of your folders by name (<code class="verbatim">find-file</code>).</td></tr> | |
| 1017 | <tr><td>Switch to Buffer… (<code class="verbatim">app.buffer.switch</code>)</td><td><code class="verbatim">C-x b</code>, <code class="verbatim">C-x C-b</code></td><td>—</td><td><code class="verbatim">SPC b b</code> (N), <code class="verbatim">SPC b B</code> (N), <code class="verbatim">SPC ,</code> (N)</td><td>Asks for an open buffer and shows it (<code class="verbatim">switch-to-buffer</code>).</td></tr> | |
| 1018 | <tr><td>Next Buffer (<code class="verbatim">app.buffer.next</code>)</td><td><code class="verbatim">C-x <right></code></td><td><code class="verbatim">⌃⇥</code></td><td><code class="verbatim">SPC b n</code> (N), <code class="verbatim">SPC b ]</code> (N), <code class="verbatim">] b</code> (N)</td><td>Shows the next open buffer (<code class="verbatim">next-buffer</code>).</td></tr> | |
| 1019 | <tr><td>Previous Buffer (<code class="verbatim">app.buffer.previous</code>)</td><td><code class="verbatim">C-x <left></code></td><td><code class="verbatim">⌃⇧⇥</code></td><td><code class="verbatim">SPC b p</code> (N), <code class="verbatim">SPC b [</code> (N), <code class="verbatim">[ b</code> (N)</td><td>Shows the previous open buffer (<code class="verbatim">previous-buffer</code>).</td></tr> | |
| 1020 | <tr><td>Last Buffer (<code class="verbatim">app.buffer.last</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC `</code> (N)</td><td>Shows the buffer you were in before this one.</td></tr> | |
| 1021 | <tr><td>Close Buffer (<code class="verbatim">app.buffer.kill</code>)</td><td><code class="verbatim">C-x k</code></td><td>—</td><td><code class="verbatim">SPC b k</code> (N), <code class="verbatim">SPC b d</code> (N)</td><td>Closes the buffer, asking about unsaved changes in explicit save mode (<code class="verbatim">kill-buffer</code>).</td></tr> | |
| 1022 | <tr><td>Close Other Buffers (<code class="verbatim">app.buffer.kill-others</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC b O</code> (N)</td><td>Closes every other buffer.</td></tr> | |
| 1023 | <tr><td>Close All Buffers (<code class="verbatim">app.buffer.kill-all</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC b K</code> (N)</td><td>Closes every buffer.</td></tr> | |
| 1024 | <tr><td>Command Palette… (<code class="verbatim">app.palette</code>)</td><td><code class="verbatim">M-x</code></td><td>—</td><td><code class="verbatim">SPC :</code> (N)</td><td>Opens the command palette (<code class="verbatim">execute-extended-command</code>).</td></tr> | |
| 1025 | <tr><td>Search Notes (<code class="verbatim">app.search</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC /</code> (N), <code class="verbatim">SPC s p</code> (N)</td><td>Moves to the search field for searching your notes.</td></tr> | |
| 1026 | <tr><td>Reload Keymap (<code class="verbatim">app.reload-keymap</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC h r r</code> (N)</td><td>Reads <code class="verbatim">keymap.toml</code> again.</td></tr> | |
| 1027 | <tr><td>Check Spelling While Typing (<code class="verbatim">editor.toggle-spell-check</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC t s</code> (N)</td><td>Turns spell checking while typing on or off.</td></tr> | |
| 1028 | <tr><td>Truncate or Wrap Long Lines (<code class="verbatim">editor.toggle-truncate-lines</code>)</td><td><code class="verbatim">C-x x t</code></td><td>—</td><td><code class="verbatim">SPC t w</code> (N)</td><td>Switches between wrapping and truncating long lines (<code class="verbatim">toggle-truncate-lines</code>).</td></tr> | |
| 1029 | <tr><td>Quit Orgstar (<code class="verbatim">app.quit</code>)</td><td>—</td><td>—</td><td><code class="verbatim">SPC q q</code> (N)</td><td>Quits Orgstar (<code class="verbatim">save-buffers-kill-terminal</code>).</td></tr> | |
| 1030 | </tbody> | |
| 1031 | </table> | |
| 1032 | <h3 id="unbound-commands">Unbound commands</h3> | |
| 1033 | <p>No preset binds these. Run them from the palette or a menu, or bind them in <code class="verbatim">keymap.toml</code>.</p> | |
| 1034 | <table> | |
| 1035 | <thead> | |
| 1036 | <tr><th>Command</th><th>What it does</th></tr> | |
| 1037 | </thead> | |
| 1038 | <tbody> | |
| 1039 | <tr><td>Board (<code class="verbatim">app.board</code>)</td><td>Opens the Board window. Window ▸ Board, <code class="verbatim">⇧⌘B</code>.</td></tr> | |
| 1040 | <tr><td>Cancel Running Task (<code class="verbatim">app.babel.cancel</code>)</td><td>Stops the src block that is running, or an export or table recalculation running in Emacs. Edit ▸ Cancel Running Task, <code class="verbatim">⌘.</code>.</td></tr> | |
| 1041 | <tr><td>Edit Config File (<code class="verbatim">app.edit-config</code>)</td><td>Opens <code class="verbatim">config.toml</code> in the editor. <code class="verbatim">⌥⌘,</code>.</td></tr> | |
| 1042 | <tr><td>Import from Emacs… (<code class="verbatim">app.import-emacs</code>)</td><td>Opens Import from Emacs….</td></tr> | |
| 1043 | <tr><td>Revert to File on Disk (<code class="verbatim">app.revert</code>)</td><td>Replaces the buffer with the file on disk; unsaved changes go to recovery (<code class="verbatim">revert-buffer</code>).</td></tr> | |
| 1044 | <tr><td>Recovery Versions… (<code class="verbatim">app.recovery</code>)</td><td>Shows the recovery versions of the file.</td></tr> | |
| 1045 | <tr><td>Resolve Sync Conflicts… (<code class="verbatim">app.sync-conflicts</code>)</td><td>Shows the file's sync conflict copies to resolve them.</td></tr> | |
| 1046 | <tr><td>Import Table from File… (<code class="verbatim">app.table-import</code>)</td><td>Asks for a CSV, TSV or space-separated file and inserts it as a table (<code class="verbatim">org-table-import</code>).</td></tr> | |
| 1047 | <tr><td>Export Table to File… (<code class="verbatim">app.table-export</code>)</td><td>Writes the table at point to a CSV or TSV file (<code class="verbatim">org-table-export</code>).</td></tr> | |
| 1048 | <tr><td>Show or Hide Outline (<code class="verbatim">app.toggle-outline</code>)</td><td>Shows or hides the outline pane. View ▸ Show or Hide Outline, <code class="verbatim">⌥⌘O</code>.</td></tr> | |
| 1049 | <tr><td>Show or Hide Backlinks (<code class="verbatim">app.toggle-backlinks</code>)</td><td>Shows or hides the backlinks pane. View ▸ Show or Hide Backlinks.</td></tr> | |
| 1050 | <tr><td>Show or Hide Columns and Clock (<code class="verbatim">app.toggle-inspector</code>)</td><td>Shows or hides the columns and clock inspector. View ▸ Show or Hide Columns and Clock, <code class="verbatim">⌥⌘I</code>.</td></tr> | |
| 1051 | <tr><td>Show or Hide Markup (<code class="verbatim">app.toggle-markup</code>)</td><td>Shows or hides link brackets and emphasis markers. View ▸ Show Markup, <code class="verbatim">⇧⌘M</code>.</td></tr> | |
| 1052 | <tr><td>Show or Hide Line Numbers (<code class="verbatim">app.toggle-line-numbers</code>)</td><td>Shows or hides line numbers. View ▸ Show Line Numbers, <code class="verbatim">⇧⌘L</code>.</td></tr> | |
| 1053 | <tr><td>Show or Hide Tab Bar (<code class="verbatim">app.toggle-tab-bar</code>)</td><td>Shows or hides the tab bar. View ▸ Show Tab Bar.</td></tr> | |
| 1054 | <tr><td>Column View of File (<code class="verbatim">org.columns.global</code>)</td><td>Shows the column view of the whole file (<code class="verbatim">org-columns</code> with <code class="verbatim">C-u</code>).</td></tr> | |
| 1055 | <tr><td>Remove Schedule (<code class="verbatim">org.schedule.remove</code>)</td><td>Removes <code class="verbatim">SCHEDULED</code> (<code class="verbatim">org-schedule</code> with <code class="verbatim">C-u</code>).</td></tr> | |
| 1056 | <tr><td>Remove Deadline (<code class="verbatim">org.deadline.remove</code>)</td><td>Removes <code class="verbatim">DEADLINE</code> (<code class="verbatim">org-deadline</code> with <code class="verbatim">C-u</code>).</td></tr> | |
| 1057 | <tr><td>Create ID (<code class="verbatim">org.id.create</code>)</td><td>Gives the entry an <code class="verbatim">ID</code> property, a lowercase UUID, unless it has one (<code class="verbatim">org-id-get-create</code>).</td></tr> | |
| 1058 | <tr><td>Delete Property… (<code class="verbatim">org.property.delete</code>)</td><td>Asks for a property of the entry and deletes it (<code class="verbatim">org-delete-property</code>).</td></tr> | |
| 1059 | <tr><td>Delete Property Everywhere… (<code class="verbatim">org.property.delete-globally</code>)</td><td>Asks for a property and deletes it from every entry in the file (<code class="verbatim">org-delete-property-globally</code>).</td></tr> | |
| 1060 | <tr><td>Property Action… (<code class="verbatim">org.property.action</code>)</td><td>Offers set, delete and delete globally for the property at point (<code class="verbatim">org-property-action</code>). <code class="verbatim">C-c C-c</code> in a property drawer runs it.</td></tr> | |
| 1061 | <tr><td>Footnote Menu (<code class="verbatim">org.footnote.menu</code>)</td><td>Offers the footnote commands as a menu (<code class="verbatim">org-footnote-action</code> with <code class="verbatim">C-u</code>).</td></tr> | |
| 1062 | <tr><td>Set Field Formula (<code class="verbatim">org.table.field-formula</code>)</td><td>Asks for the current field's formula (<code class="verbatim">org-table-eval-formula</code> with <code class="verbatim">C-u</code>).</td></tr> | |
| 1063 | <tr><td>Sort Table Lines (<code class="verbatim">org.table.sort</code>)</td><td>Asks for alphabetic, numeric or time order, or their reverse, and sorts the table's lines by the current column (<code class="verbatim">org-table-sort-lines</code>). Sort Entries does the same in a table.</td></tr> | |
| 1064 | <tr><td>Transpose Table (<code class="verbatim">org.table.transpose</code>)</td><td>Swaps the table's rows and columns (<code class="verbatim">org-table-transpose-table-at-point</code>).</td></tr> | |
| 1065 | <tr><td>Shrink Table Columns with Widths (<code class="verbatim">org.table.shrink</code>)</td><td>Shrinks the table's columns that have a width cookie (<code class="verbatim">org-table-shrink</code>).</td></tr> | |
| 1066 | <tr><td>Expand Table Columns (<code class="verbatim">org.table.expand</code>)</td><td>Expands the table's shrunk columns (<code class="verbatim">org-table-expand</code>).</td></tr> | |
| 1067 | </tbody> | |
| 1068 | </table> | |
| 1069 | <h3 id="speed-keys-reference">Speed keys reference</h3> | |
| 1070 | <p>At the very start of a heading line, with <code class="verbatim">org-use-speed-commands</code> on. The same in every preset (Doom: insert state).</p> | |
| 1071 | <table> | |
| 1072 | <thead> | |
| 1073 | <tr><th>Key</th><th>Command</th></tr> | |
| 1074 | </thead> | |
| 1075 | <tbody> | |
| 1076 | <tr><td><code class="verbatim">n</code></td><td>Next Heading (<code class="verbatim">org.heading.next</code>)</td></tr> | |
| 1077 | <tr><td><code class="verbatim">p</code></td><td>Previous Heading (<code class="verbatim">org.heading.previous</code>)</td></tr> | |
| 1078 | <tr><td><code class="verbatim">f</code></td><td>Next Heading at Same Level (<code class="verbatim">org.heading.forward-same-level</code>)</td></tr> | |
| 1079 | <tr><td><code class="verbatim">b</code></td><td>Previous Heading at Same Level (<code class="verbatim">org.heading.backward-same-level</code>)</td></tr> | |
| 1080 | <tr><td><code class="verbatim">u</code></td><td>Up to Parent Heading (<code class="verbatim">org.heading.up</code>)</td></tr> | |
| 1081 | <tr><td><code class="verbatim">j</code></td><td>Go to Heading… (<code class="verbatim">org.goto</code>)</td></tr> | |
| 1082 | <tr><td><code class="verbatim">c</code></td><td>Cycle Visibility (<code class="verbatim">org.cycle</code>)</td></tr> | |
| 1083 | <tr><td><code class="verbatim">C</code></td><td>Cycle Global Visibility (<code class="verbatim">org.cycle-global</code>)</td></tr> | |
| 1084 | <tr><td><code class="verbatim">s</code></td><td>Narrow to Subtree or Widen (<code class="verbatim">org.narrow.toggle</code>)</td></tr> | |
| 1085 | <tr><td><code class="verbatim">k</code></td><td>Cut Subtree (<code class="verbatim">org.subtree.cut</code>)</td></tr> | |
| 1086 | <tr><td><code class="verbatim">U</code></td><td>Move Subtree Up (<code class="verbatim">org.subtree.up</code>)</td></tr> | |
| 1087 | <tr><td><code class="verbatim">D</code></td><td>Move Subtree Down (<code class="verbatim">org.subtree.down</code>)</td></tr> | |
| 1088 | <tr><td><code class="verbatim">r</code></td><td>Demote Heading (<code class="verbatim">org.heading.demote</code>)</td></tr> | |
| 1089 | <tr><td><code class="verbatim">l</code></td><td>Promote Heading (<code class="verbatim">org.heading.promote</code>)</td></tr> | |
| 1090 | <tr><td><code class="verbatim">R</code></td><td>Demote Subtree (<code class="verbatim">org.subtree.demote</code>)</td></tr> | |
| 1091 | <tr><td><code class="verbatim">L</code></td><td>Promote Subtree (<code class="verbatim">org.subtree.promote</code>)</td></tr> | |
| 1092 | <tr><td><code class="verbatim">i</code></td><td>Insert Heading After Subtree (<code class="verbatim">org.heading.insert-after-subtree</code>)</td></tr> | |
| 1093 | <tr><td><code class="verbatim">w</code></td><td>Refile… (<code class="verbatim">app.refile</code>)</td></tr> | |
| 1094 | <tr><td><code class="verbatim">a</code></td><td>Archive Subtree (<code class="verbatim">app.archive</code>)</td></tr> | |
| 1095 | <tr><td><code class="verbatim">@</code></td><td>Mark Subtree (<code class="verbatim">org.subtree.mark</code>)</td></tr> | |
| 1096 | <tr><td><code class="verbatim">#</code></td><td>Toggle COMMENT (<code class="verbatim">org.heading.toggle-comment</code>)</td></tr> | |
| 1097 | <tr><td><code class="verbatim">I</code></td><td>Clock In (<code class="verbatim">app.clock.in</code>)</td></tr> | |
| 1098 | <tr><td><code class="verbatim">O</code></td><td>Clock Out (<code class="verbatim">app.clock.out</code>)</td></tr> | |
| 1099 | <tr><td><code class="verbatim">t</code></td><td>Cycle TODO State (<code class="verbatim">org.todo.cycle</code>)</td></tr> | |
| 1100 | <tr><td><code class="verbatim">,</code></td><td>Set Priority… (<code class="verbatim">org.priority.set</code>)</td></tr> | |
| 1101 | <tr><td><code class="verbatim">0</code></td><td>Remove Priority (<code class="verbatim">org.priority.remove</code>)</td></tr> | |
| 1102 | <tr><td><code class="verbatim">1</code></td><td>Set Priority A (<code class="verbatim">org.priority.set-a</code>)</td></tr> | |
| 1103 | <tr><td><code class="verbatim">2</code></td><td>Set Priority B (<code class="verbatim">org.priority.set-b</code>)</td></tr> | |
| 1104 | <tr><td><code class="verbatim">3</code></td><td>Set Priority C (<code class="verbatim">org.priority.set-c</code>)</td></tr> | |
| 1105 | <tr><td><code class="verbatim">:</code></td><td>Set Tags (<code class="verbatim">org.tags.set</code>)</td></tr> | |
| 1106 | <tr><td><code class="verbatim">e</code></td><td>Set Effort (<code class="verbatim">org.effort.set</code>)</td></tr> | |
| 1107 | <tr><td><code class="verbatim">v</code></td><td>Agenda (<code class="verbatim">app.agenda</code>)</td></tr> | |
| 1108 | <tr><td><code class="verbatim">o</code></td><td>Open Link (<code class="verbatim">org.link.open</code>)</td></tr> | |
| 1109 | </tbody> | |
| 1110 | </table> | |
| 1111 | </main> | |
| 1112 | <footer class="site"> | |
| 1113 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 1114 | </footer> | |
| 1115 | </body> | |
| 1116 | </html> | |
| \ No newline at end of file | ||
guide/04-outlines.html added +645
| @@ -0,0 +1,645 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Outlines and structure · Orgstar</title> | |
| 7 | <meta name="description" content="Headings, subtrees, plain lists, checkboxes, blocks, drawers, properties, column view, footnotes, refiling and archiving."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Outlines and structure</h1> | |
| 24 | <p class="lede">An org file is an outline of headings with text, lists and drawers under them; this chapter covers the commands that build and rearrange it.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#headings">Headings</a> | |
| 29 | <ul> | |
| 30 | <li><a href="#inserting-headings">Inserting headings</a></li> | |
| 31 | <li><a href="#promoting-and-demoting">Promoting and demoting</a></li> | |
| 32 | <li><a href="#moving-subtrees">Moving subtrees</a></li> | |
| 33 | <li><a href="#moving-between-headings">Moving between headings</a></li> | |
| 34 | <li><a href="#toggling-headings-items-and-comments">Toggling headings, items and comments</a></li> | |
| 35 | <li><a href="#selecting-a-subtree">Selecting a subtree</a></li> | |
| 36 | </ul></li> | |
| 37 | <li><a href="#subtrees-as-text">Subtrees as text</a> | |
| 38 | <ul> | |
| 39 | <li><a href="#cut-copy-and-paste">Cut, copy and paste</a></li> | |
| 40 | <li><a href="#cloning-with-a-time-shift">Cloning with a time shift</a></li> | |
| 41 | <li><a href="#sorting">Sorting</a></li> | |
| 42 | </ul></li> | |
| 43 | <li><a href="#narrowing">Narrowing</a></li> | |
| 44 | <li><a href="#sparse-trees">Sparse trees</a></li> | |
| 45 | <li><a href="#plain-lists">Plain lists</a> | |
| 46 | <ul> | |
| 47 | <li><a href="#list-commands">List commands</a></li> | |
| 48 | <li><a href="#bullets-and-numbering">Bullets and numbering</a></li> | |
| 49 | </ul></li> | |
| 50 | <li><a href="#checkboxes-and-statistics">Checkboxes and statistics</a> | |
| 51 | <ul> | |
| 52 | <li><a href="#checkboxes">Checkboxes</a></li> | |
| 53 | <li><a href="#statistics-cookies">Statistics cookies</a></li> | |
| 54 | </ul></li> | |
| 55 | <li><a href="#blocks">Blocks</a> | |
| 56 | <ul> | |
| 57 | <li><a href="#structure-templates">Structure templates</a></li> | |
| 58 | <li><a href="#org-tempo-templates">org-tempo templates</a></li> | |
| 59 | <li><a href="#folding-and-editing-blocks">Folding and editing blocks</a></li> | |
| 60 | </ul></li> | |
| 61 | <li><a href="#drawers">Drawers</a></li> | |
| 62 | <li><a href="#properties">Properties</a> | |
| 63 | <ul> | |
| 64 | <li><a href="#setting-and-deleting">Setting and deleting</a></li> | |
| 65 | <li><a href="#allowed-values">Allowed values</a></li> | |
| 66 | <li><a href="#inheritance">Inheritance</a></li> | |
| 67 | <li><a href="#special-properties">Special properties</a></li> | |
| 68 | </ul></li> | |
| 69 | <li><a href="#column-view">Column view</a> | |
| 70 | <ul> | |
| 71 | <li><a href="#the-column-view-sheet">The column view sheet</a></li> | |
| 72 | <li><a href="#the-columns-inspector">The Columns inspector</a></li> | |
| 73 | <li><a href="#column-view-tables">Column view tables</a></li> | |
| 74 | </ul></li> | |
| 75 | <li><a href="#footnotes">Footnotes</a></li> | |
| 76 | <li><a href="#refiling">Refiling</a></li> | |
| 77 | <li><a href="#archiving">Archiving</a> | |
| 78 | <ul> | |
| 79 | <li><a href="#archive-subtree">Archive Subtree</a></li> | |
| 80 | <li><a href="#the-archive-tag">The ARCHIVE tag</a></li> | |
| 81 | <li><a href="#archive-sibling">Archive sibling</a></li> | |
| 82 | </ul></li> | |
| 83 | <li><a href="#the-outline-pane">The outline pane</a></li> | |
| 84 | <li><a href="#c-c-c-c">C-c C-c</a></li> | |
| 85 | <li><a href="#speed-keys">Speed keys</a></li> | |
| 86 | <li><a href="#not-supported">Not supported</a></li> | |
| 87 | </ul> | |
| 88 | </nav> | |
| 89 | <p>Every command in this chapter is in the Org menu and the command palette (<code class="verbatim">⇧⌘P</code>), under the title given in the tables, whatever keymap you use. The Org menu shows the keys that run each command in your current keymap.</p> | |
| 90 | <p>Keys are listed for the three presets. The Emacs and Doom presets use Emacs notation (<code class="verbatim">M-RET</code> is Meta-Return, <code class="verbatim">C-c C-w</code> is Control-c then Control-w). The Mac preset uses macOS symbols. The Doom preset has every Emacs-preset key that starts with <code class="verbatim">C-c</code> or <code class="verbatim">C-x</code>, and the <code class="verbatim">M-</code>, <code class="verbatim">S-</code> arrow and <code class="verbatim">RET</code> chords, in normal, insert and visual state, plus the Doom keys listed. Where the Mac column says "menu", the Mac preset has no key for the command; run it from the Org menu or the palette, or bind one in <code class="verbatim">keymap.toml</code> (see <a href="03-keys.html">Keys</a>).</p> | |
| 91 | <h2 id="headings">Headings</h2> | |
| 92 | <p>A heading is a line that starts with one or more stars and a space. The number of stars is its level. A heading and everything under it, down to the next heading at the same or a higher level, is a subtree.</p> | |
| 93 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Project | |
| 94 | </span>Notes about the project. | |
| 95 | <span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">TODO</span> Write the plan | |
| 96 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> Meetings | |
| 97 | </span><span class="markup heading org"><span class="punctuation definition heading org">***</span> Kickoff</span></span></code></pre> | |
| 98 | <h3 id="inserting-headings">Inserting headings</h3> | |
| 99 | <table> | |
| 100 | <thead> | |
| 101 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 102 | </thead> | |
| 103 | <tbody> | |
| 104 | <tr><td>Insert Heading</td><td><code class="verbatim">org-insert-heading</code></td><td><code class="verbatim">M-RET</code></td><td><code class="verbatim">⌘↩</code></td><td><code class="verbatim">M-RET</code></td></tr> | |
| 105 | <tr><td>Insert Heading After Subtree</td><td><code class="verbatim">org-insert-heading-respect-content</code></td><td><code class="verbatim">C-RET</code></td><td><code class="verbatim">⌃⌘↩</code></td><td><code class="verbatim">C-RET</code></td></tr> | |
| 106 | <tr><td>Insert TODO Heading</td><td><code class="verbatim">org-insert-todo-heading</code></td><td><code class="verbatim">M-S-RET</code></td><td><code class="verbatim">⇧⌘↩</code></td><td><code class="verbatim">M-S-RET</code></td></tr> | |
| 107 | </tbody> | |
| 108 | </table> | |
| 109 | <p>The new heading has the level of the heading the caret is under, or level 1 before the first heading. In a plain list the same keys insert an item instead (see <a href="#plain-lists">Plain lists</a>).</p> | |
| 110 | <p>Insert TODO Heading gives the new heading the keyword of the previous heading at the same level when that keyword is not a done state, and otherwise the first keyword of the file's TODO sequence. If the parent has a statistics cookie, it is updated.</p> | |
| 111 | <p>Two settings change where Insert Heading puts the heading. Both are in Settings ▸ Editing and in <code class="verbatim">config.toml</code> under the Emacs variable names:</p> | |
| 112 | <table> | |
| 113 | <thead> | |
| 114 | <tr><th>Setting (<code class="verbatim">config.toml</code>)</th><th>Settings ▸ Editing</th><th>Orgstar default</th><th>Org default</th></tr> | |
| 115 | </thead> | |
| 116 | <tbody> | |
| 117 | <tr><td><code class="verbatim">org-insert-heading-respect-content</code></td><td>M-RET adds the new heading after the subtree</td><td><code class="verbatim">true</code></td><td><code class="verbatim">nil</code></td></tr> | |
| 118 | <tr><td><code class="verbatim">org-M-RET-may-split-line</code></td><td>M-RET splits the line at the caret</td><td><code class="verbatim">false</code></td><td><code class="verbatim">t</code></td></tr> | |
| 119 | </tbody> | |
| 120 | </table> | |
| 121 | <p>With <code class="verbatim">org-insert-heading-respect-content</code> on (the Orgstar default), Insert Heading behaves as Insert Heading After Subtree: the new heading goes after the end of the current subtree, at the current level. Insert Heading also does this when the caret is in folded text.</p> | |
| 122 | <p>With it off, Insert Heading works where the caret is:</p> | |
| 123 | <ul> | |
| 124 | <li>At the start of a heading line, the new heading is inserted above it.</li> | |
| 125 | <li>Elsewhere on a heading line, the new heading goes below that line. With <code class="verbatim">org-M-RET-may-split-line</code> on and the caret inside the title, the text after the caret moves to the new heading. Tags stay on the original line and are realigned.</li> | |
| 126 | <li>In body text, a new heading line is started below. With <code class="verbatim">org-M-RET-may-split-line</code> on, the line is split at the caret first.</li> | |
| 127 | </ul> | |
| 128 | <p>Orgstar follows Org's <code class="verbatim">org-blank-before-new-entry</code> default of <code class="verbatim">auto</code> for headings: if the heading the caret is in is preceded by a blank line, the new heading is too.</p> | |
| 129 | <p>Insert Heading After Subtree always inserts after the subtree:</p> | |
| 130 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> a | |
| 131 | </span>body | |
| 132 | <span class="markup heading org"><span class="punctuation definition heading org">**</span> b | |
| 133 | </span><span class="markup heading org"><span class="punctuation definition heading org">*</span> c</span></span></code></pre> | |
| 134 | <p>With the caret on <code class="verbatim">* a</code>, <code class="verbatim">C-RET</code> gives:</p> | |
| 135 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> a | |
| 136 | </span>body | |
| 137 | <span class="markup heading org"><span class="punctuation definition heading org">**</span> b | |
| 138 | </span><span class="markup heading org"><span class="punctuation definition heading org">*</span> | |
| 139 | </span><span class="markup heading org"><span class="punctuation definition heading org">*</span> c</span></span></code></pre> | |
| 140 | <h3 id="promoting-and-demoting">Promoting and demoting</h3> | |
| 141 | <table> | |
| 142 | <thead> | |
| 143 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 144 | </thead> | |
| 145 | <tbody> | |
| 146 | <tr><td>Promote Heading</td><td><code class="verbatim">org-promote</code></td><td><code class="verbatim">M-<left></code></td><td><code class="verbatim">⌃⌘←</code></td><td><code class="verbatim">M-h</code>; in insert state <code class="verbatim">S-TAB</code> or <code class="verbatim">C-d</code></td></tr> | |
| 147 | <tr><td>Demote Heading</td><td><code class="verbatim">org-demote</code></td><td><code class="verbatim">M-<right></code></td><td><code class="verbatim">⌃⌘→</code></td><td><code class="verbatim">M-l</code>; in insert state <code class="verbatim">TAB</code> or <code class="verbatim">C-t</code></td></tr> | |
| 148 | <tr><td>Promote Subtree</td><td><code class="verbatim">org-promote-subtree</code></td><td><code class="verbatim">M-S-<left></code></td><td><code class="verbatim">⌃⌥⌘←</code></td><td><code class="verbatim">M-H</code>, <code class="verbatim">SPC m s h</code></td></tr> | |
| 149 | <tr><td>Demote Subtree</td><td><code class="verbatim">org-demote-subtree</code></td><td><code class="verbatim">M-S-<right></code></td><td><code class="verbatim">⌃⌥⌘→</code></td><td><code class="verbatim">M-L</code>, <code class="verbatim">SPC m s l</code></td></tr> | |
| 150 | </tbody> | |
| 151 | </table> | |
| 152 | <p>These run with the caret on a heading line. Promote and Demote Heading change only that line's stars; its children keep their level. The subtree commands change the heading and every heading under it. Tags are realigned after each change. A level 1 heading can't be promoted ("Cannot promote to level 0").</p> | |
| 153 | <p>On a list item the same keys indent and outdent the item instead.</p> | |
| 154 | <h3 id="moving-subtrees">Moving subtrees</h3> | |
| 155 | <table> | |
| 156 | <thead> | |
| 157 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 158 | </thead> | |
| 159 | <tbody> | |
| 160 | <tr><td>Move Subtree Up</td><td><code class="verbatim">org-move-subtree-up</code></td><td><code class="verbatim">M-<up></code></td><td><code class="verbatim">⌃⌥⌘↑</code></td><td><code class="verbatim">M-k</code>, <code class="verbatim">SPC m s k</code></td></tr> | |
| 161 | <tr><td>Move Subtree Down</td><td><code class="verbatim">org-move-subtree-down</code></td><td><code class="verbatim">M-<down></code></td><td><code class="verbatim">⌃⌥⌘↓</code></td><td><code class="verbatim">M-j</code>, <code class="verbatim">SPC m s j</code></td></tr> | |
| 162 | </tbody> | |
| 163 | </table> | |
| 164 | <p>The subtree at the caret swaps places with the previous or next sibling subtree. It can't move past its parent or the start or end of the file. The caret keeps its column.</p> | |
| 165 | <p>On a list item the same keys move the item; in a table they move the row. On other lines they do nothing. Orgstar has no <code class="verbatim">org-drag-element</code> for paragraphs.</p> | |
| 166 | <h3 id="moving-between-headings">Moving between headings</h3> | |
| 167 | <table> | |
| 168 | <thead> | |
| 169 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 170 | </thead> | |
| 171 | <tbody> | |
| 172 | <tr><td>Next Heading</td><td><code class="verbatim">org-next-visible-heading</code></td><td><code class="verbatim">C-c C-n</code></td><td><code class="verbatim">⌥⌘↓</code></td><td><code class="verbatim">C-c C-n</code></td></tr> | |
| 173 | <tr><td>Previous Heading</td><td><code class="verbatim">org-previous-visible-heading</code></td><td><code class="verbatim">C-c C-p</code></td><td><code class="verbatim">⌥⌘↑</code></td><td><code class="verbatim">C-c C-p</code></td></tr> | |
| 174 | <tr><td>Next Heading at Same Level</td><td><code class="verbatim">org-forward-heading-same-level</code></td><td><code class="verbatim">C-c C-f</code></td><td><code class="verbatim">⌥⇧⌘↓</code></td><td><code class="verbatim">] h</code></td></tr> | |
| 175 | <tr><td>Previous Heading at Same Level</td><td><code class="verbatim">org-backward-heading-same-level</code></td><td><code class="verbatim">C-c C-b</code></td><td><code class="verbatim">⌥⇧⌘↑</code></td><td><code class="verbatim">[ h</code></td></tr> | |
| 176 | <tr><td>Up to Parent Heading</td><td><code class="verbatim">outline-up-heading</code></td><td><code class="verbatim">C-c C-u</code></td><td>menu</td><td><code class="verbatim">g h</code></td></tr> | |
| 177 | <tr><td>Go to Heading…</td><td><code class="verbatim">org-goto</code></td><td><code class="verbatim">C-c C-j</code></td><td>menu</td><td><code class="verbatim">SPC m .</code></td></tr> | |
| 178 | </tbody> | |
| 179 | </table> | |
| 180 | <p>Next and Previous Heading skip headings that are folded out of sight. The same-level commands stop at the parent's boundary. In Doom's normal state, <code class="verbatim">gj</code> and <code class="verbatim">gk</code> move by Org element, as evil-org's <code class="verbatim">org-forward-element</code> and <code class="verbatim">org-backward-element</code>: on a heading line, to the next heading after its subtree, or to the previous heading at the same level or higher (see <a href="03-keys.html">Keys and commands</a>). Go to Heading asks for a heading by its outline path (<code class="verbatim">Project/Meetings/Kickoff</code>) with completion, as <code class="verbatim">org-goto</code> does with <code class="verbatim">outline-path-completion</code>.</p> | |
| 181 | <h3 id="toggling-headings-items-and-comments">Toggling headings, items and comments</h3> | |
| 182 | <table> | |
| 183 | <thead> | |
| 184 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 185 | </thead> | |
| 186 | <tbody> | |
| 187 | <tr><td>Toggle Heading</td><td><code class="verbatim">org-toggle-heading</code></td><td><code class="verbatim">C-c *</code></td><td>menu</td><td><code class="verbatim">SPC m h</code></td></tr> | |
| 188 | <tr><td>Toggle Item</td><td><code class="verbatim">org-ctrl-c-minus</code>, <code class="verbatim">org-toggle-item</code></td><td><code class="verbatim">C-c -</code></td><td>menu</td><td><code class="verbatim">SPC m i</code></td></tr> | |
| 189 | <tr><td>Toggle COMMENT</td><td><code class="verbatim">org-toggle-comment</code></td><td><code class="verbatim">C-c ;</code></td><td>menu</td><td><code class="verbatim">C-c ;</code></td></tr> | |
| 190 | </tbody> | |
| 191 | </table> | |
| 192 | <p>These work on the caret's line, or on every line of the selection.</p> | |
| 193 | <p>Toggle Heading:</p> | |
| 194 | <ul> | |
| 195 | <li>On headings, removes their stars, so they become text.</li> | |
| 196 | <li>On list items, turns them into headings one level below the entry they are in. A checkbox becomes a keyword: <code class="verbatim">[ ]</code> the first TODO keyword, <code class="verbatim">[X]</code> the first done keyword. Nested items become deeper headings.</li> | |
| 197 | <li>On other lines, makes each non-blank line a heading one level below the current entry. Comment lines are skipped.</li> | |
| 198 | </ul> | |
| 199 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Shopping | |
| 200 | </span><span class="punctuation definition list org">- </span><span class="constant language checkbox org">[ ]</span> milk | |
| 201 | <span class="punctuation definition list org">- </span><span class="constant language checkbox org">[X]</span> bread</span></code></pre> | |
| 202 | <p>Selecting both items and pressing <code class="verbatim">C-c *</code> gives:</p> | |
| 203 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Shopping | |
| 204 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">TODO</span> milk | |
| 205 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">DONE</span> bread</span></span></code></pre> | |
| 206 | <p>Toggle Item:</p> | |
| 207 | <ul> | |
| 208 | <li>On a list item, with no selection, cycles the list's bullets (see <a href="#bullets-and-numbering">Bullets and numbering</a>).</li> | |
| 209 | <li>On items in a selection, removes their bullets.</li> | |
| 210 | <li>On headings, turns them into items. The tags, planning line and property drawer are removed. A TODO keyword becomes a checkbox, <code class="verbatim">[X]</code> for a done state and <code class="verbatim">[ ]</code> otherwise. The section's text is indented under the item.</li> | |
| 211 | <li>On other lines, puts a <code class="verbatim">-</code> bullet and a space in front of each non-blank line.</li> | |
| 212 | </ul> | |
| 213 | <p>In a table, <code class="verbatim">C-c *</code> recalculates and <code class="verbatim">C-c -</code> inserts a horizontal line instead (see <a href="10-tables.html">Tables</a>).</p> | |
| 214 | <p>Toggle COMMENT adds or removes the <code class="verbatim">COMMENT</code> keyword after the stars and TODO keyword. Commented subtrees are left out of export and column view.</p> | |
| 215 | <h3 id="selecting-a-subtree">Selecting a subtree</h3> | |
| 216 | <p>Mark Subtree (<code class="verbatim">org-mark-subtree</code>, <code class="verbatim">C-c @</code> in the Emacs and Doom presets) selects the subtree at the caret, from its heading line to the end of its last line.</p> | |
| 217 | <h2 id="subtrees-as-text">Subtrees as text</h2> | |
| 218 | <h3 id="cut-copy-and-paste">Cut, copy and paste</h3> | |
| 219 | <table> | |
| 220 | <thead> | |
| 221 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 222 | </thead> | |
| 223 | <tbody> | |
| 224 | <tr><td>Cut Subtree</td><td><code class="verbatim">org-cut-subtree</code></td><td><code class="verbatim">C-c C-x C-w</code></td><td>menu</td><td><code class="verbatim">C-c C-x C-w</code>, <code class="verbatim">SPC m s d</code></td></tr> | |
| 225 | <tr><td>Copy Subtree</td><td><code class="verbatim">org-copy-subtree</code></td><td><code class="verbatim">C-c C-x M-w</code></td><td>menu</td><td><code class="verbatim">C-c C-x M-w</code></td></tr> | |
| 226 | <tr><td>Paste Subtree</td><td><code class="verbatim">org-paste-subtree</code></td><td><code class="verbatim">C-c C-x C-y</code></td><td>menu</td><td><code class="verbatim">C-c C-x C-y</code></td></tr> | |
| 227 | </tbody> | |
| 228 | </table> | |
| 229 | <p>The kill ring is the system clipboard. Cut Subtree and Copy Subtree put the subtree at the caret, with the blank lines after it, on the clipboard and report its length.</p> | |
| 230 | <p>Paste Subtree takes the clipboard's text and adjusts its levels to fit where it lands. The text has to start with a heading and contain no heading above its first one's level; otherwise the command refuses. The level comes from:</p> | |
| 231 | <ul> | |
| 232 | <li>an empty heading line, such as <code class="verbatim">***</code> followed by a space, at the caret: that level, and the empty line is replaced;</li> | |
| 233 | <li>the caret at the start of a heading: that heading's level, pasted before it;</li> | |
| 234 | <li>otherwise the deeper of the heading above the caret and the heading below it, pasted before the next heading.</li> | |
| 235 | </ul> | |
| 236 | <h3 id="cloning-with-a-time-shift">Cloning with a time shift</h3> | |
| 237 | <p>Clone Subtree with Time Shift (<code class="verbatim">org-clone-subtree-with-time-shift</code>, <code class="verbatim">C-c C-x c</code>, Doom <code class="verbatim">SPC m s c</code>) asks for a number of clones, then, if the subtree has timestamps, for a shift per clone such as <code class="verbatim">+1d</code>, <code class="verbatim">+1w</code>, <code class="verbatim">+2m</code> or <code class="verbatim">+1y</code> (units <code class="verbatim">h</code>, <code class="verbatim">d</code>, <code class="verbatim">w</code>, <code class="verbatim">m</code>, <code class="verbatim">y</code>). Leave the shift empty to copy the dates unchanged.</p> | |
| 238 | <p>The clones are inserted after the subtree. The nth clone has its dates moved by n times the shift. Clones lose their <code class="verbatim">CLOCK:</code> lines, and drawers left empty by that are removed. An entry with an <code class="verbatim">:ID:</code> property gets a new ID in each clone. When the subtree has a repeating timestamp and a shift is given, the repeater is removed from the clones, and the original, with its repeater, moves after them with its dates shifted past the last clone, as Org does.</p> | |
| 239 | <h3 id="sorting">Sorting</h3> | |
| 240 | <p>Sort Entries (<code class="verbatim">org-sort</code>, <code class="verbatim">C-c ^</code>, Mac <code class="verbatim">⌃⇧⌘S</code>, Doom <code class="verbatim">SPC m s S</code>) sorts what the caret is in:</p> | |
| 241 | <ul> | |
| 242 | <li>In a table, the table's lines (<code class="verbatim">org-table-sort-lines</code>, see <a href="10-tables.html">Tables</a>).</li> | |
| 243 | <li>On a list item, the items of that list (<code class="verbatim">org-sort-list</code>).</li> | |
| 244 | <li>Otherwise headings (<code class="verbatim">org-sort-entries</code>): with a selection, the headings in it; on a heading, its children; before the first heading, the top-level headings.</li> | |
| 245 | </ul> | |
| 246 | <p>It then asks for a sort key, one keystroke. A capital letter sorts in reverse.</p> | |
| 247 | <table> | |
| 248 | <thead> | |
| 249 | <tr><th>Key</th><th>Headings</th><th>List items</th></tr> | |
| 250 | </thead> | |
| 251 | <tbody> | |
| 252 | <tr><td><code class="verbatim">a</code></td><td>alphabetically by title</td><td>alphabetically by text</td></tr> | |
| 253 | <tr><td><code class="verbatim">n</code></td><td>numerically by the title's leading number</td><td>numerically by the text</td></tr> | |
| 254 | <tr><td><code class="verbatim">p</code></td><td>priority</td><td></td></tr> | |
| 255 | <tr><td><code class="verbatim">r</code></td><td>a property's value (asks which property)</td><td></td></tr> | |
| 256 | <tr><td><code class="verbatim">o</code></td><td>TODO keyword, in sequence order</td><td></td></tr> | |
| 257 | <tr><td><code class="verbatim">t</code></td><td>first active timestamp, else first timestamp</td><td>first timestamp, or a timer</td></tr> | |
| 258 | <tr><td><code class="verbatim">s</code></td><td><code class="verbatim">SCHEDULED</code> date</td><td></td></tr> | |
| 259 | <tr><td><code class="verbatim">d</code></td><td><code class="verbatim">DEADLINE</code> date</td><td></td></tr> | |
| 260 | <tr><td><code class="verbatim">c</code></td><td>creation time: the first inactive timestamp at the start of a line</td><td></td></tr> | |
| 261 | <tr><td><code class="verbatim">k</code></td><td>clocked time in the subtree</td><td></td></tr> | |
| 262 | <tr><td><code class="verbatim">x</code></td><td></td><td>checkbox state</td></tr> | |
| 263 | </tbody> | |
| 264 | </table> | |
| 265 | <p>Alphabetical and numeric sorts ignore a leading <code class="verbatim">COMMENT</code>, link brackets and emphasis markers. Sorting is stable, so entries with equal keys keep their order. Entries without a date sort as if dated now. After sorting a list, its numbering is repaired. Org's <code class="verbatim">f</code> (custom function) key is not available.</p> | |
| 266 | <h2 id="narrowing">Narrowing</h2> | |
| 267 | <table> | |
| 268 | <thead> | |
| 269 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 270 | </thead> | |
| 271 | <tbody> | |
| 272 | <tr><td>Narrow to Subtree</td><td><code class="verbatim">org-narrow-to-subtree</code></td><td><code class="verbatim">C-x n s</code></td><td>menu</td><td><code class="verbatim">SPC m s n</code></td></tr> | |
| 273 | <tr><td>Narrow to Block</td><td><code class="verbatim">org-narrow-to-block</code></td><td><code class="verbatim">C-x n b</code></td><td>menu</td><td><code class="verbatim">C-x n b</code></td></tr> | |
| 274 | <tr><td>Widen</td><td><code class="verbatim">widen</code></td><td><code class="verbatim">C-x n w</code></td><td>menu</td><td><code class="verbatim">SPC m s N</code></td></tr> | |
| 275 | <tr><td>Narrow to Subtree or Widen</td><td><code class="verbatim">org-toggle-narrow-to-subtree</code></td><td>speed key <code class="verbatim">s</code></td><td><code class="verbatim">⌃⌘N</code>, speed key <code class="verbatim">s</code></td><td>speed key <code class="verbatim">s</code></td></tr> | |
| 276 | </tbody> | |
| 277 | </table> | |
| 278 | <p>Narrowing hides everything outside the current subtree or block, so the editor shows only that part of the file. Narrow to Block works on src, example, export, comment and verse blocks (with the blank lines after them) and, for other blocks, on the lines between the opening and closing lines. Edits inside the narrowed text move its bounds as you type. Jumping to a position outside it, from a link, search or the outline pane, widens first.</p> | |
| 279 | <p>Narrowing is a view. Commands still see the whole file: for example, a new footnote's definition still goes into the <code class="verbatim">Footnotes</code> section at the end of the file, and a sparse tree searches the whole file.</p> | |
| 280 | <h2 id="sparse-trees">Sparse trees</h2> | |
| 281 | <p>Sparse Tree… (<code class="verbatim">org-sparse-tree</code>, <code class="verbatim">C-c /</code>, Doom <code class="verbatim">SPC m s s</code>) folds the file to an overview and then shows only the matches and the headings above them. It asks what to match, one keystroke:</p> | |
| 282 | <table> | |
| 283 | <thead> | |
| 284 | <tr><th>Key</th><th>Shows</th><th>Org function</th></tr> | |
| 285 | </thead> | |
| 286 | <tbody> | |
| 287 | <tr><td><code class="verbatim">r</code></td><td>text matching a regular expression (asks for it); case-insensitive</td><td><code class="verbatim">org-occur</code></td></tr> | |
| 288 | <tr><td><code class="verbatim">t</code></td><td>headings with a TODO keyword that is not a done state</td><td><code class="verbatim">org-show-todo-tree</code></td></tr> | |
| 289 | <tr><td><code class="verbatim">T</code></td><td>headings with the keywords you give (several separated by a vertical bar)</td><td><code class="verbatim">org-show-todo-tree</code></td></tr> | |
| 290 | <tr><td><code class="verbatim">m</code></td><td>headings matching a tags and properties match</td><td><code class="verbatim">org-match-sparse-tree</code></td></tr> | |
| 291 | <tr><td><code class="verbatim">p</code></td><td>headings where a property has a value (asks for both, with completion)</td><td><code class="verbatim">org-match-sparse-tree</code></td></tr> | |
| 292 | <tr><td><code class="verbatim">d</code></td><td>deadlines past due or due within 14 days (fixed), in entries not done</td><td><code class="verbatim">org-check-deadlines</code></td></tr> | |
| 293 | <tr><td><code class="verbatim">b</code></td><td>entries with a <code class="verbatim">SCHEDULED</code> or <code class="verbatim">DEADLINE</code> before a date</td><td><code class="verbatim">org-check-before-date</code></td></tr> | |
| 294 | <tr><td><code class="verbatim">a</code></td><td>entries with a <code class="verbatim">SCHEDULED</code> or <code class="verbatim">DEADLINE</code> on or after a date</td><td><code class="verbatim">org-check-after-date</code></td></tr> | |
| 295 | <tr><td><code class="verbatim">D</code></td><td>entries with a <code class="verbatim">SCHEDULED</code> or <code class="verbatim">DEADLINE</code> in a date range</td><td><code class="verbatim">org-check-dates-range</code></td></tr> | |
| 296 | </tbody> | |
| 297 | </table> | |
| 298 | <p>The regular expression uses Emacs syntax. The match syntax for <code class="verbatim">m</code> is the one the agenda's tags search uses (see <a href="07-agenda.html">Agenda</a>). Dates are read as Org reads them (see <a href="06-dates-and-clocking.html">Dates and clocking</a>).</p> | |
| 299 | <p>For a text match, the whole entry around each match is shown; for heading matches, the heading line. The matched text is highlighted, and the echo area reports the number of matches. Subtrees tagged <code class="verbatim">ARCHIVE</code> stay folded. The highlights go away at the next edit or with <code class="verbatim">C-c C-c</code>. <code class="verbatim">TAB</code> and <code class="verbatim">S-TAB</code> work as usual afterwards; cycling leaves the sparse view.</p> | |
| 300 | <h2 id="plain-lists">Plain lists</h2> | |
| 301 | <p>Orgstar's list commands are ports of <code class="verbatim">org-list.el</code>. A list item starts with a bullet: <code class="verbatim">-</code>, <code class="verbatim">+</code>, <code class="verbatim">*</code> (not at the left margin, where it would be a heading), or a number followed by <code class="verbatim">.</code> or <code class="verbatim">)</code>. With alphabetical lists on, <code class="verbatim">a.</code>, <code class="verbatim">A.</code>, <code class="verbatim">a)</code> and <code class="verbatim">A)</code> are bullets too. A description item has <code class="verbatim">::</code> after its term:</p> | |
| 302 | <pre><code class="language-org highlight"><span class="text org"><span class="punctuation definition list org">- </span>milk | |
| 303 | <span class="punctuation definition list org">- </span>eggs | |
| 304 | <span class="punctuation definition list org"> 1. </span>free range | |
| 305 | <span class="punctuation definition list org"> 2. </span>brown | |
| 306 | <span class="punctuation definition list org">- </span>Orgstar :: an org editor for macOS and iOS</span></code></pre> | |
| 307 | <table> | |
| 308 | <thead> | |
| 309 | <tr><th>Setting (<code class="verbatim">config.toml</code>)</th><th>Settings ▸ Editing</th><th>Orgstar default</th><th>Org default</th></tr> | |
| 310 | </thead> | |
| 311 | <tbody> | |
| 312 | <tr><td><code class="verbatim">org-list-allow-alphabetical</code></td><td>Lists can use letters (a. b. c.)</td><td><code class="verbatim">true</code></td><td><code class="verbatim">nil</code></td></tr> | |
| 313 | </tbody> | |
| 314 | </table> | |
| 315 | <h3 id="list-commands">List commands</h3> | |
| 316 | <table> | |
| 317 | <thead> | |
| 318 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 319 | </thead> | |
| 320 | <tbody> | |
| 321 | <tr><td>Insert Item</td><td><code class="verbatim">org-insert-item</code></td><td><code class="verbatim">M-RET</code></td><td><code class="verbatim">⌘↩</code></td><td><code class="verbatim">M-RET</code></td></tr> | |
| 322 | <tr><td>Insert Checkbox Item</td><td><code class="verbatim">org-insert-item</code> with a checkbox</td><td><code class="verbatim">M-S-RET</code></td><td><code class="verbatim">⇧⌘↩</code></td><td><code class="verbatim">M-S-RET</code></td></tr> | |
| 323 | <tr><td>Indent Item</td><td><code class="verbatim">org-indent-item</code></td><td><code class="verbatim">M-<right></code></td><td><code class="verbatim">⌃⌘→</code></td><td><code class="verbatim">M-l</code>; <code class="verbatim">C-t</code> in insert state</td></tr> | |
| 324 | <tr><td>Outdent Item</td><td><code class="verbatim">org-outdent-item</code></td><td><code class="verbatim">M-<left></code></td><td><code class="verbatim">⌃⌘←</code></td><td><code class="verbatim">M-h</code>; <code class="verbatim">C-d</code> in insert state</td></tr> | |
| 325 | <tr><td>Indent Item and Children</td><td><code class="verbatim">org-indent-item-tree</code></td><td><code class="verbatim">M-S-<right></code></td><td><code class="verbatim">⌃⌥⌘→</code></td><td><code class="verbatim">M-L</code>; <code class="verbatim">TAB</code> in insert state</td></tr> | |
| 326 | <tr><td>Outdent Item and Children</td><td><code class="verbatim">org-outdent-item-tree</code></td><td><code class="verbatim">M-S-<left></code></td><td><code class="verbatim">⌃⌥⌘←</code></td><td><code class="verbatim">M-H</code>; <code class="verbatim">S-TAB</code> in insert state</td></tr> | |
| 327 | <tr><td>Move Item Up</td><td><code class="verbatim">org-move-item-up</code></td><td><code class="verbatim">M-<up></code></td><td><code class="verbatim">⌃⌥⌘↑</code></td><td><code class="verbatim">M-k</code></td></tr> | |
| 328 | <tr><td>Move Item Down</td><td><code class="verbatim">org-move-item-down</code></td><td><code class="verbatim">M-<down></code></td><td><code class="verbatim">⌃⌥⌘↓</code></td><td><code class="verbatim">M-j</code></td></tr> | |
| 329 | <tr><td>Toggle Checkbox</td><td><code class="verbatim">org-toggle-checkbox</code></td><td><code class="verbatim">C-c C-x C-b</code></td><td><code class="verbatim">⌃⌘C</code></td><td><code class="verbatim">SPC m x</code>, <code class="verbatim">RET</code> in normal state</td></tr> | |
| 330 | <tr><td>Toggle Item</td><td><code class="verbatim">org-ctrl-c-minus</code></td><td><code class="verbatim">C-c -</code></td><td>menu</td><td><code class="verbatim">SPC m i</code></td></tr> | |
| 331 | </tbody> | |
| 332 | </table> | |
| 333 | <p>Insert Item works anywhere inside an item. The new item gets the next bullet: the same symbol, the next number or the next letter. In a description list the new item has an empty term followed by <code class="verbatim">::</code>, with the caret on the term. With <code class="verbatim">org-M-RET-may-split-line</code> on, text after the caret moves to the new item; with it off (the Orgstar default), the new item goes after the current one. At the start of an item, the new item is inserted before it. If the list's items are separated by blank lines, so is the new one.</p> | |
| 334 | <p>The indent, outdent and move commands need the caret on an item's first line.</p> | |
| 335 | <ul> | |
| 336 | <li>Indent Item and Outdent Item move one item; its children stay where they are, and an item with children can't be outdented alone ("Cannot outdent an item without its children").</li> | |
| 337 | <li>The "and Children" variants move the item with its sub-items.</li> | |
| 338 | <li>On the first item of a list, Indent Item refuses; Indent Item and Children and Outdent Item and Children move the whole list. A list moved to the left margin changes <code class="verbatim">*</code> bullets to <code class="verbatim">-</code>.</li> | |
| 339 | <li>Move Item Up and Down swap the item, with its children, with the previous or next item at the same level.</li> | |
| 340 | </ul> | |
| 341 | <p>After every list command the list is repaired as Org repairs it: bullets are renumbered, indentation is fixed and checkboxes of parent items are updated.</p> | |
| 342 | <h3 id="bullets-and-numbering">Bullets and numbering</h3> | |
| 343 | <p>Toggle Item (<code class="verbatim">C-c -</code>) on an item, with no selection, cycles the bullet of the whole list (<code class="verbatim">org-cycle-list-bullet</code>) through:</p> | |
| 344 | <p><code class="verbatim">-</code>, <code class="verbatim">+</code>, <code class="verbatim">*</code>, <code class="verbatim">1.</code>, <code class="verbatim">1)</code>, then with alphabetical lists <code class="verbatim">a.</code>, <code class="verbatim">A.</code>, <code class="verbatim">a)</code>, <code class="verbatim">A)</code>.</p> | |
| 345 | <p><code class="verbatim">*</code> is skipped for a list at the left margin. Description lists skip the numbered and lettered bullets. Lettered bullets are offered only when the list has 26 items or fewer. Org also cycles bullets with <code class="verbatim">S-<left></code> and <code class="verbatim">S-<right></code> on an item; Orgstar does not bind those on items.</p> | |
| 346 | <p>Numbered and lettered lists are renumbered whenever a list command changes them, and by <code class="verbatim">C-c C-c</code> on any item. To start a list at a given number, put a counter after the bullet, as in Org:</p> | |
| 347 | <pre><code class="language-org highlight"><span class="text org"><span class="punctuation definition list org">5. </span>[@5] fifth | |
| 348 | <span class="punctuation definition list org">6. </span>sixth</span></code></pre> | |
| 349 | <h2 id="checkboxes-and-statistics">Checkboxes and statistics</h2> | |
| 350 | <h3 id="checkboxes">Checkboxes</h3> | |
| 351 | <p>An item with <code class="verbatim">[ ]</code> after its bullet has a checkbox. <code class="verbatim">[X]</code> is checked, and <code class="verbatim">[-]</code> marks a parent item whose children are partly checked.</p> | |
| 352 | <pre><code class="language-org highlight"><span class="text org"><span class="punctuation definition list org">- </span><span class="constant language checkbox org">[-]</span> packing | |
| 353 | <span class="punctuation definition list org"> - </span><span class="constant language checkbox org">[X]</span> passport | |
| 354 | <span class="punctuation definition list org"> - </span><span class="constant language checkbox org">[ ]</span> charger</span></code></pre> | |
| 355 | <p>Toggle Checkbox (<code class="verbatim">C-c C-x C-b</code>) checks or unchecks the item on the caret's line, or every item in the selection. <code class="verbatim">C-c C-c</code> on an item toggles its checkbox too, and on an item without one, repairs the list. A parent item's checkbox follows its children: it can't be checked while children are unchecked ("Cannot toggle this checkbox: unchecked subitems").</p> | |
| 356 | <p>Toggle Checkbox works only on item lines. Org's behaviour on a heading, toggling the checkboxes of the region or subtree, is not available.</p> | |
| 357 | <h3 id="statistics-cookies">Statistics cookies</h3> | |
| 358 | <p>A cookie <code class="verbatim">[/]</code> or <code class="verbatim">[%]</code> on a heading or an item shows progress:</p> | |
| 359 | <ul> | |
| 360 | <li>On an item, it counts that item's direct child checkboxes.</li> | |
| 361 | <li>On a heading, it counts the checkboxes of the top-level items in the heading's own section. If the section has none, it counts the TODO children: direct child headings with a keyword, and how many of them are in a done state.</li> | |
| 362 | </ul> | |
| 363 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Groceries [1/3] | |
| 364 | </span><span class="punctuation definition list org">- </span><span class="constant language checkbox org">[X]</span> milk | |
| 365 | <span class="punctuation definition list org">- </span><span class="constant language checkbox org">[ ]</span> eggs | |
| 366 | <span class="punctuation definition list org">- </span><span class="constant language checkbox org">[ ]</span> bread | |
| 367 | ||
| 368 | <span class="markup heading org"><span class="punctuation definition heading org">*</span> Release [50%] | |
| 369 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">DONE</span> Tag the build | |
| 370 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">TODO</span> Write the notes</span></span></code></pre> | |
| 371 | <p>Cookies update when you toggle or insert a checkbox, when a child heading's TODO state changes, when you archive an entry, and when you press <code class="verbatim">C-c C-c</code> with the caret on the cookie. A cookie with nothing to count shows <code class="verbatim">[0/0]</code> or <code class="verbatim">[100%]</code>. Tags are realigned when the cookie's width changes.</p> | |
| 372 | <p>The <code class="verbatim">COOKIE_DATA</code> property changes what a heading's cookie counts, as in Org:</p> | |
| 373 | <table> | |
| 374 | <thead> | |
| 375 | <tr><th>Value</th><th>Effect</th></tr> | |
| 376 | </thead> | |
| 377 | <tbody> | |
| 378 | <tr><td><code class="verbatim">todo</code></td><td>count TODO children, not checkboxes</td></tr> | |
| 379 | <tr><td><code class="verbatim">checkbox</code></td><td>count checkboxes, not TODO children</td></tr> | |
| 380 | <tr><td><code class="verbatim">recursive</code></td><td>count all descendants, not only direct children</td></tr> | |
| 381 | </tbody> | |
| 382 | </table> | |
| 383 | <p>For TODO statistics, <code class="verbatim">COOKIE_DATA</code> is read with inheritance, from the parent or an ancestor. Orgstar counts TODO children hierarchically, as Org does with <code class="verbatim">org-hierarchical-todo-statistics</code> at its default.</p> | |
| 384 | <h2 id="blocks">Blocks</h2> | |
| 385 | <p>Blocks are lines between <code class="verbatim">#+BEGIN_name</code> and <code class="verbatim">#+END_name</code>:</p> | |
| 386 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+BEGIN_QUOTE</span> | |
| 387 | Text to quote. | |
| 388 | <span class="keyword control block end org">#+END_QUOTE</span></span></span></code></pre> | |
| 389 | <h3 id="structure-templates">Structure templates</h3> | |
| 390 | <p>Insert Structure Template (<code class="verbatim">org-insert-structure-template</code>, <code class="verbatim">C-c C-,</code> in the Emacs and Doom presets) asks for a block type, one keystroke:</p> | |
| 391 | <table> | |
| 392 | <thead> | |
| 393 | <tr><th>Key</th><th>Block</th></tr> | |
| 394 | </thead> | |
| 395 | <tbody> | |
| 396 | <tr><td><code class="verbatim">a</code></td><td><code class="verbatim">export ascii</code></td></tr> | |
| 397 | <tr><td><code class="verbatim">c</code></td><td><code class="verbatim">center</code></td></tr> | |
| 398 | <tr><td><code class="verbatim">C</code></td><td><code class="verbatim">comment</code></td></tr> | |
| 399 | <tr><td><code class="verbatim">e</code></td><td><code class="verbatim">example</code></td></tr> | |
| 400 | <tr><td><code class="verbatim">E</code></td><td><code class="verbatim">export</code></td></tr> | |
| 401 | <tr><td><code class="verbatim">h</code></td><td><code class="verbatim">export html</code></td></tr> | |
| 402 | <tr><td><code class="verbatim">l</code></td><td><code class="verbatim">export latex</code></td></tr> | |
| 403 | <tr><td><code class="verbatim">q</code></td><td><code class="verbatim">quote</code></td></tr> | |
| 404 | <tr><td><code class="verbatim">s</code></td><td><code class="verbatim">src</code></td></tr> | |
| 405 | <tr><td><code class="verbatim">v</code></td><td><code class="verbatim">verse</code></td></tr> | |
| 406 | </tbody> | |
| 407 | </table> | |
| 408 | <p>Press <code class="verbatim">TAB</code> to type any other type. These are Org's default <code class="verbatim">org-structure-template-alist</code>; Orgstar does not read a custom one. The block is inserted at the caret's indentation. With a selection, the block wraps the selected lines, and for <code class="verbatim">src</code>, <code class="verbatim">example</code>, <code class="verbatim">export</code> and <code class="verbatim">comment</code> blocks, lines that would read as headings or keywords are protected with a leading comma. For <code class="verbatim">src</code> and <code class="verbatim">export</code>, the caret ends on the opening line after a space, ready for the language; otherwise it ends inside the block. The case of <code class="verbatim">BEGIN</code> and <code class="verbatim">END</code> follows the case of the type you typed.</p> | |
| 409 | <h3 id="org-tempo-templates">org-tempo templates</h3> | |
| 410 | <p>Typing <code class="verbatim"><</code> and a key at the start of a line (after blanks only) and then completing expands it as <code class="verbatim">org-tempo</code> does. <code class="verbatim"><s</code> becomes:</p> | |
| 411 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span> | |
| 412 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 413 | <p>with the caret after <code class="verbatim">begin_src</code>. The keys are those of the table above, plus <code class="verbatim"><L</code>, <code class="verbatim"><H</code>, <code class="verbatim"><A</code> and <code class="verbatim"><i</code>, which insert <code class="verbatim">#+latex:</code>, <code class="verbatim">#+html:</code>, <code class="verbatim">#+ascii:</code> and <code class="verbatim">#+index:</code> keyword lines.</p> | |
| 414 | <p>Completion runs with Complete at Point (<code class="verbatim">C-M-i</code> in the Emacs preset, <code class="verbatim">C-SPC</code> in Doom's insert state; in the Mac preset, from the palette). In the Doom preset the completion list also opens by itself after a short pause once you have typed <code class="verbatim"><</code> and a letter, and <code class="verbatim">TAB</code> or <code class="verbatim">RET</code> takes the selected candidate. <code class="verbatim">TAB</code> alone does not expand <code class="verbatim"><s</code> in the Emacs or Mac preset.</p> | |
| 415 | <h3 id="folding-and-editing-blocks">Folding and editing blocks</h3> | |
| 416 | <p><code class="verbatim">TAB</code> on a block's first or last line folds or unfolds it. Blocks are open when a file opens unless <code class="verbatim">org-cycle-hide-block-startup</code> is on in <code class="verbatim">config.toml</code> or the file has <code class="verbatim">#+STARTUP: hideblocks</code> (<code class="verbatim">nohideblocks</code> overrides the setting the other way). See <a href="02-the-editor.html">The editor</a> for folding in general.</p> | |
| 417 | <p>Edit Block (<code class="verbatim">org-edit-special</code>, <code class="verbatim">C-c '</code>, Mac <code class="verbatim">⌃⌘'</code>) edits a src, example or export block in a separate editor. See <a href="11-code-blocks.html">Code blocks</a>.</p> | |
| 418 | <h2 id="drawers">Drawers</h2> | |
| 419 | <p>A drawer is a named group of lines between <code class="verbatim">:NAME:</code> and <code class="verbatim">:END:</code>. Orgstar writes the <code class="verbatim">PROPERTIES</code> drawer for properties and, depending on <code class="verbatim">org-log-into-drawer</code>, a <code class="verbatim">LOGBOOK</code> drawer for state notes and clock lines (see <a href="05-todos-and-tags.html">TODOs and tags</a> and <a href="06-dates-and-clocking.html">Dates and clocking</a>). You can write any other drawer by hand:</p> | |
| 420 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Meeting | |
| 421 | </span>:NOTES: | |
| 422 | Private notes, folded away. | |
| 423 | :END:</span></code></pre> | |
| 424 | <p><code class="verbatim">TAB</code> on a drawer's first or last line folds or unfolds it. Drawers are folded when a file opens, as with Org's <code class="verbatim">org-cycle-hide-drawer-startup</code> (<code class="verbatim">true</code> by default in <code class="verbatim">config.toml</code>). <code class="verbatim">#+STARTUP: nohidedrawers</code> keeps them open in one file, and <code class="verbatim">#+STARTUP: hidedrawers</code> folds them when the setting is off.</p> | |
| 425 | <p>Org's <code class="verbatim">org-insert-drawer</code> (<code class="verbatim">C-c C-x d</code>) is not available; type the two lines yourself.</p> | |
| 426 | <h2 id="properties">Properties</h2> | |
| 427 | <p>Properties are key-value pairs in an entry's <code class="verbatim">PROPERTIES</code> drawer, right after the heading and its planning line:</p> | |
| 428 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Laptop | |
| 429 | </span>:PROPERTIES: | |
| 430 | :VENDOR: Apple | |
| 431 | :Effort: 1:00 | |
| 432 | :END:</span></code></pre> | |
| 433 | <p>File-wide properties come from <code class="verbatim">#+PROPERTY:</code> lines and from a <code class="verbatim">PROPERTIES</code> drawer before the first heading. A key written <code class="verbatim">KEY+</code> appends its value to the inherited one with a space between.</p> | |
| 434 | <h3 id="setting-and-deleting">Setting and deleting</h3> | |
| 435 | <table> | |
| 436 | <thead> | |
| 437 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 438 | </thead> | |
| 439 | <tbody> | |
| 440 | <tr><td>Set Property…</td><td><code class="verbatim">org-set-property</code></td><td><code class="verbatim">C-c C-x p</code></td><td><code class="verbatim">⌃⇧⌘P</code></td><td><code class="verbatim">SPC m o</code></td></tr> | |
| 441 | <tr><td>Delete Property…</td><td><code class="verbatim">org-delete-property</code></td><td>none</td><td>menu</td><td>none</td></tr> | |
| 442 | <tr><td>Delete Property Everywhere…</td><td><code class="verbatim">org-delete-property-globally</code></td><td>none</td><td>menu</td><td>none</td></tr> | |
| 443 | <tr><td>Property Action…</td><td><code class="verbatim">org-property-action</code></td><td><code class="verbatim">C-c C-c</code> in a property drawer</td><td><code class="verbatim">⌃⌘X</code> in a property drawer</td><td><code class="verbatim">C-c C-c</code></td></tr> | |
| 444 | <tr><td>Next Allowed Value</td><td><code class="verbatim">org-property-next-allowed-value</code></td><td><code class="verbatim">S-<right></code> on a property line</td><td><code class="verbatim">⌃⇧⌘→</code> on a property line</td><td><code class="verbatim">S-<right></code>, <code class="verbatim">C-S-l</code></td></tr> | |
| 445 | <tr><td>Previous Allowed Value</td><td><code class="verbatim">org-property-previous-allowed-value</code></td><td><code class="verbatim">S-<left></code> on a property line</td><td><code class="verbatim">⌃⇧⌘←</code> on a property line</td><td><code class="verbatim">S-<left></code>, <code class="verbatim">C-S-h</code></td></tr> | |
| 446 | </tbody> | |
| 447 | </table> | |
| 448 | <p>Set Property asks for the key, offering the keys used in the file, Org's standard keys and the properties named in <code class="verbatim">COLUMNS</code> formats; on a property line, Return takes that line's key. It then asks for the value. If the key has allowed values, those are offered and required unless the list includes <code class="verbatim">:ETC</code>; otherwise the values the key has elsewhere in the file are offered. An empty answer keeps the current value. The drawer is created if the entry has none, and lines are aligned as Org's <code class="verbatim">org-property-format</code> (<code class="verbatim">"%-10s %s"</code>) aligns them. Setting <code class="verbatim">TODO</code> sets the entry's TODO keyword instead.</p> | |
| 449 | <p>Delete Property asks which of the entry's properties to remove, when it has more than one, and removes the drawer if it becomes empty. Delete Property Everywhere removes a key from every entry in the file and reports how many it changed. Property Action, run by <code class="verbatim">C-c C-c</code> in a property drawer, asks <code class="verbatim">s</code> (set), <code class="verbatim">d</code> (delete) or <code class="verbatim">D</code> (delete everywhere).</p> | |
| 450 | <h3 id="allowed-values">Allowed values</h3> | |
| 451 | <p>A property <code class="verbatim">KEY_ALL</code> lists the values <code class="verbatim">KEY</code> may take, separated by spaces, with quotes around values that contain spaces. Orgstar looks for it on the entry, then its ancestors, then the file:</p> | |
| 452 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+PROPERTY:</span><span class="string unquoted org"> Status_ALL open blocked done</span></span></code></pre> | |
| 453 | <p>Next and Previous Allowed Value step through the list on a property line. <code class="verbatim">TODO</code> and <code class="verbatim">PRIORITY</code> take their values from the file's keywords and priority range. A property whose value is <code class="verbatim">[ ]</code> or <code class="verbatim">[X]</code> toggles between them.</p> | |
| 454 | <h3 id="inheritance">Inheritance</h3> | |
| 455 | <p>Orgstar inherits properties as Org does with <code class="verbatim">org-use-property-inheritance</code> at its default of <code class="verbatim">nil</code>: a property applies only to the entry that has it, with these exceptions:</p> | |
| 456 | <ul> | |
| 457 | <li><code class="verbatim">CATEGORY</code>, <code class="verbatim">ARCHIVE</code>, <code class="verbatim">COLUMNS</code>, <code class="verbatim">LOGGING</code> and the <code class="verbatim">header-args</code> properties are always inherited from ancestors and <code class="verbatim">#+PROPERTY:</code> lines.</li> | |
| 458 | <li><code class="verbatim">ID</code> and <code class="verbatim">CUSTOM_ID</code> are never inherited.</li> | |
| 459 | <li><code class="verbatim">KEY_ALL</code> allowed values and <code class="verbatim">COOKIE_DATA</code> for TODO statistics are looked up through the ancestors.</li> | |
| 460 | </ul> | |
| 461 | <p>Orgstar has no setting for <code class="verbatim">org-use-property-inheritance</code>.</p> | |
| 462 | <h3 id="special-properties">Special properties</h3> | |
| 463 | <p>Org computes some properties instead of reading them from a drawer. Orgstar treats these as special and doesn't offer them as allowed-value lists: <code class="verbatim">ALLTAGS</code>, <code class="verbatim">BLOCKED</code>, <code class="verbatim">CLOCKSUM</code>, <code class="verbatim">CLOCKSUM_T</code>, <code class="verbatim">CLOSED</code>, <code class="verbatim">DEADLINE</code>, <code class="verbatim">FILE</code>, <code class="verbatim">ITEM</code>, <code class="verbatim">PRIORITY</code>, <code class="verbatim">SCHEDULED</code>, <code class="verbatim">TAGS</code>, <code class="verbatim">TIMESTAMP</code>, <code class="verbatim">TIMESTAMP_IA</code> and <code class="verbatim">TODO</code>. Column view computes <code class="verbatim">ITEM</code>, <code class="verbatim">TODO</code>, <code class="verbatim">PRIORITY</code>, <code class="verbatim">TAGS</code>, <code class="verbatim">ALLTAGS</code>, <code class="verbatim">DEADLINE</code>, <code class="verbatim">SCHEDULED</code>, <code class="verbatim">CLOSED</code> and <code class="verbatim">CLOCKSUM</code>; the others show as empty there.</p> | |
| 464 | <h2 id="column-view">Column view</h2> | |
| 465 | <p>Column view shows entries as rows and properties as columns. The columns come from a <code class="verbatim">COLUMNS</code> format, found in this order:</p> | |
| 466 | <ol> | |
| 467 | <li>a <code class="verbatim">COLUMNS</code> property on the entry at the caret or one of its ancestors (the nearest one wins, and that entry becomes the top of the view);</li> | |
| 468 | <li>a <code class="verbatim">#+COLUMNS:</code> line in the file;</li> | |
| 469 | <li>Org's default, <code class="verbatim">%25ITEM %TODO %3PRIORITY %TAGS</code>.</li> | |
| 470 | </ol> | |
| 471 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+COLUMNS:</span><span class="string unquoted org"> %40ITEM %TODO %Effort(Estimate){:} %CLOCKSUM</span></span></code></pre> | |
| 472 | <p>Each column is <code class="verbatim">%[width]PROPERTY[(title)][{summary}]</code>, as in Org. The width limits the column, the title replaces the property name in the header, and the summary is computed for parent entries from their children. The summary operators are <code class="verbatim">+</code>, <code class="verbatim">$</code>, <code class="verbatim">min</code>, <code class="verbatim">max</code>, <code class="verbatim">mean</code>, <code class="verbatim">X</code>, <code class="verbatim">X/</code>, <code class="verbatim">X%</code>, <code class="verbatim">:</code>, <code class="verbatim">:min</code>, <code class="verbatim">:max</code>, <code class="verbatim">:mean</code> and <code class="verbatim">est+</code>. Org's age operators (<code class="verbatim">@min</code>, <code class="verbatim">@max</code>, <code class="verbatim">@mean</code>) are not supported. The numeric operators take a format after a semicolon, as in <code class="verbatim">{+;%.1f}</code>.</p> | |
| 473 | <p>Subtrees tagged <code class="verbatim">ARCHIVE</code> and commented subtrees are left out.</p> | |
| 474 | <h3 id="the-column-view-sheet">The column view sheet</h3> | |
| 475 | <table> | |
| 476 | <thead> | |
| 477 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 478 | </thead> | |
| 479 | <tbody> | |
| 480 | <tr><td>Column View</td><td><code class="verbatim">org-columns</code></td><td><code class="verbatim">C-c C-x C-c</code></td><td>menu</td><td><code class="verbatim">C-c C-x C-c</code></td></tr> | |
| 481 | <tr><td>Column View of File</td><td><code class="verbatim">org-columns</code> with a prefix</td><td>none</td><td>menu</td><td>none</td></tr> | |
| 482 | </tbody> | |
| 483 | </table> | |
| 484 | <p>Column View opens a sheet with the entries from the view's top (the entry with the <code class="verbatim">COLUMNS</code> property, or the entry at the caret; the whole file before the first heading). Column View of File shows every entry in the file. Click a row to go to its heading. Done (or Escape) closes the sheet.</p> | |
| 485 | <p>The sheet is read-only. Org's column view lets you edit values in place and writes parent summaries back into the file; Orgstar's does neither. Change values with Set Property, or edit the drawer.</p> | |
| 486 | <h3 id="the-columns-inspector">The Columns inspector</h3> | |
| 487 | <p>View ▸ Show or Hide Columns and Clock opens an inspector beside the editor. Its Columns tab shows the same table for the open file, kept current as you type. Choose File for every entry or Subtree for the entry at the caret. The row of the heading at the caret is shown in bold, and clicking a row goes to it. The Clock tab is described in <a href="06-dates-and-clocking.html">Dates and clocking</a>.</p> | |
| 488 | <h3 id="column-view-tables">Column view tables</h3> | |
| 489 | <p>Insert Column View Table (<code class="verbatim">org-columns-insert-dblock</code>, <code class="verbatim">C-c C-x i</code>) asks what to capture: <code class="verbatim">local</code> (the default, the entry at the caret), <code class="verbatim">global</code> (the whole file) or an <code class="verbatim">ID</code> of an entry. It inserts a <code class="verbatim">columnview</code> dynamic block and fills it:</p> | |
| 490 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+BEGIN:</span><span class="string unquoted org"> columnview :hlines 1 :id local</span> | |
| 491 | <span class="markup other table org">| ITEM | TODO | PRIORITY | TAGS |</span> | |
| 492 | <span class="markup other table org">|------+------+----------+------|</span> | |
| 493 | <span class="markup other table org">| ... | | | |</span> | |
| 494 | <span class="keyword other keyword org">#+END:</span></span></code></pre> | |
| 495 | <p><code class="verbatim">C-c C-c</code> (Mac <code class="verbatim">⌃⌘X</code>) on the <code class="verbatim">#+BEGIN:</code> line, or <code class="verbatim">C-c C-x C-u</code> anywhere in the block, updates it. Updating writes summary values into the parents' properties, as Org does. The block takes these parameters:</p> | |
| 496 | <table> | |
| 497 | <thead> | |
| 498 | <tr><th>Parameter</th><th>Meaning</th></tr> | |
| 499 | </thead> | |
| 500 | <tbody> | |
| 501 | <tr><td><code class="verbatim">:id</code></td><td><code class="verbatim">local</code>, <code class="verbatim">global</code>, or an entry's <code class="verbatim">ID</code></td></tr> | |
| 502 | <tr><td><code class="verbatim">:format</code></td><td>a column format to use instead of the entry's or file's</td></tr> | |
| 503 | <tr><td><code class="verbatim">:hlines</code></td><td><code class="verbatim">t</code> for a line between all rows, or N for one before each level N or higher row</td></tr> | |
| 504 | <tr><td><code class="verbatim">:maxlevel</code></td><td>leave out deeper headings</td></tr> | |
| 505 | <tr><td><code class="verbatim">:skip-empty-rows</code></td><td>leave out rows whose columns other than <code class="verbatim">ITEM</code> are empty</td></tr> | |
| 506 | <tr><td><code class="verbatim">:exclude-tags</code></td><td>leave out entries with these tags, as a list</td></tr> | |
| 507 | <tr><td><code class="verbatim">:indent</code></td><td>indent <code class="verbatim">ITEM</code> by level</td></tr> | |
| 508 | </tbody> | |
| 509 | </table> | |
| 510 | <p>Existing <code class="verbatim">#+TBLFM:</code> lines after the table are kept. An <code class="verbatim">:id</code> of the form <code class="verbatim">file:path</code> (another file) is not supported.</p> | |
| 511 | <h2 id="footnotes">Footnotes</h2> | |
| 512 | <table> | |
| 513 | <thead> | |
| 514 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 515 | </thead> | |
| 516 | <tbody> | |
| 517 | <tr><td>Footnote Action</td><td><code class="verbatim">org-footnote-action</code></td><td><code class="verbatim">C-c C-x f</code></td><td><code class="verbatim">⌃⇧⌘F</code></td><td><code class="verbatim">C-c C-x f</code></td></tr> | |
| 518 | <tr><td>Footnote Menu</td><td><code class="verbatim">org-footnote-action</code> with a prefix</td><td>none</td><td>menu</td><td>none</td></tr> | |
| 519 | </tbody> | |
| 520 | </table> | |
| 521 | <p>Footnote Action depends on where the caret is:</p> | |
| 522 | <ul> | |
| 523 | <li>On a reference such as <code class="verbatim">[fn:1]</code>, it goes to the definition. If there is none, it asks whether to create one.</li> | |
| 524 | <li>On a definition's label, it goes back to a reference.</li> | |
| 525 | <li>Elsewhere, where a footnote is allowed, it inserts a new reference with the next free number and creates its definition.</li> | |
| 526 | <li>Where a footnote can't go, it shows the footnote menu.</li> | |
| 527 | </ul> | |
| 528 | <p><code class="verbatim">C-c C-c</code> on a reference or a definition's label does the same jumps. After a jump to a definition, the echo area says how to get back: <code class="verbatim">Edit definition and go back with `C-c C-c' or `C-c C-x f' on its label.</code></p> | |
| 529 | <p>New definitions go in a level 1 heading named <code class="verbatim">Footnotes</code> at the end of the file, which is created when needed (Org's <code class="verbatim">org-footnote-section</code>):</p> | |
| 530 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Notes | |
| 531 | </span>Orgstar reads org files.<span class="markup other footnote org">[fn:1]</span> | |
| 532 | ||
| 533 | <span class="markup heading org"><span class="punctuation definition heading org">*</span> Footnotes | |
| 534 | </span> | |
| 535 | <span class="markup other footnote org">[fn:1]</span> And writes them.</span></code></pre> | |
| 536 | <p>The footnote menu asks, one keystroke:</p> | |
| 537 | <table> | |
| 538 | <thead> | |
| 539 | <tr><th>Key</th><th>Action</th><th>Org function</th></tr> | |
| 540 | </thead> | |
| 541 | <tbody> | |
| 542 | <tr><td><code class="verbatim">s</code></td><td>sort definitions into the order of their first reference</td><td><code class="verbatim">org-footnote-sort</code></td></tr> | |
| 543 | <tr><td><code class="verbatim">r</code></td><td>renumber numeric labels <code class="verbatim">fn:N</code> in order of appearance</td><td><code class="verbatim">org-footnote-renumber-fn:N</code></td></tr> | |
| 544 | <tr><td><code class="verbatim">S</code></td><td>renumber, then sort</td><td></td></tr> | |
| 545 | <tr><td><code class="verbatim">n</code></td><td>normalize: number every footnote, labeled, anonymous and inline, and collect all definitions in the footnote section</td><td><code class="verbatim">org-footnote-normalize</code></td></tr> | |
| 546 | <tr><td><code class="verbatim">d</code></td><td>delete the footnote at the caret: its references and definition</td><td><code class="verbatim">org-footnote-delete</code></td></tr> | |
| 547 | </tbody> | |
| 548 | </table> | |
| 549 | <p>A reference with no definition gets the text <code class="verbatim">DEFINITION NOT FOUND.</code> when sorted or normalized.</p> | |
| 550 | <h2 id="refiling">Refiling</h2> | |
| 551 | <p>Refile… (<code class="verbatim">org-refile</code>, <code class="verbatim">C-c C-w</code>, Mac <code class="verbatim">⌃⌘W</code>, Doom <code class="verbatim">SPC m r r</code> or <code class="verbatim">SPC m s r</code>) moves the subtree at the caret under another heading, in this file or another one.</p> | |
| 552 | <p>It asks for the target with completion. The targets are every org file in your folders and every heading down to level 3 in those files, written as the file's path relative to its folder followed by the outline path:</p> | |
| 553 | <pre>projects.org | |
| 554 | projects.org/Work | |
| 555 | projects.org/Work/Website | |
| 556 | notes/inbox.org/Someday</pre> | |
| 557 | <p>Choosing a heading makes the subtree its last child, at one level below it. Choosing a file adds the subtree at the end of that file as a level 1 heading. Levels inside the subtree are shifted to match, and tags are realigned. A subtree can't be refiled into itself.</p> | |
| 558 | <p>For the open file, targets come from the buffer, including unsaved edits. When the target is another file, Orgstar writes that file first, into its open buffer if it has one, otherwise through the normal save path, and removes the subtree from the source only after that succeeds. If the target file changed on disk in the meantime, nothing is refiled.</p> | |
| 559 | <p>This matches Org with <code class="verbatim">org-refile-targets</code> set to headings of maximum level 3 in all files, <code class="verbatim">org-refile-use-outline-path</code> set to <code class="verbatim">file</code>, <code class="verbatim">org-reverse-note-order</code> <code class="verbatim">nil</code> (new entries go last), <code class="verbatim">org-log-refile</code> <code class="verbatim">nil</code> and <code class="verbatim">org-refile-keep</code> <code class="verbatim">nil</code>. None of these is configurable in Orgstar. Refiling from the agenda is covered in <a href="07-agenda.html">Agenda</a>.</p> | |
| 560 | <h2 id="archiving">Archiving</h2> | |
| 561 | <h3 id="archive-subtree">Archive Subtree</h3> | |
| 562 | <p>Archive Subtree (<code class="verbatim">org-archive-subtree</code>, <code class="verbatim">C-c C-x C-s</code> or <code class="verbatim">C-c $</code>, Mac <code class="verbatim">⌃⌘A</code>, Doom <code class="verbatim">SPC m A</code> or <code class="verbatim">SPC m s A</code>) moves the subtree at the caret to an archive.</p> | |
| 563 | <p>The archive location is read from, in order: the <code class="verbatim">ARCHIVE</code> property of the entry or an ancestor, a <code class="verbatim">#+ARCHIVE:</code> line in the file, and Org's default <code class="verbatim">%s_archive::</code>. A location is <code class="verbatim">file::heading</code>, where <code class="verbatim">%s</code> stands for the current file's name:</p> | |
| 564 | <table> | |
| 565 | <thead> | |
| 566 | <tr><th>Location</th><th>Where the subtree goes</th></tr> | |
| 567 | </thead> | |
| 568 | <tbody> | |
| 569 | <tr><td><code class="verbatim">%s_archive::</code></td><td>the end of <code class="verbatim">notes.org_archive</code> next to <code class="verbatim">notes.org</code>, at level 1</td></tr> | |
| 570 | <tr><td><code class="verbatim">archive.org::* Old</code></td><td>under the heading <code class="verbatim">* Old</code> in <code class="verbatim">archive.org</code>, created if missing</td></tr> | |
| 571 | <tr><td><code class="verbatim">::* Archived</code></td><td>under <code class="verbatim">* Archived</code> in the same file</td></tr> | |
| 572 | <tr><td><code class="verbatim">%s_archive::datetree/</code></td><td>under year, month and day headings in the archive file, for the entry's <code class="verbatim">CLOSED</code> date or today</td></tr> | |
| 573 | </tbody> | |
| 574 | </table> | |
| 575 | <p>Relative paths are relative to the current file's folder, and <code class="verbatim">~</code> is your home folder. A new archive file starts with a line <code class="verbatim">Archived entries from file</code> followed by the source's path.</p> | |
| 576 | <p>The archived entry gets these properties, as with Org's default <code class="verbatim">org-archive-save-context-info</code>: <code class="verbatim">ARCHIVE_TIME</code>, <code class="verbatim">ARCHIVE_FILE</code>, <code class="verbatim">ARCHIVE_OLPATH</code>, <code class="verbatim">ARCHIVE_CATEGORY</code>, <code class="verbatim">ARCHIVE_TODO</code> and <code class="verbatim">ARCHIVE_ITAGS</code> (empty ones are left out). Within the same file, tags it inherited are added to its heading. After the subtree leaves, the parent's statistics cookies are updated. The entry's TODO state is not changed.</p> | |
| 577 | <p>If the archive file is open, the subtree goes into its buffer. Otherwise Orgstar writes the archive file first and removes the subtree from the source only after that succeeds. Org's option <code class="verbatim">org-archive-location</code> in Emacs is not read; use the <code class="verbatim">ARCHIVE</code> property or <code class="verbatim">#+ARCHIVE:</code>. Archiving from the agenda is covered in <a href="07-agenda.html">Agenda</a>.</p> | |
| 578 | <h3 id="the-archive-tag">The ARCHIVE tag</h3> | |
| 579 | <p>Toggle ARCHIVE Tag (<code class="verbatim">org-toggle-archive-tag</code>, <code class="verbatim">C-c C-x a</code>, Doom <code class="verbatim">SPC m s a</code>) adds or removes the <code class="verbatim">ARCHIVE</code> tag on the entry at the caret. Adding it folds the subtree.</p> | |
| 580 | <p>Subtrees tagged <code class="verbatim">ARCHIVE</code> stay where they are, but are folded when a file opens and in sparse trees, and are left out of column view. <code class="verbatim">TAB</code> opens an archived subtree like any other; Org's <code class="verbatim">org-cycle-open-archived-trees</code> behaviour, which keeps them closed, is not reproduced. See <a href="05-todos-and-tags.html">TODOs and tags</a> for tags in general.</p> | |
| 581 | <h3 id="archive-sibling">Archive sibling</h3> | |
| 582 | <p>Archive to Archive Sibling (<code class="verbatim">org-archive-to-archive-sibling</code>, <code class="verbatim">C-c C-x A</code>) moves the subtree at the caret under a sibling heading named <code class="verbatim">Archive</code> with the <code class="verbatim">ARCHIVE</code> tag, creating it at the end of the parent's children if needed. The moved entry gets an <code class="verbatim">ARCHIVE_TIME</code> property, and the <code class="verbatim">Archive</code> sibling is folded.</p> | |
| 583 | <h2 id="the-outline-pane">The outline pane</h2> | |
| 584 | <p>The outline pane, to the left of the editor, lists the headings of the open org file, indented by level. Click a heading to go to it; folded text around it opens. A heading with no title is shown as <code class="verbatim">(untitled)</code>.</p> | |
| 585 | <p>Show or hide it with the toolbar button or View ▸ Show or Hide Outline. Orgstar remembers the choice for org files; for other files the pane starts hidden and shows "Only org files have an outline." Drag the divider to resize it. While the search field has text, the pane shows search results instead. The backlinks pane, when shown, sits below the outline (see <a href="09-links.html">Links</a>).</p> | |
| 586 | <h2 id="c-c-c-c">C-c C-c</h2> | |
| 587 | <p><code class="verbatim">C-c C-c</code> (<code class="verbatim">org-ctrl-c-ctrl-c</code>) does what fits the caret's position. In the Emacs and Doom presets it is <code class="verbatim">C-c C-c</code>; in the Mac preset it is <code class="verbatim">⌃⌘X</code>. In order, it:</p> | |
| 588 | <table> | |
| 589 | <thead> | |
| 590 | <tr><th>Caret on</th><th>Effect</th></tr> | |
| 591 | </thead> | |
| 592 | <tbody> | |
| 593 | <tr><td>anywhere, while sparse tree highlights show</td><td>removes the highlights, and nothing else (not in a table or src block)</td></tr> | |
| 594 | <tr><td>a src block, a <code class="verbatim">#+CALL</code> line or inline code</td><td>runs it (see <a href="11-code-blocks.html">Code blocks</a>)</td></tr> | |
| 595 | <tr><td>a table or <code class="verbatim">#+TBLFM</code> line</td><td>aligns the table, or recalculates it (see <a href="10-tables.html">Tables</a>)</td></tr> | |
| 596 | <tr><td>a footnote reference or definition label</td><td>jumps between them</td></tr> | |
| 597 | <tr><td>a blank line</td><td>nothing</td></tr> | |
| 598 | <tr><td>a <code class="verbatim">CLOCK:</code> line</td><td>fixes the weekdays and writes the duration again</td></tr> | |
| 599 | <tr><td>a dynamic block's <code class="verbatim">#+BEGIN:</code> line</td><td>updates the block</td></tr> | |
| 600 | <tr><td>a statistics cookie</td><td>updates it</td></tr> | |
| 601 | <tr><td>a timestamp</td><td>fixes its weekday</td></tr> | |
| 602 | <tr><td>a heading</td><td>sets tags (see <a href="05-todos-and-tags.html">TODOs and tags</a>)</td></tr> | |
| 603 | <tr><td>a list item</td><td>toggles its checkbox, repairs the list and updates cookies</td></tr> | |
| 604 | <tr><td>a <code class="verbatim">#+KEYWORD:</code> line</td><td>rereads the file's settings and <code class="verbatim">#+SETUPFILE</code></td></tr> | |
| 605 | <tr><td>a property drawer</td><td>runs Property Action</td></tr> | |
| 606 | </tbody> | |
| 607 | </table> | |
| 608 | <p>Elsewhere it reports that it can do nothing useful.</p> | |
| 609 | <p>In the Doom preset, <code class="verbatim">RET</code> in normal state runs Doom's <code class="verbatim">+org/dwim-at-point</code> instead. It follows a link, recalculates a table with formulas or aligns one without, runs a src block, toggles an item's checkbox, or on a heading switches between the first TODO and first done keyword of its sequence.</p> | |
| 610 | <h2 id="speed-keys">Speed keys</h2> | |
| 611 | <p>With <code class="verbatim">org-use-speed-commands</code> set to <code class="verbatim">true</code> in <code class="verbatim">config.toml</code>, single keys run commands when the caret is at the very start of a heading line, before the stars. These are Org's <code class="verbatim">org-speed-commands</code>; the structure ones are:</p> | |
| 612 | <table> | |
| 613 | <thead> | |
| 614 | <tr><th>Key</th><th>Command</th><th>Key</th><th>Command</th></tr> | |
| 615 | </thead> | |
| 616 | <tbody> | |
| 617 | <tr><td><code class="verbatim">n</code></td><td>Next Heading</td><td><code class="verbatim">U</code></td><td>Move Subtree Up</td></tr> | |
| 618 | <tr><td><code class="verbatim">p</code></td><td>Previous Heading</td><td><code class="verbatim">D</code></td><td>Move Subtree Down</td></tr> | |
| 619 | <tr><td><code class="verbatim">f</code></td><td>Next Heading at Same Level</td><td><code class="verbatim">r</code></td><td>Demote Heading</td></tr> | |
| 620 | <tr><td><code class="verbatim">b</code></td><td>Previous Heading at Same Level</td><td><code class="verbatim">l</code></td><td>Promote Heading</td></tr> | |
| 621 | <tr><td><code class="verbatim">u</code></td><td>Up to Parent Heading</td><td><code class="verbatim">R</code></td><td>Demote Subtree</td></tr> | |
| 622 | <tr><td><code class="verbatim">j</code></td><td>Go to Heading…</td><td><code class="verbatim">L</code></td><td>Promote Subtree</td></tr> | |
| 623 | <tr><td><code class="verbatim">s</code></td><td>Narrow to Subtree or Widen</td><td><code class="verbatim">i</code></td><td>Insert Heading After Subtree</td></tr> | |
| 624 | <tr><td><code class="verbatim">k</code></td><td>Cut Subtree</td><td><code class="verbatim">^</code></td><td>Sort Entries</td></tr> | |
| 625 | <tr><td><code class="verbatim">@</code></td><td>Mark Subtree</td><td><code class="verbatim">w</code></td><td>Refile…</td></tr> | |
| 626 | <tr><td><code class="verbatim">#</code></td><td>Toggle COMMENT</td><td><code class="verbatim">a</code></td><td>Archive Subtree</td></tr> | |
| 627 | </tbody> | |
| 628 | </table> | |
| 629 | <p>The full list is in <a href="03-keys.html">Keys</a>.</p> | |
| 630 | <h2 id="not-supported">Not supported</h2> | |
| 631 | <p>These Org structure features are not in Orgstar:</p> | |
| 632 | <ul> | |
| 633 | <li><code class="verbatim">org-insert-drawer</code>, <code class="verbatim">org-copy</code> (refile a copy) and <code class="verbatim">org-refile</code> with a prefix (jump to a target).</li> | |
| 634 | <li>Editing values in column view, and writing summaries from it; the <code class="verbatim">columnview</code> dynamic block does write summaries.</li> | |
| 635 | <li>The <code class="verbatim">ORDERED</code> property, radio lists and timer list items in the list commands.</li> | |
| 636 | <li><code class="verbatim">S-<left></code> and <code class="verbatim">S-<right></code> to cycle bullets on an item; use <code class="verbatim">C-c -</code>.</li> | |
| 637 | <li><code class="verbatim">org-drag-element</code> (<code class="verbatim">M-<up></code> and <code class="verbatim">M-<down></code> on paragraphs).</li> | |
| 638 | <li>Custom <code class="verbatim">org-structure-template-alist</code>, <code class="verbatim">org-refile-targets</code>, <code class="verbatim">org-archive-location</code> and <code class="verbatim">org-use-property-inheritance</code>.</li> | |
| 639 | </ul> | |
| 640 | </main> | |
| 641 | <footer class="site"> | |
| 642 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 643 | </footer> | |
| 644 | </body> | |
| 645 | </html> | |
| \ No newline at end of file | ||
guide/05-todos-and-tags.html added +316
| @@ -0,0 +1,316 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>TODOs and tags · Orgstar</title> | |
| 7 | <meta name="description" content="TODO keywords, state logging, priorities, tags and progress cookies in Orgstar."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>TODOs and tags</h1> | |
| 24 | <p class="lede">Mark headings as tasks, record when their state changes, rank them, and label them with tags.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#keywords">keywords</a> | |
| 29 | <ul> | |
| 30 | <li><a href="#the-default-keywords">The default keywords</a></li> | |
| 31 | <li><a href="#keywords-in-the-file">Keywords in the file</a></li> | |
| 32 | <li><a href="#keyword-options">Keyword options</a></li> | |
| 33 | </ul></li> | |
| 34 | <li><a href="#changing-the-state">Changing the state</a> | |
| 35 | <ul> | |
| 36 | <li><a href="#cycling">Cycling</a></li> | |
| 37 | <li><a href="#fast-selection">Fast selection</a></li> | |
| 38 | <li><a href="#inserting-a-todo-heading">Inserting a TODO heading</a></li> | |
| 39 | <li><a href="#dependencies">Dependencies</a></li> | |
| 40 | </ul></li> | |
| 41 | <li><a href="#logging-state-changes">Logging state changes</a> | |
| 42 | <ul> | |
| 43 | <li><a href="#closed">CLOSED</a></li> | |
| 44 | <li><a href="#state-notes">State notes</a></li> | |
| 45 | <li><a href="#the-logbook-drawer">The LOGBOOK drawer</a></li> | |
| 46 | <li><a href="#where-the-settings-come-from">Where the settings come from</a></li> | |
| 47 | </ul></li> | |
| 48 | <li><a href="#priorities">Priorities</a></li> | |
| 49 | <li><a href="#tags">Tags</a> | |
| 50 | <ul> | |
| 51 | <li><a href="#setting-tags">Setting tags</a></li> | |
| 52 | <li><a href="#fast-tag-selection">Fast tag selection</a></li> | |
| 53 | <li><a href="#inheritance">Inheritance</a></li> | |
| 54 | <li><a href="#alignment">Alignment</a></li> | |
| 55 | </ul></li> | |
| 56 | <li><a href="#progress-on-child-tasks">Progress on child tasks</a></li> | |
| 57 | <li><a href="#related-settings">Related settings</a></li> | |
| 58 | </ul> | |
| 59 | </nav> | |
| 60 | <h2 id="keywords"><span class="todo TODO">TODO</span> keywords</h2> | |
| 61 | <p>A heading becomes a task when its first word after the stars is a TODO keyword:</p> | |
| 62 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Write the quarterly report | |
| 63 | </span><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">DONE</span> Book the venue</span></span></code></pre> | |
| 64 | <p>Keywords come in sequences. Each sequence has active keywords, a <code class="verbatim">|</code>, and done keywords. A keyword after the <code class="verbatim">|</code> counts as done for logging, statistics cookies, repeating tasks and the agenda.</p> | |
| 65 | <h3 id="the-default-keywords">The default keywords</h3> | |
| 66 | <p>Files without a <code class="verbatim">#+TODO</code> line use the keywords in Settings ▸ Editing ▸ Default TODO keywords, which is the <code class="verbatim">org-todo-keywords</code> key in <code class="verbatim">config.toml</code>. The default is:</p> | |
| 67 | <pre><code class="language-org highlight"><span class="text org">TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) | DONE(d) KILL(k)</span></code></pre> | |
| 68 | <p>The value uses <code class="verbatim">#+TODO</code> syntax. To define more than one sequence, put one per line (<code class="verbatim">\n</code> in <code class="verbatim">config.toml</code>). Orgstar reads this setting at launch, so a change takes effect after you restart the app. See <a href="13-configuration.html">Configuration</a> for the file itself and for keyword colors under <code class="verbatim">[theme.todo]</code>.</p> | |
| 69 | <h3 id="keywords-in-the-file">Keywords in the file</h3> | |
| 70 | <p>A file can set its own keywords, which replace the default ones for that file:</p> | |
| 71 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TODO:</span><span class="string unquoted org"> TODO NEXT WAIT | DONE CANCELED</span> | |
| 72 | <span class="keyword other keyword org">#+TODO:</span><span class="string unquoted org"> BUG(b) | FIXED(f)</span> | |
| 73 | <span class="keyword other keyword org">#+SEQ_TODO:</span><span class="string unquoted org"> DRAFT REVIEW | PUBLISHED</span> | |
| 74 | <span class="keyword other keyword org">#+TYP_TODO:</span><span class="string unquoted org"> ALICE BOB | DONE</span></span></code></pre> | |
| 75 | <ul> | |
| 76 | <li>Each line is one sequence. <code class="verbatim">#+SEQ_TODO</code> means the same as <code class="verbatim">#+TODO</code>.</li> | |
| 77 | <li>Without a <code class="verbatim">|</code>, the last word is the done keyword.</li> | |
| 78 | <li><code class="verbatim">#+TYP_TODO</code> marks a sequence of types (<code class="verbatim">org-todo-interpretation</code> <code class="verbatim">type</code>). Cycling with <code class="verbatim">C-c C-t</code> from a type keyword goes to the sequence's first done keyword (see <em>Cycling</em>), and a repeating entry returns to the keyword it had before it was done, instead of to the first keyword of the sequence.</li> | |
| 79 | <li>The order of sequences is the order Org uses: <code class="verbatim">#+TYP_TODO</code> lines first, then <code class="verbatim">#+TODO</code>, then <code class="verbatim">#+SEQ_TODO</code>.</li> | |
| 80 | <li>Lines inside blocks are ignored. Lines from a <code class="verbatim">#+SETUPFILE</code> count as if they came first in the file.</li> | |
| 81 | </ul> | |
| 82 | <p>Edits to these lines take effect as you type. If the keywords come from a setup file you changed, press <code class="verbatim">C-c C-c</code> on any <code class="verbatim">#+</code> keyword line to read the setup files again (<code class="verbatim">org-mode-restart</code>).</p> | |
| 83 | <h3 id="keyword-options">Keyword options</h3> | |
| 84 | <p>The parentheses after a keyword hold a fast-selection key and logging flags, as in Org:</p> | |
| 85 | <table> | |
| 86 | <thead> | |
| 87 | <tr><th>Form</th><th>Meaning</th></tr> | |
| 88 | </thead> | |
| 89 | <tbody> | |
| 90 | <tr><td><code class="verbatim">WAIT(w)</code></td><td>Fast-selection key <code class="verbatim">w</code></td></tr> | |
| 91 | <tr><td><code class="verbatim">WAIT(w!)</code></td><td>Key <code class="verbatim">w</code>, record the time when entering the state</td></tr> | |
| 92 | <tr><td><code class="verbatim">WAIT(w@)</code></td><td>Key <code class="verbatim">w</code>, ask for a note when entering the state</td></tr> | |
| 93 | <tr><td><code class="verbatim">WAIT(w@/!)</code></td><td>Note when entering, time when leaving to a state that logs nothing</td></tr> | |
| 94 | <tr><td><code class="verbatim">WAIT(@/!)</code></td><td>No key, same logging</td></tr> | |
| 95 | </tbody> | |
| 96 | </table> | |
| 97 | <p>Logging is described under "Logging state changes" below.</p> | |
| 98 | <h2 id="changing-the-state">Changing the state</h2> | |
| 99 | <table> | |
| 100 | <thead> | |
| 101 | <tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th></tr> | |
| 102 | </thead> | |
| 103 | <tbody> | |
| 104 | <tr><td>Cycle TODO State</td><td><code class="verbatim">org-todo</code></td><td><code class="verbatim">C-c C-t</code></td><td>⌃⌘T</td><td><code class="verbatim">SPC m t</code></td></tr> | |
| 105 | <tr><td>Next TODO Keyword</td><td><code class="verbatim">org-shiftright</code></td><td><code class="verbatim">S-<right></code></td><td>⌃⇧⌘→</td><td></td></tr> | |
| 106 | <tr><td>Previous TODO Keyword</td><td><code class="verbatim">org-shiftleft</code></td><td><code class="verbatim">S-<left></code></td><td>⌃⇧⌘←</td><td></td></tr> | |
| 107 | </tbody> | |
| 108 | </table> | |
| 109 | <p><code class="verbatim">S-<right></code> and <code class="verbatim">S-<left></code> act on the TODO keyword when the caret is on a heading line and not on a timestamp. In the Doom preset they also work in normal and insert state, and <code class="verbatim">C-S-l</code> and <code class="verbatim">C-S-h</code> do the same. The Mac preset's <code class="verbatim">⌃⇧⌘→</code> and <code class="verbatim">⌃⇧⌘←</code> act on the keyword when the caret is on a heading line.</p> | |
| 110 | <p>With speed commands on (<code class="verbatim">org-use-speed-commands</code>), <code class="verbatim">t</code> at the start of a heading line runs Cycle TODO State.</p> | |
| 111 | <h3 id="cycling">Cycling</h3> | |
| 112 | <p><code class="verbatim">C-c C-t</code> behaves in one of two ways:</p> | |
| 113 | <ul> | |
| 114 | <li>If any keyword in the file has a fast-selection key, it opens fast selection (<code class="verbatim">org-use-fast-todo-selection</code> <code class="verbatim">auto</code>). The default keywords all have keys, so this is what you get unless you define keywords without keys.</li> | |
| 115 | <li>Otherwise it cycles: no keyword, then each keyword of the first sequence in order, then no keyword again. From a keyword in another sequence it moves through that sequence and then to no keyword. From a <code class="verbatim">#+TYP_TODO</code> keyword it goes straight to the sequence's first done keyword, as Org does; pressing <code class="verbatim">C-c C-t</code> again right away moves to the next type keyword instead. In the iOS app and the agenda, each press on a type keyword goes to the done keyword.</li> | |
| 116 | </ul> | |
| 117 | <p><code class="verbatim">S-<right></code> and <code class="verbatim">S-<left></code> never use fast selection. They step through every keyword of every sequence in order, then to no keyword, and wrap around.</p> | |
| 118 | <h3 id="fast-selection">Fast selection</h3> | |
| 119 | <p>Fast selection appears in the echo area under the editor. Each sequence is shown on its own row in braces, with the key in brackets before each keyword.</p> | |
| 120 | <table> | |
| 121 | <thead> | |
| 122 | <tr><th>Key</th><th>Effect</th></tr> | |
| 123 | </thead> | |
| 124 | <tbody> | |
| 125 | <tr><td>a keyword's key</td><td>Set that keyword</td></tr> | |
| 126 | <tr><td><code class="verbatim">SPC</code></td><td>Remove the keyword</td></tr> | |
| 127 | <tr><td><code class="verbatim">Esc</code>, <code class="verbatim">C-g</code>, any other key</td><td>Quit without changing anything</td></tr> | |
| 128 | </tbody> | |
| 129 | </table> | |
| 130 | <p>Keywords without a key in parentheses get one: the first letter of the keyword not already taken (a leading <code class="verbatim">@</code> is skipped), and failing that a digit counting up from <code class="verbatim">0</code>. When two sequences use the same key, the key picks the keyword from the current keyword's sequence.</p> | |
| 131 | <h3 id="inserting-a-todo-heading">Inserting a TODO heading</h3> | |
| 132 | <p>Insert TODO Heading (<code class="verbatim">org-insert-todo-heading</code>, <code class="verbatim">M-S-RET</code> in Emacs and Doom, ⌘⇧↩ on Mac) adds a heading with the current entry's keyword when that keyword is active, and with the first keyword otherwise. See <a href="04-outlines.html">Outlines</a>.</p> | |
| 133 | <h3 id="dependencies">Dependencies</h3> | |
| 134 | <p>Orgstar does not enforce TODO dependencies. <code class="verbatim">org-enforce-todo-dependencies</code> and the <code class="verbatim">ORDERED</code> and <code class="verbatim">NOBLOCKING</code> properties have no effect: a parent can be marked done while its children are open. The property names are offered in completion only so that files written for Emacs keep working there.</p> | |
| 135 | <h2 id="logging-state-changes">Logging state changes</h2> | |
| 136 | <p>Orgstar logs state changes as <code class="verbatim">org-todo</code> does in Org 9.8.</p> | |
| 137 | <h3 id="closed">CLOSED</h3> | |
| 138 | <p>When <code class="verbatim">org-log-done</code> is <code class="verbatim">time</code> and an entry moves from an active keyword to a done one, Orgstar adds a <code class="verbatim">CLOSED</code> stamp to its planning line:</p> | |
| 139 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">DONE</span> Book the venue | |
| 140 | </span>CLOSED: <span class="constant other timestamp org">[2026-10-07 Wed 14:32]</span></span></code></pre> | |
| 141 | <p>With <code class="verbatim">note</code>, it also asks for a closing note. Moving the entry back to an active keyword, or removing the keyword, removes <code class="verbatim">CLOSED</code>. This happens only while some logging is on (<code class="verbatim">org-log-done</code> or a keyword with <code class="verbatim">!</code> or <code class="verbatim">@</code>); with no logging at all, an existing <code class="verbatim">CLOSED</code> stamp stays.</p> | |
| 142 | <h3 id="state-notes">State notes</h3> | |
| 143 | <p>A keyword with <code class="verbatim">!</code> or <code class="verbatim">@</code> records a note when the entry enters it, and the part after <code class="verbatim">/</code> records one when the entry leaves it for a state that logs nothing on entry. <code class="verbatim">!</code> records the time; <code class="verbatim">@</code> asks for a note in the echo area:</p> | |
| 144 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TODO:</span><span class="string unquoted org"> TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@)</span> | |
| 145 | ||
| 146 | <span class="markup heading org"><span class="punctuation definition heading org">*</span> WAIT Call the supplier | |
| 147 | </span><span class="punctuation definition list org">- </span>State "WAIT" from "TODO" <span class="constant other timestamp org">[2026-10-07 Wed 09:15]</span> \\ | |
| 148 | Left a message, waiting for a reply.</span></code></pre> | |
| 149 | <p>Notes go first in the entry, after the planning line and property drawer, newest first (<code class="verbatim">org-log-states-order-reversed</code> <code class="verbatim">t</code>). The note text is indented under the item; lines starting with <code class="verbatim">#</code> and a space are dropped. If the keyword's own flag and <code class="verbatim">org-log-done</code> both apply, the keyword's flag wins.</p> | |
| 150 | <p>The headings are Org's default <code class="verbatim">org-log-note-headings</code>:</p> | |
| 151 | <table> | |
| 152 | <thead> | |
| 153 | <tr><th>Event</th><th>Note heading</th></tr> | |
| 154 | </thead> | |
| 155 | <tbody> | |
| 156 | <tr><td>State change</td><td><code class="verbatim">State "DONE" from "TODO" [timestamp]</code></td></tr> | |
| 157 | <tr><td>Closing note</td><td><code class="verbatim">CLOSING NOTE [timestamp]</code></td></tr> | |
| 158 | <tr><td>Rescheduled</td><td><code class="verbatim">Rescheduled from "[old date]" on [timestamp]</code></td></tr> | |
| 159 | <tr><td>Schedule removed</td><td><code class="verbatim">Not scheduled, was "[old date]" on [timestamp]</code></td></tr> | |
| 160 | <tr><td>New deadline</td><td><code class="verbatim">New deadline from "[old date]" on [timestamp]</code></td></tr> | |
| 161 | <tr><td>Deadline removed</td><td><code class="verbatim">Removed deadline, was "[old date]" on [timestamp]</code></td></tr> | |
| 162 | </tbody> | |
| 163 | </table> | |
| 164 | <p>Rescheduling and deadline notes are covered in <a href="06-dates-and-clocking.html">Dates, scheduling and clocking</a>. Orgstar has no command to add a free note to an entry (<code class="verbatim">org-add-note</code>).</p> | |
| 165 | <h3 id="the-logbook-drawer">The LOGBOOK drawer</h3> | |
| 166 | <p>With <code class="verbatim">org-log-into-drawer</code> set to a drawer name, notes go at the top of that drawer, which Orgstar creates when it is missing:</p> | |
| 167 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">DONE</span> Book the venue | |
| 168 | </span>CLOSED: <span class="constant other timestamp org">[2026-10-07 Wed 14:32]</span> | |
| 169 | :LOGBOOK: | |
| 170 | <span class="punctuation definition list org">- </span>State "DONE" from "TODO" <span class="constant other timestamp org">[2026-10-07 Wed 14:32]</span> | |
| 171 | :END:</span></code></pre> | |
| 172 | <p>In <code class="verbatim">config.toml</code>, <code class="verbatim">"LOGBOOK"</code> is the equivalent of Emacs's <code class="verbatim">t</code>, and <code class="verbatim">""</code> (the default) means no drawer. Clock lines always go into a <code class="verbatim">LOGBOOK</code> drawer, whatever this setting says.</p> | |
| 173 | <h3 id="where-the-settings-come-from">Where the settings come from</h3> | |
| 174 | <p>Later sources override earlier ones:</p> | |
| 175 | <ol> | |
| 176 | <li><code class="verbatim">config.toml</code>: <code class="verbatim">org-log-done</code>, <code class="verbatim">org-log-reschedule</code>, <code class="verbatim">org-log-redeadline</code> (each <code class="verbatim">nil</code>, <code class="verbatim">time</code> or <code class="verbatim">note</code>, default <code class="verbatim">nil</code>) and <code class="verbatim">org-log-into-drawer</code> (default <code class="verbatim">""</code>). These have no control in the Settings window. <code class="verbatim">org-log-repeat</code> is always <code class="verbatim">time</code> unless the file changes it.</li> | |
| 177 | <li>Keyword flags such as <code class="verbatim">DONE(d!)</code>.</li> | |
| 178 | <li><code class="verbatim">#+STARTUP</code> words in the file or its setup files.</li> | |
| 179 | <li>The <code class="verbatim">LOGGING</code> property, inherited from ancestors.</li> | |
| 180 | <li>The <code class="verbatim">LOG_INTO_DRAWER</code> property, inherited from ancestors: <code class="verbatim">t</code> for <code class="verbatim">LOGBOOK</code>, <code class="verbatim">nil</code> for none, or a drawer name.</li> | |
| 181 | </ol> | |
| 182 | <table> | |
| 183 | <thead> | |
| 184 | <tr><th><code class="verbatim">#+STARTUP</code> word</th><th>Effect</th></tr> | |
| 185 | </thead> | |
| 186 | <tbody> | |
| 187 | <tr><td><code class="verbatim">logdone</code>, <code class="verbatim">lognotedone</code>, <code class="verbatim">nologdone</code></td><td><code class="verbatim">org-log-done</code> <code class="verbatim">time</code>, <code class="verbatim">note</code>, <code class="verbatim">nil</code></td></tr> | |
| 188 | <tr><td><code class="verbatim">logrepeat</code>, <code class="verbatim">lognoterepeat</code>, <code class="verbatim">nologrepeat</code></td><td><code class="verbatim">org-log-repeat</code> <code class="verbatim">time</code>, <code class="verbatim">note</code>, <code class="verbatim">nil</code></td></tr> | |
| 189 | <tr><td><code class="verbatim">logreschedule</code>, <code class="verbatim">lognotereschedule</code>, <code class="verbatim">nologreschedule</code></td><td><code class="verbatim">org-log-reschedule</code></td></tr> | |
| 190 | <tr><td><code class="verbatim">logredeadline</code>, <code class="verbatim">lognoteredeadline</code>, <code class="verbatim">nologredeadline</code></td><td><code class="verbatim">org-log-redeadline</code></td></tr> | |
| 191 | <tr><td><code class="verbatim">logdrawer</code>, <code class="verbatim">nologdrawer</code></td><td><code class="verbatim">org-log-into-drawer</code> <code class="verbatim">LOGBOOK</code> or none</td></tr> | |
| 192 | </tbody> | |
| 193 | </table> | |
| 194 | <p>A <code class="verbatim">LOGGING</code> property (<code class="verbatim">org-local-logging</code>) replaces the done, repeat and per-keyword settings for its subtree. It takes the <code class="verbatim">logdone</code> and <code class="verbatim">logrepeat</code> words above and keyword specifications such as <code class="verbatim">WAIT(@)</code>; <code class="verbatim">nil</code> turns them all off:</p> | |
| 195 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Errands | |
| 196 | </span>:PROPERTIES: | |
| 197 | :LOGGING: DONE(!) WAIT(@) logrepeat | |
| 198 | :LOG<span class="markup underline org">_INTO_</span>DRAWER: NOTES | |
| 199 | :END:</span></code></pre> | |
| 200 | <h2 id="priorities">Priorities</h2> | |
| 201 | <p>A priority cookie goes after the keyword:</p> | |
| 202 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> <span class="constant other priority org">[#A]</span> Renew the passport</span></span></code></pre> | |
| 203 | <p>The range is <code class="verbatim">A</code> (highest) to <code class="verbatim">C</code> (lowest), with <code class="verbatim">B</code> as the default. A file can change it with <code class="verbatim">#+PRIORITIES: highest lowest default</code>, using letters or numbers:</p> | |
| 204 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+PRIORITIES:</span><span class="string unquoted org"> A E C</span> | |
| 205 | <span class="keyword other keyword org">#+PRIORITIES:</span><span class="string unquoted org"> 1 10 5</span></span></code></pre> | |
| 206 | <table> | |
| 207 | <thead> | |
| 208 | <tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th></tr> | |
| 209 | </thead> | |
| 210 | <tbody> | |
| 211 | <tr><td>Set Priority…</td><td><code class="verbatim">org-priority</code></td><td><code class="verbatim">C-c ,</code></td><td>⌃⌘,</td><td><code class="verbatim">SPC m p p</code></td></tr> | |
| 212 | <tr><td>Raise Priority</td><td><code class="verbatim">org-priority-up</code></td><td><code class="verbatim">S-<up></code></td><td>⌃⌘↑</td><td><code class="verbatim">SPC m p u</code></td></tr> | |
| 213 | <tr><td>Lower Priority</td><td><code class="verbatim">org-priority-down</code></td><td><code class="verbatim">S-<down></code></td><td>⌃⌘↓</td><td><code class="verbatim">SPC m p d</code></td></tr> | |
| 214 | </tbody> | |
| 215 | </table> | |
| 216 | <p><code class="verbatim">S-<up></code> and <code class="verbatim">S-<down></code> act on the priority when the caret is on a heading line and not on a timestamp; Doom also binds <code class="verbatim">C-S-k</code> and <code class="verbatim">C-S-j</code>.</p> | |
| 217 | <ul> | |
| 218 | <li>Set Priority shows the priorities with their keys (lowercase letters, or the digits of a numeric range) and <code class="verbatim">SPC</code> to remove the cookie. When the lowest numeric priority is 10 or more, it asks you to type the number instead.</li> | |
| 219 | <li>Raise and Lower start at the default priority when the heading has none (<code class="verbatim">org-priority-start-cycle-with-default</code>). Going past the highest or lowest priority removes the cookie.</li> | |
| 220 | <li>With speed commands on, <code class="verbatim">,</code> runs Set Priority, <code class="verbatim">1</code>, <code class="verbatim">2</code> and <code class="verbatim">3</code> set <code class="verbatim">A</code>, <code class="verbatim">B</code> and <code class="verbatim">C</code>, and <code class="verbatim">0</code> removes the priority.</li> | |
| 221 | </ul> | |
| 222 | <p>The agenda sorts by priority; see <a href="07-agenda.html">The agenda</a>.</p> | |
| 223 | <h2 id="tags">Tags</h2> | |
| 224 | <p>Tags go at the end of a heading, between colons:</p> | |
| 225 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Order parts <span class="entity name tag org">:work:urgent:</span></span></span></code></pre> | |
| 226 | <p>A tag consists of letters, digits, <code class="verbatim">_</code>, <code class="verbatim">@</code>, <code class="verbatim">#</code> and <code class="verbatim">%</code>.</p> | |
| 227 | <h3 id="setting-tags">Setting tags</h3> | |
| 228 | <table> | |
| 229 | <thead> | |
| 230 | <tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th></tr> | |
| 231 | </thead> | |
| 232 | <tbody> | |
| 233 | <tr><td>Set Tags</td><td><code class="verbatim">org-set-tags-command</code></td><td><code class="verbatim">C-c C-q</code></td><td>⌃⌘G</td><td><code class="verbatim">SPC m q</code></td></tr> | |
| 234 | </tbody> | |
| 235 | </table> | |
| 236 | <p><code class="verbatim">C-c C-c</code> (Mac <code class="verbatim">⌃⌘X</code>) on a heading line also runs Set Tags, and so does <code class="verbatim">:</code> as a speed command.</p> | |
| 237 | <p>Without fast selection (see below), Set Tags asks for the tags in the echo area, starting with the current ones. Completion offers the tags in the file's <code class="verbatim">#+TAGS</code> lines, or, without those, every tag used in the file and its <code class="verbatim">#+FILETAGS</code>, and in both cases the tags used across your folders. You can type tags that are not offered. Spaces, commas and colons all separate tags; an empty answer removes all tags.</p> | |
| 238 | <p>Setting tags on the text before the first heading (file tags) is not supported; edit the <code class="verbatim">#+FILETAGS</code> line directly.</p> | |
| 239 | <p>Typing <code class="verbatim">:</code> at the end of a heading line also completes tags: from the <code class="verbatim">#+TAGS</code> lines when the file has any, and otherwise from the file's tags and those used across your folders. Tags the heading already has are left out. See <a href="02-the-editor.html">The editor</a> for how completion works.</p> | |
| 240 | <h3 id="fast-tag-selection">Fast tag selection</h3> | |
| 241 | <p>When a <code class="verbatim">#+TAGS</code> line gives at least one tag a key, Set Tags opens fast selection (<code class="verbatim">org-fast-tag-selection</code>):</p> | |
| 242 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TAGS:</span><span class="string unquoted org"> { @office(o) @home(h) @errand(e) } laptop(l) phone(p)</span> | |
| 243 | <span class="keyword other keyword org">#+TAGS:</span><span class="string unquoted org"> [ Project : alpha beta ]</span></span></code></pre> | |
| 244 | <table> | |
| 245 | <thead> | |
| 246 | <tr><th>Key</th><th>Effect</th></tr> | |
| 247 | </thead> | |
| 248 | <tbody> | |
| 249 | <tr><td>a tag's key</td><td>Toggle that tag</td></tr> | |
| 250 | <tr><td><code class="verbatim">SPC</code></td><td>Remove all tags</td></tr> | |
| 251 | <tr><td><code class="verbatim">TAB</code></td><td>Type a tag by name, then <code class="verbatim">RET</code></td></tr> | |
| 252 | <tr><td><code class="verbatim">RET</code></td><td>Apply the selection</td></tr> | |
| 253 | <tr><td><code class="verbatim">q</code></td><td>Quit, unless a tag uses <code class="verbatim">q</code> as its key</td></tr> | |
| 254 | <tr><td><code class="verbatim">Esc</code>, <code class="verbatim">C-g</code></td><td>Quit</td></tr> | |
| 255 | </tbody> | |
| 256 | </table> | |
| 257 | <p>The view shows the inherited tags, the current selection, and each tag with its key, in the rows and groups of the <code class="verbatim">#+TAGS</code> lines.</p> | |
| 258 | <ul> | |
| 259 | <li>Tags between <code class="verbatim">{</code> and <code class="verbatim">}</code> exclude each other: selecting one removes the others in the group.</li> | |
| 260 | <li>Tags between <code class="verbatim">[</code> and <code class="verbatim">]</code>, with <code class="verbatim">:</code> after the first, form a group tag. The selection shows them as written; they do not change how keys act. Searching by group tag is part of <a href="07-agenda.html">The agenda</a>.</li> | |
| 261 | <li>Tags without a key get one: their first letter if it is free, otherwise the next free character from <code class="verbatim">a–z</code>, <code class="verbatim">A–Z</code> and <code class="verbatim">{|}~</code>.</li> | |
| 262 | <li>The selected tags are written in the order of the <code class="verbatim">#+TAGS</code> lines, followed by any others.</li> | |
| 263 | </ul> | |
| 264 | <p><code class="verbatim">#+TAGS</code> lines come only from the file and its setup files. Orgstar has no global tag list (<code class="verbatim">org-tag-alist</code>); the workspace's tags are used for completion only.</p> | |
| 265 | <h3 id="inheritance">Inheritance</h3> | |
| 266 | <p>An entry inherits the tags of its ancestors and the file's <code class="verbatim">#+FILETAGS</code> (<code class="verbatim">org-use-tag-inheritance</code> <code class="verbatim">t</code>). Fast selection lists inherited tags separately. Agenda matches and clock tables with <code class="verbatim">:tags t</code> use the inherited tags too. Orgstar has no setting to limit inheritance (<code class="verbatim">org-tags-exclude-from-inheritance</code>).</p> | |
| 267 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+FILETAGS:</span><span class="string unquoted org"> :home:</span> | |
| 268 | ||
| 269 | <span class="markup heading org"><span class="punctuation definition heading org">*</span> Garden <span class="entity name tag org">:outdoor: | |
| 270 | </span></span><span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">TODO</span> Prune the roses</span></span></code></pre> | |
| 271 | <p>Here "Prune the roses" has the tags <code class="verbatim">home</code> and <code class="verbatim">outdoor</code> through inheritance.</p> | |
| 272 | <h3 id="alignment">Alignment</h3> | |
| 273 | <p>Orgstar aligns tags whenever it changes a heading line: setting tags, changing the TODO keyword or the priority, and updating a statistics cookie. The column is <code class="verbatim">org-tags-column</code>, under Settings ▸ Editing ▸ Tags:</p> | |
| 274 | <table> | |
| 275 | <thead> | |
| 276 | <tr><th>Value</th><th>Placement</th></tr> | |
| 277 | </thead> | |
| 278 | <tbody> | |
| 279 | <tr><td><code class="verbatim">-77</code></td><td>Tags end at column 77 (the default)</td></tr> | |
| 280 | <tr><td><code class="verbatim">0</code></td><td>One space after the title</td></tr> | |
| 281 | <tr><td>negative N</td><td>Tags end at column N</td></tr> | |
| 282 | <tr><td>positive N</td><td>Tags start at column N</td></tr> | |
| 283 | </tbody> | |
| 284 | </table> | |
| 285 | <p>The Settings window offers <code class="verbatim">-77</code> and <code class="verbatim">0</code>; other values go in <code class="verbatim">config.toml</code>. Columns are counted as Emacs displays the line, so links count as their description and, when <code class="verbatim">org-hide-emphasis-markers</code> is on, emphasis markers do not count. A heading always keeps at least one space before its tags.</p> | |
| 286 | <h2 id="progress-on-child-tasks">Progress on child tasks</h2> | |
| 287 | <p>A <code class="verbatim">[/]</code> or <code class="verbatim">[%]</code> cookie in a heading shows how many of its children are done:</p> | |
| 288 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Move house [1/3] | |
| 289 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">DONE</span> Hire a van | |
| 290 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">TODO</span> Pack the kitchen | |
| 291 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">TODO</span> Forward the mail</span></span></code></pre> | |
| 292 | <p>Orgstar updates the cookie whenever a child's TODO keyword changes (<code class="verbatim">org-update-parent-todo-statistics</code>, with <code class="verbatim">org-hierarchical-todo-statistics</code> <code class="verbatim">t</code>). Only direct children with a TODO keyword count; children without one are ignored. <code class="verbatim">C-c C-c</code> on a cookie updates it by hand.</p> | |
| 293 | <p>The <code class="verbatim">COOKIE_DATA</code> property changes what the parent's cookie counts:</p> | |
| 294 | <ul> | |
| 295 | <li><code class="verbatim">recursive</code> counts every descendant with a keyword, and a change updates the cookies of every ancestor up to the heading that sets the property. Without it, only the direct parent's cookie is updated.</li> | |
| 296 | <li><code class="verbatim">checkbox</code> makes the cookie count checkboxes in the entry's lists instead of child tasks. Checkbox cookies are described in <a href="04-outlines.html">Outlines</a>.</li> | |
| 297 | </ul> | |
| 298 | <h2 id="related-settings">Related settings</h2> | |
| 299 | <table> | |
| 300 | <thead> | |
| 301 | <tr><th>Setting</th><th>Where</th><th>Default</th></tr> | |
| 302 | </thead> | |
| 303 | <tbody> | |
| 304 | <tr><td><code class="verbatim">org-todo-keywords</code></td><td>Settings ▸ Editing, <code class="verbatim">config.toml</code></td><td>See "The default keywords" above</td></tr> | |
| 305 | <tr><td><code class="verbatim">org-log-done</code></td><td><code class="verbatim">config.toml</code></td><td><code class="verbatim">nil</code></td></tr> | |
| 306 | <tr><td><code class="verbatim">org-log-into-drawer</code></td><td><code class="verbatim">config.toml</code></td><td><code class="verbatim">""</code> (no drawer)</td></tr> | |
| 307 | <tr><td><code class="verbatim">org-tags-column</code></td><td>Settings ▸ Editing, <code class="verbatim">config.toml</code></td><td><code class="verbatim">-77</code></td></tr> | |
| 308 | <tr><td><code class="verbatim">org-use-speed-commands</code></td><td><code class="verbatim">config.toml</code></td><td><code class="verbatim">false</code></td></tr> | |
| 309 | </tbody> | |
| 310 | </table> | |
| 311 | </main> | |
| 312 | <footer class="site"> | |
| 313 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 314 | </footer> | |
| 315 | </body> | |
| 316 | </html> | |
| \ No newline at end of file | ||
guide/06-dates-and-clocking.html added +469
| @@ -0,0 +1,469 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Dates, scheduling and clocking · Orgstar</title> | |
| 7 | <meta name="description" content="Timestamps, the date prompt, SCHEDULED and DEADLINE, repeating tasks, effort, clocking, clock tables, habits and reminders in Orgstar."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Dates, scheduling and clocking</h1> | |
| 24 | <p class="lede">Put dates on entries, plan work with scheduled dates and deadlines, and record the time you spend.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#timestamps">Timestamps</a> | |
| 29 | <ul> | |
| 30 | <li><a href="#repeaters-and-warning-periods">Repeaters and warning periods</a></li> | |
| 31 | <li><a href="#diary-sexps">Diary sexps</a></li> | |
| 32 | </ul></li> | |
| 33 | <li><a href="#inserting-timestamps">Inserting timestamps</a></li> | |
| 34 | <li><a href="#the-date-prompt">The date prompt</a></li> | |
| 35 | <li><a href="#changing-dates">Changing dates</a></li> | |
| 36 | <li><a href="#scheduled-and-deadline">SCHEDULED and DEADLINE</a></li> | |
| 37 | <li><a href="#repeating-tasks">Repeating tasks</a></li> | |
| 38 | <li><a href="#effort">Effort</a></li> | |
| 39 | <li><a href="#clocking">Clocking</a> | |
| 40 | <ul> | |
| 41 | <li><a href="#clocking-in-and-out">Clocking in and out</a></li> | |
| 42 | <li><a href="#the-running-clock">The running clock</a></li> | |
| 43 | <li><a href="#recent-entries">Recent entries</a></li> | |
| 44 | <li><a href="#open-clocks">Open clocks</a></li> | |
| 45 | <li><a href="#idle-time">Idle time</a></li> | |
| 46 | <li><a href="#editing-clock-lines">Editing clock lines</a></li> | |
| 47 | </ul></li> | |
| 48 | <li><a href="#clock-summaries">Clock summaries</a> | |
| 49 | <ul> | |
| 50 | <li><a href="#the-inspector">The inspector</a></li> | |
| 51 | <li><a href="#the-clock-report-window">The clock report window</a></li> | |
| 52 | </ul></li> | |
| 53 | <li><a href="#clock-tables">Clock tables</a> | |
| 54 | <ul> | |
| 55 | <li><a href="#parameters">Parameters</a></li> | |
| 56 | </ul></li> | |
| 57 | <li><a href="#habits">Habits</a></li> | |
| 58 | <li><a href="#reminders">Reminders</a></li> | |
| 59 | </ul> | |
| 60 | </nav> | |
| 61 | <h2 id="timestamps">Timestamps</h2> | |
| 62 | <p>A timestamp is a date, optionally with a time, in angle brackets (active) or square brackets (inactive):</p> | |
| 63 | <pre><code class="language-org highlight"><span class="text org"><span class="constant other timestamp org"><2026-10-07 Wed></span> | |
| 64 | <span class="constant other timestamp org"><2026-10-07 Wed 14:30></span> | |
| 65 | <span class="constant other timestamp org"><2026-10-07 Wed 10:00-11:30></span> | |
| 66 | <span class="constant other timestamp org"><2026-10-07 Wed></span>--<span class="constant other timestamp org"><2026-10-09 Fri></span> | |
| 67 | <span class="constant other timestamp org">[2026-10-07 Wed 09:12]</span></span></code></pre> | |
| 68 | <ul> | |
| 69 | <li>Active timestamps put the entry on the agenda for that day. Inactive ones are records only.</li> | |
| 70 | <li><code class="verbatim">10:00-11:30</code> is a time range within one day. <code class="verbatim"><…>--<…></code> is a range of days; both ends must be of the same kind.</li> | |
| 71 | <li>Orgstar writes day names in English. When reading, it accepts a day name in any language, as Org does.</li> | |
| 72 | </ul> | |
| 73 | <h3 id="repeaters-and-warning-periods">Repeaters and warning periods</h3> | |
| 74 | <p>After the date and time, a timestamp can carry a repeater and a warning or delay:</p> | |
| 75 | <pre><code class="language-org highlight"><span class="text org"><span class="constant other timestamp org"><2026-10-07 Wed +1w></span> | |
| 76 | <span class="constant other timestamp org"><2026-10-07 Wed 08:00 ++1d></span> | |
| 77 | <span class="constant other timestamp org"><2026-10-07 Wed .+2w></span> | |
| 78 | <span class="constant other timestamp org"><2026-10-31 Sat -3d></span> | |
| 79 | <span class="constant other timestamp org"><2026-10-31 Sat +1m -5d></span> | |
| 80 | <span class="constant other timestamp org"><2026-10-07 Wed .+2d/4d></span></span></code></pre> | |
| 81 | <table> | |
| 82 | <thead> | |
| 83 | <tr><th>Element</th><th>Meaning</th></tr> | |
| 84 | </thead> | |
| 85 | <tbody> | |
| 86 | <tr><td><code class="verbatim">+1w</code></td><td>Repeat every week, counted from the date in the timestamp</td></tr> | |
| 87 | <tr><td><code class="verbatim">++1w</code></td><td>Repeat every week, moving the date past today when the task is done</td></tr> | |
| 88 | <tr><td><code class="verbatim">.+1w</code></td><td>Repeat one week after the day the task is done</td></tr> | |
| 89 | <tr><td><code class="verbatim">-3d</code></td><td>On a deadline, start warning 3 days before; on a scheduled date, hide it from the agenda until 3 days after</td></tr> | |
| 90 | <tr><td><code class="verbatim">--3d</code></td><td>As <code class="verbatim">-3d</code>, for the first occurrence only; it is dropped when the task repeats</td></tr> | |
| 91 | <tr><td><code class="verbatim">/4d</code></td><td>After a repeater, the longest interval a habit allows (see "Habits")</td></tr> | |
| 92 | </tbody> | |
| 93 | </table> | |
| 94 | <p>Units are <code class="verbatim">h</code> (hours), <code class="verbatim">d</code>, <code class="verbatim">w</code>, <code class="verbatim">m</code> and <code class="verbatim">y</code>. What happens when a repeating task is done is described under "Repeating tasks".</p> | |
| 95 | <h3 id="diary-sexps">Diary sexps</h3> | |
| 96 | <p>The agenda also reads <code class="verbatim"><%%(…)></code> timestamps and <code class="verbatim">%%(…)</code> lines with Emacs diary expressions such as <code class="verbatim">diary-float</code>, <code class="verbatim">diary-anniversary</code>, <code class="verbatim">diary-block</code> and <code class="verbatim">diary-cyclic</code>, and their <code class="verbatim">org-</code> counterparts. See <a href="07-agenda.html">The agenda</a> for the functions that are supported. Orgstar does not insert or edit these.</p> | |
| 97 | <h2 id="inserting-timestamps">Inserting timestamps</h2> | |
| 98 | <table> | |
| 99 | <thead> | |
| 100 | <tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th></tr> | |
| 101 | </thead> | |
| 102 | <tbody> | |
| 103 | <tr><td>Insert Timestamp</td><td><code class="verbatim">org-timestamp</code></td><td><code class="verbatim">C-c .</code></td><td>⌃⌘.</td><td><code class="verbatim">SPC m d t</code></td></tr> | |
| 104 | <tr><td>Insert Inactive Timestamp</td><td><code class="verbatim">org-timestamp-inactive</code></td><td><code class="verbatim">C-c !</code></td><td>⌃⌥⌘.</td><td><code class="verbatim">SPC m d T</code></td></tr> | |
| 105 | </tbody> | |
| 106 | </table> | |
| 107 | <p>Both ask for a date in the echo area (see "The date prompt"). With the caret on an existing timestamp, they replace it with the date you give, keep its repeater, and start from its date and time. In a range of days, the caret picks the end: with the caret between the two dashes of <code class="verbatim">--</code> or after them, the second timestamp is replaced and the prompt starts from its date; before that, the first. Run the command again right after inserting a timestamp to add a second one and make a range, <code class="verbatim"><…>--<…></code>; the second date starts from the timestamp at the caret.</p> | |
| 108 | <p>Org's prefix arguments are not available: to include the current time, type it, or use a relative time such as <code class="verbatim">+0h</code> (see below).</p> | |
| 109 | <h2 id="the-date-prompt">The date prompt</h2> | |
| 110 | <p>Every command that asks for a date shows the same prompt (<code class="verbatim">org-read-date</code>): a text field, the date the text reads as, and a month calendar.</p> | |
| 111 | <ul> | |
| 112 | <li>Type a date in any of the forms below. The line above the field shows the result, such as <code class="verbatim"><2026-10-09 Fri 15:00></code>, as you type; for an inactive timestamp it is in square brackets, <code class="verbatim">[2026-10-09 Fri 15:00]</code>.</li> | |
| 113 | <li>Click a day in the calendar to answer with that day. A time you typed is kept.</li> | |
| 114 | <li><code class="verbatim">S-<left></code> and <code class="verbatim">S-<right></code> in the field move the answer one day; <code class="verbatim">S-<up></code> and <code class="verbatim">S-<down></code> move it one week.</li> | |
| 115 | <li><code class="verbatim">RET</code> accepts. An empty answer takes the default: the date of the timestamp being changed, or today.</li> | |
| 116 | <li><code class="verbatim">Esc</code> cancels.</li> | |
| 117 | </ul> | |
| 118 | <p>Orgstar reads the answer as Org 9.8 does, with <code class="verbatim">org-read-date-prefer-future</code> <code class="verbatim">t</code>: a date given without a year, or without a month, is taken to be the next such date from today.</p> | |
| 119 | <table> | |
| 120 | <thead> | |
| 121 | <tr><th>You type</th><th>Result</th></tr> | |
| 122 | </thead> | |
| 123 | <tbody> | |
| 124 | <tr><td><code class="verbatim">.</code></td><td>Today</td></tr> | |
| 125 | <tr><td><code class="verbatim">+0</code></td><td>Today</td></tr> | |
| 126 | <tr><td><code class="verbatim">+1</code>, <code class="verbatim">+2d</code></td><td>Tomorrow, two days from today</td></tr> | |
| 127 | <tr><td><code class="verbatim">-3d</code></td><td>Three days ago</td></tr> | |
| 128 | <tr><td><code class="verbatim">+1w</code>, <code class="verbatim">+2m</code>, <code class="verbatim">-1y</code></td><td>One week, two months from today; one year ago</td></tr> | |
| 129 | <tr><td><code class="verbatim">++3</code></td><td>Three days after the default date, not after today</td></tr> | |
| 130 | <tr><td><code class="verbatim">+3h</code></td><td>Three hours after the default time; sets a time</td></tr> | |
| 131 | <tr><td><code class="verbatim">fri</code>, <code class="verbatim">mon</code></td><td>The next Friday or Monday, the default date included</td></tr> | |
| 132 | <tr><td><code class="verbatim">+fri</code></td><td>The next Friday after today</td></tr> | |
| 133 | <tr><td><code class="verbatim">-fri</code></td><td>The last Friday before today</td></tr> | |
| 134 | <tr><td><code class="verbatim">+2fri</code></td><td>The second Friday from today</td></tr> | |
| 135 | <tr><td><code class="verbatim">2026-10-07</code>, <code class="verbatim">2026-10-7</code></td><td>That date</td></tr> | |
| 136 | <tr><td><code class="verbatim">10-7</code></td><td>7 October, the next one</td></tr> | |
| 137 | <tr><td><code class="verbatim">7.10.</code>, <code class="verbatim">7.10.2027</code></td><td>7 October (day first)</td></tr> | |
| 138 | <tr><td><code class="verbatim">10/7</code>, <code class="verbatim">10/7/27</code></td><td>7 October (month first)</td></tr> | |
| 139 | <tr><td><code class="verbatim">15</code></td><td>The 15th, this month or next</td></tr> | |
| 140 | <tr><td><code class="verbatim">sep 15</code>, <code class="verbatim">15 sep</code></td><td>15 September, the next one</td></tr> | |
| 141 | <tr><td><code class="verbatim">dec 25 2027</code></td><td>25 December 2027</td></tr> | |
| 142 | <tr><td><code class="verbatim">w42</code>, <code class="verbatim">2027-w01</code>, <code class="verbatim">w3-5</code></td><td>Monday of ISO week 42; Monday of week 1 of 2027; Friday of week 3</td></tr> | |
| 143 | <tr><td><code class="verbatim">10:00</code>, <code class="verbatim">9:30</code></td><td>The default date at that time</td></tr> | |
| 144 | <tr><td><code class="verbatim">10am</code>, <code class="verbatim">3pm</code>, <code class="verbatim">12:30pm</code></td><td>12-hour times</td></tr> | |
| 145 | <tr><td><code class="verbatim">10h</code>, <code class="verbatim">10h30</code>, <code class="verbatim">h45</code></td><td>10:00, 10:30, 00:45</td></tr> | |
| 146 | <tr><td><code class="verbatim">10:00-11:30</code></td><td>A time range</td></tr> | |
| 147 | <tr><td><code class="verbatim">10:00+1:30</code></td><td>10:00-11:30</td></tr> | |
| 148 | <tr><td><code class="verbatim">fri 10:00</code>, <code class="verbatim">+2d 9:00</code></td><td>A date and a time together</td></tr> | |
| 149 | </tbody> | |
| 150 | </table> | |
| 151 | <p>Forms without a sign, such as <code class="verbatim">fri</code>, <code class="verbatim">15</code> or <code class="verbatim">10:00</code>, fill in what is missing from the default date: the date of the timestamp being changed, or today. Forms with a single sign count from today; <code class="verbatim">++</code> counts from the default date. Two-digit years are read relative to the current year. Words the prompt does not recognize are ignored, so <code class="verbatim">tomorrow</code> gives the default date.</p> | |
| 152 | <h2 id="changing-dates">Changing dates</h2> | |
| 153 | <table> | |
| 154 | <thead> | |
| 155 | <tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th></tr> | |
| 156 | </thead> | |
| 157 | <tbody> | |
| 158 | <tr><td>Increase Timestamp Part</td><td><code class="verbatim">org-timestamp-up</code></td><td><code class="verbatim">S-<up></code></td><td>⌃⌘↑</td></tr> | |
| 159 | <tr><td>Decrease Timestamp Part</td><td><code class="verbatim">org-timestamp-down</code></td><td><code class="verbatim">S-<down></code></td><td>⌃⌘↓</td></tr> | |
| 160 | <tr><td>Timestamp One Day Later</td><td><code class="verbatim">org-timestamp-up-day</code></td><td><code class="verbatim">S-<right></code></td><td>⌃⌘→</td></tr> | |
| 161 | <tr><td>Timestamp One Day Earlier</td><td><code class="verbatim">org-timestamp-down-day</code></td><td><code class="verbatim">S-<left></code></td><td>⌃⌘←</td></tr> | |
| 162 | <tr><td>Evaluate Time Range</td><td><code class="verbatim">org-evaluate-time-range</code></td><td><code class="verbatim">C-c C-y</code></td><td></td></tr> | |
| 163 | </tbody> | |
| 164 | </table> | |
| 165 | <p>These keys act on the timestamp when the caret is in one. Elsewhere the same keys do other things, such as changing the TODO keyword or priority on a heading line (<a href="05-todos-and-tags.html">TODOs and tags</a>). In the Doom preset they work in normal and insert state, and <code class="verbatim">C-S-h</code>, <code class="verbatim">C-S-j</code>, <code class="verbatim">C-S-k</code> and <code class="verbatim">C-S-l</code> do the same as <code class="verbatim">S-<left></code>, <code class="verbatim">S-<down></code>, <code class="verbatim">S-<up></code> and <code class="verbatim">S-<right></code>.</p> | |
| 166 | <p><code class="verbatim">S-<up></code> and <code class="verbatim">S-<down></code> change the part of the timestamp under the caret:</p> | |
| 167 | <ul> | |
| 168 | <li>the year, month or day (on the day name, the day);</li> | |
| 169 | <li>the hour, or the minute in steps of 5 (<code class="verbatim">org-time-stamp-rounding-minutes</code>), first rounding to a multiple of 5;</li> | |
| 170 | <li>in a time range, the end time; changing the start time moves the end time with it;</li> | |
| 171 | <li>the number or unit of a repeater or warning (the unit cycles <code class="verbatim">d</code>, <code class="verbatim">w</code>, <code class="verbatim">m</code>, <code class="verbatim">y</code>);</li> | |
| 172 | <li>on the opening or closing bracket, the timestamp switches between active and inactive.</li> | |
| 173 | </ul> | |
| 174 | <p><code class="verbatim">S-<left></code> and <code class="verbatim">S-<right></code> move the whole timestamp by a day, wherever the caret is in it. The day name is rewritten after every change. In a range of days, each end changes on its own.</p> | |
| 175 | <p><code class="verbatim">C-c C-c</code> on a timestamp rewrites its day name to match its date. <code class="verbatim">C-c C-y</code> shows the length of the range at the caret, or of the first range on the line, such as <code class="verbatim">2 days 3 hours</code>; on a clock line it recomputes the clock's duration.</p> | |
| 176 | <h2 id="scheduled-and-deadline">SCHEDULED and DEADLINE</h2> | |
| 177 | <p>A planning line goes directly under the heading:</p> | |
| 178 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Submit the tax return | |
| 179 | </span>DEADLINE: <span class="constant other timestamp org"><2026-10-31 Sat -7d></span> SCHEDULED: <span class="constant other timestamp org"><2026-10-20 Tue></span></span></code></pre> | |
| 180 | <ul> | |
| 181 | <li><code class="verbatim">SCHEDULED</code> is the day you plan to start. The agenda shows the entry from that day until it is done.</li> | |
| 182 | <li><code class="verbatim">DEADLINE</code> is the day it is due. The agenda warns about it 14 days ahead (<code class="verbatim">org-deadline-warning-days</code>), or as the timestamp's own <code class="verbatim">-Nd</code> says.</li> | |
| 183 | </ul> | |
| 184 | <table> | |
| 185 | <thead> | |
| 186 | <tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th></tr> | |
| 187 | </thead> | |
| 188 | <tbody> | |
| 189 | <tr><td>Schedule</td><td><code class="verbatim">org-schedule</code></td><td><code class="verbatim">C-c C-s</code></td><td>⌃⌘S</td><td><code class="verbatim">SPC m d s</code></td></tr> | |
| 190 | <tr><td>Set Deadline</td><td><code class="verbatim">org-deadline</code></td><td><code class="verbatim">C-c C-d</code></td><td>⌃⌘E</td><td><code class="verbatim">SPC m d d</code></td></tr> | |
| 191 | <tr><td>Remove Schedule</td><td><code class="verbatim">C-u C-c C-s</code></td><td></td><td></td><td></td></tr> | |
| 192 | <tr><td>Remove Deadline</td><td><code class="verbatim">C-u C-c C-d</code></td><td></td><td></td><td></td></tr> | |
| 193 | </tbody> | |
| 194 | </table> | |
| 195 | <p>Schedule and Set Deadline ask for a date, starting from the entry's current one and its time. They replace an existing date, keep its repeater and warning, and remove a <code class="verbatim">CLOSED</code> stamp from the entry. Remove Schedule and Remove Deadline have no default keys; run them from the Org menu or the command palette (<a href="03-keys.html">Keys</a>).</p> | |
| 196 | <p>With <code class="verbatim">org-log-reschedule</code> or <code class="verbatim">org-log-redeadline</code> set to <code class="verbatim">time</code> or <code class="verbatim">note</code> in <code class="verbatim">config.toml</code>, or the matching <code class="verbatim">#+STARTUP</code> words, Orgstar logs each change of an existing date and each removal:</p> | |
| 197 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Submit the tax return | |
| 198 | </span>SCHEDULED: <span class="constant other timestamp org"><2026-10-22 Thu></span> | |
| 199 | <span class="punctuation definition list org">- </span>Rescheduled from "<span class="constant other timestamp org">[2026-10-20 Tue]</span>" on <span class="constant other timestamp org">[2026-10-19 Mon 08:40]</span></span></code></pre> | |
| 200 | <p>Where these notes go, and the <code class="verbatim">#+STARTUP</code> words, are covered in <a href="05-todos-and-tags.html">TODOs and tags</a>.</p> | |
| 201 | <h2 id="repeating-tasks">Repeating tasks</h2> | |
| 202 | <p>When an entry with a repeater in an active timestamp changes from an active TODO keyword to a done one (<code class="verbatim">org-auto-repeat-maybe</code>), Orgstar does not leave it done:</p> | |
| 203 | <ol> | |
| 204 | <li>The keyword returns to the first keyword of its sequence. In a <code class="verbatim">#+TYP_TODO</code> sequence it returns to the keyword it had. A <code class="verbatim">REPEAT_TO_STATE</code> property, inherited from ancestors, names another keyword to use.</li> | |
| 205 | <li><code class="verbatim">CLOSED</code> is removed.</li> | |
| 206 | <li>With <code class="verbatim">org-log-repeat</code> on (the default, <code class="verbatim">time</code>), the <code class="verbatim">LAST_REPEAT</code> property is set to the current time and a state note is logged, such as <code class="verbatim">- State "DONE" from "TODO" [2026-10-07 Wed 18:02]</code>.</li> | |
| 207 | <li>A <code class="verbatim">SCHEDULED</code> date without a repeater is removed.</li> | |
| 208 | <li>Every active timestamp with a repeater in the entry moves forward:<ul> | |
| 209 | <li><code class="verbatim">+N</code> moves it by N once, which may leave it in the past.</li> | |
| 210 | <li><code class="verbatim">++N</code> moves it by N until it is after today (for hours, after now).</li> | |
| 211 | <li><code class="verbatim">.+N</code> sets it to today and then moves it by N. With hours, <code class="verbatim">.+Nh</code>, the new time is N hours after the current time, to the minute, and a time range loses its end time.</li> | |
| 212 | </ul> | |
| 213 | </li> | |
| 214 | <li><code class="verbatim">--</code> delays in those timestamps are removed.</li> | |
| 215 | </ol> | |
| 216 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Water the plants | |
| 217 | </span>SCHEDULED: <span class="constant other timestamp org"><2026-10-07 Wed .+3d></span></span></code></pre> | |
| 218 | <p>Marking this done on 7 October gives:</p> | |
| 219 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Water the plants | |
| 220 | </span>SCHEDULED: <span class="constant other timestamp org"><2026-10-10 Sat .+3d></span> | |
| 221 | :PROPERTIES: | |
| 222 | :LAST_REPEAT: <span class="constant other timestamp org">[2026-10-07 Wed 18:02]</span> | |
| 223 | :END: | |
| 224 | <span class="punctuation definition list org">- </span>State "DONE" from "TODO" <span class="constant other timestamp org">[2026-10-07 Wed 18:02]</span></span></code></pre> | |
| 225 | <p>A repeater of <code class="verbatim">0</code> (<code class="verbatim">+0d</code>) does not repeat. An hourly repeater needs a time in the timestamp; without one, Orgstar reports "Cannot repeat in N hour(s) because no hour has been set". Inactive timestamps never repeat.</p> | |
| 226 | <p>To turn the repeat note off for a file, use <code class="verbatim">#+STARTUP: nologrepeat</code>; <code class="verbatim">lognoterepeat</code> asks for a note instead.</p> | |
| 227 | <h2 id="effort">Effort</h2> | |
| 228 | <p>Effort estimates live in the <code class="verbatim">Effort</code> property.</p> | |
| 229 | <table> | |
| 230 | <thead> | |
| 231 | <tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th><th>Speed key</th></tr> | |
| 232 | </thead> | |
| 233 | <tbody> | |
| 234 | <tr><td>Set Effort</td><td><code class="verbatim">org-set-effort</code></td><td><code class="verbatim">C-c C-x e</code></td><td><code class="verbatim">⌃⇧⌘E</code></td><td><code class="verbatim">SPC m c E</code></td><td><code class="verbatim">e</code></td></tr> | |
| 235 | </tbody> | |
| 236 | </table> | |
| 237 | <p>Set Effort asks for a value, such as <code class="verbatim">0:30</code> or <code class="verbatim">2:00</code>, starting with the current one. If the entry, an ancestor, or a <code class="verbatim">#+PROPERTY: Effort_ALL</code> line defines <code class="verbatim">Effort_ALL</code>, its values are offered as choices; you can also type another value.</p> | |
| 238 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+PROPERTY:</span><span class="string unquoted org"> Effort_ALL 0:15 0:30 1:00 2:00 4:00</span></span></code></pre> | |
| 239 | <p>Effort appears in column view and in clock tables with <code class="verbatim">:properties ("Effort")</code>. Orgstar does not compare the running clock with the effort estimate.</p> | |
| 240 | <h2 id="clocking">Clocking</h2> | |
| 241 | <p>Clocking records the time you work on an entry as <code class="verbatim">CLOCK:</code> lines in its <code class="verbatim">LOGBOOK</code> drawer.</p> | |
| 242 | <table> | |
| 243 | <thead> | |
| 244 | <tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th><th>Mac</th><th>Doom leader</th><th>Speed key</th></tr> | |
| 245 | </thead> | |
| 246 | <tbody> | |
| 247 | <tr><td>Clock In</td><td><code class="verbatim">org-clock-in</code></td><td><code class="verbatim">C-c C-x C-i</code></td><td><code class="verbatim">⌃⌘I</code></td><td><code class="verbatim">SPC m c i</code></td><td><code class="verbatim">I</code></td></tr> | |
| 248 | <tr><td>Clock In to Recent Entry…</td><td><code class="verbatim">org-clock-in</code> with <code class="verbatim">C-u</code></td><td></td><td><code class="verbatim">⌃⌥⌘I</code></td><td></td><td></td></tr> | |
| 249 | <tr><td>Clock In to Last Entry</td><td><code class="verbatim">org-clock-in-last</code></td><td><code class="verbatim">C-c C-x C-x</code></td><td></td><td><code class="verbatim">SPC m c I</code></td><td></td></tr> | |
| 250 | <tr><td>Clock Out</td><td><code class="verbatim">org-clock-out</code></td><td><code class="verbatim">C-c C-x C-o</code></td><td><code class="verbatim">⌃⇧⌘I</code></td><td><code class="verbatim">SPC m c o</code></td><td><code class="verbatim">O</code></td></tr> | |
| 251 | <tr><td>Cancel Clock</td><td><code class="verbatim">org-clock-cancel</code></td><td><code class="verbatim">C-c C-x C-q</code></td><td><code class="verbatim">⌃⌘K</code></td><td><code class="verbatim">SPC m c c</code></td><td></td></tr> | |
| 252 | <tr><td>Go to Clocked Entry</td><td><code class="verbatim">org-clock-goto</code></td><td><code class="verbatim">C-c C-x C-j</code></td><td><code class="verbatim">⌃⌘J</code></td><td><code class="verbatim">SPC m c g</code></td><td></td></tr> | |
| 253 | <tr><td>Go to Recent Clocked Entry…</td><td><code class="verbatim">org-clock-goto</code> with <code class="verbatim">C-u</code></td><td></td><td><code class="verbatim">⌃⌥⌘J</code></td><td><code class="verbatim">SPC m c G</code></td><td></td></tr> | |
| 254 | <tr><td>Mark as Default Clock Task</td><td><code class="verbatim">org-clock-mark-default-task</code></td><td></td><td></td><td><code class="verbatim">SPC m c d</code></td><td></td></tr> | |
| 255 | <tr><td>Resolve Open Clocks…</td><td><code class="verbatim">org-resolve-clocks</code></td><td><code class="verbatim">C-c C-x C-z</code></td><td></td><td><code class="verbatim">SPC m c r</code></td><td></td></tr> | |
| 256 | </tbody> | |
| 257 | </table> | |
| 258 | <p>The Emacs keys are Org's own, and work in the Doom preset too, as every <code class="verbatim">C-c</code> key does. Commands without a key in your preset are in the command palette and in Org ▸ Clock, which lists every clock command with its keys, followed by the recent entries. In the agenda, <code class="verbatim">I</code>, <code class="verbatim">O</code> and <code class="verbatim">X</code> clock in, out and cancel for the entry at the line (<a href="07-agenda.html">The agenda</a>). Capture templates can clock in too (<a href="08-capture.html">Capture</a>).</p> | |
| 259 | <p>Orgstar has no <code class="verbatim">C-u</code> forms of these commands. Clock In to Recent Entry… and Go to Recent Clocked Entry… stand for <code class="verbatim">C-u C-c C-x C-i</code> and <code class="verbatim">C-u C-c C-x C-j</code>.</p> | |
| 260 | <h3 id="clocking-in-and-out">Clocking in and out</h3> | |
| 261 | <p>Clock In starts a clock on the heading at the caret and inserts a line at the top of its <code class="verbatim">LOGBOOK</code> drawer, creating the drawer after the planning line and property drawer if needed:</p> | |
| 262 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Write the report | |
| 263 | </span>:LOGBOOK: | |
| 264 | CLOCK: <span class="constant other timestamp org">[2026-10-07 Wed 09:00]</span> | |
| 265 | CLOCK: <span class="constant other timestamp org">[2026-10-06 Tue 14:00]</span>--<span class="constant other timestamp org">[2026-10-06 Tue 15:30]</span> => 1:30 | |
| 266 | :END:</span></code></pre> | |
| 267 | <ul> | |
| 268 | <li>Only one clock runs at a time. Clocking in while another clock runs clocks that one out first, and remembers it as the interrupted task (<code class="verbatim">i</code> in the selection below).</li> | |
| 269 | <li>Clocking in on the entry whose clock is running changes nothing and says <code class="verbatim">Clock continues in "Write the report"</code>.</li> | |
| 270 | <li><code class="verbatim">CLOCK:</code> lines outside a drawer move into the new drawer the first time you clock in on that entry.</li> | |
| 271 | <li>Clock Out completes the line with the end time and the duration in hours and minutes. Clocks of zero minutes are kept.</li> | |
| 272 | <li>Cancel Clock removes the running clock's line, and the drawer if it is left empty.</li> | |
| 273 | <li>Go to Clocked Entry opens the file and moves the caret to the running clock's line. With no clock running, it goes to the most recently clocked entry and says "No running clock, this is the most recently clocked task".</li> | |
| 274 | </ul> | |
| 275 | <p>With no clock running, Clock In first asks about open clocks; see Open clocks below. So do the agenda's <code class="verbatim">I</code> and a capture template's <code class="verbatim">clock-in</code>.</p> | |
| 276 | <p>Orgstar remembers the running clock and the clock history across restarts, in <code class="verbatim">clock.json</code> in <code class="verbatim">~/Library/Application Support/Orgstar</code>. If the open <code class="verbatim">CLOCK:</code> line is deleted from the file, Clock Out reports "Clock start time is gone" and forgets the clock.</p> | |
| 277 | <p>These parts of Org's clocking are not implemented:</p> | |
| 278 | <ul> | |
| 279 | <li>sharing the running clock with Emacs: Orgstar does not read or write Emacs's <code class="verbatim">org-clock-persist</code> file, so a clock started in one is not known to the other, although both see the open <code class="verbatim">CLOCK:</code> line;</li> | |
| 280 | <li>rounding, changing the TODO state on clock-in (<code class="verbatim">org-clock-in-switch-to-state</code>), and clocking out when the entry is marked done (<code class="verbatim">org-clock-out-when-done</code>): the clock keeps running;</li> | |
| 281 | <li>a <code class="verbatim">CLOCK_INTO_DRAWER</code> property or another drawer name: clocks always go into <code class="verbatim">LOGBOOK</code>.</li> | |
| 282 | </ul> | |
| 283 | <h3 id="the-running-clock">The running clock</h3> | |
| 284 | <p>While a clock runs, Orgstar shows it in three places, refreshed every 30 seconds:</p> | |
| 285 | <ul> | |
| 286 | <li>the mode line under the editor: <code class="verbatim">⏱ 0:42 Write the report</code>;</li> | |
| 287 | <li>the window's toolbar;</li> | |
| 288 | <li>the macOS menu bar, with the elapsed time.</li> | |
| 289 | </ul> | |
| 290 | <p>The time shown is the time since you clocked in, not the entry's total. Each of them opens a menu with Clock Out, Cancel Clock and Go to Clocked Entry. The toolbar's menu also has Clock In to Recent Entry…, Go to Recent Clocked Entry… and the recent entries. The menu bar item also has Clock In to Recent Entry…, Clock Report and a Recent Entries section. Choosing a recent entry clocks in to it.</p> | |
| 291 | <h3 id="recent-entries">Recent entries</h3> | |
| 292 | <p>Orgstar keeps a clock history, as <code class="verbatim">org-clock-history</code>. Every clock-in, including one from the agenda or a capture template, puts the entry first in the history and removes its other entries there. The history holds <code class="verbatim">org-clock-history-length</code> entries (5 by default); the oldest go first.</p> | |
| 293 | <p>Entries are found again after edits by their <code class="verbatim">ID</code> property, else by the heading's position among the file's headings together with its title, else by the title alone. An entry that can't be found is dropped from the history the next time an entry is added, and left out of the selection.</p> | |
| 294 | <p>Clock In to Recent Entry… and Go to Recent Clocked Entry… ask for an entry in the echo area, as <code class="verbatim">org-clock-select-task</code> does. Each line shows its key, the entry's category padded to 12 characters, and the heading with its TODO keyword and priority, under these sections:</p> | |
| 295 | <table> | |
| 296 | <thead> | |
| 297 | <tr><th>Key</th><th>Section</th></tr> | |
| 298 | </thead> | |
| 299 | <tbody> | |
| 300 | <tr><td><code class="verbatim">d</code></td><td>Default Task: the entry marked with Mark as Default Clock Task</td></tr> | |
| 301 | <tr><td><code class="verbatim">i</code></td><td>The task interrupted by starting the last one</td></tr> | |
| 302 | <tr><td><code class="verbatim">c</code></td><td>Current Clocking Task</td></tr> | |
| 303 | <tr><td><code class="verbatim">1</code> … <code class="verbatim">9</code>, <code class="verbatim">A</code>, <code class="verbatim">B</code>, …</td><td>Recent Tasks, most recent first</td></tr> | |
| 304 | </tbody> | |
| 305 | </table> | |
| 306 | <p>Type a key to choose. <code class="verbatim">q</code>, <code class="verbatim">x</code> or <code class="verbatim">Esc</code> leave the question. With an empty history the commands say "No recent clock"; a key that isn't listed says "Invalid task choice X".</p> | |
| 307 | <p>Clock In to Last Entry clocks in to the first entry of the history, the same as <code class="verbatim">1</code>. With no clock running it says "Clocking back: Write the report (in work.org)"; with an empty history, "No last clock".</p> | |
| 308 | <p>Mark as Default Clock Task makes the heading at the caret the <code class="verbatim">d</code> entry and says "Default clock task: Write the report"; Org sets it without a message. As in Org, the default task lasts until you quit Orgstar.</p> | |
| 309 | <h3 id="open-clocks">Open clocks</h3> | |
| 310 | <p>An open clock is a <code class="verbatim">CLOCK:</code> line with a start and no end. Org calls one that isn't the running clock dangling, for example after Orgstar or Emacs quit while it ran, or a line synced from another machine.</p> | |
| 311 | <p>When you clock in with no clock running, Orgstar first looks for open clocks in the org files of your folders and in the open buffers (<code class="verbatim">org-clock-auto-clock-resolution</code> set to <code class="verbatim">when-no-clock-is-running</code>), and asks about each one:</p> | |
| 312 | <pre>Dangling clock started 95 mins ago [jkKtTgGSscCiq]?</pre> | |
| 313 | <p>Clocking in from the agenda (<code class="verbatim">I</code>) or from a capture template with <code class="verbatim">clock-in</code> asks too, as <code class="verbatim">org-clock-in</code> does in Org. A capture template resolves open clocks as of when the capture began, which is when its clock starts. On the Mac, the questions for an agenda or capture clock-in are asked in the main window's echo area.</p> | |
| 314 | <p>Resolve Open Clocks… asks the same about every open clock, the running one included, and says "No open clocks" when there are none.</p> | |
| 315 | <p>Unlike Org, Orgstar doesn't show the clock's line while it asks; <code class="verbatim">j</code> opens it afterwards, except while clocking in.</p> | |
| 316 | <p>The answer is a key, as in <code class="verbatim">org-clock-resolve</code>. The idle time is the time since the clock started, for an open clock, or since you stopped using the Mac, for an idle one (see Idle time below).</p> | |
| 317 | <table> | |
| 318 | <thead> | |
| 319 | <tr><th>Key</th><th>What happens to the <code class="verbatim">CLOCK:</code> line</th></tr> | |
| 320 | </thead> | |
| 321 | <tbody> | |
| 322 | <tr><td><code class="verbatim">j</code></td><td>Nothing; the line opens in the editor to adjust by hand (after the clock-in, when you were clocking in).</td></tr> | |
| 323 | <tr><td><code class="verbatim">J</code></td><td>Ends the line now, then opens it in the editor.</td></tr> | |
| 324 | <tr><td><code class="verbatim">k</code></td><td>Asks how many minutes of the idle time to keep, all of them by default. With all, the clock keeps running. With fewer, the line ends that many minutes after the idle time began, and a new clock starts now.</td></tr> | |
| 325 | <tr><td><code class="verbatim">K</code></td><td>Asks the same, then ends the line after the minutes kept and leaves you clocked out.</td></tr> | |
| 326 | <tr><td><code class="verbatim">t</code></td><td>Like <code class="verbatim">k</code>, but asks for the date and time you got distracted; the line ends then.</td></tr> | |
| 327 | <tr><td><code class="verbatim">T</code></td><td>Like <code class="verbatim">t</code>, then leaves you clocked out.</td></tr> | |
| 328 | <tr><td><code class="verbatim">g</code></td><td>Asks how many minutes ago you got back, all of the idle time by default. The line ends when the idle time began, and a new clock starts that many minutes ago.</td></tr> | |
| 329 | <tr><td><code class="verbatim">G</code></td><td>Like <code class="verbatim">g</code>, but leaves you clocked out: the line ends when the idle time began.</td></tr> | |
| 330 | <tr><td><code class="verbatim">s</code></td><td>Subtracts the idle time: the line ends when the idle time began, and a new clock starts now.</td></tr> | |
| 331 | <tr><td><code class="verbatim">S</code></td><td>Subtracts the idle time and leaves you clocked out.</td></tr> | |
| 332 | <tr><td><code class="verbatim">C</code></td><td>Removes the line, as though you never clocked in.</td></tr> | |
| 333 | <tr><td><code class="verbatim">i</code>, <code class="verbatim">q</code>, <code class="verbatim">Esc</code></td><td>Leaves the line as it is, keeping all the idle time.</td></tr> | |
| 334 | </tbody> | |
| 335 | </table> | |
| 336 | <ul> | |
| 337 | <li><code class="verbatim">k</code>, <code class="verbatim">K</code>, <code class="verbatim">g</code> and <code class="verbatim">G</code> ask for minutes with the default in the question, as <code class="verbatim">Keep how many minutes (default 95):</code>; Return with an empty field takes the default.</li> | |
| 338 | <li><code class="verbatim">t</code> and <code class="verbatim">T</code> ask <code class="verbatim">Date+time:</code> with Org's date syntax, as <code class="verbatim">14:00</code> or <code class="verbatim">-1h</code>.</li> | |
| 339 | <li>If the clock ran less than 45 seconds before the idle time began, <code class="verbatim">s</code> removes the line and starts a new clock now, and <code class="verbatim">S</code> removes it. For an open clock all its time is idle time, so <code class="verbatim">s</code> and <code class="verbatim">S</code> remove its line.</li> | |
| 340 | <li>Any other key asks again.</li> | |
| 341 | </ul> | |
| 342 | <p>While clocking in, an answer never restarts the clock it resolves: where a key would start a new clock or keep one running, the line ends instead, and the clock you asked for starts. Resolving an open clock that isn't running with <code class="verbatim">k</code> and all the minutes, outside a clock-in, makes it the running clock.</p> | |
| 343 | <p>When <code class="verbatim">K</code>, <code class="verbatim">T</code> or <code class="verbatim">S</code> ends a clock outside a clock-in, the next clock-in, from the agenda or a capture template too, asks:</p> | |
| 344 | <pre>You stopped another clock 12 mins ago; start this one from then? (y or n)</pre> | |
| 345 | <p><code class="verbatim">y</code> starts the new clock when the old one ended.</p> | |
| 346 | <h3 id="idle-time">Idle time</h3> | |
| 347 | <p>On the Mac, set <code class="verbatim">org-clock-idle-time</code> to a number of minutes, or turn on Settings ▸ Agenda ▸ "Ask what to do with idle time while clocked in", to be asked about time away from the Mac. The default, <code class="verbatim">0</code>, never asks, as <code class="verbatim">nil</code> does in Emacs.</p> | |
| 348 | <p>While a clock runs, Orgstar checks every minute how long the Mac has had no keyboard or mouse input, in any app. Past the limit, it requests your attention, which bounces its Dock icon while another app is active, and asks in the echo area:</p> | |
| 349 | <pre>Clocked in & idle for 17.3 mins [jkKtTgGSscCiq]?</pre> | |
| 350 | <p>The keys are those in the table above, with the idle time starting when input stopped. The iOS app has no idle detection.</p> | |
| 351 | <h3 id="editing-clock-lines">Editing clock lines</h3> | |
| 352 | <p>You can edit clock lines by hand. <code class="verbatim">S-<up></code>, <code class="verbatim">S-<down></code>, <code class="verbatim">S-<left></code> and <code class="verbatim">S-<right></code> change their timestamps as anywhere else, and then write the duration after <code>=></code> again, as <code class="verbatim">H:MM</code>. After typing changes yourself, press <code class="verbatim">C-c C-c</code> (or <code class="verbatim">C-c C-y</code>) on the line: Orgstar fixes both day names and writes the duration again (<code class="verbatim">org-clock-update-time-maybe</code>).</p> | |
| 353 | <p><code class="verbatim">C-c .</code> on a clock line's range replaces one of its timestamps, as in any range of days (see "Inserting timestamps").</p> | |
| 354 | <p>A line of the form <code>CLOCK: => 1:15</code>, with only a duration, counts towards clock tables.</p> | |
| 355 | <h2 id="clock-summaries">Clock summaries</h2> | |
| 356 | <h3 id="the-inspector">The inspector</h3> | |
| 357 | <p>View ▸ Show or Hide Columns and Clock opens the inspector beside the editor. Its Clock tab lists the clocked time per heading in the open file for Today, This Week (weeks start on Monday) or All, with a total. Clicking a heading moves to it. Only finished clocks count.</p> | |
| 358 | <h3 id="the-clock-report-window">The clock report window</h3> | |
| 359 | <p>Clock Report (<code class="verbatim">SPC m c R</code> and <code class="verbatim">SPC z t</code> in Doom, the command palette, or the clock menus) opens a window that totals time across files. Choose files on the left; files with clock lines are selected when the window opens. Turn on From to limit the report to a range of dates. The report is an Org table of time per date and heading, with a total after each ISO week:</p> | |
| 360 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+title:</span><span class="string unquoted org"> Time Report</span> | |
| 361 | ||
| 362 | <span class="markup other table org">| Date | Code | Hours |</span> | |
| 363 | <span class="markup other table org">|--------------+-----------------------------------------------+-------|</span> | |
| 364 | <span class="markup other table org">| 2026-10-05 | Write the report | 2:15 |</span> | |
| 365 | <span class="markup other table org">| 2026-10-06 | Write the report | 1:30 |</span> | |
| 366 | <span class="markup other table org">|--------------+-----------------------------------------------+-------|</span> | |
| 367 | <span class="markup other table org">| 2026-W41 | WEEK TOTAL | 3:45 |</span></span></code></pre> | |
| 368 | <p>Copy puts it on the clipboard; Save writes it to a file.</p> | |
| 369 | <h2 id="clock-tables">Clock tables</h2> | |
| 370 | <p>A clock table is a dynamic block that Orgstar fills with a summary of clocked time (<code class="verbatim">org-clocktable-write-default</code>).</p> | |
| 371 | <table> | |
| 372 | <thead> | |
| 373 | <tr><th>Command</th><th>Org command</th><th>Emacs, Doom</th></tr> | |
| 374 | </thead> | |
| 375 | <tbody> | |
| 376 | <tr><td>Insert or Update Clock Table</td><td><code class="verbatim">org-clock-report</code></td><td><code class="verbatim">C-c C-x C-r</code></td></tr> | |
| 377 | <tr><td>Update Dynamic Block</td><td><code class="verbatim">org-update-dblock</code></td><td><code class="verbatim">C-c C-x C-u</code></td></tr> | |
| 378 | </tbody> | |
| 379 | </table> | |
| 380 | <p><code class="verbatim">C-c C-c</code> on the <code class="verbatim">#+BEGIN:</code> line also updates the block; in the Mac preset, <code class="verbatim">⌃⌘X</code> does.</p> | |
| 381 | <p>Insert or Update Clock Table updates the clock table at the caret. Elsewhere it inserts a new one, with <code class="verbatim">:scope subtree</code> inside an entry or <code class="verbatim">:scope file</code> before the first heading, and fills it:</p> | |
| 382 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+BEGIN:</span><span class="string unquoted org"> clocktable :scope file :maxlevel 2 :block thisweek</span> | |
| 383 | <span class="keyword other keyword org">#+CAPTION:</span><span class="string unquoted org"> Clock summary at [2026-10-07 Wed 17:00], for week 2026-W41.</span> | |
| 384 | <span class="markup other table org">| Headline | Time | |</span> | |
| 385 | <span class="markup other table org">|------------------+--------+------|</span> | |
| 386 | <span class="markup other table org">| *Total time* | *5:15* | |</span> | |
| 387 | <span class="markup other table org">|------------------+--------+------|</span> | |
| 388 | <span class="markup other table org">| Project Alpha | 5:15 | |</span> | |
| 389 | <span class="markup other table org">| \_ Design | | 3:00 |</span> | |
| 390 | <span class="markup other table org">| \_ Write code | | 2:15 |</span> | |
| 391 | <span class="keyword other keyword org">#+END:</span></span></code></pre> | |
| 392 | <p>Times are written as <code class="verbatim">H:MM</code>, with a day count such as <code class="verbatim">2d</code> before them for a day or more. A heading's time includes its subtree's. Only finished clock lines and <code>CLOCK: => H:MM</code> lines count; a running clock does not. A <code class="verbatim">COMMENT</code> prefix is left out of headlines.</p> | |
| 393 | <h3 id="parameters">Parameters</h3> | |
| 394 | <table> | |
| 395 | <thead> | |
| 396 | <tr><th>Parameter</th><th>Values</th><th>Default</th></tr> | |
| 397 | </thead> | |
| 398 | <tbody> | |
| 399 | <tr><td><code class="verbatim">:scope</code></td><td><code class="verbatim">file</code> (or <code class="verbatim">nil</code>), <code class="verbatim">subtree</code>, <code class="verbatim">tree</code>, <code class="verbatim">treeN</code></td><td><code class="verbatim">file</code></td></tr> | |
| 400 | <tr><td><code class="verbatim">:maxlevel</code></td><td>Deepest heading level listed</td><td><code class="verbatim">2</code></td></tr> | |
| 401 | <tr><td><code class="verbatim">:block</code></td><td>A time block (see below)</td><td>none</td></tr> | |
| 402 | <tr><td><code class="verbatim">:tstart</code>, <code class="verbatim">:tend</code></td><td>Start and end, such as <code class="verbatim">"<2026-09-01>"</code>, <code class="verbatim">"<today>"</code>, <code class="verbatim">"<-1w>"</code></td><td>none</td></tr> | |
| 403 | <tr><td><code class="verbatim">:wstart</code></td><td>First day of the week for <code class="verbatim">:block</code> weeks, <code class="verbatim">1</code> is Monday</td><td><code class="verbatim">1</code></td></tr> | |
| 404 | <tr><td><code class="verbatim">:mstart</code></td><td>First day of the month for <code class="verbatim">:block</code> months</td><td><code class="verbatim">1</code></td></tr> | |
| 405 | <tr><td><code class="verbatim">:link</code></td><td><code class="verbatim">t</code>: headlines link to their headings</td><td><code class="verbatim">nil</code></td></tr> | |
| 406 | <tr><td><code class="verbatim">:narrow</code></td><td><code class="verbatim">N</code> adds a <code class="verbatim"><N></code> width cookie; <code class="verbatim">N!</code> cuts headlines to N characters</td><td><code class="verbatim">40!</code></td></tr> | |
| 407 | <tr><td><code class="verbatim">:indent</code></td><td><code class="verbatim">t</code>: indent sublevels with <code class="verbatim">\_</code></td><td><code class="verbatim">t</code></td></tr> | |
| 408 | <tr><td><code class="verbatim">:compact</code></td><td><code class="verbatim">t</code>: one time column, indented, cut to 40 characters</td><td><code class="verbatim">nil</code></td></tr> | |
| 409 | <tr><td><code class="verbatim">:emphasize</code></td><td><code class="verbatim">t</code>: level 1 bold, level 2 italic</td><td><code class="verbatim">nil</code></td></tr> | |
| 410 | <tr><td><code class="verbatim">:level</code></td><td><code class="verbatim">t</code>: a column with the level</td><td><code class="verbatim">nil</code></td></tr> | |
| 411 | <tr><td><code class="verbatim">:tags</code></td><td><code class="verbatim">t</code>: a column with the tags, inherited ones first</td><td><code class="verbatim">nil</code></td></tr> | |
| 412 | <tr><td><code class="verbatim">:properties</code></td><td>A list of property names, such as <code class="verbatim">("Effort")</code>, one column each</td><td>none</td></tr> | |
| 413 | <tr><td><code class="verbatim">:tcolumns</code></td><td>Number of time columns</td><td>up to <code class="verbatim">:maxlevel</code></td></tr> | |
| 414 | <tr><td><code class="verbatim">:formula</code></td><td><code class="verbatim">%</code> adds a percentage column; a string becomes the table's <code class="verbatim">#+TBLFM</code></td><td>none</td></tr> | |
| 415 | <tr><td><code class="verbatim">:fileskip0</code></td><td>Accepted; has no effect within one file</td><td><code class="verbatim">nil</code></td></tr> | |
| 416 | </tbody> | |
| 417 | </table> | |
| 418 | <p><code class="verbatim">:scope tree</code> covers the top-level tree around the block; <code class="verbatim">tree2</code> the tree from its level-2 ancestor, and so on. <code class="verbatim">:block</code> takes precedence over <code class="verbatim">:tstart</code> and <code class="verbatim">:tend</code>. Clocks that cross the start or end of the range count only the part inside it.</p> | |
| 419 | <p><code class="verbatim">:block</code> values:</p> | |
| 420 | <table> | |
| 421 | <thead> | |
| 422 | <tr><th>Value</th><th>Range</th></tr> | |
| 423 | </thead> | |
| 424 | <tbody> | |
| 425 | <tr><td><code class="verbatim">today</code>, <code class="verbatim">yesterday</code>, <code class="verbatim">today-N</code></td><td>One day</td></tr> | |
| 426 | <tr><td><code class="verbatim">thisweek</code>, <code class="verbatim">lastweek</code>, <code class="verbatim">thisweek-N</code></td><td>One week, from <code class="verbatim">:wstart</code></td></tr> | |
| 427 | <tr><td><code class="verbatim">thismonth</code>, <code class="verbatim">lastmonth</code>, <code class="verbatim">thismonth-N</code></td><td>One month, from <code class="verbatim">:mstart</code></td></tr> | |
| 428 | <tr><td><code class="verbatim">thisyear</code>, <code class="verbatim">lastyear</code>, <code class="verbatim">thisyear-N</code></td><td>One year</td></tr> | |
| 429 | <tr><td><code class="verbatim">2026</code>, <code class="verbatim">2026-10</code>, <code class="verbatim">2026-W41</code>, <code class="verbatim">2026-10-07</code></td><td>That year, month, ISO week or day</td></tr> | |
| 430 | </tbody> | |
| 431 | </table> | |
| 432 | <p><code class="verbatim">week</code>, <code class="verbatim">month</code> and <code class="verbatim">year</code> are the same as <code class="verbatim">thisweek</code>, <code class="verbatim">thismonth</code> and <code class="verbatim">thisyear</code>, and a <code class="verbatim">+N</code> suffix moves forward.</p> | |
| 433 | <p>A <code class="verbatim">#+TBLFM</code> line already under the table is kept when the table is updated, unless <code class="verbatim">:formula</code> gives one.</p> | |
| 434 | <p>Not supported: scopes over other files (<code class="verbatim">agenda</code>, file lists, <code class="verbatim">file-with-archives</code>), <code class="verbatim">:match</code> and <code class="verbatim">:step</code>, which stop the update with a message, and <code class="verbatim">:formatter</code>, which is ignored along with other unknown parameters. Labels are in English only.</p> | |
| 435 | <h2 id="habits">Habits</h2> | |
| 436 | <p>A habit is a repeating task whose history the agenda shows as a consistency graph (<code class="verbatim">org-habit</code>). Define one with the <code class="verbatim">STYLE</code> property and a <code class="verbatim">SCHEDULED</code> date with a repeater:</p> | |
| 437 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Go for a run | |
| 438 | </span>SCHEDULED: <span class="constant other timestamp org"><2026-10-07 Wed .+2d/4d></span> | |
| 439 | :PROPERTIES: | |
| 440 | :STYLE: habit | |
| 441 | :END: | |
| 442 | :LOGBOOK: | |
| 443 | <span class="punctuation definition list org">- </span>State "DONE" from "TODO" <span class="constant other timestamp org">[2026-10-05 Mon 07:30]</span> | |
| 444 | <span class="punctuation definition list org">- </span>State "DONE" from "TODO" <span class="constant other timestamp org">[2026-10-03 Sat 07:10]</span> | |
| 445 | :END:</span></code></pre> | |
| 446 | <ul> | |
| 447 | <li>The repeater sets the interval you aim for. Use <code class="verbatim">.+</code> for most habits, so the next date counts from when you last did it.</li> | |
| 448 | <li>The optional <code class="verbatim">/4d</code> sets the longest acceptable interval. It must be longer than the repeater.</li> | |
| 449 | <li>The repeater's unit must be <code class="verbatim">d</code>, <code class="verbatim">w</code>, <code class="verbatim">m</code> or <code class="verbatim">y</code>. A month counts as 30.4 days and a year as 365.25.</li> | |
| 450 | <li>The history comes from the entry's state notes for done keywords and its <code class="verbatim">CLOSING NOTE</code> lines, up to 28 of them. Those are written when the task repeats, as long as <code class="verbatim">org-log-repeat</code> is on (the default), or when <code class="verbatim">org-log-done</code> is <code class="verbatim">note</code>.</li> | |
| 451 | </ul> | |
| 452 | <p>How habits appear in the agenda, with the graph covering 21 days back and 7 ahead, is described in <a href="07-agenda.html">The agenda</a>.</p> | |
| 453 | <h2 id="reminders">Reminders</h2> | |
| 454 | <p>Orgstar can post a macOS notification before entries that have a time of day, as Emacs's <code class="verbatim">appt</code> does with <code class="verbatim">org-agenda-to-appt</code>.</p> | |
| 455 | <ul> | |
| 456 | <li>It covers the agenda's files and the next 7 days: scheduled items, deadlines, plain active timestamps and date ranges with a time, that are not done.</li> | |
| 457 | <li>Each reminder comes the lead time before the entry's time: 12 minutes by default (<code class="verbatim">appt-message-warning-time</code>). An <code class="verbatim">APPT_WARNTIME</code> property on the entry, in minutes, overrides it.</li> | |
| 458 | <li>If the warning time has already passed when Orgstar sets a reminder but the entry has not started, the notification comes at once.</li> | |
| 459 | <li>At most 64 reminders are pending at a time, the earliest first.</li> | |
| 460 | <li>The notification shows the entry's text, its time, and its category. Clicking it opens the entry. Notifications also show while Orgstar is the active app.</li> | |
| 461 | </ul> | |
| 462 | <p>Orgstar updates the reminders a couple of seconds after you stop editing, when files change, and every hour. The agenda window shows how far ahead reminders are set. Reminders already set still arrive after you quit Orgstar; changes to your files are taken into account the next time it runs.</p> | |
| 463 | <p>Turn reminders on or off, and set the lead time from 0 to 120 minutes, in Settings ▸ Agenda; in <code class="verbatim">config.toml</code> the keys are <code class="verbatim">reminders</code> under <code class="verbatim">[orgstar]</code> (default <code class="verbatim">true</code>) and <code class="verbatim">appt-message-warning-time</code>. The first time, macOS asks whether Orgstar may post notifications; if you decline, the agenda says so, and you can change it in System Settings ▸ Notifications. The iOS app's reminders are described in <a href="14-ios.html">iOS</a>.</p> | |
| 464 | </main> | |
| 465 | <footer class="site"> | |
| 466 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 467 | </footer> | |
| 468 | </body> | |
| 469 | </html> | |
| \ No newline at end of file | ||
guide/07-agenda.html added +465
| @@ -0,0 +1,465 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>The agenda · Orgstar</title> | |
| 7 | <meta name="description" content="The agenda window, the TODO list, tag and property matches, saved views, filters, reminders and the board."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>The agenda</h1> | |
| 24 | <p class="lede">The agenda collects dated entries and TODO items from your agenda files into one list you can act on.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#opening-the-agenda">Opening the agenda</a></li> | |
| 29 | <li><a href="#agenda-files">Agenda files</a></li> | |
| 30 | <li><a href="#the-day-and-week-view">The day and week view</a> | |
| 31 | <ul> | |
| 32 | <li><a href="#moving-through-days">Moving through days</a></li> | |
| 33 | <li><a href="#what-appears-on-each-day">What appears on each day</a></li> | |
| 34 | <li><a href="#sorting">Sorting</a></li> | |
| 35 | <li><a href="#log-mode">Log mode</a></li> | |
| 36 | </ul></li> | |
| 37 | <li><a href="#diary-sexps">Diary sexps</a></li> | |
| 38 | <li><a href="#habits">Habits</a></li> | |
| 39 | <li><a href="#the-todo-list">The TODO list</a></li> | |
| 40 | <li><a href="#tag-and-property-matches">Tag and property matches</a> | |
| 41 | <ul> | |
| 42 | <li><a href="#tags">Tags</a></li> | |
| 43 | <li><a href="#properties">Properties</a></li> | |
| 44 | <li><a href="#keywords">keywords</a></li> | |
| 45 | </ul></li> | |
| 46 | <li><a href="#text-search">Text search</a></li> | |
| 47 | <li><a href="#views">Views</a></li> | |
| 48 | <li><a href="#filters">Filters</a></li> | |
| 49 | <li><a href="#the-prefix-and-line-layout">The prefix and line layout</a></li> | |
| 50 | <li><a href="#acting-on-entries">Acting on entries</a> | |
| 51 | <ul> | |
| 52 | <li><a href="#bulk-actions">Bulk actions</a></li> | |
| 53 | </ul></li> | |
| 54 | <li><a href="#reminders">Reminders</a></li> | |
| 55 | <li><a href="#the-board">The board</a> | |
| 56 | <ul> | |
| 57 | <li><a href="#table">Table</a></li> | |
| 58 | <li><a href="#kanban">Kanban</a></li> | |
| 59 | </ul></li> | |
| 60 | <li><a href="#the-agenda-on-ios">The agenda on iOS</a></li> | |
| 61 | </ul> | |
| 62 | </nav> | |
| 63 | <h2 id="opening-the-agenda">Opening the agenda</h2> | |
| 64 | <p>On the Mac the agenda is its own window. Open it with Window ▸ Agenda, or with the key for your preset:</p> | |
| 65 | <table> | |
| 66 | <thead> | |
| 67 | <tr><th>Preset</th><th>Key</th></tr> | |
| 68 | </thead> | |
| 69 | <tbody> | |
| 70 | <tr><td>Mac</td><td><code class="verbatim">⇧⌘A</code></td></tr> | |
| 71 | <tr><td>Emacs</td><td><code class="verbatim">C-c a</code> or <code class="verbatim">⇧⌘A</code></td></tr> | |
| 72 | <tr><td>Doom</td><td><code class="verbatim">SPC o a</code> (normal state), <code class="verbatim">C-c a</code> or <code class="verbatim">⇧⌘A</code></td></tr> | |
| 73 | </tbody> | |
| 74 | </table> | |
| 75 | <p>With <code class="verbatim">org-use-speed-commands</code> on, <code class="verbatim">v</code> at the start of a heading line opens it too (see <a href="03-keys.html">Keys</a>).</p> | |
| 76 | <p>The key opens the window directly. There is no <code class="verbatim">org-agenda</code> dispatcher; you choose what the window shows from the view menu at the left of its toolbar (see <a href="#views">Views</a>).</p> | |
| 77 | <p>Opening a timestamp with <code class="verbatim">org-open-at-point</code> (<code class="verbatim">C-c C-o</code> in the Emacs preset) opens the agenda on that timestamp's day, or on every day of a date range.</p> | |
| 78 | <p>On iOS the agenda is the first tab. See <a href="#the-agenda-on-ios">The agenda on iOS</a>.</p> | |
| 79 | <h2 id="agenda-files">Agenda files</h2> | |
| 80 | <p>Orgstar has no <code class="verbatim">org-agenda-files</code> list. The agenda reads every <code class="verbatim">.org</code> file at the top level of each folder you have added (see <a href="01-files-and-folders.html">Files and folders</a>). Files whose names start with a dot are left out, as <code class="verbatim">org-agenda-file-regexp</code> leaves them out.</p> | |
| 81 | <p>To include files in subfolders as well, turn on Settings ▸ Agenda ▸ Include files in subfolders, or set this in <code class="verbatim">config.toml</code>:</p> | |
| 82 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">orgstar</span><span class="punctuation definition table toml">]</span> | |
| 83 | <span class="variable other key toml">agenda-include-subfolders</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span></span></code></pre> | |
| 84 | <p>When a file is open in the editor, the agenda reads the buffer, so unsaved edits show. Other files are read from disk and cached until their modification date or size changes. A file that uses <code class="verbatim">#+SETUPFILE</code> is read again on every refresh, because its setup file may have changed.</p> | |
| 85 | <p>Within a file, the agenda skips:</p> | |
| 86 | <ul> | |
| 87 | <li>trees tagged <code class="verbatim">ARCHIVE</code>, and every entry in a file whose <code class="verbatim">#+FILETAGS</code> include <code class="verbatim">ARCHIVE</code>;</li> | |
| 88 | <li>commented trees (a heading whose title starts with <code class="verbatim">COMMENT</code>);</li> | |
| 89 | <li>everything below a skipped heading.</li> | |
| 90 | </ul> | |
| 91 | <p>An entry's category is the nearest <code class="verbatim">CATEGORY</code> property on it or an ancestor, else the file's <code class="verbatim">#+CATEGORY</code>, else the file name without <code class="verbatim">.org</code>.</p> | |
| 92 | <p>If no agenda file exists, the window says so.</p> | |
| 93 | <h2 id="the-day-and-week-view">The day and week view</h2> | |
| 94 | <p>The default view is <code class="verbatim">org-agenda-list</code>: a run of days, each with a header such as <code class="verbatim">Monday 5 October 2026 W41</code> (the ISO week number appears on Mondays).</p> | |
| 95 | <table> | |
| 96 | <thead> | |
| 97 | <tr><th>Setting</th><th>Default</th><th><code class="verbatim">config.toml</code></th><th>Range in Settings</th></tr> | |
| 98 | </thead> | |
| 99 | <tbody> | |
| 100 | <tr><td>Days shown</td><td>10</td><td><code class="verbatim">org-agenda-span = 10</code></td><td>1 to 366</td></tr> | |
| 101 | <tr><td>First day, relative to today</td><td>3 days before</td><td><code class="verbatim">org-agenda-start-day = "-3d"</code></td><td>0 to 14 days before</td></tr> | |
| 102 | </tbody> | |
| 103 | </table> | |
| 104 | <p>Both mirror the Emacs variables of the same name. The defaults are Doom's values, not plain Emacs's (a week starting today). <code class="verbatim">org-agenda-start-day</code> takes only day offsets such as <code class="verbatim">"-3d"</code> or <code class="verbatim">"+0d"</code>. There are no day, week or month view keys (<code class="verbatim">d</code>, <code class="verbatim">w</code>, <code class="verbatim">m</code> in Emacs) and no <code class="verbatim">org-agenda-start-on-weekday</code>: the span is a number of days and always begins at the configured offset.</p> | |
| 105 | <h3 id="moving-through-days">Moving through days</h3> | |
| 106 | <table> | |
| 107 | <thead> | |
| 108 | <tr><th>Key</th><th>Toolbar</th><th>Does</th><th>Org command</th></tr> | |
| 109 | </thead> | |
| 110 | <tbody> | |
| 111 | <tr><td><code class="verbatim">f</code></td><td>Later (›)</td><td>Moves forward by a whole span</td><td><code class="verbatim">org-agenda-later</code></td></tr> | |
| 112 | <tr><td><code class="verbatim">b</code></td><td>Earlier (‹)</td><td>Moves back by a whole span</td><td><code class="verbatim">org-agenda-earlier</code></td></tr> | |
| 113 | <tr><td><code class="verbatim">.</code></td><td>Today</td><td>Returns to the span around today</td><td><code class="verbatim">org-agenda-goto-today</code></td></tr> | |
| 114 | <tr><td><code class="verbatim">g</code>, <code class="verbatim">r</code></td><td></td><td>Refreshes, and reloads <code class="verbatim">views.toml</code></td><td><code class="verbatim">org-agenda-redo</code></td></tr> | |
| 115 | </tbody> | |
| 116 | </table> | |
| 117 | <p>The agenda also refreshes on its own when files change, when you edit an open buffer, and once a minute so the time grid and the current day stay correct.</p> | |
| 118 | <h3 id="what-appears-on-each-day">What appears on each day</h3> | |
| 119 | <p>The entries follow <code class="verbatim">org-agenda-get-day-entries</code> with Org's default entry types, in the formats Org prints.</p> | |
| 120 | <table> | |
| 121 | <thead> | |
| 122 | <tr><th>Entry</th><th>Where it appears</th><th>Leader</th></tr> | |
| 123 | </thead> | |
| 124 | <tbody> | |
| 125 | <tr><td><code class="verbatim">DEADLINE</code> on that day</td><td>On its day</td><td><code class="verbatim">Deadline:</code></td></tr> | |
| 126 | <tr><td><code class="verbatim">DEADLINE</code> in the future</td><td>On today, from the warning period before it</td><td><code class="verbatim">In 3 d.:</code></td></tr> | |
| 127 | <tr><td><code class="verbatim">DEADLINE</code> in the past, not done</td><td>On today</td><td><code class="verbatim">2 d. ago:</code></td></tr> | |
| 128 | <tr><td><code class="verbatim">SCHEDULED</code> on that day</td><td>On its day</td><td><code class="verbatim">Scheduled:</code></td></tr> | |
| 129 | <tr><td><code class="verbatim">SCHEDULED</code> in the past, not done</td><td>On today</td><td><code class="verbatim">Sched. 3x:</code></td></tr> | |
| 130 | <tr><td>Active timestamp <code class="verbatim"><2026-10-05 Mon></code></td><td>On its day; also in property drawers</td><td>none</td></tr> | |
| 131 | <tr><td>Repeating timestamp <code class="verbatim"><… +1w></code></td><td>On each occurrence within the span</td><td>none</td></tr> | |
| 132 | <tr><td>Date range <code class="verbatim"><…>--<…></code></td><td>On every day of the range</td><td><code class="verbatim">(2/5):</code> (day 2 of 5)</td></tr> | |
| 133 | <tr><td>Diary sexp <code class="verbatim">%%(…)</code> line or <code class="verbatim"><%%(…)></code></td><td>On each day the sexp applies; see <a href="#diary-sexps">Diary sexps</a></td><td>none</td></tr> | |
| 134 | <tr><td>Habit (<code class="verbatim">STYLE: habit</code>)</td><td>On today only, while not done; see <a href="#habits">Habits</a></td><td>none, with a consistency graph</td></tr> | |
| 135 | </tbody> | |
| 136 | </table> | |
| 137 | <p>Details:</p> | |
| 138 | <ul> | |
| 139 | <li>Deadline warnings use <code class="verbatim">org-deadline-warning-days</code>, fixed at 14 days. A <code class="verbatim">-Nd</code> cookie in the timestamp (<code class="verbatim"><2026-10-20 Tue -3d></code>) changes the warning for that deadline; <code class="verbatim">w</code>, <code class="verbatim">m</code> and <code class="verbatim">y</code> units work too.</li> | |
| 140 | <li>A <code class="verbatim">-Nd</code> cookie on a <code class="verbatim">SCHEDULED</code> timestamp delays it: the entry first shows N days after the scheduled date.</li> | |
| 141 | <li>Repeaters on <code class="verbatim">SCHEDULED</code> and <code class="verbatim">DEADLINE</code> timestamps (<code class="verbatim">+1w</code>, <code class="verbatim">++1w</code>, <code class="verbatim">.+1d</code>) make the entry show on the next occurrence on future days, as in Org.</li> | |
| 142 | <li>A done entry shows only on the day of its deadline or scheduled date, not as overdue.</li> | |
| 143 | <li>Inactive timestamps (<code class="verbatim">[…]</code>) never appear, except in log mode.</li> | |
| 144 | <li>Ranges in comment lines and inside source blocks are ignored, as in Org.</li> | |
| 145 | </ul> | |
| 146 | <p>Entries with a time of day sort into the day by time. On today, and on any day when the span is one day, a time grid is added when at least one entry has a time: lines at 8:00, 10:00, 12:00, 14:00, 16:00, 18:00 and 20:00, and on today a "now" line at the current time. The grid times are not configurable.</p> | |
| 147 | <p>A time can come from the timestamp (<code class="verbatim"><2026-10-05 Mon 14:00-15:30></code>) or from the heading text (<code class="verbatim">Call Ada 9:30am</code>), as <code class="verbatim">org-agenda-search-headline-for-time</code> allows. Times past 24:00, such as <code class="verbatim">25:30</code>, show as <code class="verbatim">+1:30</code>.</p> | |
| 148 | <h3 id="sorting">Sorting</h3> | |
| 149 | <p>Days are sorted as <code class="verbatim">org-agenda-sorting-strategy</code> sorts them by default for the agenda: <code class="verbatim">(habit-down time-up urgency-down category-keep)</code>. Habits go last; timed entries come first, earliest first; the rest by urgency, which combines priority with how overdue an entry is; ties keep file order. The TODO list and match views sort by urgency, then file order. The sorting is not configurable.</p> | |
| 150 | <h3 id="log-mode">Log mode</h3> | |
| 151 | <p>Press <code class="verbatim">l</code> to turn log mode (<code class="verbatim">org-agenda-log-mode</code>) on or off. Each day then also shows:</p> | |
| 152 | <ul> | |
| 153 | <li><code class="verbatim">Closed:</code> entries whose <code class="verbatim">CLOSED:</code> timestamp is on that day;</li> | |
| 154 | <li><code class="verbatim">Clocked: (1:30)</code> for each <code class="verbatim">CLOCK:</code> line that starts on that day, with the clock's range and duration.</li> | |
| 155 | </ul> | |
| 156 | <p>A note under a clock line (a list item directly below it) is added to the line after a <code class="verbatim">-</code>. These are the default <code class="verbatim">org-agenda-log-mode-items</code>, <code class="verbatim">(closed clock)</code>; state changes are not shown and there is no setting for that.</p> | |
| 157 | <h2 id="diary-sexps">Diary sexps</h2> | |
| 158 | <p>The agenda evaluates diary sexps as <code class="verbatim">org-diary-sexp-entry</code> does. They can appear as a line starting with <code class="verbatim">%%(</code> under a heading, as an active timestamp <code class="verbatim"><%%(…)></code>, or as a <code class="verbatim">SCHEDULED</code> or <code class="verbatim">DEADLINE</code> value.</p> | |
| 159 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Birthdays | |
| 160 | </span>%%(diary-anniversary 10 7 1990) Ada is %d years old | |
| 161 | %%(org-anniversary 1985 3 14) Bob turns %d | |
| 162 | ||
| 163 | <span class="markup heading org"><span class="punctuation definition heading org">*</span> Teaching | |
| 164 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> Algebra lecture | |
| 165 | </span><%%(org-class 2026 9 7 2026 12 18 1 41)></span></code></pre> | |
| 166 | <p>Lines before the first heading are ignored. A sexp that uses a function Orgstar doesn't have, or signals an error, doesn't apply on any day, as Emacs reports a bad sexp and moves on.</p> | |
| 167 | <table> | |
| 168 | <thead> | |
| 169 | <tr><th>Function</th><th>Applies</th><th>Date order</th></tr> | |
| 170 | </thead> | |
| 171 | <tbody> | |
| 172 | <tr><td><code class="verbatim">diary-date</code> <em>month day year</em></td><td>On matching dates; <code class="verbatim">t</code> or a list matches any or several</td><td>month day year</td></tr> | |
| 173 | <tr><td><code class="verbatim">diary-block</code> <em>m1 d1 y1 m2 d2 y2</em></td><td>Every day from the first date to the second</td><td>month day year</td></tr> | |
| 174 | <tr><td><code class="verbatim">diary-float</code> <em>month dayname n</em> [/day/]</td><td>The nth <em>dayname</em> (0 is Sunday) of the month; negative n counts from the end</td><td>month</td></tr> | |
| 175 | <tr><td><code class="verbatim">diary-anniversary</code> <em>month day</em> [/year/]</td><td>Each year on the date; <code class="verbatim">%d</code> is the count, <code class="verbatim">%s</code> its ordinal suffix</td><td>month day year</td></tr> | |
| 176 | <tr><td><code class="verbatim">diary-cyclic</code> <em>n month day year</em></td><td>Every n days from the date</td><td>month day year</td></tr> | |
| 177 | <tr><td><code class="verbatim">diary-remind</code> <em>sexp days</em></td><td>On the days before another sexp applies: <code class="verbatim">Reminder: Only 3 days until …</code></td><td>n/a</td></tr> | |
| 178 | <tr><td><code class="verbatim">org-anniversary</code> <em>year month day</em></td><td>As <code class="verbatim">diary-anniversary</code></td><td>year month day</td></tr> | |
| 179 | <tr><td><code class="verbatim">org-cyclic</code> <em>n year month day</em></td><td>As <code class="verbatim">diary-cyclic</code></td><td>year month day</td></tr> | |
| 180 | <tr><td><code class="verbatim">org-block</code> <em>y1 m1 d1 y2 m2 d2</em></td><td>As <code class="verbatim">diary-block</code></td><td>year month day</td></tr> | |
| 181 | <tr><td><code class="verbatim">org-date</code> <em>year month day</em></td><td>As <code class="verbatim">diary-date</code></td><td>year month day</td></tr> | |
| 182 | <tr><td><code class="verbatim">org-class</code> <em>y1 m1 d1 y2 m2 d2 dayname</em> [/skip-weeks…/]</td><td>On <em>dayname</em> between the dates, except the ISO weeks listed</td><td>year month day</td></tr> | |
| 183 | </tbody> | |
| 184 | </table> | |
| 185 | <p>The <code class="verbatim">diary-</code> functions read dates in <code class="verbatim">calendar-date-style</code> <code class="verbatim">american</code> (month, day, year); the <code class="verbatim">org-</code> functions use ISO order. <code class="verbatim">org-class</code> skip lists take ISO week numbers only; holiday names and <code class="verbatim">holidays</code> need the Emacs calendar's holiday lists and make the sexp fail.</p> | |
| 186 | <p>For your own expressions, the variables <code class="verbatim">date</code> (as <code class="verbatim">(month day year)</code>) and <code class="verbatim">entry</code> are bound, and these calendar functions are available: <code class="verbatim">calendar-extract-month</code>, <code class="verbatim">calendar-extract-day</code>, <code class="verbatim">calendar-extract-year</code>, <code class="verbatim">calendar-absolute-from-gregorian</code>, <code class="verbatim">calendar-gregorian-from-absolute</code>, <code class="verbatim">calendar-day-of-week</code>, <code class="verbatim">calendar-leap-year-p</code>, <code class="verbatim">calendar-last-day-of-month</code>, <code class="verbatim">calendar-date-equal</code>, <code class="verbatim">calendar-day-number</code>, <code class="verbatim">calendar-nth-named-absday</code>, <code class="verbatim">calendar-nth-named-day</code>, <code class="verbatim">calendar-iso-from-absolute</code>, <code class="verbatim">diary-ordinal-suffix</code> and <code class="verbatim">diary-make-date</code>. The evaluator also has the common special forms (<code class="verbatim">if</code>, <code class="verbatim">when</code>, <code class="verbatim">cond</code>, <code class="verbatim">and</code>, <code class="verbatim">or</code>, <code class="verbatim">let</code>, <code class="verbatim">progn</code> and others) and arithmetic. It is a small subset of Emacs Lisp, not Emacs.</p> | |
| 187 | <p>A sexp line that returns a string shows that string; one that returns a list of strings shows one line per string; otherwise the line's text after the sexp shows.</p> | |
| 188 | <h2 id="habits">Habits</h2> | |
| 189 | <p>An entry with the property <code class="verbatim">STYLE: habit</code> and a <code class="verbatim">SCHEDULED</code> timestamp with a repeater is a habit, as in <code class="verbatim">org-habit</code>:</p> | |
| 190 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Run | |
| 191 | </span>SCHEDULED: <span class="constant other timestamp org"><2026-10-05 Mon .+2d/4d></span> | |
| 192 | :PROPERTIES: | |
| 193 | :STYLE: habit | |
| 194 | :END: | |
| 195 | <span class="punctuation definition list org">- </span>State "DONE" from "TODO" <span class="constant other timestamp org">[2026-10-03 Sat 07:10]</span> | |
| 196 | <span class="punctuation definition list org">- </span>State "DONE" from "TODO" <span class="constant other timestamp org">[2026-10-01 Thu 07:05]</span></span></code></pre> | |
| 197 | <p>The repeater can be <code class="verbatim">+</code>, <code class="verbatim">++</code> or <code class="verbatim">.+</code>, with an optional <code class="verbatim">/Nd</code> maximum interval. Days the habit was done are read from <code class="verbatim">- State "DONE" … [date]</code> lines (for any done keyword) and <code class="verbatim">CLOSING NOTE [date]</code> lines in the entry.</p> | |
| 198 | <p>A habit appears only on today's agenda and not once it is done for the day. Its line carries the consistency graph: one cell per day for the 21 days before today and the 7 after (<code class="verbatim">org-habit-preceding-days</code> and <code class="verbatim">org-habit-following-days</code>), with <code class="verbatim">*</code> on days it was done and <code class="verbatim">!</code> on today. Cell colors follow org-habit's faces:</p> | |
| 199 | <table> | |
| 200 | <thead> | |
| 201 | <tr><th>Color</th><th>Meaning</th><th>Theme key</th></tr> | |
| 202 | </thead> | |
| 203 | <tbody> | |
| 204 | <tr><td>Blue</td><td>Not yet due</td><td><code class="verbatim">habit-clear</code></td></tr> | |
| 205 | <tr><td>Green</td><td>Due, within the allowed interval</td><td><code class="verbatim">habit-ready</code></td></tr> | |
| 206 | <tr><td>Yellow</td><td>Last day of the interval</td><td><code class="verbatim">habit-alert</code></td></tr> | |
| 207 | <tr><td>Red</td><td>Overdue</td><td><code class="verbatim">habit-overdue</code></td></tr> | |
| 208 | </tbody> | |
| 209 | </table> | |
| 210 | <p>Future days use lighter shades. Hover a cell to see its date. Habits sort after other entries.</p> | |
| 211 | <h2 id="the-todo-list">The TODO list</h2> | |
| 212 | <p>The built-in view TODO List is <code class="verbatim">org-todo-list</code>: every heading with a TODO keyword that is not a done keyword, sorted by urgency (priority first). The time-based skipping options (<code class="verbatim">org-agenda-todo-ignore-scheduled</code> and its relatives) are not supported; every open TODO appears, as with Org's defaults.</p> | |
| 213 | <p>A saved view can list specific keywords instead, done ones included, with <code class="verbatim">keywords = "WAIT|HOLD"</code> (see <a href="#views">Views</a>). This mirrors <code class="verbatim">C-u M-x org-todo-list</code> with a keyword argument.</p> | |
| 214 | <h2 id="tag-and-property-matches">Tag and property matches</h2> | |
| 215 | <p>Choose Match… from the view menu to list entries matching a match string, as <code class="verbatim">org-tags-view</code> (<code class="verbatim">m</code>) does, or TODO Match… to list only entries with an open TODO keyword (<code class="verbatim">M</code>). Type the match in the toolbar field and press Return.</p> | |
| 216 | <p>The syntax is <code class="verbatim">org-make-tags-matcher</code>'s:</p> | |
| 217 | <pre><code class="language-text">+work-boss|LEVEL>2+TODO="WAIT"/!NEXT</code></pre> | |
| 218 | <h3 id="tags">Tags</h3> | |
| 219 | <table> | |
| 220 | <thead> | |
| 221 | <tr><th>Form</th><th>Matches</th></tr> | |
| 222 | </thead> | |
| 223 | <tbody> | |
| 224 | <tr><td><code class="verbatim">work</code>, <code class="verbatim">+work</code></td><td>Entries with the tag</td></tr> | |
| 225 | <tr><td><code class="verbatim">-boss</code></td><td>Entries without the tag</td></tr> | |
| 226 | <tr><td><code class="verbatim">+work-boss</code></td><td>Both conditions (and)</td></tr> | |
| 227 | <tr><td><code class="verbatim">a&b</code></td><td><code class="verbatim">&</code> between terms is the same as <code class="verbatim">+</code></td></tr> | |
| 228 | <tr><td><code class="verbatim">{^proj}</code></td><td>Any tag matching the regular expression</td></tr> | |
| 229 | </tbody> | |
| 230 | </table> | |
| 231 | <p><code class="verbatim">work|home</code> matches either side: the vertical bar separates alternatives, and within an alternative, terms are joined by <code class="verbatim">+</code>, <code class="verbatim">-</code> or <code class="verbatim">&</code>. Tags include inherited tags and <code class="verbatim">#+FILETAGS</code>. Tag names compare exactly; regular expressions in braces are Emacs regexps, matched without case.</p> | |
| 232 | <h3 id="properties">Properties</h3> | |
| 233 | <p>A term can compare a property: <code class="verbatim">NAME op value</code>.</p> | |
| 234 | <table> | |
| 235 | <thead> | |
| 236 | <tr><th>Operator</th><th>Meaning</th></tr> | |
| 237 | </thead> | |
| 238 | <tbody> | |
| 239 | <tr><td><code class="verbatim">=</code>, <code class="verbatim">==</code></td><td>Equal</td></tr> | |
| 240 | <tr><td><code class="verbatim"><></code>, <code class="verbatim">!=</code>, <code class="verbatim">/=</code></td><td>Not equal</td></tr> | |
| 241 | <tr><td><code class="verbatim"><</code>, <code class="verbatim"><=</code></td><td>Less, less or equal</td></tr> | |
| 242 | <tr><td><code class="verbatim">></code>, <code class="verbatim">>=</code></td><td>Greater, greater or equal</td></tr> | |
| 243 | </tbody> | |
| 244 | </table> | |
| 245 | <p>The value decides how the comparison works:</p> | |
| 246 | <table> | |
| 247 | <thead> | |
| 248 | <tr><th>Value</th><th>Compared as</th></tr> | |
| 249 | </thead> | |
| 250 | <tbody> | |
| 251 | <tr><td><code class="verbatim">3</code>, <code class="verbatim">-1.5</code></td><td>Numbers; a missing or non-numeric property is 0</td></tr> | |
| 252 | <tr><td><code class="verbatim">"WAIT"</code></td><td>Strings</td></tr> | |
| 253 | <tr><td><code class="verbatim">{regexp}</code></td><td>Regular expression match; with <code class="verbatim"><></code>, <code class="verbatim">!=</code> or <code class="verbatim">/=</code> it must not match</td></tr> | |
| 254 | <tr><td><code class="verbatim">"<2026-10-01>"</code></td><td>Dates. Also <code class="verbatim">"<now>"</code>, <code class="verbatim">"<today>"</code>, <code class="verbatim">"<tomorrow>"</code>, <code class="verbatim">"<yesterday>"</code>, and offsets such as <code class="verbatim">"<-1w>"</code> or <code class="verbatim">"<+3d>"</code> (units <code class="verbatim">h</code> <code class="verbatim">d</code> <code class="verbatim">w</code> <code class="verbatim">m</code> <code class="verbatim">y</code>). Brackets may be <code class="verbatim">[…]</code>.</td></tr> | |
| 255 | </tbody> | |
| 256 | </table> | |
| 257 | <p>Follow the operator with <code class="verbatim">*</code> (<code class="verbatim">Effort>*1</code>) to require that the property exists; without it, a missing property compares as an empty string or 0.</p> | |
| 258 | <p>Names are case-insensitive. Prefix a character in a name with <code class="verbatim">\</code> to use it literally (<code class="verbatim">MY\-PROP</code>"x"=). Besides the entry's own property drawer, these special properties work:</p> | |
| 259 | <table> | |
| 260 | <thead> | |
| 261 | <tr><th>Name</th><th>Value</th></tr> | |
| 262 | </thead> | |
| 263 | <tbody> | |
| 264 | <tr><td><code class="verbatim">LEVEL</code></td><td>The heading's level</td></tr> | |
| 265 | <tr><td><code class="verbatim">TODO</code></td><td>The TODO keyword</td></tr> | |
| 266 | <tr><td><code class="verbatim">ITEM</code></td><td>The heading title</td></tr> | |
| 267 | <tr><td><code class="verbatim">PRIORITY</code></td><td>The priority letter, or the default priority</td></tr> | |
| 268 | <tr><td><code class="verbatim">CATEGORY</code></td><td>The entry's category</td></tr> | |
| 269 | <tr><td><code class="verbatim">FILE</code></td><td>The file's path</td></tr> | |
| 270 | <tr><td><code class="verbatim">TAGS</code></td><td>The heading's own tags, as <code class="verbatim">:a:b:</code></td></tr> | |
| 271 | <tr><td><code class="verbatim">ALLTAGS</code></td><td>All tags including inherited ones</td></tr> | |
| 272 | <tr><td><code class="verbatim">SCHEDULED</code>, <code class="verbatim">DEADLINE</code>, <code class="verbatim">CLOSED</code></td><td>The planning timestamp</td></tr> | |
| 273 | <tr><td><code class="verbatim">TIMESTAMP</code>, <code class="verbatim">TIMESTAMP_IA</code></td><td>The entry's first active or inactive timestamp</td></tr> | |
| 274 | </tbody> | |
| 275 | </table> | |
| 276 | <p>Properties are not inherited in matches (<code class="verbatim">org-use-property-inheritance</code> is nil). With a date value, <code class="verbatim"><></code> and its synonyms match dates that are equal, as Orgstar's comparison mirrors <code class="verbatim">org-time<></code> in Org 9.8.7; use <code class="verbatim"><</code> and <code class="verbatim">></code> for date ranges.</p> | |
| 277 | <h3 id="keywords"><span class="todo TODO">TODO</span> keywords</h3> | |
| 278 | <p>After the last <code class="verbatim">/</code> (one not followed by a quote), the match restricts TODO keywords:</p> | |
| 279 | <table> | |
| 280 | <thead> | |
| 281 | <tr><th>Form</th><th>Matches</th></tr> | |
| 282 | </thead> | |
| 283 | <tbody> | |
| 284 | <tr><td><code class="verbatim">/NEXT</code></td><td>Entries whose keyword is <code class="verbatim">NEXT</code></td></tr> | |
| 285 | <tr><td><code class="verbatim">/-WAIT</code></td><td>Any keyword but <code class="verbatim">WAIT</code>, and entries with none</td></tr> | |
| 286 | <tr><td><code class="verbatim">/{^W}</code></td><td>Keywords matching the regexp</td></tr> | |
| 287 | <tr><td><code class="verbatim">/!</code></td><td>Only entries with an open (not done) TODO keyword</td></tr> | |
| 288 | <tr><td><code class="verbatim">/!-WAIT-HOLD</code></td><td>Open TODO entries except those two</td></tr> | |
| 289 | </tbody> | |
| 290 | </table> | |
| 291 | <p><code class="verbatim">/TODO|NEXT</code> matches either keyword, and <code class="verbatim">/!NEXT|WAIT</code> either one while open. <code class="verbatim">/!</code> has the same effect as choosing TODO Match….</p> | |
| 292 | <h2 id="text-search">Text search</h2> | |
| 293 | <p>The agenda has no <code class="verbatim">org-search-view</code> (<code class="verbatim">s</code>). To search the text of your files, use Search Notes (<code class="verbatim">⇧⌘F</code>).</p> | |
| 294 | <h2 id="views">Views</h2> | |
| 295 | <p>The view menu lists the built-in views, Agenda and TODO List, then the views in <code class="verbatim">views.toml</code>, then Match… and TODO Match…. Saved views mirror <code class="verbatim">org-agenda-custom-commands</code>, with fewer options.</p> | |
| 296 | <p><code class="verbatim">views.toml</code> lives in the configuration folder beside <code class="verbatim">config.toml</code> (<code class="verbatim">~/.config/orgstar/</code> by default; see <a href="13-configuration.html">Configuration</a>). Each view is a <code class="verbatim">[[view]]</code> table:</p> | |
| 297 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">view</span><span class="punctuation definition table array toml">]]</span> | |
| 298 | <span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Fortnight<span class="punctuation definition string end toml">"</span></span> | |
| 299 | <span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>agenda<span class="punctuation definition string end toml">"</span></span> | |
| 300 | <span class="variable other key toml">span</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">14</span> | |
| 301 | <span class="variable other key toml">start</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">0</span> | |
| 302 | ||
| 303 | <span class="punctuation definition table array toml">[[</span><span class="entity name section toml">view</span><span class="punctuation definition table array toml">]]</span> | |
| 304 | <span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Waiting<span class="punctuation definition string end toml">"</span></span> | |
| 305 | <span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>todo<span class="punctuation definition string end toml">"</span></span> | |
| 306 | <span class="variable other key toml">keywords</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>WAIT|HOLD<span class="punctuation definition string end toml">"</span></span> | |
| 307 | ||
| 308 | <span class="punctuation definition table array toml">[[</span><span class="entity name section toml">view</span><span class="punctuation definition table array toml">]]</span> | |
| 309 | <span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Work<span class="punctuation definition string end toml">"</span></span> | |
| 310 | <span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>match<span class="punctuation definition string end toml">"</span></span> | |
| 311 | <span class="variable other key toml">match</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>+work-boss<span class="punctuation definition string end toml">"</span></span> | |
| 312 | ||
| 313 | <span class="punctuation definition table array toml">[[</span><span class="entity name section toml">view</span><span class="punctuation definition table array toml">]]</span> | |
| 314 | <span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Next at work<span class="punctuation definition string end toml">"</span></span> | |
| 315 | <span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>todo-match<span class="punctuation definition string end toml">"</span></span> | |
| 316 | <span class="variable other key toml">match</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>+work/NEXT<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 317 | <table> | |
| 318 | <thead> | |
| 319 | <tr><th>Key</th><th>Applies to</th><th>Meaning</th></tr> | |
| 320 | </thead> | |
| 321 | <tbody> | |
| 322 | <tr><td><code class="verbatim">name</code></td><td>all, required</td><td>The name in the view menu</td></tr> | |
| 323 | <tr><td><code class="verbatim">type</code></td><td>all</td><td><code class="verbatim">agenda</code> (the default), <code class="verbatim">todo</code>, <code class="verbatim">match</code> or <code class="verbatim">todo-match</code></td></tr> | |
| 324 | <tr><td><code class="verbatim">span</code></td><td><code class="verbatim">agenda</code></td><td>Days shown; the setting when omitted</td></tr> | |
| 325 | <tr><td><code class="verbatim">start</code></td><td><code class="verbatim">agenda</code></td><td>First day as an integer number of days from today (<code class="verbatim">-3</code>, <code class="verbatim">0</code>); the setting when omitted</td></tr> | |
| 326 | <tr><td><code class="verbatim">keywords</code></td><td><code class="verbatim">todo</code></td><td>Keywords separated by the vertical bar; all open TODOs when omitted</td></tr> | |
| 327 | <tr><td><code class="verbatim">match</code></td><td><code class="verbatim">match</code>, <code class="verbatim">todo-match</code>, required</td><td>A match string as in <a href="#tag-and-property-matches">Tag and property matches</a>; <code class="verbatim">todo-match</code> keeps only open TODO entries</td></tr> | |
| 328 | </tbody> | |
| 329 | </table> | |
| 330 | <p>Note that <code class="verbatim">start</code> is a plain integer here, while <code class="verbatim">org-agenda-start-day</code> in <code class="verbatim">config.toml</code> is a string such as <code class="verbatim">"-3d"</code>.</p> | |
| 331 | <p>Not supported: block agendas (several views in one), per-view settings such as <code class="verbatim">org-agenda-skip-function</code> or a different prefix format, <code class="verbatim">stuck</code> projects, and search views. The views load when the window opens and again on <code class="verbatim">g</code> or <code class="verbatim">r</code>. A problem in the file, such as a missing <code class="verbatim">name</code> or an unknown <code class="verbatim">type</code>, shows in the status line at the bottom of the window, and the remaining views still load.</p> | |
| 332 | <h2 id="filters">Filters</h2> | |
| 333 | <p>Filters hide lines without changing the view, as <code class="verbatim">org-agenda-filter</code> does. Time grid lines always stay. The active filter shows in the status line at the bottom of the window as <code class="verbatim">Filter: …</code>.</p> | |
| 334 | <table> | |
| 335 | <thead> | |
| 336 | <tr><th>Key</th><th>Does</th><th>Org command</th></tr> | |
| 337 | </thead> | |
| 338 | <tbody> | |
| 339 | <tr><td><code class="verbatim">\</code></td><td>Asks for a tag filter</td><td><code class="verbatim">org-agenda-filter-by-tag</code></td></tr> | |
| 340 | <tr><td><code class="verbatim"><</code></td><td>Keeps only the selected line's category; again removes it</td><td><code class="verbatim">org-agenda-filter-by-category</code></td></tr> | |
| 341 | <tr><td><code class="verbatim">=</code></td><td>Asks for a regexp filter</td><td><code class="verbatim">org-agenda-filter-by-regexp</code></td></tr> | |
| 342 | </tbody> | |
| 343 | </table> | |
| 344 | <p>The vertical bar key, <code class="verbatim">|</code>, removes every filter (<code class="verbatim">org-agenda-filter-remove-all</code>).</p> | |
| 345 | <p>The combined filter <code class="verbatim">/</code> reads terms such as:</p> | |
| 346 | <pre><code class="language-text">+work-phone<2:00/report/</code></pre> | |
| 347 | <ul> | |
| 348 | <li><code class="verbatim">+word</code> keeps and <code class="verbatim">-word</code> drops lines. A word without a sign keeps.</li> | |
| 349 | <li>A word is a tag if a line in the view has that tag, else a category if a line has that category; otherwise it is ignored and the status line says so. Quote a category that contains <code class="verbatim">-</code>: <code class="verbatim">"my-cat"</code>.</li> | |
| 350 | <li><code class="verbatim"><0:30</code>, <code class="verbatim">>1:00</code> and <code class="verbatim">=1:00</code> compare the entry's <code class="verbatim">Effort</code> property. Entries without an effort count as longer than any effort, as with <code class="verbatim">org-agenda-sort-noeffort-is-high</code> t. Durations can be <code class="verbatim">H:MM</code>, minutes, or units such as <code class="verbatim">1h 30min</code> or <code class="verbatim">2d</code>.</li> | |
| 351 | <li><code class="verbatim">/regexp/</code> keeps lines whose text matches; <code class="verbatim">-/regexp/</code> drops them. Matching ignores case.</li> | |
| 352 | <li>Starting the input with <code class="verbatim">+</code> followed by another sign (<code class="verbatim">++urgent</code>) adds to the current filter instead of replacing it.</li> | |
| 353 | </ul> | |
| 354 | <p>With two or more <code class="verbatim">+</code> categories, a line may have any of them. Tag terms all have to hold.</p> | |
| 355 | <p>The <code class="verbatim">/</code> prompt starts with the whole current filter written in this form, every term with its sign: categories, then tags, efforts and regexps, with categories that contain <code class="verbatim">-</code> in quotes. Pressing <code class="verbatim">Return</code> on it unchanged keeps the same filter.</p> | |
| 356 | <p>The <code class="verbatim">\</code> prompt reads every word as a tag, whether or not a line has it; there, <code class="verbatim">{regexp}</code> matches any tag that matches the regexp. The <code class="verbatim">=</code> prompt takes one regexp, with a leading <code class="verbatim">-</code> to drop matches. The <code class="verbatim">_</code> prompt takes one comparison such as <code class="verbatim"><0:30</code>.</p> | |
| 357 | <h2 id="the-prefix-and-line-layout">The prefix and line layout</h2> | |
| 358 | <p>Each line shows the category, the time, the leader (<code class="verbatim">Deadline:</code>, <code class="verbatim">In 3 d.:</code>, <code class="verbatim">(2/5):</code>), the heading with its TODO keyword colored, the habit graph if any, and the tags.</p> | |
| 359 | <p>To change what comes before the heading, set <code class="verbatim">org-agenda-prefix-format</code> in <code class="verbatim">config.toml</code>:</p> | |
| 360 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">org-agenda-prefix-format</span><span class="punctuation definition table toml">]</span> | |
| 361 | <span class="variable other key toml">agenda</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span> %i %-12:c%?-12t% s<span class="punctuation definition string end toml">"</span></span> | |
| 362 | <span class="variable other key toml">todo</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span> %i %-12:c<span class="punctuation definition string end toml">"</span></span> | |
| 363 | <span class="variable other key toml">tags</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span> %i %-12:c<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 364 | <p>These are the defaults. <code class="verbatim">agenda</code> applies to the day view, <code class="verbatim">todo</code> to the TODO list, and <code class="verbatim">tags</code> to match views. When a format differs from its default, the agenda shows the prefix as Emacs prints it, in a monospaced font, instead of its own columns.</p> | |
| 365 | <table> | |
| 366 | <thead> | |
| 367 | <tr><th>Field</th><th>Shows</th></tr> | |
| 368 | </thead> | |
| 369 | <tbody> | |
| 370 | <tr><td><code class="verbatim">%c</code></td><td>The category</td></tr> | |
| 371 | <tr><td><code class="verbatim">%t</code></td><td>The time of day, or the time range</td></tr> | |
| 372 | <tr><td><code class="verbatim">%s</code></td><td>The leader: <code class="verbatim">Scheduled:</code>, <code class="verbatim">Deadline:</code>, <code class="verbatim">In 3 d.:</code> and so on</td></tr> | |
| 373 | <tr><td><code class="verbatim">%e</code></td><td>The <code class="verbatim">Effort</code> property</td></tr> | |
| 374 | <tr><td><code class="verbatim">%l</code></td><td>One space per heading level</td></tr> | |
| 375 | <tr><td><code class="verbatim">%b</code></td><td>The outline path above the heading, each title followed by <code class="verbatim">-></code></td></tr> | |
| 376 | <tr><td><code class="verbatim">%T</code></td><td>The item's last tag, counting inherited tags</td></tr> | |
| 377 | <tr><td><code class="verbatim">%i</code></td><td>The category icon; always empty in Orgstar</td></tr> | |
| 378 | </tbody> | |
| 379 | </table> | |
| 380 | <p>Each field takes Org's modifiers: <code class="verbatim">%-12c</code> pads to 12 columns on the right (<code class="verbatim">%12c</code> on the left); <code class="verbatim">%-12.6c</code> limits a category to 5 characters; <code class="verbatim">%?t</code> leaves the field out entirely when empty; a punctuation character after the width (<code class="verbatim">%-12:c</code>) is added after a non-empty value. When the format contains <code class="verbatim">%t</code>, times move out of the heading text into the prefix, as <code class="verbatim">org-agenda-remove-times-when-in-prefix</code> does. <code class="verbatim">%(…)</code> Lisp forms are accepted but always empty.</p> | |
| 381 | <p>Colors come from the theme keys <code class="verbatim">agenda-background</code>, <code class="verbatim">agenda-date</code>, <code class="verbatim">agenda-today</code>, <code class="verbatim">agenda-time</code>, <code class="verbatim">agenda-category</code>, <code class="verbatim">agenda-deadline</code>, <code class="verbatim">agenda-upcoming</code>, <code class="verbatim">agenda-scheduled</code> and <code class="verbatim">agenda-scheduled-past</code> (see <a href="13-configuration.html">Configuration</a>).</p> | |
| 382 | <h2 id="acting-on-entries">Acting on entries</h2> | |
| 383 | <p>Select a line with the arrow keys or the mouse. These keys work in the agenda window in every keymap preset; they are fixed and are not read from <code class="verbatim">keymap.toml</code>.</p> | |
| 384 | <table> | |
| 385 | <thead> | |
| 386 | <tr><th>Key</th><th>Does</th><th>Org command</th></tr> | |
| 387 | </thead> | |
| 388 | <tbody> | |
| 389 | <tr><td><code class="verbatim">RET</code> or double click</td><td>Shows the entry in the main window</td><td><code class="verbatim">org-agenda-switch-to</code></td></tr> | |
| 390 | <tr><td><code class="verbatim">t</code> or <code class="verbatim">C-c C-t</code></td><td>Changes the TODO state, as in the editor</td><td><code class="verbatim">org-agenda-todo</code></td></tr> | |
| 391 | <tr><td><code class="verbatim">+</code>, <code class="verbatim">-</code></td><td>Raises or lowers the priority</td><td><code class="verbatim">org-agenda-priority-up=/</code>-down=</td></tr> | |
| 392 | <tr><td><code class="verbatim">:</code> or <code class="verbatim">C-c C-q</code></td><td>Sets tags</td><td><code class="verbatim">org-agenda-set-tags</code></td></tr> | |
| 393 | <tr><td><code class="verbatim">C-c C-s</code></td><td>Schedules</td><td><code class="verbatim">org-agenda-schedule</code></td></tr> | |
| 394 | <tr><td><code class="verbatim">C-c C-d</code></td><td>Sets a deadline</td><td><code class="verbatim">org-agenda-deadline</code></td></tr> | |
| 395 | <tr><td><code class="verbatim">S-<right></code>, <code class="verbatim">S-<left></code> (<code class="verbatim">⇧→</code>, <code class="verbatim">⇧←</code>)</td><td>Moves the date the line is listed for by a day</td><td><code class="verbatim">org-agenda-date-later=/</code>-earlier=</td></tr> | |
| 396 | <tr><td><code class="verbatim">I</code></td><td>Clocks in</td><td><code class="verbatim">org-agenda-clock-in</code></td></tr> | |
| 397 | <tr><td><code class="verbatim">O</code></td><td>Clocks out</td><td><code class="verbatim">org-agenda-clock-out</code></td></tr> | |
| 398 | <tr><td><code class="verbatim">X</code></td><td>Cancels the clock</td><td><code class="verbatim">org-agenda-clock-cancel</code></td></tr> | |
| 399 | <tr><td><code class="verbatim">C-c C-w</code></td><td>Refiles</td><td><code class="verbatim">org-agenda-refile</code></td></tr> | |
| 400 | <tr><td><code class="verbatim">$</code>, <code class="verbatim">C-c $</code>, <code class="verbatim">C-c C-x C-s</code></td><td>Archives</td><td><code class="verbatim">org-agenda-archive</code></td></tr> | |
| 401 | </tbody> | |
| 402 | </table> | |
| 403 | <p><code class="verbatim">t</code> follows <code class="verbatim">org-todo</code>: with fast-selection keys in your TODO keywords it asks for the state, otherwise it cycles (see <a href="05-todos-and-tags.html">TODOs and tags</a>). Questions an action needs, such as a date for <code class="verbatim">C-c C-s</code> or a note on a state change, appear in the agenda window. Dates take the same input as in the editor (see <a href="06-dates-and-clocking.html">Dates, scheduling and clocking</a>). <code class="verbatim">S-<right></code> and <code class="verbatim">S-<left></code> work only on deadline, scheduled and timestamp lines; they change the timestamp the line comes from.</p> | |
| 404 | <p><code class="verbatim">C-c C-w</code> brings the main window forward and asks for the target there, where the target list is searchable.</p> | |
| 405 | <p><code class="verbatim">I</code> clocks in as Clock In does, so with no clock running it first asks about open clocks, in the main window's echo area. See <a href="06-dates-and-clocking.html">Dates, scheduling and clocking</a>.</p> | |
| 406 | <p>Each action finds the entry again by its heading line before it changes anything, so an action on a line whose entry has since moved or changed reports that rather than editing the wrong text. Edits go through the open buffer when the file is open, and through the file otherwise.</p> | |
| 407 | <h3 id="bulk-actions">Bulk actions</h3> | |
| 408 | <table> | |
| 409 | <thead> | |
| 410 | <tr><th>Key</th><th>Does</th><th>Org command</th></tr> | |
| 411 | </thead> | |
| 412 | <tbody> | |
| 413 | <tr><td><code class="verbatim">m</code></td><td>Marks the selected entry (shown with <code class="verbatim">›</code>)</td><td><code class="verbatim">org-agenda-bulk-mark</code></td></tr> | |
| 414 | <tr><td><code class="verbatim">u</code></td><td>Unmarks it</td><td><code class="verbatim">org-agenda-bulk-unmark</code></td></tr> | |
| 415 | <tr><td><code class="verbatim">U</code></td><td>Unmarks everything</td><td><code class="verbatim">org-agenda-bulk-unmark-all</code></td></tr> | |
| 416 | <tr><td><code class="verbatim">B</code></td><td>Asks for an action on every marked entry</td><td><code class="verbatim">org-agenda-bulk-action</code></td></tr> | |
| 417 | </tbody> | |
| 418 | </table> | |
| 419 | <p><code class="verbatim">B</code> offers <code class="verbatim">$</code> archive, <code class="verbatim">r</code> refile, <code class="verbatim">t</code> set a TODO state (typed; empty for none), <code class="verbatim">+</code> add a tag, <code class="verbatim">-</code> remove a tag, <code class="verbatim">s</code> schedule and <code class="verbatim">d</code> set a deadline. Type the letter and press OK. Entries that changed since they were marked are skipped and counted in the status line. An action that needs a further answer per entry, such as a state-change note, is not run in bulk; the status line tells you to run it on the entry.</p> | |
| 420 | <h2 id="reminders">Reminders</h2> | |
| 421 | <p>Orgstar can post a notification before each timed entry, as <code class="verbatim">org-agenda-to-appt</code> hands entries to <code class="verbatim">appt</code>. Reminders cover the next 7 days and include deadline, scheduled, plain timestamp and range lines that have a time of day and are not done. Overdue items and upcoming-deadline warnings don't get reminders.</p> | |
| 422 | <table> | |
| 423 | <thead> | |
| 424 | <tr><th>Setting</th><th>Default</th><th><code class="verbatim">config.toml</code></th></tr> | |
| 425 | </thead> | |
| 426 | <tbody> | |
| 427 | <tr><td>Notify before timed entries</td><td>on</td><td><code class="verbatim">reminders = true</code> under <code class="verbatim">[orgstar]</code></td></tr> | |
| 428 | <tr><td>Minutes of warning</td><td>12</td><td><code class="verbatim">appt-message-warning-time = 12</code></td></tr> | |
| 429 | </tbody> | |
| 430 | </table> | |
| 431 | <p>Both are in Settings ▸ Agenda. An entry's <code class="verbatim">APPT_WARNTIME</code> property, in minutes, overrides the warning time for that entry. If the warning time has already passed but the entry hasn't started, the reminder fires at once.</p> | |
| 432 | <p>The notification's title is the heading; its body is the time, the leader if any, and the category, such as <code class="verbatim">14:00 · Scheduled: · work</code>. Clicking it shows the entry in the main window.</p> | |
| 433 | <p>On the Mac, reminders are updated two seconds after edits stop, when files change, and every hour. At most 64 are set, the earliest first. The agenda's status line says how far ahead they are set, or that notifications are off for Orgstar in System Settings. Turning reminders off removes the pending ones.</p> | |
| 434 | <h2 id="the-board">The board</h2> | |
| 435 | <p>The board shows the entries of your agenda files as a table or as kanban columns. It has no Org equivalent; the table is close to Org's column view across files. Open it with Window ▸ Board (<code class="verbatim">⇧⌘B</code>). It reads the same files as the agenda, including the subfolder setting.</p> | |
| 436 | <p>The toolbar has:</p> | |
| 437 | <ul> | |
| 438 | <li>a Table / Kanban switch;</li> | |
| 439 | <li>a match field, with the syntax of <a href="#tag-and-property-matches">Tag and property matches</a>. When empty, the board shows every entry with a TODO keyword;</li> | |
| 440 | <li>in table mode, a field of property names to show as extra columns, separated by commas (default <code class="verbatim">EFFORT</code>).</li> | |
| 441 | </ul> | |
| 442 | <p>These three choices are remembered by the app; they are not in <code class="verbatim">config.toml</code>.</p> | |
| 443 | <h3 id="table">Table</h3> | |
| 444 | <p>Columns: TODO, priority, title, tags, scheduled, deadline, your property columns, and the file. Click a column header to sort (the property columns don't sort). The TODO column sorts by the keyword's order in your sequences. The context menu on a row offers Set TODO (a keyword or None), Set Property… (asked in the main window as <code class="verbatim">NAME value</code>) and Open. Double-click a row to open the entry.</p> | |
| 445 | <h3 id="kanban">Kanban</h3> | |
| 446 | <p>Each TODO keyword your files use gets a column, in sequence order, done keywords included. A card shows the priority and title, the category and tags, and the deadline (in red) or the scheduled date. Drag a card to another column to set that keyword; this is the same edit as changing the state in the editor, so logging and state-change notes apply (a note is asked for in the main window). Double-click a card to open its entry. With VoiceOver, each card has a Move to … action for each other column.</p> | |
| 447 | <p>With a match that includes entries without a TODO keyword, those entries appear in the table but not on the kanban board, which has no column for them.</p> | |
| 448 | <p>The board is not available on iOS.</p> | |
| 449 | <h2 id="the-agenda-on-ios">The agenda on iOS</h2> | |
| 450 | <p>The Agenda tab shows the same views from the same files, using the settings in the synced <code class="verbatim">config.toml</code> and the views in <code class="verbatim">views.toml</code> (see <a href="14-ios.html">iOS</a>). Differences from the Mac:</p> | |
| 451 | <ul> | |
| 452 | <li>The Views menu lists the built-in views, your saved views, and Tags and Properties…, which asks for a match string. There is no TODO-only match from the menu; use <code class="verbatim">/!</code> in the match or a <code class="verbatim">todo-match</code> view. Today, Earlier and Later are in the same menu.</li> | |
| 453 | <li>Pull down to refresh.</li> | |
| 454 | <li>The Filter button opens a sheet: type a filter as for <code class="verbatim">/</code>, or tap a tag or category to cycle between Keep, Leave out and no filter.</li> | |
| 455 | <li>Tap an entry to open it. Swipe left on an open TODO to mark it done with the first done keyword of its sequence, as the file defines its keywords: the default keywords from <code class="verbatim">config.toml</code>, the file's own <code class="verbatim">#+TODO</code> lines, and those of its setup files, with unsaved edits in an open buffer included.</li> | |
| 456 | <li>Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile… and Archive….</li> | |
| 457 | <li>There are no keyboard commands, time grid lines, habit graphs, log mode, bulk marks or custom prefix formats.</li> | |
| 458 | <li>Reminders are set while the app is open. iOS allows at most 64 pending notifications and the app can't add more while it isn't running, so the agenda's footer says how far ahead they go and asks you to open Orgstar to set later ones.</li> | |
| 459 | </ul> | |
| 460 | </main> | |
| 461 | <footer class="site"> | |
| 462 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 463 | </footer> | |
| 464 | </body> | |
| 465 | </html> | |
| \ No newline at end of file | ||
guide/08-capture.html added +340
| @@ -0,0 +1,340 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Capture · Orgstar</title> | |
| 7 | <meta name="description" content="Capture templates, the capture window, date trees, org-protocol, Shortcuts and the iOS share sheet."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Capture</h1> | |
| 24 | <p class="lede">Capture files a note, task or link into the right place in your org files without leaving what you are doing.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#starting-a-capture">Starting a capture</a></li> | |
| 29 | <li><a href="#the-capture-window">The capture window</a></li> | |
| 30 | <li><a href="#capture-templates">Capture templates</a> | |
| 31 | <ul> | |
| 32 | <li><a href="#keys">Keys</a></li> | |
| 33 | <li><a href="#targets">Targets</a></li> | |
| 34 | <li><a href="#template-types">Template types</a></li> | |
| 35 | <li><a href="#clocking-while-capturing">Clocking while capturing</a></li> | |
| 36 | </ul></li> | |
| 37 | <li><a href="#template-escapes">Template escapes</a> | |
| 38 | <ul> | |
| 39 | <li><a href="#inserted-values">Inserted values</a></li> | |
| 40 | <li><a href="#prompts">Prompts</a></li> | |
| 41 | <li><a href="#escaping-and-unsupported-escapes">Escaping and unsupported escapes</a></li> | |
| 42 | </ul></li> | |
| 43 | <li><a href="#date-trees">Date trees</a></li> | |
| 44 | <li><a href="#org-protocol">org-protocol</a> | |
| 45 | <ul> | |
| 46 | <li><a href="#capture">capture</a></li> | |
| 47 | <li><a href="#store-link">store-link</a></li> | |
| 48 | <li><a href="#bookmarklets">Bookmarklets</a></li> | |
| 49 | </ul></li> | |
| 50 | <li><a href="#shortcuts">Shortcuts</a></li> | |
| 51 | <li><a href="#capture-on-ios">Capture on iOS</a> | |
| 52 | <ul> | |
| 53 | <li><a href="#the-share-sheet">The share sheet</a></li> | |
| 54 | </ul></li> | |
| 55 | <li><a href="#importing-templates-from-emacs">Importing templates from Emacs</a></li> | |
| 56 | </ul> | |
| 57 | </nav> | |
| 58 | <h2 id="starting-a-capture">Starting a capture</h2> | |
| 59 | <p>Capture mirrors <code class="verbatim">org-capture</code>. Start it from anywhere in the app:</p> | |
| 60 | <table> | |
| 61 | <thead> | |
| 62 | <tr><th>Preset</th><th>Key</th></tr> | |
| 63 | </thead> | |
| 64 | <tbody> | |
| 65 | <tr><td>Mac</td><td><code class="verbatim">⇧⌘N</code> (File ▸ Capture…)</td></tr> | |
| 66 | <tr><td>Emacs</td><td><code class="verbatim">C-c c</code> or <code class="verbatim">⇧⌘N</code></td></tr> | |
| 67 | <tr><td>Doom</td><td><code class="verbatim">SPC X</code> (normal state), <code class="verbatim">C-c c</code> or <code class="verbatim">⇧⌘N</code></td></tr> | |
| 68 | </tbody> | |
| 69 | </table> | |
| 70 | <p><code class="verbatim">⌃⌥Space</code> opens the capture window from any app, with Orgstar in the background. Turn it off in Settings ▸ Capture, or in <code class="verbatim">config.toml</code>:</p> | |
| 71 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">orgstar</span><span class="punctuation definition table toml">]</span> | |
| 72 | <span class="variable other key toml">global-capture-hotkey</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">false</span></span></code></pre> | |
| 73 | <p>The shortcut is registered as a system hot key and needs no accessibility permission.</p> | |
| 74 | <p>Captures can also arrive from a browser through org-protocol, from Shortcuts, and on iOS from the share sheet; see the sections below.</p> | |
| 75 | <h2 id="the-capture-window">The capture window</h2> | |
| 76 | <p>A capture goes through up to three steps.</p> | |
| 77 | <ol> | |
| 78 | <li><strong>Choose a template.</strong> The window lists your templates with their keys and targets. Type a template's key, or click it. For a key of several characters, such as <code class="verbatim">wb</code>, each character you type narrows the list to the templates whose keys start with what you typed, and the header shows the keys so far (<code class="verbatim">Capture: w</code>). <code class="verbatim">Delete</code> removes the last key typed. The template is chosen as soon as the keys match one.</li> | |
| 79 | <li><strong>Answer its questions.</strong> If the template has prompts (<code class="verbatim">%^{…}</code>, <code class="verbatim">%^g</code>, <code class="verbatim">%^t</code> and the others below), they appear as a form. Leave a field empty for its default. Press Return (Continue) to go on.</li> | |
| 80 | <li><strong>Edit and file.</strong> The filled template appears in an editor, headed with the template's name and target, with the cursor where <code class="verbatim">%?</code> was. Press <code class="verbatim">⌘Return</code> (File It) to file it.</li> | |
| 81 | </ol> | |
| 82 | <p>Press Esc (Cancel) at any step to close the window without filing anything, as <code class="verbatim">org-capture-kill</code> does.</p> | |
| 83 | <p>Filing, the equivalent of <code class="verbatim">org-capture-finalize</code>, places the text in its target and saves it through the open buffer if the file is open, or into the file otherwise. A target file that doesn't exist is created, with its folders. The status line in the main window then says where the entry went.</p> | |
| 84 | <p>If filing fails, for example because a heading on an <code class="verbatim">olp</code> path is missing, the window stays open with your text and shows the error in red below it, so you can try again after fixing the file or cancel.</p> | |
| 85 | <p>Limits compared with Emacs:</p> | |
| 86 | <ul> | |
| 87 | <li>The editor is a plain text editor. Org editing commands and keys such as <code class="verbatim">C-c C-c</code> and <code class="verbatim">C-c C-k</code> don't work in it; use <code class="verbatim">⌘Return</code> and Esc.</li> | |
| 88 | <li>There is no refile from the capture window (<code class="verbatim">C-c C-w</code> in an Emacs capture buffer). Capture to an inbox heading and refile from the agenda or the editor.</li> | |
| 89 | <li>The target is not shown while you edit (the capture buffer in Emacs is narrowed to the new entry in the target file).</li> | |
| 90 | </ul> | |
| 91 | <h2 id="capture-templates">Capture templates</h2> | |
| 92 | <p>Templates live in <code class="verbatim">capture.toml</code> in the configuration folder (<code class="verbatim">~/.config/orgstar/capture.toml</code> by default; see <a href="13-configuration.html">Configuration</a>). Settings ▸ Capture shows its path. Each template is a <code class="verbatim">[[template]]</code> table:</p> | |
| 93 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">template</span><span class="punctuation definition table array toml">]]</span> | |
| 94 | <span class="variable other key toml">key</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>t<span class="punctuation definition string end toml">"</span></span> | |
| 95 | <span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Personal todo<span class="punctuation definition string end toml">"</span></span> | |
| 96 | <span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>entry<span class="punctuation definition string end toml">"</span></span> | |
| 97 | <span class="variable other key toml">file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>todo.org<span class="punctuation definition string end toml">"</span></span> | |
| 98 | <span class="variable other key toml">headline</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Inbox<span class="punctuation definition string end toml">"</span></span> | |
| 99 | <span class="variable other key toml">template</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>* TODO %?<span class="constant character escape toml">\n</span>%i<span class="constant character escape toml">\n</span>%a<span class="punctuation definition string end toml">"</span></span> | |
| 100 | <span class="variable other key toml">prepend</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">false</span></span></code></pre> | |
| 101 | <p>The file is read each time the capture window opens. If it doesn't exist, or none of its templates is valid, these two built-in templates are used:</p> | |
| 102 | <table> | |
| 103 | <thead> | |
| 104 | <tr><th>Key</th><th>Name</th><th>Target</th><th>Template</th></tr> | |
| 105 | </thead> | |
| 106 | <tbody> | |
| 107 | <tr><td><code class="verbatim">t</code></td><td>Personal todo</td><td><code class="verbatim">todo.org</code>, heading <code class="verbatim">Inbox</code></td><td><code class="verbatim">* TODO %?\n%i\n%a</code></td></tr> | |
| 108 | <tr><td><code class="verbatim">n</code></td><td>Personal notes</td><td><code class="verbatim">notes.org</code>, heading <code class="verbatim">Inbox</code></td><td><code class="verbatim">* %u %?\n%i\n%a</code></td></tr> | |
| 109 | </tbody> | |
| 110 | </table> | |
| 111 | <p>A problem in the file, such as a table without a key, shows in red at the bottom of the window; the other templates still load.</p> | |
| 112 | <p>Templates are a flat list. Keys of several characters are typed one character at a time, as in Emacs, but Emacs's template groups (an entry with only a key and a description) have no equivalent: the list shows every template whose key starts with what you typed.</p> | |
| 113 | <h3 id="keys">Keys</h3> | |
| 114 | <table> | |
| 115 | <thead> | |
| 116 | <tr><th>Key</th><th>Value</th><th>Meaning</th><th>Org property</th></tr> | |
| 117 | </thead> | |
| 118 | <tbody> | |
| 119 | <tr><td><code class="verbatim">key</code></td><td>string, required</td><td>What you press to choose the template</td><td>key</td></tr> | |
| 120 | <tr><td><code class="verbatim">name</code></td><td>string</td><td>The name in the list; the key when omitted</td><td>description</td></tr> | |
| 121 | <tr><td><code class="verbatim">type</code></td><td>string</td><td><code class="verbatim">entry</code> (the default), <code class="verbatim">item</code>, <code class="verbatim">checkitem</code>, <code class="verbatim">plain</code> or <code class="verbatim">table-line</code></td><td>type</td></tr> | |
| 122 | <tr><td><code class="verbatim">template</code></td><td>string, required</td><td>The text to fill; see <a href="#template-escapes">Template escapes</a></td><td>template</td></tr> | |
| 123 | <tr><td><code class="verbatim">file</code></td><td>string</td><td>The target file; required except with <code class="verbatim">id</code> or <code class="verbatim">clock</code></td><td>target</td></tr> | |
| 124 | <tr><td><code class="verbatim">headline</code></td><td>string</td><td>A heading in <code class="verbatim">file</code></td><td><code class="verbatim">file+headline</code></td></tr> | |
| 125 | <tr><td><code class="verbatim">olp</code></td><td>string</td><td>An outline path in <code class="verbatim">file</code>, titles separated by <code class="verbatim">/</code></td><td><code class="verbatim">file+olp</code></td></tr> | |
| 126 | <tr><td><code class="verbatim">datetree</code></td><td>boolean</td><td>Today's entry in a date tree in <code class="verbatim">file</code>, under <code class="verbatim">olp</code> if given</td><td><code class="verbatim">file+olp+datetree</code></td></tr> | |
| 127 | <tr><td><code class="verbatim">tree-type</code></td><td>string</td><td><code class="verbatim">day</code> (the default), <code class="verbatim">week</code> or <code class="verbatim">month</code>, for <code class="verbatim">datetree</code></td><td><code class="verbatim">:tree-type</code></td></tr> | |
| 128 | <tr><td><code class="verbatim">id</code></td><td>string</td><td>The heading with this <code class="verbatim">ID</code> property, in any file</td><td><code class="verbatim">id</code></td></tr> | |
| 129 | <tr><td><code class="verbatim">clock</code></td><td>boolean</td><td>The entry the clock is running in</td><td><code class="verbatim">clock</code></td></tr> | |
| 130 | <tr><td><code class="verbatim">prepend</code></td><td>boolean</td><td>Put the text first rather than last</td><td><code class="verbatim">:prepend</code></td></tr> | |
| 131 | <tr><td><code class="verbatim">immediate-finish</code></td><td>boolean</td><td>File without showing the editor</td><td><code class="verbatim">:immediate-finish</code></td></tr> | |
| 132 | <tr><td><code class="verbatim">empty-lines</code></td><td>integer</td><td>Blank lines before and after the captured text</td><td><code class="verbatim">:empty-lines</code></td></tr> | |
| 133 | <tr><td><code class="verbatim">empty-lines-before</code></td><td>integer</td><td>Blank lines before; overrides <code class="verbatim">empty-lines</code></td><td><code class="verbatim">:empty-lines-before</code></td></tr> | |
| 134 | <tr><td><code class="verbatim">empty-lines-after</code></td><td>integer</td><td>Blank lines after; overrides <code class="verbatim">empty-lines</code></td><td><code class="verbatim">:empty-lines-after</code></td></tr> | |
| 135 | <tr><td><code class="verbatim">jump-to-captured</code></td><td>boolean</td><td>Show the new entry in the editor after filing</td><td><code class="verbatim">:jump-to-captured</code></td></tr> | |
| 136 | <tr><td><code class="verbatim">clock-in</code></td><td>boolean</td><td>Clock in to the captured entry</td><td><code class="verbatim">:clock-in</code></td></tr> | |
| 137 | <tr><td><code class="verbatim">clock-keep</code></td><td>boolean</td><td>With <code class="verbatim">clock-in</code>, keep the clock running after filing</td><td><code class="verbatim">:clock-keep</code></td></tr> | |
| 138 | <tr><td><code class="verbatim">clock-resume</code></td><td>boolean</td><td>With <code class="verbatim">clock-in</code>, restart the clock that was running before</td><td><code class="verbatim">:clock-resume</code></td></tr> | |
| 139 | <tr><td><code class="verbatim">table-line-pos</code></td><td>string</td><td>Where a <code class="verbatim">table-line</code> goes, such as <code class="verbatim">"II-3"</code></td><td><code class="verbatim">:table-line-pos</code></td></tr> | |
| 140 | </tbody> | |
| 141 | </table> | |
| 142 | <p><code class="verbatim">capture.toml</code> uses a subset of TOML: basic strings in double quotes, literal strings in single quotes, booleans and integers. Multi-line strings (<code class="verbatim">"""…"""</code>) are not supported, so write a newline in a template as <code class="verbatim">\n</code> inside a double-quoted string. A double-quoted string accepts only the escapes <code class="verbatim">\"</code>, <code class="verbatim">\\</code>, <code class="verbatim">\n</code>, <code class="verbatim">\t</code>, <code class="verbatim">\uXXXX</code> and <code class="verbatim">\UXXXXXXXX</code>; any other backslash is an error. A template backslash, as in <code class="verbatim">%\1</code> or <code class="verbatim">\%</code>, is therefore written <code class="verbatim">%\\1</code> or <code class="verbatim">\\%</code> in double quotes, or as it is in a single-quoted string, which has no escapes and no <code class="verbatim">\n</code>.</p> | |
| 143 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">template</span><span class="punctuation definition table array toml">]]</span> | |
| 144 | <span class="variable other key toml">key</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>m<span class="punctuation definition string end toml">"</span></span> | |
| 145 | <span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Meeting<span class="punctuation definition string end toml">"</span></span> | |
| 146 | <span class="variable other key toml">file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>work.org<span class="punctuation definition string end toml">"</span></span> | |
| 147 | <span class="variable other key toml">olp</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Meetings<span class="punctuation definition string end toml">"</span></span> | |
| 148 | <span class="variable other key toml">template</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>* %^{Topic} :meeting:<span class="constant character escape toml">\n</span>%U<span class="constant character escape toml">\n</span>- Attendees: %^{Attendees}<span class="constant character escape toml">\n</span>- Topic again: %<span class="constant character escape toml">\\</span>1<span class="constant character escape toml">\n</span>%?<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 149 | <h3 id="targets">Targets</h3> | |
| 150 | <p>The target keys are checked in this order: <code class="verbatim">id</code>, <code class="verbatim">clock</code>, <code class="verbatim">datetree</code>, <code class="verbatim">headline</code>, <code class="verbatim">olp</code>; with none of them the target is <code class="verbatim">file</code> itself.</p> | |
| 151 | <table> | |
| 152 | <thead> | |
| 153 | <tr><th>Target</th><th>Where the text goes</th></tr> | |
| 154 | </thead> | |
| 155 | <tbody> | |
| 156 | <tr><td><code class="verbatim">file</code> alone</td><td>The file's top level: an <code class="verbatim">entry</code> becomes a top-level heading at the end (or start, with <code class="verbatim">prepend</code>)</td></tr> | |
| 157 | <tr><td><code class="verbatim">headline = "Inbox"</code></td><td>Under the first heading with that exact title, at any level. If there is none, <code class="verbatim">* Inbox</code> is added at the end of the file</td></tr> | |
| 158 | <tr><td><code class="verbatim">olp = "Projects/Work"</code></td><td>Under <code class="verbatim">Work</code>, a child of <code class="verbatim">Projects</code>. Every heading on the path must exist; otherwise filing fails with <code class="verbatim">Heading not found on outline path</code></td></tr> | |
| 159 | <tr><td><code class="verbatim">datetree = true</code></td><td>Under today's heading in a date tree; see <a href="#date-trees">Date trees</a></td></tr> | |
| 160 | <tr><td><code class="verbatim">id = "…"</code></td><td>Under the heading with that <code class="verbatim">ID</code>, found through the workspace index. Fails with <code class="verbatim">Cannot find target ID</code> if no heading has it</td></tr> | |
| 161 | <tr><td><code class="verbatim">clock = true</code></td><td>Under the heading the running clock is in. Fails with <code class="verbatim">No running clock</code> when no clock runs</td></tr> | |
| 162 | </tbody> | |
| 163 | </table> | |
| 164 | <p><code class="verbatim">file</code> may be absolute (<code class="verbatim">/Users/me/org/todo.org</code>), start with <code class="verbatim">~/</code>, or be relative. A relative path is relative to the first folder in the sidebar (your home folder if you have none). Heading titles match the title text without its TODO keyword, priority or tags. Because <code class="verbatim">olp</code> uses <code class="verbatim">/</code> as its separator, a heading whose title contains <code class="verbatim">/</code> can't be on an outline path; use <code class="verbatim">headline</code> or <code class="verbatim">id</code> for it.</p> | |
| 165 | <p>Emacs's <code class="verbatim">file+regexp</code>, <code class="verbatim">file+function</code> and <code class="verbatim">function</code> targets, and templates read from a file (<code class="verbatim">(file "…")</code>), are not supported.</p> | |
| 166 | <h3 id="template-types">Template types</h3> | |
| 167 | <table> | |
| 168 | <thead> | |
| 169 | <tr><th>Type</th><th>What is inserted</th></tr> | |
| 170 | </thead> | |
| 171 | <tbody> | |
| 172 | <tr><td><code class="verbatim">entry</code></td><td>An Org entry. If the text has no heading, <code class="verbatim">* = is added. Its level is adjusted to be one below the target heading, or 1 at the top level. Placed as the last child (first with =prepend</code>). Text whose first heading isn't its highest is refused: <code class="verbatim">Template is not a valid Org entry or tree</code></td></tr> | |
| 173 | <tr><td><code class="verbatim">item</code></td><td>A list item. A =- = bullet is added if the text has none. Goes after the last item of the first list in the target entry (or the file), with that list's indentation; if there is no list, at the end of the entry's text</td></tr> | |
| 174 | <tr><td><code class="verbatim">checkitem</code></td><td>As <code class="verbatim">item</code>, with a <code class="verbatim">[ ]</code> checkbox added if there is none</td></tr> | |
| 175 | <tr><td><code class="verbatim">plain</code></td><td>The text as it is, at the end of the entry's body (with <code class="verbatim">prepend</code>, right after the heading line)</td></tr> | |
| 176 | <tr><td><code class="verbatim">table-line</code></td><td>A table row, in the first table in the target entry (or the file); a new table is made if there is none</td></tr> | |
| 177 | </tbody> | |
| 178 | </table> | |
| 179 | <p>For <code class="verbatim">table-line</code>, a text that doesn't start with a vertical bar gets one. The row goes at the end of the table. With <code class="verbatim">prepend</code> it goes before the first data row after the first rule. With <code class="verbatim">table-line-pos</code>, <code class="verbatim">II-3</code> means three lines above the second horizontal rule and <code class="verbatim">I+1</code> the first line below the first rule; an impossible position fails with <code class="verbatim">Invalid table line specification</code>. After the row is placed, the table is aligned and its formulas recomputed; a table whose formulas need Emacs makes the capture fail with a message that says so (see <a href="10-tables.html">Tables</a>).</p> | |
| 180 | <p>Placement follows <code class="verbatim">org-capture-place-entry</code> and its siblings, including how blank lines are kept: without <code class="verbatim">empty-lines</code> options, a new heading gets a blank line before it when its neighbors have one (<code class="verbatim">org-blank-before-new-entry</code> <code class="verbatim">(heading . auto)</code>). Within an existing list, at most one blank line goes between items.</p> | |
| 181 | <h3 id="clocking-while-capturing">Clocking while capturing</h3> | |
| 182 | <p>With <code class="verbatim">clock-in = true</code>, the captured entry gets a clock entry from when the template was filled to when you filed it, as Emacs clocks in while the capture buffer is open and out on finalize. With <code class="verbatim">clock-keep = true</code> as well, the clock keeps running in the new entry. With <code class="verbatim">clock-resume = true</code>, the clock that was running before the capture starts again after filing. With no clock running, clocking in to the entry first asks about open clocks, as Clock In does, as of when the capture began; on the Mac the questions are in the main window's echo area. See <a href="06-dates-and-clocking.html">Dates, scheduling and clocking</a>.</p> | |
| 183 | <h2 id="template-escapes">Template escapes</h2> | |
| 184 | <p>These follow <code class="verbatim">org-capture-fill-template</code>. Escapes that need no answer are filled first; prompts are then asked in order.</p> | |
| 185 | <h3 id="inserted-values">Inserted values</h3> | |
| 186 | <table> | |
| 187 | <thead> | |
| 188 | <tr><th>Escape</th><th>Inserts</th></tr> | |
| 189 | </thead> | |
| 190 | <tbody> | |
| 191 | <tr><td><code class="verbatim">%?</code></td><td>Nothing; the cursor goes here</td></tr> | |
| 192 | <tr><td><code class="verbatim">%i</code></td><td>The initial text: the selection in the editor, or the body from org-protocol, Shortcuts or the share sheet. Later lines get the indentation of the line <code class="verbatim">%i</code> is on</td></tr> | |
| 193 | <tr><td><code class="verbatim">%a</code></td><td>A link to where capture started, <code class="verbatim">[[target][description]]</code></td></tr> | |
| 194 | <tr><td><code class="verbatim">%A</code></td><td>The same link, asking for its description</td></tr> | |
| 195 | <tr><td><code class="verbatim">%l</code></td><td>The link as <code class="verbatim">[[target]]</code>, without description</td></tr> | |
| 196 | <tr><td><code class="verbatim">%L</code></td><td>The link target alone</td></tr> | |
| 197 | <tr><td><code class="verbatim">%c</code>, <code class="verbatim">%x</code></td><td>The clipboard's text</td></tr> | |
| 198 | <tr><td><code class="verbatim">%f</code></td><td>The name of the file capture started from</td></tr> | |
| 199 | <tr><td><code class="verbatim">%F</code></td><td>The full path of that file</td></tr> | |
| 200 | <tr><td><code class="verbatim">%n</code></td><td>Your full name from macOS</td></tr> | |
| 201 | <tr><td><code class="verbatim">%k</code></td><td>The title of the entry the clock is running in</td></tr> | |
| 202 | <tr><td><code class="verbatim">%K</code></td><td>A link to that entry</td></tr> | |
| 203 | <tr><td><code class="verbatim">%t</code></td><td>Today's date as an active timestamp, <code class="verbatim"><2026-10-07 Wed></code></td></tr> | |
| 204 | <tr><td><code class="verbatim">%T</code></td><td>Active timestamp with the current time</td></tr> | |
| 205 | <tr><td><code class="verbatim">%u</code></td><td>Inactive timestamp, <code class="verbatim">[2026-10-07 Wed]</code></td></tr> | |
| 206 | <tr><td><code class="verbatim">%U</code></td><td>Inactive timestamp with the current time</td></tr> | |
| 207 | <tr><td><code class="verbatim">%<…></code></td><td>The current time formatted with a <code class="verbatim">format-time-string</code> pattern, such as <code class="verbatim">%<%Y-%m-%d %H:%M></code></td></tr> | |
| 208 | <tr><td><code class="verbatim">%:name</code></td><td>A link property; see below</td></tr> | |
| 209 | </tbody> | |
| 210 | </table> | |
| 211 | <p>From the Mac capture window, <code class="verbatim">%a</code> links to the heading at the cursor in the open file, as <code class="verbatim">[[file:~/org/work.org::*Heading][Heading]]</code>, or to the file itself before the first heading. It is empty with no file open.</p> | |
| 212 | <p><code class="verbatim">%<…></code> understands <code class="verbatim">%Y</code>, <code class="verbatim">%m</code>, <code class="verbatim">%d</code>, <code class="verbatim">%e</code>, <code class="verbatim">%H</code>, <code class="verbatim">%M</code>, <code class="verbatim">%S</code>, <code class="verbatim">%a</code>, <code class="verbatim">%A</code>, <code class="verbatim">%b</code>, <code class="verbatim">%B</code>, <code class="verbatim">%F</code>, <code class="verbatim">%R</code> and <code class="verbatim">%%</code>, with English day and month names. Other <code class="verbatim">format-time-string</code> codes are left in the text as they are.</p> | |
| 213 | <p><code class="verbatim">%:name</code> inserts a property of the link being captured. From org-protocol these are <code class="verbatim">%:link</code>, <code class="verbatim">%:description</code> (the page title), <code class="verbatim">%:type</code> (the link's scheme, such as <code class="verbatim">https</code>), <code class="verbatim">%:annotation</code> (the same as <code class="verbatim">%a</code>) and <code class="verbatim">%:initial</code> (the same as <code class="verbatim">%i</code>). Without org-protocol, <code class="verbatim">%:annotation</code> and <code class="verbatim">%:initial</code> still work and other names insert nothing.</p> | |
| 214 | <h3 id="prompts">Prompts</h3> | |
| 215 | <table> | |
| 216 | <thead> | |
| 217 | <tr><th>Escape</th><th>Asks for</th></tr> | |
| 218 | </thead> | |
| 219 | <tbody> | |
| 220 | <tr><td><code class="verbatim">%^{Prompt}</code></td><td>A line of text</td></tr> | |
| 221 | <tr><td><code class="verbatim">%^g</code></td><td>Tags, offering the tags used in the target file</td></tr> | |
| 222 | <tr><td><code class="verbatim">%^G</code></td><td>Tags, offering every tag in your folders</td></tr> | |
| 223 | <tr><td><code class="verbatim">%^t</code>, <code class="verbatim">%^T</code></td><td>A date, inserted as an active timestamp; <code class="verbatim">%^T</code> always includes a time</td></tr> | |
| 224 | <tr><td><code class="verbatim">%^u</code>, <code class="verbatim">%^U</code></td><td>The same as an inactive timestamp</td></tr> | |
| 225 | <tr><td><code class="verbatim">%^C</code></td><td>Text, offering the initial text and the clipboard</td></tr> | |
| 226 | <tr><td><code class="verbatim">%^L</code></td><td>As <code class="verbatim">%^C</code>, inserted as a link</td></tr> | |
| 227 | <tr><td><code class="verbatim">%^{NAME}p</code></td><td>A value for the property <code class="verbatim">NAME</code>, set in the entry's property drawer</td></tr> | |
| 228 | </tbody> | |
| 229 | </table> | |
| 230 | <p><code class="verbatim">%^{Prompt|default|a|b}</code> asks for text with a default and suggested choices, separated by vertical bars.</p> | |
| 231 | <p>A name in braces before any of the keyed forms becomes its prompt: <code class="verbatim">%^{Start}T</code>, <code class="verbatim">%^{Context}g</code>. Leave a text answer empty for the default. Tags are typed separated by colons (<code class="verbatim">work:urgent</code>); on a heading line they are aligned to <code class="verbatim">org-tags-column</code>. A date takes the same input as the editor's date prompt, such as <code class="verbatim">+2d</code>, <code class="verbatim">fri</code> or <code class="verbatim">fri 14:00</code> (see <a href="06-dates-and-clocking.html">Dates, scheduling and clocking</a>); an empty answer is today, or now for <code class="verbatim">%^T</code> and <code class="verbatim">%^U</code>. A time in the answer makes <code class="verbatim">%^t</code> include it.</p> | |
| 232 | <p>After the prompts are answered, <code class="verbatim">%\1</code>, <code class="verbatim">%\2</code> and so on insert the answer to the first, second, … text prompt (<code class="verbatim">%^{…}</code> only), and <code class="verbatim">%\*1</code>, <code class="verbatim">%\*2</code> the answer to the first, second, … prompt of any kind.</p> | |
| 233 | <h3 id="escaping-and-unsupported-escapes">Escaping and unsupported escapes</h3> | |
| 234 | <p>Put a backslash before <code class="verbatim">%</code> to keep it literally: <code class="verbatim">\%t</code> inserts <code class="verbatim">%t</code> (in a double-quoted TOML string, write <code class="verbatim">\\%t</code>). Two backslashes insert one backslash followed by the escape's value.</p> | |
| 235 | <p><code class="verbatim">%(…)</code> runs Emacs Lisp in Org and is not supported; a template that contains it fails with a message saying so. <code class="verbatim">%[file]</code> (insert a file's contents) is not supported either. Any other <code class="verbatim">%</code> sequence is left as it is.</p> | |
| 236 | <h2 id="date-trees">Date trees</h2> | |
| 237 | <p>With <code class="verbatim">datetree = true</code>, the entry goes under today's date in a tree of headings, as <code class="verbatim">org-datetree-find-create-entry</code> builds it. Missing levels are created in date order among their siblings.</p> | |
| 238 | <table> | |
| 239 | <thead> | |
| 240 | <tr><th><code class="verbatim">tree-type</code></th><th>Levels</th></tr> | |
| 241 | </thead> | |
| 242 | <tbody> | |
| 243 | <tr><td><code class="verbatim">day</code></td><td><code class="verbatim">* 2026</code>, <code class="verbatim">** 2026-10 October</code>, <code class="verbatim">*** 2026-10-07 Wednesday</code></td></tr> | |
| 244 | <tr><td><code class="verbatim">week</code></td><td><code class="verbatim">* 2026</code>, <code class="verbatim">** 2026-W41</code>, <code class="verbatim">*** 2026-10-07 Wednesday</code> (ISO week and its year)</td></tr> | |
| 245 | <tr><td><code class="verbatim">month</code></td><td><code class="verbatim">* 2026</code>, <code class="verbatim">** 2026-10 October</code></td></tr> | |
| 246 | </tbody> | |
| 247 | </table> | |
| 248 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">template</span><span class="punctuation definition table array toml">]]</span> | |
| 249 | <span class="variable other key toml">key</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>j<span class="punctuation definition string end toml">"</span></span> | |
| 250 | <span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Journal<span class="punctuation definition string end toml">"</span></span> | |
| 251 | <span class="variable other key toml">file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>journal.org<span class="punctuation definition string end toml">"</span></span> | |
| 252 | <span class="variable other key toml">datetree</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span> | |
| 253 | <span class="variable other key toml">template</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>* %<%H:%M> %?<span class="constant character escape toml">\n</span>%i<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 254 | <p>With <code class="verbatim">olp</code>, the tree goes under that outline path, one level down, instead of at the top of the file. The date is the day you file the capture. There is no <code class="verbatim">:time-prompt</code> to choose another day.</p> | |
| 255 | <h2 id="org-protocol">org-protocol</h2> | |
| 256 | <p>Orgstar registers the <code class="verbatim">org-protocol:</code> URL scheme and handles the two handlers browser bookmarklets use, as <code class="verbatim">org-protocol.el</code> does in Org 9.8.7. Both the <code class="verbatim">?key=value</code> form and the older <code class="verbatim">:/a/b/c</code> form work.</p> | |
| 257 | <h3 id="capture">capture</h3> | |
| 258 | <pre><code class="language-text">org-protocol://capture?template=w&url=https%3A%2F%2Fexample.com&title=Example&body=Selected%20text</code></pre> | |
| 259 | <p>This opens the capture window with:</p> | |
| 260 | <ul> | |
| 261 | <li><code class="verbatim">template</code> chosen. Without <code class="verbatim">template</code>, the template list shows. A key with no template reports <code class="verbatim">No capture template "w"</code>.</li> | |
| 262 | <li><code class="verbatim">%a</code> and <code class="verbatim">%:annotation</code> set to <code class="verbatim">[[url][title]]</code> (the URL as its own description when the title is blank; the title alone when there is no URL).</li> | |
| 263 | <li><code class="verbatim">%i</code> and <code class="verbatim">%:initial</code> set to <code class="verbatim">body</code>.</li> | |
| 264 | <li><code class="verbatim">%:link</code> set to the URL, <code class="verbatim">%:description</code> to the title, and <code class="verbatim">%:type</code> to the URL's scheme.</li> | |
| 265 | </ul> | |
| 266 | <p>In the query form, <code class="verbatim">+</code> stands for a space, as in Org; encode a literal <code class="verbatim">+</code> as <code class="verbatim">%2B</code>.</p> | |
| 267 | <h3 id="store-link">store-link</h3> | |
| 268 | <pre><code class="language-text">org-protocol://store-link?url=https%3A%2F%2Fexample.com&title=Example</code></pre> | |
| 269 | <p>This stores the link, so <code class="verbatim">C-c C-l</code> in the editor offers it (see <a href="09-links.html">Links</a>), and puts the URL on the clipboard.</p> | |
| 270 | <p>Other handlers, such as <code class="verbatim">open-source</code>, report that Orgstar handles only capture and store-link. On iOS only <code class="verbatim">capture</code> links are handled.</p> | |
| 271 | <h3 id="bookmarklets">Bookmarklets</h3> | |
| 272 | <p>Bookmarklets written for Emacs's org-protocol work unchanged. Add a bookmark with one of these as its address:</p> | |
| 273 | <pre><code class="language-js highlight"><span class="source js"><span class="entity name label js">javascript</span><span class="punctuation separator js">:</span><span class="variable other object js">location</span><span class="punctuation accessor js">.</span><span class="meta property object js">href</span><span class="keyword operator assignment js">=</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>org-protocol://capture?template=w&url=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="variable other object js">location</span><span class="punctuation accessor js">.</span><span class="meta property object js">href</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span><span class="keyword operator arithmetic js">+</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>&title=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="support type object dom js">document</span><span class="punctuation accessor js">.</span><span class="meta property object js">title</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span><span class="keyword operator arithmetic js">+</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>&body=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="support type object dom js">window</span><span class="punctuation accessor js">.</span><span class="meta function-call method js"><span class="variable function js">getSelection</span><span class="meta group js"><span class="punctuation section group js">(</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span></span></code></pre> | |
| 274 | <pre><code class="language-js highlight"><span class="source js"><span class="entity name label js">javascript</span><span class="punctuation separator js">:</span><span class="variable other object js">location</span><span class="punctuation accessor js">.</span><span class="meta property object js">href</span><span class="keyword operator assignment js">=</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>org-protocol://store-link?url=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="variable other object js">location</span><span class="punctuation accessor js">.</span><span class="meta property object js">href</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span><span class="keyword operator arithmetic js">+</span><span class="string quoted single js"><span class="punctuation definition string begin js">'</span>&title=<span class="punctuation definition string end js">'</span></span><span class="keyword operator arithmetic js">+</span><span class="meta function-call js"><span class="support function js">encodeURIComponent</span><span class="meta group js"><span class="punctuation section group js">(</span><span class="support type object dom js">document</span><span class="punctuation accessor js">.</span><span class="meta property object js">title</span></span><span class="meta group js"><span class="punctuation section group js">)</span></span></span></span></code></pre> | |
| 275 | <p>A matching web capture template:</p> | |
| 276 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">template</span><span class="punctuation definition table array toml">]]</span> | |
| 277 | <span class="variable other key toml">key</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>w<span class="punctuation definition string end toml">"</span></span> | |
| 278 | <span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Web page<span class="punctuation definition string end toml">"</span></span> | |
| 279 | <span class="variable other key toml">file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>inbox.org<span class="punctuation definition string end toml">"</span></span> | |
| 280 | <span class="variable other key toml">headline</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>Web<span class="punctuation definition string end toml">"</span></span> | |
| 281 | <span class="variable other key toml">template</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>* %:description<span class="constant character escape toml">\n</span>:PROPERTIES:<span class="constant character escape toml">\n</span>:URL: %:link<span class="constant character escape toml">\n</span>:END:<span class="constant character escape toml">\n</span>%U<span class="constant character escape toml">\n</span>%i<span class="constant character escape toml">\n</span>%?<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 282 | <h2 id="shortcuts">Shortcuts</h2> | |
| 283 | <p>The Shortcuts action Capture to Orgstar files text with a template, without the capture window. It has two parameters:</p> | |
| 284 | <table> | |
| 285 | <thead> | |
| 286 | <tr><th>Parameter</th><th>Meaning</th></tr> | |
| 287 | </thead> | |
| 288 | <tbody> | |
| 289 | <tr><td>Text</td><td>The text, inserted as <code class="verbatim">%i</code></td></tr> | |
| 290 | <tr><td>Template Key</td><td>A template's <code class="verbatim">key</code> in <code class="verbatim">capture.toml</code>; the first template when empty</td></tr> | |
| 291 | </tbody> | |
| 292 | </table> | |
| 293 | <p>Every prompt in the template takes its default (an empty answer: today for dates, no tags), and <code class="verbatim">%?</code> is ignored. <code class="verbatim">%a</code> is empty. On the Mac, <code class="verbatim">%c</code> is the clipboard and <code class="verbatim">%n</code> your name; on iOS both are empty, because reading the pasteboard would ask for permission on every run. The action returns a message, <code class="verbatim">Captured to …</code> with the target on the Mac and <code class="verbatim">Captured with …</code> with the template name on iOS, or fails with the same messages as the capture window. You can also say "Capture to Orgstar" to Siri.</p> | |
| 294 | <p>On the Mac, the action opens Orgstar if it isn't running and waits up to five seconds for it to be ready.</p> | |
| 295 | <h2 id="capture-on-ios">Capture on iOS</h2> | |
| 296 | <p>The Capture button (a square with a pencil) at the top of the Agenda and Folders tabs opens the capture sheet. The templates come from the <code class="verbatim">capture.toml</code> in your synced configuration folder (see <a href="14-ios.html">iOS</a>).</p> | |
| 297 | <p>The sheet works as on the Mac, in a form:</p> | |
| 298 | <ul> | |
| 299 | <li>The Template picker chooses the template; it starts on the first one.</li> | |
| 300 | <li>Prompts appear as fields. Date prompts have a date picker; choices and tags appear as buttons, and tapping a tag adds it.</li> | |
| 301 | <li>Continue fills the template and shows the text to edit; File files it; Cancel discards it.</li> | |
| 302 | </ul> | |
| 303 | <p>Differences from the Mac: there is no selection, clipboard, current file, user name or clock link to insert, so <code class="verbatim">%i</code> and <code class="verbatim">%a</code> are empty unless the capture came from a link or the share sheet, and <code class="verbatim">%c</code>, <code class="verbatim">%x</code>, <code class="verbatim">%f</code>, <code class="verbatim">%F</code>, <code class="verbatim">%n</code>, <code class="verbatim">%k</code> and <code class="verbatim">%K</code> are empty. An org-protocol link naming a template key that doesn't exist opens the sheet on the first template and shows <code class="verbatim">No capture template "x"</code> with the key.</p> | |
| 304 | <h3 id="the-share-sheet">The share sheet</h3> | |
| 305 | <p>In another app, share a web page or text and choose Orgstar. The share form has:</p> | |
| 306 | <ul> | |
| 307 | <li>a Template picker, with the templates the app read the last time it ran;</li> | |
| 308 | <li>for a link, its title (editable) and address;</li> | |
| 309 | <li>a Text field, filled with shared text.</li> | |
| 310 | </ul> | |
| 311 | <p>Capture saves the item in the app group's capture inbox. The next time you open Orgstar, it opens the capture sheet with the item as an org-protocol capture: the link becomes <code class="verbatim">%a</code> and <code class="verbatim">%:link</code>, the title <code class="verbatim">%:description</code>, and the text <code class="verbatim">%i</code>. Several waiting items open one after another, oldest first. If the extension says Orgstar's shared folder isn't available, the app group is missing from the build and nothing can be saved.</p> | |
| 312 | <p>The share form lists no templates until Orgstar has run once with your configuration folder; the capture sheet then starts on the first template.</p> | |
| 313 | <h2 id="importing-templates-from-emacs">Importing templates from Emacs</h2> | |
| 314 | <p>Import from Emacs (see <a href="13-configuration.html">Configuration</a> and <a href="15-alongside-emacs.html">Alongside Emacs</a>) reads <code class="verbatim">org-capture-templates</code> and appends a <code class="verbatim">[[template]]</code> table to <code class="verbatim">capture.toml</code> for each template whose key isn't there already.</p> | |
| 315 | <table> | |
| 316 | <thead> | |
| 317 | <tr><th>Emacs</th><th>Imported as</th></tr> | |
| 318 | </thead> | |
| 319 | <tbody> | |
| 320 | <tr><td>types <code class="verbatim">entry</code>, <code class="verbatim">item</code>, <code class="verbatim">checkitem</code>, <code class="verbatim">plain</code>, <code class="verbatim">table-line</code></td><td><code class="verbatim">type</code></td></tr> | |
| 321 | <tr><td><code class="verbatim">(file "f")</code></td><td><code class="verbatim">file</code></td></tr> | |
| 322 | <tr><td><code class="verbatim">(file+headline "f" "H")</code></td><td><code class="verbatim">file</code>, <code class="verbatim">headline</code></td></tr> | |
| 323 | <tr><td><code class="verbatim">(file+olp "f" "A" "B")</code></td><td><code class="verbatim">file</code>, <code class="verbatim">olp = "A/B"</code></td></tr> | |
| 324 | <tr><td><code class="verbatim">(file+olp+datetree "f" …)</code></td><td><code class="verbatim">file</code>, <code class="verbatim">datetree</code>, <code class="verbatim">olp</code> if a path is given</td></tr> | |
| 325 | <tr><td><code class="verbatim">(file+datetree "f")</code></td><td><code class="verbatim">file</code>, <code class="verbatim">datetree</code></td></tr> | |
| 326 | <tr><td><code class="verbatim">(file+weektree "f")</code></td><td><code class="verbatim">file</code>, <code class="verbatim">datetree</code>, <code class="verbatim">tree-type = "week"</code></td></tr> | |
| 327 | <tr><td><code class="verbatim">(id "…")</code></td><td><code class="verbatim">id</code></td></tr> | |
| 328 | <tr><td><code class="verbatim">(clock)</code></td><td><code class="verbatim">clock</code></td></tr> | |
| 329 | <tr><td><code class="verbatim">:prepend</code>, <code class="verbatim">:immediate-finish</code>, <code class="verbatim">:jump-to-captured</code>, <code class="verbatim">:clock-in</code>, <code class="verbatim">:clock-keep</code>, <code class="verbatim">:clock-resume</code></td><td>the boolean of the same name</td></tr> | |
| 330 | <tr><td><code class="verbatim">:empty-lines</code>, <code class="verbatim">:empty-lines-before</code>, <code class="verbatim">:empty-lines-after</code>, <code class="verbatim">:table-line-pos</code>, <code class="verbatim">:tree-type</code></td><td>the key of the same name</td></tr> | |
| 331 | </tbody> | |
| 332 | </table> | |
| 333 | <p>A file name given as a variable or a simple form is evaluated where the importer can. The import report lists what it left out: other targets, templates that aren't strings, unknown <code class="verbatim">:tree-type</code> values, and other properties such as <code class="verbatim">:time-prompt</code>, <code class="verbatim">:kill-buffer</code> or <code class="verbatim">:unnarrowed</code>. Template groups are skipped.</p> | |
| 334 | <p>Emacs resolves relative target files against <code class="verbatim">org-directory</code>; Orgstar resolves them against the first folder in the sidebar. If <code class="verbatim">org-directory</code> isn't your first folder, edit the imported <code class="verbatim">file</code> values or make them absolute.</p> | |
| 335 | </main> | |
| 336 | <footer class="site"> | |
| 337 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 338 | </footer> | |
| 339 | </body> | |
| 340 | </html> | |
| \ No newline at end of file | ||
guide/09-links.html added +269
| @@ -0,0 +1,269 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Links · Orgstar</title> | |
| 7 | <meta name="description" content="Link syntax, the link types Orgstar follows, storing and inserting links, IDs, backlinks and inline images."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Links</h1> | |
| 24 | <p class="lede">Write links as Org does, follow them with a key or a click, and see which headings link to the one you are reading.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#link-syntax">Link syntax</a></li> | |
| 29 | <li><a href="#how-links-display">How links display</a></li> | |
| 30 | <li><a href="#following-links">Following links</a> | |
| 31 | <ul> | |
| 32 | <li><a href="#what-each-link-type-does">What each link type does</a></li> | |
| 33 | <li><a href="#file-links">File links</a></li> | |
| 34 | <li><a href="#attachment-links">Attachment links</a></li> | |
| 35 | <li><a href="#id-links">id links</a></li> | |
| 36 | <li><a href="#timestamps">Timestamps</a></li> | |
| 37 | </ul></li> | |
| 38 | <li><a href="#inserting-and-editing-links">Inserting and editing links</a> | |
| 39 | <ul> | |
| 40 | <li><a href="#file-paths-in-inserted-links">File paths in inserted links</a></li> | |
| 41 | <li><a href="#completion-while-typing">Completion while typing</a></li> | |
| 42 | </ul></li> | |
| 43 | <li><a href="#storing-links">Storing links</a></li> | |
| 44 | <li><a href="#ids">IDs</a></li> | |
| 45 | <li><a href="#targets-and-radio-targets">Targets and radio targets</a></li> | |
| 46 | <li><a href="#link-abbreviations">Link abbreviations</a></li> | |
| 47 | <li><a href="#the-backlinks-pane">The backlinks pane</a></li> | |
| 48 | <li><a href="#inline-images">Inline images</a> | |
| 49 | <ul> | |
| 50 | <li><a href="#sizing">Sizing</a></li> | |
| 51 | <li><a href="#showing-images-when-a-file-opens">Showing images when a file opens</a></li> | |
| 52 | </ul></li> | |
| 53 | <li><a href="#org-protocol-store-link">org-protocol store-link</a></li> | |
| 54 | <li><a href="#on-ios">On iOS</a></li> | |
| 55 | </ul> | |
| 56 | </nav> | |
| 57 | <h2 id="link-syntax">Link syntax</h2> | |
| 58 | <p>Orgstar reads links the way <code class="verbatim">org-element-link-parser</code> does. There are three forms.</p> | |
| 59 | <table> | |
| 60 | <thead> | |
| 61 | <tr><th>Form</th><th>Example</th><th>Notes</th></tr> | |
| 62 | </thead> | |
| 63 | <tbody> | |
| 64 | <tr><td>Bracket link</td><td><code class="verbatim">[[https://orgmode.org][Org website]]</code></td><td>Any link type. The description after <code class="verbatim">][</code> is optional.</td></tr> | |
| 65 | <tr><td>Angle link</td><td><code class="verbatim"><https://orgmode.org></code></td><td>For <code class="verbatim">http</code>, <code class="verbatim">https</code>, <code class="verbatim">mailto</code>, <code class="verbatim">file</code>, <code class="verbatim">id</code>, <code class="verbatim">doi</code>, <code class="verbatim">ftp</code>, <code class="verbatim">news</code>, <code class="verbatim">shell</code>, <code class="verbatim">elisp</code>, <code class="verbatim">info</code>, <code class="verbatim">help</code> and <code class="verbatim">attachment</code>.</td></tr> | |
| 66 | <tr><td>Plain link</td><td><code class="verbatim">https://orgmode.org</code></td><td>Only <code class="verbatim">https://</code>, <code class="verbatim">http://</code>, <code class="verbatim">mailto:</code> and <code class="verbatim">file:</code> are recognized in running text.</td></tr> | |
| 67 | </tbody> | |
| 68 | </table> | |
| 69 | <p>Inside a bracket link, a target that starts with <code class="verbatim">/</code>, <code class="verbatim">~</code>, <code class="verbatim">./</code> or <code class="verbatim">../</code> is a file link. A target in parentheses, <code class="verbatim">(name)</code>, is a coderef. One that starts with <code class="verbatim">#</code> is a custom ID. Anything without a known <code class="verbatim">type:</code> prefix is a search for text in the current file (a "fuzzy" link). A link may run over a line break; the break and surrounding blanks read as one space.</p> | |
| 70 | <p>Backslashes before brackets are escaped as in <code class="verbatim">org-link-escape</code>: when Orgstar writes a link it doubles backslashes that come before a bracket or the end, and it reads them back the same way.</p> | |
| 71 | <h2 id="how-links-display">How links display</h2> | |
| 72 | <p>With View ▸ Show Markup off (the default, <code class="verbatim">⇧⌘M</code> toggles it), a link with a description shows only its description, and its brackets and target are hidden. This is <code class="verbatim">org-link-descriptive</code>. The full text appears on the line that holds the caret, so you can edit it. With Show Markup on, every link shows as written. The setting is <code class="verbatim">show-markup</code> under <code class="verbatim">[orgstar]</code> in the config file (see <a href="13-configuration.html">Configuration</a>).</p> | |
| 73 | <p>Links without a description show their target, with the brackets hidden in the same way. Radio targets (<code class="verbatim"><<<words>>></code>) turn every other occurrence of those words in the file into a link, matched case-insensitively, as in Org.</p> | |
| 74 | <h2 id="following-links">Following links</h2> | |
| 75 | <p><code class="verbatim">org-open-at-point</code> follows the link at the caret, or opens the agenda for a timestamp.</p> | |
| 76 | <table> | |
| 77 | <thead> | |
| 78 | <tr><th>Preset</th><th>Key</th></tr> | |
| 79 | </thead> | |
| 80 | <tbody> | |
| 81 | <tr><td>Emacs</td><td><code class="verbatim">C-c C-o</code></td></tr> | |
| 82 | <tr><td>Mac</td><td><code class="verbatim">⌃⌘O</code></td></tr> | |
| 83 | <tr><td>Doom</td><td><code class="verbatim">C-c C-o</code> in any state; <code class="verbatim">RET</code> in normal state follows a link before doing anything else</td></tr> | |
| 84 | <tr><td>All</td><td><code class="verbatim">⌘</code>-click on the link; <code class="verbatim">o</code> at the start of a heading line when speed commands are on</td></tr> | |
| 85 | </tbody> | |
| 86 | </table> | |
| 87 | <p>A message in the echo area explains a link that can't be followed.</p> | |
| 88 | <h3 id="what-each-link-type-does">What each link type does</h3> | |
| 89 | <table> | |
| 90 | <thead> | |
| 91 | <tr><th>Link</th><th>Example</th><th>Result</th></tr> | |
| 92 | </thead> | |
| 93 | <tbody> | |
| 94 | <tr><td><code class="verbatim">http</code>, <code class="verbatim">https</code>, <code class="verbatim">ftp</code>, <code class="verbatim">news</code>, <code class="verbatim">mailto</code></td><td><code class="verbatim">[[mailto:me@example.com]]</code></td><td>Opened by macOS in your default browser or mail app.</td></tr> | |
| 95 | <tr><td><code class="verbatim">doi</code></td><td><code class="verbatim">[[doi:10.1000/182]]</code></td><td>Opens <code class="verbatim">https://doi.org/</code> followed by the DOI.</td></tr> | |
| 96 | <tr><td><code class="verbatim">file</code> (also <code class="verbatim">file+sys:</code>, <code class="verbatim">file+emacs:</code>)</td><td><code class="verbatim">[[file:notes.org::*Ideas]]</code></td><td>See <em>File links</em> below.</td></tr> | |
| 97 | <tr><td><code class="verbatim">id</code></td><td><code class="verbatim">[[id:6a3c…]]</code></td><td>Opens the file with the heading whose <code class="verbatim">ID</code> property matches, and moves to the heading.</td></tr> | |
| 98 | <tr><td>Custom ID</td><td><code class="verbatim">[[#setup]]</code></td><td>Moves to the heading in this file whose <code class="verbatim">CUSTOM_ID</code> property is <code class="verbatim">setup</code>.</td></tr> | |
| 99 | <tr><td>Heading</td><td><code class="verbatim">[[*Weekly review]]</code></td><td>Moves to the heading in this file with that title.</td></tr> | |
| 100 | <tr><td>Text</td><td><code class="verbatim">[[budget table]]</code></td><td>Searches this file: a <code class="verbatim"><<budget table>></code> target, then <code class="verbatim">#+NAME: budget table</code>, then a heading.</td></tr> | |
| 101 | <tr><td>Coderef</td><td><code class="verbatim">[[(ref)]]</code></td><td>Not supported. The echo area says so.</td></tr> | |
| 102 | <tr><td><code class="verbatim">shell</code>, <code class="verbatim">elisp</code></td><td><code class="verbatim">[[shell:ls]]</code></td><td>Not run. Orgstar never executes these links.</td></tr> | |
| 103 | <tr><td><code class="verbatim">attachment</code></td><td><code class="verbatim">[[attachment:scan.pdf]]</code></td><td>Opens the file in the entry's attachment folder; see <em>Attachment links</em> below.</td></tr> | |
| 104 | <tr><td>Radio link</td><td>Text matching a <code class="verbatim"><<<radio target>>></code></td><td>Moves to the radio target.</td></tr> | |
| 105 | <tr><td><code class="verbatim">info</code>, <code class="verbatim">help</code>, others</td><td></td><td>Not followed. The echo area says Orgstar can't open the type.</td></tr> | |
| 106 | </tbody> | |
| 107 | </table> | |
| 108 | <p>The text search follows <code class="verbatim">org-link-search</code>. A dedicated <code class="verbatim"><<target>></code> matches its words case-insensitively, with any run of blanks between them. A heading matches when its title, with statistics cookies such as <code class="verbatim">[2/5]</code> and a leading <code class="verbatim">COMMENT</code> removed, has the same words as the link, ignoring case. A search that starts with <code class="verbatim">*</code> looks at headings only. Regular-expression searches (<code class="verbatim">/re/</code>) are not supported.</p> | |
| 109 | <p>Following a radio link moves to its <code class="verbatim"><<<radio target>>></code>, matching the words without regard to case, as <code class="verbatim">org-link--search-radio-target</code> does. When the target is gone, the echo area shows <code class="verbatim">No match for radio target:</code> and the text.</p> | |
| 110 | <h3 id="file-links">File links</h3> | |
| 111 | <p>A relative path is resolved against the folder of the file that holds the link, as Org does; <code class="verbatim">~</code> is your home folder; an absolute path is used as written. Links between files in different sidebar folders work the same way, for example <code class="verbatim">[[file:../work/projects.org]]</code> or <code class="verbatim">[[file:~/Documents/org/inbox.org]]</code>.</p> | |
| 112 | <p>What happens depends on the file:</p> | |
| 113 | <ul> | |
| 114 | <li>An <code class="verbatim">.org</code> or <code class="verbatim">.org_archive</code> file opens as a buffer in Orgstar.</li> | |
| 115 | <li>Another text file opens in Orgstar as a plain buffer.</li> | |
| 116 | <li>Anything else (images, PDFs, archives, media) is handed to macOS, which opens it in the default app for that type.</li> | |
| 117 | </ul> | |
| 118 | <p>If the file doesn't exist, the echo area shows <code class="verbatim">No file</code> and the path.</p> | |
| 119 | <p>After <code class="verbatim">::</code>, a file link can carry a search option:</p> | |
| 120 | <table> | |
| 121 | <thead> | |
| 122 | <tr><th>Option</th><th>Example</th><th>Moves to</th></tr> | |
| 123 | </thead> | |
| 124 | <tbody> | |
| 125 | <tr><td>A number</td><td><code class="verbatim">[[file:log.txt::120]]</code></td><td>Line 120.</td></tr> | |
| 126 | <tr><td><code class="verbatim">*Title</code></td><td><code class="verbatim">[[file:notes.org::*Ideas]]</code></td><td>The heading with that title.</td></tr> | |
| 127 | <tr><td><code class="verbatim">#custom-id</code></td><td><code class="verbatim">[[file:notes.org::#setup]]</code></td><td>The heading with that <code class="verbatim">CUSTOM_ID</code>.</td></tr> | |
| 128 | <tr><td>Other text</td><td><code class="verbatim">[[file:notes.org::budget]]</code></td><td>A target, a <code class="verbatim">#+NAME</code> or a heading, as above.</td></tr> | |
| 129 | </tbody> | |
| 130 | </table> | |
| 131 | <h3 id="attachment-links">Attachment links</h3> | |
| 132 | <p>An <code class="verbatim">attachment:</code> link names a file in the attachment folder of the entry that holds the link, with org-attach's default settings. Relative folders are resolved against the folder of the file that holds the link:</p> | |
| 133 | <ol> | |
| 134 | <li>When the entry has a <code class="verbatim">DIR</code> property, or the older <code class="verbatim">ATTACH_DIR</code>, that folder.</li> | |
| 135 | <li>Otherwise, for an entry with an <code class="verbatim">ID</code>, the first of these folders that exists: <code class="verbatim">data/</code> followed by the ID's first two characters, <code class="verbatim">/</code> and the rest of the ID; <code class="verbatim">data/</code> followed by its first six characters, <code class="verbatim">/</code> and the rest; <code class="verbatim">data/__/</code>, the ID's first character, <code class="verbatim">/</code> and the whole ID.</li> | |
| 136 | </ol> | |
| 137 | <p>When the folder does not exist, the path is relative to the file's own folder. The file then opens as a <code class="verbatim">file:</code> link would, and a search option after <code class="verbatim">::</code> works the same way.</p> | |
| 138 | <h3 id="id-links">id links</h3> | |
| 139 | <p><code class="verbatim">id:</code> links are resolved through the index, so the target heading must be in a file under one of your sidebar folders. A link to an ID that isn't indexed shows <code class="verbatim">No heading has the ID</code> followed by the ID.</p> | |
| 140 | <h3 id="timestamps">Timestamps</h3> | |
| 141 | <p><code class="verbatim">C-c C-o</code> (Mac <code class="verbatim">⌃⌘O</code>) or <code class="verbatim">⌘</code>-click on a timestamp opens the agenda on that day, as <code class="verbatim">org-follow-timestamp-link</code> does. On a date range such as <code class="verbatim"><2026-10-05 Mon>--<2026-10-09 Fri></code>, the agenda shows the whole span. See <a href="07-agenda.html">Agenda</a>.</p> | |
| 142 | <h2 id="inserting-and-editing-links">Inserting and editing links</h2> | |
| 143 | <p><code class="verbatim">org-insert-link</code> asks for a link and a description in the echo area.</p> | |
| 144 | <table> | |
| 145 | <thead> | |
| 146 | <tr><th>Preset</th><th>Key</th></tr> | |
| 147 | </thead> | |
| 148 | <tbody> | |
| 149 | <tr><td>Emacs</td><td><code class="verbatim">C-c C-l</code></td></tr> | |
| 150 | <tr><td>Mac</td><td><code class="verbatim">⌘K</code></td></tr> | |
| 151 | <tr><td>Doom</td><td><code class="verbatim">SPC m l l</code>, or <code class="verbatim">C-c C-l</code></td></tr> | |
| 152 | </tbody> | |
| 153 | </table> | |
| 154 | <p>The first prompt reads <code class="verbatim">Insert link:</code>, or <code class="verbatim">Insert link (default …):</code> when you have stored links. It completes from:</p> | |
| 155 | <ul> | |
| 156 | <li>your stored links, most recent first, and their descriptions;</li> | |
| 157 | <li>the link abbreviations defined in the file (see <em>Link abbreviations</em>);</li> | |
| 158 | <li>the link types <code class="verbatim">attachment</code>, <code class="verbatim">id</code>, <code class="verbatim">eww</code>, <code class="verbatim">rmail</code>, <code class="verbatim">mhe</code>, <code class="verbatim">irc</code>, <code class="verbatim">info</code>, <code class="verbatim">gnus</code>, <code class="verbatim">docview</code>, <code class="verbatim">bibtex</code>, <code class="verbatim">bbdb</code>, <code class="verbatim">w3m</code>, <code class="verbatim">doi</code>, <code class="verbatim">file+sys</code>, <code class="verbatim">file+emacs</code>, <code class="verbatim">shell</code>, <code class="verbatim">news</code>, <code class="verbatim">mailto</code>, <code class="verbatim">https</code>, <code class="verbatim">http</code>, <code class="verbatim">ftp</code>, <code class="verbatim">shortdoc</code>, <code class="verbatim">help</code>, <code class="verbatim">file</code> and <code class="verbatim">elisp</code>, each followed by <code class="verbatim">:</code>.</li> | |
| 159 | </ul> | |
| 160 | <p>Pressing Return on an empty answer inserts the most recent stored link. Choosing a description inserts the link it belongs to. If you choose a bare type such as <code class="verbatim">https:</code>, a second prompt, <code class="verbatim">Link (no completion support):</code>, asks for the rest.</p> | |
| 161 | <p>The next prompt, <code class="verbatim">Description:</code>, offers the stored link's description, or the selected text if you selected some before running the command. An empty description inserts a link without one. With text selected, the link replaces the selection.</p> | |
| 162 | <p>When the caret is on an existing link, the same command edits it: the <code class="verbatim">Link:</code> prompt starts with the current target and <code class="verbatim">Description:</code> with the current description.</p> | |
| 163 | <p>A stored link that you insert is removed from the stored list, as with <code class="verbatim">org-link-keep-stored-after-insertion</code> set to nil.</p> | |
| 164 | <h3 id="file-paths-in-inserted-links">File paths in inserted links</h3> | |
| 165 | <p>When the inserted link is a <code class="verbatim">file:</code> link, Orgstar rewrites it as <code class="verbatim">org-link-make-string-for-buffer</code> does:</p> | |
| 166 | <ul> | |
| 167 | <li>A link to a heading or target in the file you are editing loses its <code class="verbatim">file:</code> part and keeps only the search, for example <code class="verbatim">[[*Ideas]]</code>.</li> | |
| 168 | <li>A path under the current file's folder becomes relative to it.</li> | |
| 169 | <li>Any other path is written with <code class="verbatim">~</code> for your home folder.</li> | |
| 170 | </ul> | |
| 171 | <h3 id="completion-while-typing">Completion while typing</h3> | |
| 172 | <p>You can also type a link by hand. With the caret right after <code class="verbatim">[[</code>, completion at point offers <code class="verbatim">attachment:</code>, <code class="verbatim">doi:</code>, <code class="verbatim">file:</code>, <code class="verbatim">http:</code>, <code class="verbatim">https:</code>, <code class="verbatim">id:</code> and <code class="verbatim">mailto:</code>, plus the file's link abbreviations. After <code class="verbatim">[[*</code>, it offers the headings of the current file. Completion at point is <code class="verbatim">C-M-i</code> in the Emacs preset and <code class="verbatim">C-SPC</code> in Doom's insert state; see <a href="02-the-editor.html">The editor</a>.</p> | |
| 173 | <h2 id="storing-links">Storing links</h2> | |
| 174 | <p><code class="verbatim">org-store-link</code> remembers a link to where the caret is, for a later Insert Link.</p> | |
| 175 | <table> | |
| 176 | <thead> | |
| 177 | <tr><th>Preset</th><th>Key</th></tr> | |
| 178 | </thead> | |
| 179 | <tbody> | |
| 180 | <tr><td>Emacs</td><td><code class="verbatim">C-c l</code></td></tr> | |
| 181 | <tr><td>Mac</td><td><code class="verbatim">⌃⌘L</code></td></tr> | |
| 182 | <tr><td>Doom</td><td><code class="verbatim">SPC m l s</code> or <code class="verbatim">SPC n l</code></td></tr> | |
| 183 | </tbody> | |
| 184 | </table> | |
| 185 | <p>The stored link is a <code class="verbatim">file:</code> link to the current file, written with <code class="verbatim">~</code> for your home folder, followed by a search option chosen as Org does with <code class="verbatim">org-link-context-for-files</code> on:</p> | |
| 186 | <ol> | |
| 187 | <li>If the caret touches a <code class="verbatim"><<target>></code> on its line, the link points at the target.</li> | |
| 188 | <li>Otherwise, if text is selected, the link searches for that text.</li> | |
| 189 | <li>Otherwise, if the caret is in an element with a <code class="verbatim">#+NAME</code>, the link uses the name.</li> | |
| 190 | <li>Otherwise, inside a heading's entry, the link uses <code class="verbatim">#custom-id</code> if the heading has a <code class="verbatim">CUSTOM_ID</code> property, and <code class="verbatim">*Title</code> if not. The title becomes the description.</li> | |
| 191 | <li>Before the first heading, the link searches for the text of the current line.</li> | |
| 192 | </ol> | |
| 193 | <p>The echo area shows <code class="verbatim">Stored:</code> and the description or link. Storing the same link again moves it to the front of the list. Stored links last until you quit Orgstar; they aren't saved between sessions, as in Emacs.</p> | |
| 194 | <h2 id="ids">IDs</h2> | |
| 195 | <p>Org identifies headings across files with an <code class="verbatim">ID</code> property. Two commands manage it.</p> | |
| 196 | <table> | |
| 197 | <thead> | |
| 198 | <tr><th>Command</th><th>Org function</th><th>Keys</th></tr> | |
| 199 | </thead> | |
| 200 | <tbody> | |
| 201 | <tr><td>Org ▸ Create ID</td><td><code class="verbatim">org-id-get-create</code></td><td>No default key</td></tr> | |
| 202 | <tr><td>Org ▸ Store ID Link</td><td><code class="verbatim">org-id-get-create</code> + <code class="verbatim">org-id-store-link</code></td><td>Doom <code class="verbatim">SPC m l i</code>; no key in Emacs or Mac</td></tr> | |
| 203 | </tbody> | |
| 204 | </table> | |
| 205 | <p>Create ID gives the heading at the caret an <code class="verbatim">ID</code> property if it doesn't have one. The ID is a new UUID in lower case, for example <code class="verbatim">6a3c2f9e-…</code>, as <code class="verbatim">org-id-uuid</code> makes them. Before the first heading, the property goes into the file-level property drawer.</p> | |
| 206 | <p>Store ID Link does the same, then stores an <code class="verbatim">id:</code> link to the heading with its title as the description. Before the first heading, the description is the <code class="verbatim">#+TITLE</code>, or the file name. If the caret is on a target or named element inside the entry, the link carries that search, as <code class="verbatim">id:…::search</code>, which mirrors <code class="verbatim">org-id-link-use-context</code>.</p> | |
| 207 | <p><code class="verbatim">CUSTOM_ID</code> is a property you set yourself, with the property commands in <a href="04-outlines.html">Outlines</a>. Link to it with <code class="verbatim">[[#name]]</code> in the same file or <code class="verbatim">[[file:other.org::#name]]</code> from another. Store Link uses it when the heading has one.</p> | |
| 208 | <h2 id="targets-and-radio-targets">Targets and radio targets</h2> | |
| 209 | <p><code class="verbatim"><<target>></code> marks a place in the text that a link with the same words reaches: <code class="verbatim">[[target]]</code>. Store Link with the caret on a target stores a link to it.</p> | |
| 210 | <p><code class="verbatim"><<<radio target>>></code> makes every other occurrence of its words in the file a link, matched case-insensitively and between non-word characters. Radio links are highlighted as links and exported as links to the target (see <a href="12-export.html">Export</a>). Following one moves to the radio target.</p> | |
| 211 | <h2 id="link-abbreviations">Link abbreviations</h2> | |
| 212 | <p>A <code class="verbatim">#+LINK:</code> line defines an abbreviation, as <code class="verbatim">org-link-abbrev-alist-local</code> does:</p> | |
| 213 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+LINK:</span><span class="string unquoted org"> gh https://github.com/%s</span> | |
| 214 | <span class="keyword other keyword org">#+LINK:</span><span class="string unquoted org"> search https://duckduckgo.com/?q=%h</span> | |
| 215 | <span class="keyword other keyword org">#+LINK:</span><span class="string unquoted org"> wiki https://en.wikipedia.org/wiki/</span> | |
| 216 | ||
| 217 | <span class="punctuation definition link org">[[</span><span class="markup underline link org">gh:orgmode/org-mode</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">]</span> → https:/<span class="markup italic org">/github.com/</span>orgmode/org-mode | |
| 218 | <span class="punctuation definition link org">[[</span><span class="markup underline link org">search:org tables</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">]</span> → https:/<span class="markup italic org">/duckduckgo.com/</span>?q=org%20tables | |
| 219 | <span class="punctuation definition link org">[[</span><span class="markup underline link org">wiki:Org-mode</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">]</span> → https:/<span class="markup italic org">/en.wikipedia.org/</span>wiki/Org-mode</span></code></pre> | |
| 220 | <p>In the template, <code class="verbatim">%s</code> is replaced by the text after the colon, <code class="verbatim">%h</code> by the same text percent-encoded, and a template with neither has the text appended. Function templates (<code class="verbatim">%(…)</code>) are not supported. Abbreviations from a <code class="verbatim">#+SETUPFILE</code> count too. When a key is defined twice, the first definition wins.</p> | |
| 221 | <h2 id="the-backlinks-pane">The backlinks pane</h2> | |
| 222 | <p>View ▸ Show or Hide Backlinks shows a pane beside the editor of an org file. It has two sections:</p> | |
| 223 | <ul> | |
| 224 | <li><strong>Links to</strong> the heading at the caret, named after that heading.</li> | |
| 225 | <li><strong>Links to this file</strong>.</li> | |
| 226 | </ul> | |
| 227 | <p>Each row shows the linking heading and its file name; a link in the text before a file's first heading is listed under the file's name. Click a row to open it. The pane is shown by default and updates as you move the caret and edit.</p> | |
| 228 | <p>The pane looks at every org file in your sidebar folders, including unsaved changes in open buffers. A link counts when following it would lead to the heading or the file:</p> | |
| 229 | <ul> | |
| 230 | <li><code class="verbatim">id:</code> links to the heading's <code class="verbatim">ID</code>;</li> | |
| 231 | <li><code class="verbatim">file:</code> links and plain paths (<code class="verbatim">./</code>, <code class="verbatim">../</code>, <code class="verbatim">/</code>, <code class="verbatim">~/</code>) to the file, with no search option for the file section, or with <code class="verbatim">::*Title</code>, <code class="verbatim">::#custom-id</code> or <code class="verbatim">::Title</code> for a heading;</li> | |
| 232 | <li>within the same file, <code class="verbatim">[[*Title]]</code>, <code class="verbatim">[[#custom-id]]</code> and <code class="verbatim">[[Title]]</code>.</li> | |
| 233 | </ul> | |
| 234 | <p>Links to targets, names and line numbers are not counted. A heading's links to itself are left out.</p> | |
| 235 | <h2 id="inline-images">Inline images</h2> | |
| 236 | <p><code class="verbatim">org-toggle-inline-images</code> shows image links as images.</p> | |
| 237 | <table> | |
| 238 | <thead> | |
| 239 | <tr><th>Preset</th><th>Key</th></tr> | |
| 240 | </thead> | |
| 241 | <tbody> | |
| 242 | <tr><td>Emacs</td><td><code class="verbatim">C-c C-x C-v</code></td></tr> | |
| 243 | <tr><td>Mac</td><td>Org ▸ Show or Hide Inline Images</td></tr> | |
| 244 | <tr><td>Doom</td><td><code class="verbatim">C-c C-x C-v</code></td></tr> | |
| 245 | </tbody> | |
| 246 | </table> | |
| 247 | <p>The echo area reports how many images are shown, or that inline display is off.</p> | |
| 248 | <p>A line shows an image when it holds nothing but a bracket link, without a description, to a file ending in <code class="verbatim">.png</code>, <code class="verbatim">.jpg</code>, <code class="verbatim">.jpeg</code>, <code class="verbatim">.gif</code>, <code class="verbatim">.svg</code>, <code class="verbatim">.webp</code>, <code class="verbatim">.tif</code>, <code class="verbatim">.tiff</code>, <code class="verbatim">.bmp</code>, <code class="verbatim">.heic</code> or <code class="verbatim">.avif</code> (in any case):</p> | |
| 249 | <pre><code class="language-org highlight"><span class="text org"><span class="punctuation definition link org">[[</span><span class="markup underline link org">file:images/diagram.png</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">]</span> | |
| 250 | <span class="punctuation definition link org">[[</span><span class="markup underline link org">./photo.jpg</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">]</span></span></code></pre> | |
| 251 | <p>Relative paths are resolved against the file's folder. Web addresses and <code class="verbatim">attachment:</code> links are not shown as images. The link text is hidden while the image is shown, except on the line that holds the caret.</p> | |
| 252 | <h3 id="sizing">Sizing</h3> | |
| 253 | <p>An image is drawn at its own width, up to the width of the text area. To set a width, put <code class="verbatim">#+ATTR_ORG: :width</code> with a number of points among the keywords above the link:</p> | |
| 254 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+CAPTION:</span><span class="string unquoted org"> Network layout</span> | |
| 255 | <span class="keyword other keyword org">#+ATTR_ORG:</span><span class="string unquoted org"> :width 300</span> | |
| 256 | <span class="punctuation definition link org">[[</span><span class="markup underline link org">file:images/network.png</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">]</span></span></code></pre> | |
| 257 | <p>The height follows the image's proportions. <code class="verbatim">#+ATTR_HTML</code> and other exporters' attributes don't affect the editor.</p> | |
| 258 | <h3 id="showing-images-when-a-file-opens">Showing images when a file opens</h3> | |
| 259 | <p>The config key <code class="verbatim">org-startup-with-inline-images</code> (default <code class="verbatim">false</code>) shows images in every file when it opens. In a file, <code class="verbatim">#+STARTUP: inlineimages</code> or <code class="verbatim">#+STARTUP: noinlineimages</code> overrides it.</p> | |
| 260 | <h2 id="org-protocol-store-link">org-protocol store-link</h2> | |
| 261 | <p>Orgstar handles <code class="verbatim">org-protocol://store-link</code> URLs, in the new form <code>org-protocol://store-link?url=…&title=…</code> and the old form <code class="verbatim">org-protocol://store-link:/URL/TITLE</code>. The URL is added to your stored links with the title as its description, and is also copied to the clipboard. Insert it with Insert Link. Setting up a browser bookmarklet, and <code class="verbatim">org-protocol://capture</code>, are in <a href="08-capture.html">Capture</a>.</p> | |
| 262 | <h2 id="on-ios">On iOS</h2> | |
| 263 | <p>The iOS app follows links: tap a link in the reader. Org files open in the app, and web, mail and other files go to the system. The iOS editor shows inline images as the Mac does; the reader doesn't. Storing and inserting links and the backlinks pane are Mac features. See <a href="14-ios.html">iOS</a>.</p> | |
| 264 | </main> | |
| 265 | <footer class="site"> | |
| 266 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 267 | </footer> | |
| 268 | </body> | |
| 269 | </html> | |
| \ No newline at end of file | ||
guide/10-tables.html added +421
| @@ -0,0 +1,421 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Tables · Orgstar</title> | |
| 7 | <meta name="description" content="Creating and editing Org tables, column widths, import and export, and spreadsheet formulas."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Tables</h1> | |
| 24 | <p class="lede">Org tables are plain text that Orgstar keeps aligned, edits by row and column, and recalculates with the same formulas Emacs uses.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#tables-in-org">Tables in Org</a></li> | |
| 29 | <li><a href="#creating-a-table">Creating a table</a></li> | |
| 30 | <li><a href="#moving-around-and-alignment">Moving around and alignment</a></li> | |
| 31 | <li><a href="#editing-rows-and-columns">Editing rows and columns</a> | |
| 32 | <ul> | |
| 33 | <li><a href="#sorting">Sorting</a></li> | |
| 34 | <li><a href="#transposing">Transposing</a></li> | |
| 35 | <li><a href="#the-field-editor">The field editor</a></li> | |
| 36 | </ul></li> | |
| 37 | <li><a href="#narrow-columns">Narrow columns</a></li> | |
| 38 | <li><a href="#importing-and-exporting">Importing and exporting</a></li> | |
| 39 | <li><a href="#formulas">Formulas</a> | |
| 40 | <ul> | |
| 41 | <li><a href="#kinds-of-formula">Kinds of formula</a></li> | |
| 42 | <li><a href="#references">References</a></li> | |
| 43 | <li><a href="#names-parameters-and-constants">Names, parameters and constants</a></li> | |
| 44 | <li><a href="#remote-references">Remote references</a></li> | |
| 45 | <li><a href="#calc-expressions">Calc expressions</a></li> | |
| 46 | <li><a href="#mode-flags-and-formats">Mode flags and formats</a></li> | |
| 47 | <li><a href="#durations">Durations</a></li> | |
| 48 | <li><a href="#dates">Dates</a></li> | |
| 49 | <li><a href="#lisp-formulas">Lisp formulas</a></li> | |
| 50 | </ul></li> | |
| 51 | <li><a href="#entering-formulas">Entering formulas</a></li> | |
| 52 | <li><a href="#recalculating">Recalculating</a></li> | |
| 53 | <li><a href="#when-emacs-is-needed">When Emacs is needed</a></li> | |
| 54 | <li><a href="#table-el-tables">table.el tables</a></li> | |
| 55 | <li><a href="#plotting">Plotting</a></li> | |
| 56 | <li><a href="#on-ios">On iOS</a></li> | |
| 57 | </ul> | |
| 58 | </nav> | |
| 59 | <h2 id="tables-in-org">Tables in Org</h2> | |
| 60 | <p>A table is a run of lines that start with <code class="verbatim">|</code>. Fields are separated by <code class="verbatim">|</code>, and a line that starts with <code class="verbatim">|-</code> is a horizontal rule:</p> | |
| 61 | <pre><code class="language-org highlight"><span class="text org"><span class="markup other table org">| Name | Qty | Price |</span> | |
| 62 | <span class="markup other table org">|-------+-----+-------|</span> | |
| 63 | <span class="markup other table org">| Apple | 3 | 0.50 |</span> | |
| 64 | <span class="markup other table org">| Pear | 12 | 0.75 |</span></span></code></pre> | |
| 65 | <p>Orgstar follows <code class="verbatim">org-table.el</code> from Org 9.8.7, with <code class="verbatim">org-table-automatic-realign</code> on, <code class="verbatim">org-table-tab-jumps-over-hlines</code> on, and formulas adjusted without asking when rows and columns move (<code class="verbatim">org-table-fix-formulas-confirm</code> nil). Tables inside dynamic blocks count as tables; tables inside other blocks don't.</p> | |
| 66 | <h2 id="creating-a-table">Creating a table</h2> | |
| 67 | <p>Type <code class="verbatim">|</code>, a few field names separated by <code class="verbatim">|</code>, and press <code class="verbatim">TAB</code>: Orgstar aligns the line as a table and moves to the next field, adding a row after the last one. Type <code class="verbatim">|-</code> on the line below a row and press <code class="verbatim">TAB</code> to turn it into a full-width rule.</p> | |
| 68 | <p><code class="verbatim">org-table-create-or-convert-from-region</code> builds one for you: <code>C-c |</code> in the Emacs and Doom presets, <code class="verbatim">⌃⌘\</code> in the Mac preset.</p> | |
| 69 | <p>With no selection it asks <code class="verbatim">Table size Columns x Rows [e.g. 5x2]:</code>. An empty answer makes a 5 × 2 table. When there is more than one row, a rule follows the first row.</p> | |
| 70 | <p>With text selected, the command converts the selected lines to a table instead (<code class="verbatim">org-table-convert-region</code>). The separator is guessed:</p> | |
| 71 | <ul> | |
| 72 | <li>tabs, when every line has a tab;</li> | |
| 73 | <li>otherwise commas, when every line has a comma, read as CSV: a field in double quotes can hold commas, and a line break in it becomes a space;</li> | |
| 74 | <li>otherwise runs of spaces.</li> | |
| 75 | </ul> | |
| 76 | <h2 id="moving-around-and-alignment">Moving around and alignment</h2> | |
| 77 | <table> | |
| 78 | <thead> | |
| 79 | <tr><th>Key</th><th>Org command</th><th>Action</th></tr> | |
| 80 | </thead> | |
| 81 | <tbody> | |
| 82 | <tr><td><code class="verbatim">TAB</code></td><td><code class="verbatim">org-table-next-field</code></td><td>Aligns the table and moves to the next field, skipping rules. In the last field it adds a row.</td></tr> | |
| 83 | <tr><td><code class="verbatim">S-TAB</code></td><td><code class="verbatim">org-table-previous-field</code></td><td>Aligns the table and moves to the previous field.</td></tr> | |
| 84 | <tr><td><code class="verbatim">RET</code></td><td><code class="verbatim">org-table-next-row</code></td><td>Aligns the table and moves down a row in the same column. Before a rule or at the end of the table it inserts a row.</td></tr> | |
| 85 | </tbody> | |
| 86 | </table> | |
| 87 | <p>These keys work the same in the Emacs and Mac presets. In Doom they apply in insert state; in normal state <code class="verbatim">RET</code> is Doom's "act at point" (see <em>Recalculating</em>).</p> | |
| 88 | <p>Alignment (<code class="verbatim">org-table-align</code>) pads every field to its column's width and redraws rules to match. A column is right-aligned when at least half of its non-empty fields are numbers, and left-aligned otherwise. A field that holds only a cookie <code class="verbatim"><l></code>, <code class="verbatim"><c></code> or <code class="verbatim"><r></code> (optionally with a width, such as <code class="verbatim"><r10></code>) fixes the column's alignment. Widths count display columns, so wide characters and hidden link markup are measured as they appear.</p> | |
| 89 | <p>Alignment happens when you press <code class="verbatim">TAB</code>, <code class="verbatim">S-TAB</code> or <code class="verbatim">RET</code> in a table and after every table command, not while you type. To align without moving, use Org ▸ Align Table:</p> | |
| 90 | <table> | |
| 91 | <thead> | |
| 92 | <tr><th>Preset</th><th>Key</th></tr> | |
| 93 | </thead> | |
| 94 | <tbody> | |
| 95 | <tr><td>Emacs</td><td><code class="verbatim">C-c C-c</code> in a table</td></tr> | |
| 96 | <tr><td>Mac</td><td><code class="verbatim">⌃⌘X</code> in a table</td></tr> | |
| 97 | <tr><td>Doom</td><td><code class="verbatim">C-c C-c</code>, or <code class="verbatim">SPC m b a</code></td></tr> | |
| 98 | </tbody> | |
| 99 | </table> | |
| 100 | <p><code class="verbatim">C-c C-c</code> (Mac <code class="verbatim">⌃⌘X</code>) in a table is <code class="verbatim">org-ctrl-c-ctrl-c</code>, as in Emacs. It first evaluates a formula typed in the current field (see <em>Entering formulas</em>). Then, in a row marked <code class="verbatim">#</code> (see <em>Names, parameters and constants</em>), it recalculates that row, which also aligns the table; in any other row it aligns the table. With the caret at the table's very first character, it recalculates the whole table instead.</p> | |
| 101 | <p>To align every table when a file opens, set <code class="verbatim">org-startup-align-all-tables</code> to <code class="verbatim">true</code> in the config file (default <code class="verbatim">false</code>), or put <code class="verbatim">#+STARTUP: align</code> in the file; <code class="verbatim">#+STARTUP: noalign</code> turns it off for that file. See <a href="13-configuration.html">Configuration</a>.</p> | |
| 102 | <h2 id="editing-rows-and-columns">Editing rows and columns</h2> | |
| 103 | <table> | |
| 104 | <thead> | |
| 105 | <tr><th>Action</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 106 | </thead> | |
| 107 | <tbody> | |
| 108 | <tr><td>Move row up</td><td><code class="verbatim">org-table-move-row-up</code></td><td><code class="verbatim">M-<up></code></td><td><code class="verbatim">⌃⌘↑</code></td><td><code class="verbatim">M-<up></code>, <code class="verbatim">M-k</code></td></tr> | |
| 109 | <tr><td>Move row down</td><td><code class="verbatim">org-table-move-row-down</code></td><td><code class="verbatim">M-<down></code></td><td><code class="verbatim">⌃⌘↓</code></td><td><code class="verbatim">M-<down></code>, <code class="verbatim">M-j</code></td></tr> | |
| 110 | <tr><td>Move column left</td><td><code class="verbatim">org-table-move-column-left</code></td><td><code class="verbatim">M-<left></code></td><td><code class="verbatim">⌃⌘←</code></td><td><code class="verbatim">M-<left></code>, <code class="verbatim">M-h</code></td></tr> | |
| 111 | <tr><td>Move column right</td><td><code class="verbatim">org-table-move-column-right</code></td><td><code class="verbatim">M-<right></code></td><td><code class="verbatim">⌃⌘→</code></td><td><code class="verbatim">M-<right></code>, <code class="verbatim">M-l</code></td></tr> | |
| 112 | <tr><td>Insert column</td><td><code class="verbatim">org-table-insert-column</code></td><td><code class="verbatim">M-S-<right></code></td><td><code class="verbatim">⌃⌥⌘→</code></td><td><code class="verbatim">M-S-<right></code>, <code class="verbatim">SPC m b i c</code></td></tr> | |
| 113 | <tr><td>Delete column</td><td><code class="verbatim">org-table-delete-column</code></td><td><code class="verbatim">M-S-<left></code></td><td><code class="verbatim">⌃⌥⌘←</code></td><td><code class="verbatim">M-S-<left></code>, <code class="verbatim">SPC m b d c</code></td></tr> | |
| 114 | <tr><td>Insert row above</td><td><code class="verbatim">org-table-insert-row</code></td><td><code class="verbatim">M-S-<down></code></td><td><code class="verbatim">⌃⌥⌘↓</code></td><td><code class="verbatim">M-S-<down></code>, <code class="verbatim">SPC m b i r</code></td></tr> | |
| 115 | <tr><td>Delete row</td><td><code class="verbatim">org-table-kill-row</code></td><td><code class="verbatim">M-S-<up></code></td><td><code class="verbatim">⌃⌥⌘↑</code></td><td><code class="verbatim">M-S-<up></code>, <code class="verbatim">SPC m b d r</code></td></tr> | |
| 116 | <tr><td>Insert rule below</td><td><code class="verbatim">org-table-insert-hline</code></td><td><code class="verbatim">C-c -</code></td><td><code class="verbatim">⌃⌘-</code></td><td><code class="verbatim">C-c -</code>, <code class="verbatim">SPC m b -</code>, <code class="verbatim">SPC m b i h</code></td></tr> | |
| 117 | <tr><td>Sort rows</td><td><code class="verbatim">org-table-sort-lines</code></td><td><code class="verbatim">C-c ^</code></td><td><code class="verbatim">⌃⇧⌘S</code></td><td><code class="verbatim">C-c ^</code></td></tr> | |
| 118 | <tr><td>Transpose</td><td><code class="verbatim">org-table-transpose-table-at-point</code></td><td>Org ▸ Transpose Table</td><td>Org ▸ Transpose Table</td><td>Org ▸ Transpose Table</td></tr> | |
| 119 | <tr><td>Edit field in its own editor</td><td><code class="verbatim">org-table-edit-field</code></td><td><code class="verbatim">C-c `</code></td><td>Org ▸ Edit Table Field</td><td><code class="verbatim">C-c `</code></td></tr> | |
| 120 | </tbody> | |
| 121 | </table> | |
| 122 | <p>The new column goes to the left of the caret's column, empty. Deleting a row deletes the line; it doesn't go to the clipboard. When rows and columns move, are inserted or are deleted, the <code class="verbatim">#+TBLFM</code> line is updated to match: references are renumbered, and formulas for a deleted row or column are removed.</p> | |
| 123 | <p>The Mac preset uses the same keys for headings and list items; in a table they act on the table.</p> | |
| 124 | <h3 id="sorting">Sorting</h3> | |
| 125 | <p><code class="verbatim">C-c ^</code> in a table asks <code class="verbatim">Sort Table: [a]lphabetic, [n]umeric, [t]ime. A/N/T means reversed:</code> and sorts the rows between the rules around the caret by the caret's column. If the caret isn't in a field, it asks for the column first. Sorting is stable.</p> | |
| 126 | <ul> | |
| 127 | <li><strong>a</strong> compares text without case.</li> | |
| 128 | <li><strong>n</strong> compares the number at the start of each field.</li> | |
| 129 | <li><strong>t</strong> compares a timestamp in the field, else a duration such as <code class="verbatim">1:30</code> or <code class="verbatim">2h 15min</code>, else a clock time <code class="verbatim">H:MM</code>. Fields with none of these sort as 0.</li> | |
| 130 | </ul> | |
| 131 | <h3 id="transposing">Transposing</h3> | |
| 132 | <p>Org ▸ Transpose Table swaps rows and columns. Rules are dropped.</p> | |
| 133 | <h3 id="the-field-editor">The field editor</h3> | |
| 134 | <p><code class="verbatim">C-c `</code> opens the field at the caret in an editor of its own, which is easier for long text. <code class="verbatim">C-c '</code> or <code class="verbatim">⌘Return</code> puts it back; <code class="verbatim">Escape</code> or <code class="verbatim">C-c C-k</code> leaves it unchanged. Line breaks become single spaces and lines that start with <code class="verbatim">#</code> are dropped, as <code class="verbatim">org-table-finish-edit-field</code> does.</p> | |
| 135 | <h2 id="narrow-columns">Narrow columns</h2> | |
| 136 | <p>A field that holds a width cookie <code class="verbatim"><N></code>, optionally with an alignment letter (<code class="verbatim"><l10></code>, <code class="verbatim"><c8></code>, <code class="verbatim"><r12></code>), marks the column for narrowing. Narrowed fields show their first <em>N</em> display columns followed by <code class="verbatim">…</code>. The text itself is unchanged.</p> | |
| 137 | <table> | |
| 138 | <thead> | |
| 139 | <tr><th>Command</th><th>Org command</th><th>Keys</th></tr> | |
| 140 | </thead> | |
| 141 | <tbody> | |
| 142 | <tr><td>Org ▸ Shrink or Expand Table Column</td><td><code class="verbatim">org-table-toggle-column-width</code></td><td>Emacs and Doom <code class="verbatim">C-c TAB</code></td></tr> | |
| 143 | <tr><td>Org ▸ Shrink Table Columns with Widths</td><td><code class="verbatim">org-table-shrink</code></td><td>No default key</td></tr> | |
| 144 | <tr><td>Org ▸ Expand Table Columns</td><td><code class="verbatim">org-table-expand</code></td><td>No default key</td></tr> | |
| 145 | </tbody> | |
| 146 | </table> | |
| 147 | <p><code class="verbatim">C-c TAB</code> in a field toggles that column. Outside a column, for example on the leading <code class="verbatim">|</code>, it asks for <code class="verbatim">Column ranges (e.g. 2-4 6-):</code>, where <code class="verbatim">6-</code> means column 6 to the end. A column without a width cookie shrinks to a bare <code class="verbatim">…</code> when toggled. Typing in a narrowed field widens its column again, as editing Org's overlays does. <code class="verbatim">#+STARTUP: shrink</code> narrows every column with a width cookie when the file opens.</p> | |
| 148 | <p>The iOS editor narrows columns the same way, with <code class="verbatim">#+STARTUP: shrink</code> and the three commands, which are in Commands when the caret is in a table. The iOS reader shows tables at full width.</p> | |
| 149 | <h2 id="importing-and-exporting">Importing and exporting</h2> | |
| 150 | <table> | |
| 151 | <thead> | |
| 152 | <tr><th>Command</th><th>Org command</th></tr> | |
| 153 | </thead> | |
| 154 | <tbody> | |
| 155 | <tr><td>Import Table from File… (command palette)</td><td><code class="verbatim">org-table-import</code></td></tr> | |
| 156 | <tr><td>Export Table to File… (command palette)</td><td><code class="verbatim">org-table-export</code></td></tr> | |
| 157 | </tbody> | |
| 158 | </table> | |
| 159 | <p>Open the command palette with <code class="verbatim">⇧⌘P</code> (<code class="verbatim">M-x</code> in the Emacs preset, <code class="verbatim">SPC :</code> in Doom).</p> | |
| 160 | <p>Import asks for a CSV, TSV or plain text file, inserts its contents at the caret on a line of its own, and converts them to a table with the separator guessed as for a region (see <em>Creating a table</em>).</p> | |
| 161 | <p>Export writes the table at the caret. A file name ending in <code class="verbatim">.csv</code> gets CSV: fields separated by commas, with fields that contain a comma or a double quote quoted and inner quotes doubled. Any other name gets TSV. Rules are left out.</p> | |
| 162 | <p>Import and export are Mac only.</p> | |
| 163 | <h2 id="formulas">Formulas</h2> | |
| 164 | <p>Orgstar evaluates Org's spreadsheet formulas, <code class="verbatim">org-table-recalculate</code> and <code class="verbatim">org-table-eval-formula</code>, natively: Calc expressions in a reimplementation of the part of Emacs Calc that tables use, and Lisp formulas in a small Emacs Lisp evaluator. What falls outside them is handed to Emacs on the Mac (see <em>When Emacs is needed</em>).</p> | |
| 165 | <p>Formulas live in a <code class="verbatim">#+TBLFM:</code> line right after the table, separated by <code class="verbatim">::</code>:</p> | |
| 166 | <pre><code class="language-org highlight"><span class="text org"><span class="markup other table org">| Item | Qty | Price | Total |</span> | |
| 167 | <span class="markup other table org">|-------+-----+-------+-------|</span> | |
| 168 | <span class="markup other table org">| Apple | 3 | 0.50 | 1.50 |</span> | |
| 169 | <span class="markup other table org">| Pear | 12 | 0.75 | 9.00 |</span> | |
| 170 | <span class="markup other table org">|-------+-----+-------+-------|</span> | |
| 171 | <span class="markup other table org">| Sum | | | 10.50 |</span> | |
| 172 | <span class="keyword other keyword org">#+TBLFM:</span><span class="string unquoted org"> $4=$2*$3;%.2f::@>$4=vsum(@I..@II);%.2f</span></span></code></pre> | |
| 173 | <p>Blank lines between the table and <code class="verbatim">#+TBLFM:</code> are allowed. If there are several <code class="verbatim">#+TBLFM:</code> lines, recalculating the table uses the first; <code class="verbatim">C-c C-c</code> on another applies that line instead (<code class="verbatim">org-table-calc-current-TBLFM</code>).</p> | |
| 174 | <h3 id="kinds-of-formula">Kinds of formula</h3> | |
| 175 | <table> | |
| 176 | <thead> | |
| 177 | <tr><th>Left side</th><th>Kind</th><th>Applies to</th></tr> | |
| 178 | </thead> | |
| 179 | <tbody> | |
| 180 | <tr><td><code class="verbatim">$3</code></td><td>Column formula</td><td>Every data row of column 3, except rows marked <code class="verbatim">!</code>, <code class="verbatim">^</code>, <code class="verbatim">_</code>, <code class="verbatim">$</code> or <code class="verbatim">/</code> in the first column.</td></tr> | |
| 181 | <tr><td><code class="verbatim">$<</code>, <code class="verbatim">$></code></td><td>Column formula</td><td>The first or last column.</td></tr> | |
| 182 | <tr><td><code class="verbatim">@2$3</code>, <code class="verbatim">@>$3</code></td><td>Field formula</td><td>One field. Field formulas override column formulas.</td></tr> | |
| 183 | <tr><td><code class="verbatim">@2$2..@4$3</code></td><td>Range formula</td><td>Every field in the rectangle.</td></tr> | |
| 184 | <tr><td><code class="verbatim">@4</code></td><td>Row formula</td><td>Every field of data row 4.</td></tr> | |
| 185 | <tr><td><code class="verbatim">$name</code></td><td>Named field formula</td><td>The field named by a <code class="verbatim">^</code> or <code class="verbatim">_</code> row (see <em>Names, parameters and constants</em>).</td></tr> | |
| 186 | </tbody> | |
| 187 | </table> | |
| 188 | <p>A left side relative to the current row, such as <code class="verbatim">@-1$2</code>, is an error (<code class="verbatim">Unknown field</code>), and so is one relative to a rule, such as <code class="verbatim">@I$2</code>, as in Org. Two formulas for the same field are an error.</p> | |
| 189 | <h3 id="references">References</h3> | |
| 190 | <p>Rows count data lines from 1; rules don't count. Columns count from 1.</p> | |
| 191 | <table> | |
| 192 | <thead> | |
| 193 | <tr><th>Reference</th><th>Meaning</th></tr> | |
| 194 | </thead> | |
| 195 | <tbody> | |
| 196 | <tr><td><code class="verbatim">$2</code></td><td>Column 2 in the current row.</td></tr> | |
| 197 | <tr><td><code class="verbatim">$-1</code>, <code class="verbatim">$+1</code></td><td>The column before or after the current one.</td></tr> | |
| 198 | <tr><td><code class="verbatim">$<</code>, <code class="verbatim">$></code>, <code class="verbatim">$>></code></td><td>The first column, the last, the one before last.</td></tr> | |
| 199 | <tr><td><code class="verbatim">@3</code></td><td>Row 3 in the current column.</td></tr> | |
| 200 | <tr><td><code class="verbatim">@-1</code>, <code class="verbatim">@+1</code></td><td>The row above or below.</td></tr> | |
| 201 | <tr><td><code class="verbatim">@<</code>, <code class="verbatim">@></code></td><td>The first or last data row.</td></tr> | |
| 202 | <tr><td><code class="verbatim">@I</code>, <code class="verbatim">@II</code>, <code class="verbatim">@III</code></td><td>The first, second, third rule; as a row, the line after it.</td></tr> | |
| 203 | <tr><td><code class="verbatim">@-I</code></td><td>The rule above the current row.</td></tr> | |
| 204 | <tr><td><code class="verbatim">@I+2</code></td><td>Two data rows after the first rule.</td></tr> | |
| 205 | <tr><td><code class="verbatim">@2$3</code></td><td>Row 2, column 3.</td></tr> | |
| 206 | <tr><td><code class="verbatim">$0</code></td><td>The current column.</td></tr> | |
| 207 | <tr><td><code class="verbatim">@0</code></td><td>The current row: <code class="verbatim">@0$2</code> is <code class="verbatim">$2</code>.</td></tr> | |
| 208 | <tr><td><code class="verbatim">@#</code>, <code class="verbatim">$#</code></td><td>The current row's or column's number, as a value.</td></tr> | |
| 209 | <tr><td><code class="verbatim">@2$1..@4$3</code></td><td>A range: the fields of the rectangle, as a vector.</td></tr> | |
| 210 | <tr><td><code class="verbatim">$1..$3</code></td><td>Columns 1 to 3 of the current row.</td></tr> | |
| 211 | <tr><td><code class="verbatim">@I..@II</code></td><td>The current column from the first rule to the second.</td></tr> | |
| 212 | </tbody> | |
| 213 | </table> | |
| 214 | <p>In a Calc formula a single field becomes a number in parentheses, and a range becomes a vector such as <code class="verbatim">[1,2,3]</code>. Without the <code class="verbatim">E</code> flag, empty fields count as 0 on their own and are left out of ranges.</p> | |
| 215 | <p>Fields in a Calc formula must hold numbers, timestamps or <code class="verbatim">nan</code>, unless the <code class="verbatim">N</code> flag reads every field as a number. A reference to a field with other text needs Emacs, because Calc would treat the text as a symbol.</p> | |
| 216 | <h3 id="names-parameters-and-constants">Names, parameters and constants</h3> | |
| 217 | <p>The first column can mark special rows, as in Org's spreadsheet:</p> | |
| 218 | <table> | |
| 219 | <thead> | |
| 220 | <tr><th>Mark</th><th>Row</th></tr> | |
| 221 | </thead> | |
| 222 | <tbody> | |
| 223 | <tr><td><code class="verbatim">#</code></td><td>Marked for recalculation.</td></tr> | |
| 224 | <tr><td><code class="verbatim">*</code></td><td>Marked for recalculation.</td></tr> | |
| 225 | </tbody> | |
| 226 | </table> | |
| 227 | <p>When any row's first field is one of <code class="verbatim">!</code>, <code class="verbatim">^</code>, <code class="verbatim">_</code>, <code class="verbatim">$</code>, <code class="verbatim">#</code> or <code class="verbatim">*</code>, column formulas in a whole-table recalculation apply only to the rows marked <code class="verbatim">#</code> or <code class="verbatim">*</code>, as <code class="verbatim">org-table-calculate-mark-regexp</code> decides in Org. So a table with a <code class="verbatim">!</code> names row and no <code class="verbatim">#</code> rows gets no column formulas applied; mark the rows to calculate. Field formulas apply either way. Rows marked <code class="verbatim">!</code>, <code class="verbatim">^</code>, <code class="verbatim">_</code>, <code class="verbatim">$</code> or <code class="verbatim">/</code> are never changed by column formulas.</p> | |
| 228 | <pre><code class="language-org highlight"><span class="text org"><span class="markup other table org">| ! | qty | price | total |</span> | |
| 229 | <span class="markup other table org">|---+-----+-------+-------|</span> | |
| 230 | <span class="markup other table org">| # | 2 | 3 | 6 |</span> | |
| 231 | <span class="markup other table org">| # | 4 | 0.5 | 2 |</span> | |
| 232 | <span class="keyword other keyword org">#+TBLFM:</span><span class="string unquoted org"> $4=$qty*$price</span></span></code></pre> | |
| 233 | <p>A <code class="verbatim">$name</code> that isn't a column name, parameter or named field is looked up as <code class="verbatim">org-table-get-constant</code> does:</p> | |
| 234 | <ul> | |
| 235 | <li>in <code class="verbatim">#+CONSTANTS:</code> lines of the file or its setup file, written <code>name=value</code> and separated by spaces (<code>#+CONSTANTS: c=299792458 g=9.81</code>);</li> | |
| 236 | <li><code class="verbatim">$PROP_xyz</code> reads the <code class="verbatim">xyz</code> property of the entry holding the table, with inheritance.</li> | |
| 237 | </ul> | |
| 238 | <p>A name that isn't found becomes <code class="verbatim">#UNDEFINED_NAME</code>. A parameter named <code class="verbatim">%</code> in a <code class="verbatim">$</code> row, for example <code>%=%.2f</code>, is put in front of the flags of every formula that has a <code class="verbatim">;</code>, so <code>$3=$2/3;</code> is formatted with <code class="verbatim">%.2f</code>.</p> | |
| 239 | <h3 id="remote-references">Remote references</h3> | |
| 240 | <p><code class="verbatim">remote(NAME, REF)</code> reads a field or range from another table:</p> | |
| 241 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> rates</span> | |
| 242 | <span class="markup other table org">| item | rate |</span> | |
| 243 | <span class="markup other table org">|------+------|</span> | |
| 244 | <span class="markup other table org">| a | 2 |</span> | |
| 245 | <span class="markup other table org">| b | 3 |</span> | |
| 246 | ||
| 247 | <span class="markup other table org">| x | y | z |</span> | |
| 248 | <span class="markup other table org">|---+---+---|</span> | |
| 249 | <span class="markup other table org">| 4 | 8 | 5 |</span> | |
| 250 | <span class="keyword other keyword org">#+TBLFM:</span><span class="string unquoted org"> $2=$1*remote(rates,@2$2)::$3=vsum(remote(rates,@2$2..@>$2))</span></span></code></pre> | |
| 251 | <p><code class="verbatim">NAME</code> is found in this order:</p> | |
| 252 | <ol> | |
| 253 | <li>a table after <code class="verbatim">#+NAME: NAME</code> or <code class="verbatim">#+TBLNAME: NAME</code> in the same file;</li> | |
| 254 | <li>the first table in the entry whose <code class="verbatim">ID</code> property is <code class="verbatim">NAME</code>, in the same file;</li> | |
| 255 | <li>the first table in the entry with that <code class="verbatim">ID</code> in any indexed file in your sidebar folders, read from the file on disk.</li> | |
| 256 | </ol> | |
| 257 | <p><code class="verbatim">REF</code> may use spreadsheet-style references such as <code class="verbatim">B3</code> (column B, row 3), which become <code class="verbatim">@3$2</code>. A <code class="verbatim">REF</code> without a row, such as <code class="verbatim">$1..$2</code>, reads the row of the other table that has the current row's number. <code class="verbatim">NAME</code> can itself be a reference: in <code class="verbatim">remote($1,@1$1)</code>, the current row's first field holds the table's name.</p> | |
| 258 | <h3 id="calc-expressions">Calc expressions</h3> | |
| 259 | <p>Calc formulas use Calc's number rules: integers are exact, and decimal numbers are rounded to 12 significant digits after every operation. Results are shown with up to 8 significant digits unless a format flag says otherwise (<code class="verbatim">org-calc-default-modes</code>).</p> | |
| 260 | <p>Operators, from lowest to highest precedence (the lowest, <code>||</code>, is logical or, giving 1 or 0):</p> | |
| 261 | <table> | |
| 262 | <thead> | |
| 263 | <tr><th>Operator</th><th>Meaning</th></tr> | |
| 264 | </thead> | |
| 265 | <tbody> | |
| 266 | <tr><td><code class="verbatim">&&</code></td><td>Logical and.</td></tr> | |
| 267 | <tr><td><code>==</code>, <code>!=</code>, <code class="verbatim"><</code>, <code class="verbatim">></code>, <code><=</code>, <code>>=</code></td><td>Comparisons, giving 1 or 0. They can't be chained.</td></tr> | |
| 268 | <tr><td><code class="verbatim">+</code>, <code class="verbatim">-</code></td><td>Addition and subtraction.</td></tr> | |
| 269 | <tr><td><code class="verbatim">/</code>, <code class="verbatim">%</code>, <code class="verbatim">\</code></td><td>Division, modulo (sign of the divisor), integer division rounding down.</td></tr> | |
| 270 | <tr><td><code class="verbatim">*</code></td><td>Multiplication.</td></tr> | |
| 271 | <tr><td>unary <code class="verbatim">-</code></td><td>Negation.</td></tr> | |
| 272 | </tbody> | |
| 273 | </table> | |
| 274 | <p>Parentheses group, <code class="verbatim">[a, b, c]</code> writes a vector, <code class="verbatim"><2026-10-05 Mon></code> writes a date, and <code class="verbatim">nan</code> is "not a number".</p> | |
| 275 | <p>Functions:</p> | |
| 276 | <table> | |
| 277 | <thead> | |
| 278 | <tr><th>Function</th><th>Result</th></tr> | |
| 279 | </thead> | |
| 280 | <tbody> | |
| 281 | <tr><td><code class="verbatim">vsum</code>, <code class="verbatim">vprod</code></td><td>Sum or product of a vector.</td></tr> | |
| 282 | <tr><td><code class="verbatim">vcount</code></td><td>Number of elements.</td></tr> | |
| 283 | <tr><td><code class="verbatim">vmean</code>, <code class="verbatim">vmedian</code></td><td>Mean, median.</td></tr> | |
| 284 | <tr><td><code class="verbatim">vmax</code>, <code class="verbatim">vmin</code></td><td>Largest, smallest element.</td></tr> | |
| 285 | <tr><td><code class="verbatim">vvar</code>, <code class="verbatim">vsdev</code></td><td>Sample variance, sample standard deviation.</td></tr> | |
| 286 | <tr><td><code class="verbatim">vpvar</code>, <code class="verbatim">vpsdev</code></td><td>Population variance, population standard deviation.</td></tr> | |
| 287 | <tr><td><code class="verbatim">max(a, b, …)</code>, <code class="verbatim">min(a, b, …)</code></td><td>Largest, smallest argument.</td></tr> | |
| 288 | <tr><td><code class="verbatim">if(c, a, b)</code></td><td><code class="verbatim">a</code> if <code class="verbatim">c</code> is nonzero, else <code class="verbatim">b</code>.</td></tr> | |
| 289 | <tr><td><code class="verbatim">abs</code></td><td>Absolute value.</td></tr> | |
| 290 | <tr><td><code class="verbatim">floor</code>, <code class="verbatim">ceil</code>, <code class="verbatim">trunc</code></td><td>Round down, up, toward zero, to an integer.</td></tr> | |
| 291 | <tr><td><code class="verbatim">round(x)</code>, <code class="verbatim">round(x, n)</code></td><td>Round to an integer, or to <em>n</em> decimal places.</td></tr> | |
| 292 | <tr><td><code class="verbatim">mod(a, b)</code>, <code class="verbatim">idiv(a, b)</code></td><td>As <code class="verbatim">%</code> and <code class="verbatim">\</code>.</td></tr> | |
| 293 | <tr><td><code class="verbatim">fact</code></td><td>Factorial of a non-negative integer.</td></tr> | |
| 294 | <tr><td><code class="verbatim">sqrt</code>, <code class="verbatim">exp</code>, <code class="verbatim">ln</code>, <code class="verbatim">log10</code></td><td>Square root, exponential, natural and base-10 logarithm.</td></tr> | |
| 295 | <tr><td><code class="verbatim">sin</code>, <code class="verbatim">cos</code>, <code class="verbatim">tan</code></td><td>Trigonometry, in degrees unless the <code class="verbatim">R</code> flag is set.</td></tr> | |
| 296 | <tr><td><code class="verbatim">arcsin</code>, <code class="verbatim">arccos</code>, <code class="verbatim">arctan</code></td><td>Inverse trigonometry, in degrees unless <code class="verbatim">R</code>.</td></tr> | |
| 297 | </tbody> | |
| 298 | </table> | |
| 299 | <p>Other Calc functions, variables such as <code class="verbatim">pi</code> or <code class="verbatim">e</code>, symbolic results, complex results and division by zero need Emacs.</p> | |
| 300 | <h3 id="mode-flags-and-formats">Mode flags and formats</h3> | |
| 301 | <p>After the formula, a <code class="verbatim">;</code> starts its flags, as in <code>$3=$1/$2;%.2f</code> or <code>$4=$1*2;f2</code>:</p> | |
| 302 | <table> | |
| 303 | <thead> | |
| 304 | <tr><th>Flag</th><th>Meaning</th></tr> | |
| 305 | </thead> | |
| 306 | <tbody> | |
| 307 | <tr><td><code class="verbatim">nN</code></td><td>Float format with <em>N</em> significant digits.</td></tr> | |
| 308 | <tr><td><code class="verbatim">fN</code></td><td>Fixed format with <em>N</em> decimal places.</td></tr> | |
| 309 | <tr><td><code class="verbatim">sN</code></td><td>Scientific format with <em>N</em> digits.</td></tr> | |
| 310 | <tr><td><code class="verbatim">eN</code></td><td>Engineering format with <em>N</em> digits.</td></tr> | |
| 311 | <tr><td><code class="verbatim">pN</code></td><td>Calc precision. Only <code class="verbatim">p12</code>, the default, is evaluated natively; others need Emacs.</td></tr> | |
| 312 | <tr><td><code class="verbatim">D</code>, <code class="verbatim">R</code></td><td>Angles in degrees (the default) or radians.</td></tr> | |
| 313 | <tr><td><code class="verbatim">F</code></td><td>Prefer fractions: <code class="verbatim">1/3</code> stays <code class="verbatim">1:3</code>.</td></tr> | |
| 314 | <tr><td><code class="verbatim">N</code></td><td>Treat every field as a number; text counts as 0.</td></tr> | |
| 315 | <tr><td><code class="verbatim">E</code></td><td>Keep empty fields: in ranges they stay in, and count as <code class="verbatim">nan</code> in Calc.</td></tr> | |
| 316 | <tr><td><code class="verbatim">L</code></td><td>Literal: in Lisp formulas, insert fields as they are written.</td></tr> | |
| 317 | <tr><td><code class="verbatim">T</code></td><td>Durations: read <code class="verbatim">H:MM</code> and <code class="verbatim">H:MM:SS</code> fields as times, show the result as <code class="verbatim">HH:MM:SS</code>.</td></tr> | |
| 318 | <tr><td><code class="verbatim">U</code></td><td>As <code class="verbatim">T</code>, showing <code class="verbatim">HH:MM</code>.</td></tr> | |
| 319 | <tr><td><code class="verbatim">t</code></td><td>As <code class="verbatim">T</code>, showing decimal hours with two places, such as <code class="verbatim">1.50</code>.</td></tr> | |
| 320 | </tbody> | |
| 321 | </table> | |
| 322 | <p>The flags <code class="verbatim">S</code> (symbolic) and <code class="verbatim">u</code> need Emacs. Any other text after the flags is a <code class="verbatim">format</code> string applied to the result, such as <code class="verbatim">%.2f</code> or <code class="verbatim">%d</code>; <code class="verbatim">format</code> supports <code class="verbatim">%s</code>, <code class="verbatim">%S</code>, <code class="verbatim">%d</code>, <code class="verbatim">%o</code>, <code class="verbatim">%x</code>, <code class="verbatim">%X</code>, <code class="verbatim">%c</code>, <code class="verbatim">%e</code>, <code class="verbatim">%f</code> and <code class="verbatim">%g</code>.</p> | |
| 323 | <h3 id="durations">Durations</h3> | |
| 324 | <p>With <code class="verbatim">T</code>, <code class="verbatim">U</code> or <code class="verbatim">t</code>, fields like <code class="verbatim">1:30</code> or <code class="verbatim">10:00:30</code> are read as hours, minutes and seconds:</p> | |
| 325 | <pre><code class="language-org highlight"><span class="text org"><span class="markup other table org">| start | end | sum | diff | hours |</span> | |
| 326 | <span class="markup other table org">|----------+---------+----------+-------+-------|</span> | |
| 327 | <span class="markup other table org">| 1:30 | 0:45 | 02:15:00 | 00:45 | 3.00 |</span> | |
| 328 | <span class="markup other table org">| 10:00:30 | 2:15:10 | 12:15:40 | 07:45 | 20.02 |</span> | |
| 329 | <span class="keyword other keyword org">#+TBLFM:</span><span class="string unquoted org"> $3=$1+$2;T::$4=$1-$2;U::$5=$1*2;t</span></span></code></pre> | |
| 330 | <h3 id="dates">Dates</h3> | |
| 331 | <p>Timestamps in fields, active or inactive, take part in Calc arithmetic as dates. The difference of two dates is a number of days, with a fraction when the timestamps have times. A date plus a number is a date, written back as an inactive timestamp:</p> | |
| 332 | <pre><code class="language-org highlight"><span class="text org"><span class="markup other table org">| start | end | days | later |</span> | |
| 333 | <span class="markup other table org">|------------------+------------------+------+------------------|</span> | |
| 334 | <span class="markup other table org">| <2026-10-05 Mon> | <2026-10-12 Mon> | 7 | [2026-10-12 Mon] |</span> | |
| 335 | <span class="keyword other keyword org">#+TBLFM:</span><span class="string unquoted org"> $3=$2-$1::$4=$1+7</span></span></code></pre> | |
| 336 | <h3 id="lisp-formulas">Lisp formulas</h3> | |
| 337 | <p>A formula that starts with <code class="verbatim">'(</code> is Emacs Lisp. Each reference becomes a Lisp string, or a number with <code class="verbatim">N</code>, or the field's text inserted as is with <code class="verbatim">L</code>. A range becomes the values separated by spaces, so wrap it in a quoted list:</p> | |
| 338 | <pre><code class="language-org highlight"><span class="text org"><span class="markup other table org">| name | greeting |</span> | |
| 339 | <span class="markup other table org">|-------+----------|</span> | |
| 340 | <span class="markup other table org">| Ada | Ada! |</span> | |
| 341 | <span class="markup other table org">| Grace | Grace! |</span> | |
| 342 | <span class="keyword other keyword org">#+TBLFM:</span><span class="string unquoted org"> $2='(concat $1 "!")</span> | |
| 343 | ||
| 344 | <span class="markup other table org">| n |</span> | |
| 345 | <span class="markup other table org">|---|</span> | |
| 346 | <span class="markup other table org">| 1 |</span> | |
| 347 | <span class="markup other table org">| 2 |</span> | |
| 348 | <span class="markup other table org">|---|</span> | |
| 349 | <span class="markup other table org">| 3 |</span> | |
| 350 | <span class="keyword other keyword org">#+TBLFM:</span><span class="string unquoted org"> @>$1='(apply '+ '(@I..@II));N</span></span></code></pre> | |
| 351 | <p>The evaluator supports:</p> | |
| 352 | <ul> | |
| 353 | <li>special forms: <code class="verbatim">quote</code>, <code class="verbatim">function</code>, <code class="verbatim">lambda</code>, <code class="verbatim">progn</code>, <code class="verbatim">prog1</code>, <code class="verbatim">if</code>, <code class="verbatim">when</code>, <code class="verbatim">unless</code>, <code class="verbatim">cond</code>, <code class="verbatim">and</code>, <code class="verbatim">or</code>, <code class="verbatim">let</code>, <code class="verbatim">let*</code>, <code class="verbatim">setq</code>, <code class="verbatim">push</code>, <code class="verbatim">pop</code>, <code class="verbatim">while</code>, <code class="verbatim">dolist</code>, <code class="verbatim">dotimes</code>, <code class="verbatim">with-output-to-string</code>, <code class="verbatim">ignore-errors</code>, <code class="verbatim">condition-case</code>;</li> | |
| 354 | <li>arithmetic: <code class="verbatim">+</code>, <code class="verbatim">-</code>, <code class="verbatim">*</code>, <code class="verbatim">/</code>, <code class="verbatim">%</code>, <code class="verbatim">mod</code>, <code class="verbatim">1+</code>, <code class="verbatim">1-</code>, <code class="verbatim">abs</code>, <code class="verbatim">max</code>, <code class="verbatim">min</code>, <code class="verbatim">float</code>, <code class="verbatim">floor</code>, <code class="verbatim">ceiling</code>, <code class="verbatim">round</code>, <code class="verbatim">truncate</code>, <code>=</code>, <code class="verbatim"><</code>, <code class="verbatim">></code>, <code><=</code>, <code>>=</code>, <code>/=</code>, <code class="verbatim">zerop</code>;</li> | |
| 355 | <li>predicates: <code class="verbatim">not</code>, <code class="verbatim">null</code>, <code class="verbatim">eq</code>, <code class="verbatim">eql</code>, <code class="verbatim">equal</code>, <code class="verbatim">numberp</code>, <code class="verbatim">integerp</code>, <code class="verbatim">floatp</code>, <code class="verbatim">stringp</code>, <code class="verbatim">listp</code>, <code class="verbatim">consp</code>, <code class="verbatim">symbolp</code>;</li> | |
| 356 | <li>lists: <code class="verbatim">car</code>, <code class="verbatim">cdr</code>, <code class="verbatim">cadr</code>, <code class="verbatim">cddr</code>, <code class="verbatim">cons</code>, <code class="verbatim">list</code>, <code class="verbatim">nth</code>, <code class="verbatim">nthcdr</code>, <code class="verbatim">elt</code>, <code class="verbatim">aref</code>, <code class="verbatim">append</code>, <code class="verbatim">length</code>, <code class="verbatim">reverse</code>, <code class="verbatim">number-sequence</code>, <code class="verbatim">memq</code>, <code class="verbatim">member</code>, <code class="verbatim">memql</code>, <code class="verbatim">assoc</code>, <code class="verbatim">assq</code>, <code class="verbatim">delq</code>, <code class="verbatim">delete</code>, <code class="verbatim">mapcar</code>, <code class="verbatim">mapc</code>, <code class="verbatim">mapconcat</code>, <code class="verbatim">funcall</code>, <code class="verbatim">apply</code>, <code class="verbatim">identity</code>, <code class="verbatim">ignore</code>;</li> | |
| 357 | <li>strings: <code class="verbatim">concat</code>, <code class="verbatim">format</code>, <code class="verbatim">format-message</code>, <code>string=</code>, <code class="verbatim">string-equal</code>, <code class="verbatim">string<</code>, <code class="verbatim">string-lessp</code>, <code class="verbatim">upcase</code>, <code class="verbatim">downcase</code>, <code class="verbatim">capitalize</code>, <code class="verbatim">substring</code>, <code class="verbatim">string-to-number</code>, <code class="verbatim">number-to-string</code>, <code class="verbatim">int-to-string</code>, <code class="verbatim">string-prefix-p</code>, <code class="verbatim">string-suffix-p</code>, <code class="verbatim">string-empty-p</code>, <code class="verbatim">string-trim</code>, <code class="verbatim">split-string</code>, <code class="verbatim">prin1-to-string</code>;</li> | |
| 358 | <li>output and errors: <code class="verbatim">princ</code>, <code class="verbatim">prin1</code>, <code class="verbatim">print</code>, <code class="verbatim">terpri</code>, <code class="verbatim">message</code>, <code class="verbatim">error</code>, <code class="verbatim">user-error</code>;</li> | |
| 359 | <li>Org's lookup functions <code class="verbatim">org-lookup-first</code>, <code class="verbatim">org-lookup-last</code> and <code class="verbatim">org-lookup-all</code>.</li> | |
| 360 | </ul> | |
| 361 | <p>Any other function needs Emacs. An error inside a Lisp formula writes <code class="verbatim">#ERROR</code> in the field, as does a Calc error.</p> | |
| 362 | <h2 id="entering-formulas">Entering formulas</h2> | |
| 363 | <p>There are three ways to set a formula.</p> | |
| 364 | <p><strong>In the field.</strong> Type <code>=expr</code> in a field and press <code class="verbatim">TAB</code> or <code class="verbatim">RET</code>: Orgstar stores <code>$N=expr</code> as the column's formula and evaluates it, as <code class="verbatim">org-table-maybe-eval-formula</code> does. Type <code>:=expr</code> instead to store a field formula <code>@R$C=expr</code>.</p> | |
| 365 | <p><strong>With a prompt.</strong> <code class="verbatim">org-table-eval-formula</code> asks for the formula (<code>Column formula $N=</code> or <code>Field formula @R$C=</code>) with the stored one filled in, stores it and evaluates it in the current field. Clearing the prompt and pressing <code class="verbatim">Return</code> removes the stored formula, as in Emacs, and the echo area shows <code class="verbatim">Formula removed</code>. You can also delete a formula in the formula editor below or from the <code class="verbatim">#+TBLFM:</code> line.</p> | |
| 366 | <table> | |
| 367 | <thead> | |
| 368 | <tr><th>Command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 369 | </thead> | |
| 370 | <tbody> | |
| 371 | <tr><td>Org ▸ Set Column Formula</td><td><code>C-c =</code></td><td>Org ▸ Set Column Formula</td><td><code>C-c =</code></td></tr> | |
| 372 | <tr><td>Org ▸ Set Field Formula</td><td>none</td><td>Org ▸ Set Field Formula</td><td>none</td></tr> | |
| 373 | </tbody> | |
| 374 | </table> | |
| 375 | <p>Org's <code>C-u C-c =</code> for field formulas has no equivalent key, because Orgstar has no prefix argument; use the menu item or type <code>:=</code> in the field.</p> | |
| 376 | <p><strong>In the formula editor.</strong> <code class="verbatim">C-c '</code> in a table or on its <code class="verbatim">#+TBLFM:</code> line (<code class="verbatim">org-table-edit-formulas</code>) opens the formulas in an editor of their own, one per line, grouped under <code class="verbatim"># Column Formulas</code>, <code class="verbatim"># Field and Range Formulas</code> and <code class="verbatim"># Named Field Formulas</code>. A formula can continue on indented lines. <code class="verbatim">C-c '</code> or <code class="verbatim">⌘Return</code> installs the formulas; <code class="verbatim">Escape</code> or <code class="verbatim">C-c C-k</code> leaves them unchanged. Installing doesn't recalculate. The echo area says so and points to Recalculate Table: <code class="verbatim">C-c C-c</code> on the <code class="verbatim">#+TBLFM:</code> line, or <code class="verbatim">⌃⌘X</code> there in the Mac preset.</p> | |
| 377 | <p>The formulas are stored sorted the way <code class="verbatim">org-table-formula-less-p</code> sorts them.</p> | |
| 378 | <h2 id="recalculating">Recalculating</h2> | |
| 379 | <table> | |
| 380 | <thead> | |
| 381 | <tr><th>Command</th><th>Org command</th><th>Emacs</th><th>Mac</th><th>Doom</th></tr> | |
| 382 | </thead> | |
| 383 | <tbody> | |
| 384 | <tr><td>Recalculate Table</td><td><code class="verbatim">org-table-recalculate</code> with <code class="verbatim">C-u</code></td><td><code class="verbatim">C-c C-c</code> on <code class="verbatim">#+TBLFM:</code></td><td><code class="verbatim">⌃⌘X</code> on <code class="verbatim">#+TBLFM:</code></td><td><code class="verbatim">SPC m b r</code>, <code class="verbatim">C-c C-c</code> on <code class="verbatim">#+TBLFM:</code></td></tr> | |
| 385 | <tr><td>Recalculate Table Row</td><td><code class="verbatim">org-table-recalculate</code></td><td><code class="verbatim">C-c *</code></td><td><code class="verbatim">⌃⌘*</code> (<code class="verbatim">⌃⇧⌘8</code> on a US keyboard)</td><td><code class="verbatim">C-c *</code></td></tr> | |
| 386 | </tbody> | |
| 387 | </table> | |
| 388 | <p>In Doom's normal state, <code class="verbatim">RET</code> in a table recalculates it when it has a <code class="verbatim">#+TBLFM:</code> line and aligns it otherwise; on a <code class="verbatim">#+TBLFM:</code> line it recalculates.</p> | |
| 389 | <p>When the table has a rule below its first data row, recalculating the whole table leaves the rows above that rule, the header, alone. With marked rows, the marks decide instead (see <em>Names, parameters and constants</em>). Each command evaluates the column formulas row by row, then the field formulas, then aligns the table. Formulas are evaluated once; Org's iterate-until-stable recalculation (<code class="verbatim">C-u C-u C-c *</code>) isn't available.</p> | |
| 390 | <p>Tables are not recalculated automatically. Rows marked <code class="verbatim">#</code> are not recalculated when you press <code class="verbatim">TAB</code> or <code class="verbatim">RET</code> in them, as <code class="verbatim">org-table-maybe-recalculate-line</code> would do in Emacs; recalculate with one of the commands above, or with <code class="verbatim">C-c C-c</code> (Mac <code class="verbatim">⌃⌘X</code>) in the row.</p> | |
| 391 | <h2 id="when-emacs-is-needed">When Emacs is needed</h2> | |
| 392 | <p>When a formula uses something the native evaluator doesn't have, the command reports what it was and the Mac recalculates the table in Emacs instead. This happens for:</p> | |
| 393 | <ul> | |
| 394 | <li>references to fields holding text in a Calc formula, and symbolic results;</li> | |
| 395 | <li>Calc functions and variables not listed above, precision other than <code class="verbatim">p12</code>, and the <code class="verbatim">S</code> and <code class="verbatim">u</code> flags;</li> | |
| 396 | <li>division by zero, complex results, vector results, and numbers too large for 64-bit integers;</li> | |
| 397 | <li>Lisp functions not listed above.</li> | |
| 398 | </ul> | |
| 399 | <p>The echo area shows <code class="verbatim">Recalculating in Emacs (reason)…</code>, then <code class="verbatim">Recalculated in Emacs</code>. Orgstar runs <code class="verbatim">emacs -Q --batch</code> on a copy of the file, so your Emacs init file, packages and customizations are not loaded, then replaces the table with Emacs's result. It looks for Emacs at the path in the <code class="verbatim">ORGSTAR_EMACS</code> environment variable, then <code class="verbatim">/opt/homebrew/bin/emacs</code>, <code class="verbatim">/usr/local/bin/emacs</code>, <code class="verbatim">/Applications/Emacs.app/Contents/MacOS/Emacs</code>, <code class="verbatim">/run/current-system/sw/bin/emacs</code> and <code class="verbatim">/usr/bin/emacs</code>. If none is found, the echo area says Emacs isn't installed and the table is unchanged. Emacs gets your <code class="verbatim">PATH</code> with <code class="verbatim">/opt/homebrew/bin</code>, <code class="verbatim">/usr/local/bin</code>, <code class="verbatim">/Library/TeX/texbin</code>, <code class="verbatim">/usr/bin</code> and <code class="verbatim">/bin</code> added, as code blocks and export do, so programs a formula starts are found when Orgstar was opened from the Dock. The run stops after 60 seconds. If you edit the table while Emacs is working, its result is discarded.</p> | |
| 400 | <p>Edit ▸ Cancel Running Task (<code class="verbatim">⌘.</code>) stops the recalculation; the echo area shows <code class="verbatim">Recalculation canceled</code> and the table is unchanged. Starting another recalculation or export in Emacs cancels the one that is running.</p> | |
| 401 | <p>If the table's formulas contain Lisp, Orgstar asks first: <code class="verbatim">This table's formulas run Lisp. Run them? (yes, no, always)</code>. <code class="verbatim">always</code> trusts this table's text in this file, so the question isn't asked again until the text changes.</p> | |
| 402 | <p>Entering a formula that needs Emacs with <code>C-c =</code>, Set Field Formula or <code>=</code> in a field is not handed to Emacs. The formula is stored in the <code class="verbatim">#+TBLFM:</code> line and the field is left as it was; the echo area shows <code class="verbatim">The formula was stored; recalculating it needs Emacs</code> and the reason. <code class="verbatim">TAB</code> and <code class="verbatim">RET</code> still move to the next field. Recalculate the table to run the formula in Emacs.</p> | |
| 403 | <p>For how Orgstar and Emacs share files, see <a href="15-alongside-emacs.html">Using Orgstar alongside Emacs</a>.</p> | |
| 404 | <h2 id="table-el-tables">table.el tables</h2> | |
| 405 | <p>Tables drawn with <code class="verbatim">+</code> corners and <code class="verbatim">-</code> and <code class="verbatim">|</code> borders, as the <code class="verbatim">table.el</code> package makes them, are recognized and kept as written:</p> | |
| 406 | <pre><code class="language-org highlight"><span class="text org"><span class="markup strikethrough org">+-------+</span>-------+ | |
| 407 | <span class="markup other table org">| Name | Value |</span> | |
| 408 | <span class="markup strikethrough org">+-------+</span>-------+ | |
| 409 | <span class="markup other table org">| a | 1 |</span> | |
| 410 | <span class="markup strikethrough org">+-------+</span>-------+</span></code></pre> | |
| 411 | <p>Orgstar doesn't edit them as tables: <code class="verbatim">TAB</code>, alignment and formulas don't apply. HTML export renders them as tables, with cells that span rows and columns, and Markdown export writes them as a code block. See <a href="12-export.html">Export</a>.</p> | |
| 412 | <h2 id="plotting">Plotting</h2> | |
| 413 | <p><code class="verbatim">#+PLOT:</code> lines are recognized and completed as keywords, but Orgstar doesn't draw plots (<code class="verbatim">org-plot/gnuplot</code> is not available).</p> | |
| 414 | <h2 id="on-ios">On iOS</h2> | |
| 415 | <p>The iOS app evaluates formulas natively with the same engine. Tables that need Emacs are not recalculated there; the app reports <code class="verbatim">This table needs Emacs, which runs on the Mac</code> with the reason. Table import and export are Mac only. Narrow columns work in the editor, as described under <em>Narrow columns</em>. See <a href="14-ios.html">iOS</a>.</p> | |
| 416 | </main> | |
| 417 | <footer class="site"> | |
| 418 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 419 | </footer> | |
| 420 | </body> | |
| 421 | </html> | |
| \ No newline at end of file | ||
guide/11-code-blocks.html added +743
| @@ -0,0 +1,743 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Code blocks · Orgstar</title> | |
| 7 | <meta name="description" content="Source blocks in Orgstar: highlighting, editing, running with Babel, results, header arguments, noweb and tangling."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Code blocks</h1> | |
| 24 | <p class="lede">Orgstar runs and tangles source blocks the way Org Babel does, and refuses anything it would run differently.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#source-blocks">Source blocks</a> | |
| 29 | <ul> | |
| 30 | <li><a href="#syntax-highlighting">Syntax highlighting</a></li> | |
| 31 | </ul></li> | |
| 32 | <li><a href="#editing-a-block-apart">Editing a block apart</a></li> | |
| 33 | <li><a href="#running-a-block">Running a block</a> | |
| 34 | <ul> | |
| 35 | <li><a href="#languages-that-run">Languages that run</a></li> | |
| 36 | <li><a href="#compiled-languages">Compiled languages</a></li> | |
| 37 | <li><a href="#the-trust-prompt">The trust prompt</a></li> | |
| 38 | <li><a href="#eval">:eval</a></li> | |
| 39 | <li><a href="#cancelling-a-run">Cancelling a run</a></li> | |
| 40 | </ul></li> | |
| 41 | <li><a href="#results">Results</a> | |
| 42 | <ul> | |
| 43 | <li><a href="#value-or-output">Value or output</a></li> | |
| 44 | <li><a href="#result-types">Result types</a></li> | |
| 45 | <li><a href="#result-formats">Result formats</a></li> | |
| 46 | <li><a href="#inserting">Inserting</a></li> | |
| 47 | <li><a href="#wrap">:wrap</a></li> | |
| 48 | <li><a href="#results-in-files">Results in files</a></li> | |
| 49 | </ul></li> | |
| 50 | <li><a href="#header-arguments">Header arguments</a> | |
| 51 | <ul> | |
| 52 | <li><a href="#where-they-come-from">Where they come from</a></li> | |
| 53 | <li><a href="#lisp-in-header-values">Lisp in header values</a></li> | |
| 54 | <li><a href="#header-argument-reference">Header argument reference</a></li> | |
| 55 | <li><a href="#arguments-that-are-refused">Arguments that are refused</a></li> | |
| 56 | </ul></li> | |
| 57 | <li><a href="#variables">Variables</a> | |
| 58 | <ul> | |
| 59 | <li><a href="#tables-in-variables">Tables in variables</a></li> | |
| 60 | <li><a href="#standard-input-and-arguments">Standard input and arguments</a></li> | |
| 61 | </ul></li> | |
| 62 | <li><a href="#sessions">Sessions</a></li> | |
| 63 | <li><a href="#caching">Caching</a></li> | |
| 64 | <li><a href="#noweb">Noweb</a></li> | |
| 65 | <li><a href="#calls">Calls</a> | |
| 66 | <ul> | |
| 67 | <li><a href="#call-lines">#+CALL: lines</a></li> | |
| 68 | <li><a href="#inline-calls-and-blocks">Inline calls and blocks</a></li> | |
| 69 | </ul></li> | |
| 70 | <li><a href="#emacs-lisp-blocks">Emacs Lisp blocks</a></li> | |
| 71 | <li><a href="#graphics">Graphics</a></li> | |
| 72 | <li><a href="#tangling">Tangling</a> | |
| 73 | <ul> | |
| 74 | <li><a href="#tangle-and-file-names">:tangle and file names</a></li> | |
| 75 | <li><a href="#tangling-arguments">Tangling arguments</a></li> | |
| 76 | <li><a href="#comments">Comments</a></li> | |
| 77 | <li><a href="#writing-the-files">Writing the files</a></li> | |
| 78 | <li><a href="#what-tangling-refuses">What tangling refuses</a></li> | |
| 79 | </ul></li> | |
| 80 | <li><a href="#on-ios">On iOS</a></li> | |
| 81 | </ul> | |
| 82 | </nav> | |
| 83 | <h2 id="source-blocks">Source blocks</h2> | |
| 84 | <p>A source block holds code in a named language:</p> | |
| 85 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python</span> | |
| 86 | return 6 * 7 | |
| 87 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 88 | <p>Orgstar reads the same syntax Org does: the language after <code class="verbatim">#+begin_src</code>, then any switches such as <code class="verbatim">-i</code> or <code class="verbatim">-r</code>, then header arguments. A <code class="verbatim">#+NAME:</code> line above a block names it, so other blocks, <code class="verbatim">#+CALL:</code> lines and <code class="verbatim">:var</code> references can refer to it.</p> | |
| 89 | <p>Lines inside a block that start with <code class="verbatim">*</code> or <code class="verbatim">#+</code> are protected with a leading comma, as Org does (<code class="verbatim">org-escape-code-in-region</code>). The comma is removed when the block runs, tangles or exports, and when you edit the block apart.</p> | |
| 90 | <h3 id="syntax-highlighting">Syntax highlighting</h3> | |
| 91 | <p>The code in a block is highlighted in the editor on the Mac and on iOS, in the iOS reader, and in the Mac's block editor, in the theme's <code class="verbatim">syntax-*</code> colours. Highlighting uses tree-sitter grammars for these language names:</p> | |
| 92 | <table> | |
| 93 | <thead> | |
| 94 | <tr><th>Language names</th><th>Grammar</th></tr> | |
| 95 | </thead> | |
| 96 | <tbody> | |
| 97 | <tr><td><code class="verbatim">sh</code>, <code class="verbatim">bash</code>, <code class="verbatim">shell</code>, <code class="verbatim">zsh</code></td><td>Bash</td></tr> | |
| 98 | <tr><td><code class="verbatim">python</code>, <code class="verbatim">python3</code>, <code class="verbatim">py</code></td><td>Python</td></tr> | |
| 99 | <tr><td><code class="verbatim">emacs-lisp</code>, <code class="verbatim">elisp</code></td><td>Emacs Lisp</td></tr> | |
| 100 | <tr><td><code class="verbatim">c</code></td><td>C</td></tr> | |
| 101 | <tr><td><code class="verbatim">c++</code>, <code class="verbatim">cpp</code></td><td>C++</td></tr> | |
| 102 | <tr><td><code class="verbatim">r</code></td><td>R</td></tr> | |
| 103 | <tr><td><code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">node</code></td><td>JavaScript</td></tr> | |
| 104 | <tr><td><code class="verbatim">java</code></td><td>Java</td></tr> | |
| 105 | <tr><td><code class="verbatim">scheme</code></td><td>Scheme</td></tr> | |
| 106 | <tr><td><code class="verbatim">clojure</code>, <code class="verbatim">clj</code></td><td>Clojure</td></tr> | |
| 107 | <tr><td><code class="verbatim">haskell</code></td><td>Haskell</td></tr> | |
| 108 | <tr><td><code class="verbatim">rust</code></td><td>Rust</td></tr> | |
| 109 | <tr><td><code class="verbatim">go</code></td><td>Go</td></tr> | |
| 110 | <tr><td><code class="verbatim">ruby</code></td><td>Ruby</td></tr> | |
| 111 | <tr><td><code class="verbatim">json</code></td><td>JSON</td></tr> | |
| 112 | <tr><td><code class="verbatim">yaml</code>, <code class="verbatim">yml</code></td><td>YAML</td></tr> | |
| 113 | <tr><td><code class="verbatim">toml</code>, <code class="verbatim">conf-toml</code></td><td>TOML</td></tr> | |
| 114 | <tr><td><code class="verbatim">lua</code></td><td>Lua</td></tr> | |
| 115 | </tbody> | |
| 116 | </table> | |
| 117 | <p>Names are matched without regard to case. Blocks in any other language show as plain monospaced text.</p> | |
| 118 | <h2 id="editing-a-block-apart">Editing a block apart</h2> | |
| 119 | <p><code class="verbatim">org-edit-special</code> edits a block's contents in a separate editor. Put the caret in a <code class="verbatim">src</code>, <code class="verbatim">example</code> or <code class="verbatim">export</code> block (or on a <code class="verbatim">#+TBLFM:</code> line; see <a href="10-tables.html">Tables</a>) and run <strong>Edit Block</strong>.</p> | |
| 120 | <table> | |
| 121 | <thead> | |
| 122 | <tr><th>Preset</th><th>Key</th></tr> | |
| 123 | </thead> | |
| 124 | <tbody> | |
| 125 | <tr><td>Emacs</td><td><code class="verbatim">C-c '</code></td></tr> | |
| 126 | <tr><td>Doom</td><td><code class="verbatim">C-c '</code>, or <code class="verbatim">SPC m '</code> in normal state</td></tr> | |
| 127 | <tr><td>Mac</td><td><code class="verbatim">⌃⌘'</code></td></tr> | |
| 128 | </tbody> | |
| 129 | </table> | |
| 130 | <p>On the Mac the block opens in a sheet titled with the block's kind and language, with the same highlighting as the main editor. The protecting commas are removed while you edit and added back when you save.</p> | |
| 131 | <table> | |
| 132 | <thead> | |
| 133 | <tr><th>Action</th><th>Keys</th></tr> | |
| 134 | </thead> | |
| 135 | <tbody> | |
| 136 | <tr><td>Save</td><td><code class="verbatim">C-c '</code> or ⌘Return, or <strong>Save Block</strong></td></tr> | |
| 137 | <tr><td>Leave</td><td><code class="verbatim">C-c C-k</code> or Escape, or <strong>Cancel</strong></td></tr> | |
| 138 | </tbody> | |
| 139 | </table> | |
| 140 | <p>If the block changed in the main editor while you edited it, the edit is not saved and the message area says so.</p> | |
| 141 | <p>On iOS the block opens in a plain text sheet with Cancel and Save buttons.</p> | |
| 142 | <h2 id="running-a-block">Running a block</h2> | |
| 143 | <p><code class="verbatim">C-c C-c</code> in a source block runs it (<code class="verbatim">org-babel-execute-src-block</code>) and writes its result under it. The same command runs a <code class="verbatim">#+CALL:</code> line or an inline <code class="verbatim">src_</code> block when the caret is on one.</p> | |
| 144 | <table> | |
| 145 | <thead> | |
| 146 | <tr><th>Preset</th><th>Key</th></tr> | |
| 147 | </thead> | |
| 148 | <tbody> | |
| 149 | <tr><td>Emacs</td><td><code class="verbatim">C-c C-c</code></td></tr> | |
| 150 | <tr><td>Doom</td><td><code class="verbatim">C-c C-c</code> in normal, insert and visual state</td></tr> | |
| 151 | <tr><td>Mac</td><td><code class="verbatim">⌃⌘X</code></td></tr> | |
| 152 | </tbody> | |
| 153 | </table> | |
| 154 | <p>The program runs in the folder of the file, or in <code class="verbatim">:dir</code>. It reads the code on standard input. While it runs, the message area shows "Running <em>language</em> block…"; when it ends, it shows "Code block evaluation complete." or the problem.</p> | |
| 155 | <p>If the program writes to standard error or exits with a non-zero status, the message area shows the exit status and the first line of standard error. The result is still inserted, as Emacs does.</p> | |
| 156 | <p>The block's text is remembered when the run starts. If you edit the block while it runs, so it can no longer be found, the result is not written.</p> | |
| 157 | <h3 id="languages-that-run">Languages that run</h3> | |
| 158 | <p>On the Mac, Orgstar starts each interpreter through <code class="verbatim">/usr/bin/env</code>. Because an app opened from the Dock does not see your shell's <code class="verbatim">PATH</code>, Orgstar adds <code class="verbatim">/opt/homebrew/bin</code>, <code class="verbatim">/usr/local/bin</code>, <code class="verbatim">/Library/TeX/texbin</code>, <code class="verbatim">/usr/bin</code> and <code class="verbatim">/bin</code> to the end of it.</p> | |
| 159 | <table> | |
| 160 | <thead> | |
| 161 | <tr><th>Language</th><th>Program run</th></tr> | |
| 162 | </thead> | |
| 163 | <tbody> | |
| 164 | <tr><td><code class="verbatim">sh</code>, <code class="verbatim">bash</code>, <code class="verbatim">zsh</code>, <code class="verbatim">fish</code>, <code class="verbatim">ksh</code>, <code class="verbatim">dash</code>, <code class="verbatim">ash</code>, <code class="verbatim">csh</code>, <code class="verbatim">mksh</code>, <code class="verbatim">posh</code></td><td>The shell of that name</td></tr> | |
| 165 | <tr><td><code class="verbatim">shell</code></td><td>The shell in <code class="verbatim">SHELL</code>, or <code class="verbatim">/bin/sh</code></td></tr> | |
| 166 | <tr><td><code class="verbatim">python</code></td><td><code class="verbatim">python3</code>, or the program in <code class="verbatim">:python</code></td></tr> | |
| 167 | <tr><td><code class="verbatim">emacs-lisp</code>, <code class="verbatim">elisp</code></td><td><code class="verbatim">emacs -Q --batch</code>; see Emacs Lisp blocks below</td></tr> | |
| 168 | <tr><td><code class="verbatim">ruby</code></td><td><code class="verbatim">ruby</code></td></tr> | |
| 169 | <tr><td><code class="verbatim">js</code>, <code class="verbatim">javascript</code></td><td><code class="verbatim">node</code></td></tr> | |
| 170 | <tr><td><code class="verbatim">R</code></td><td><code class="verbatim">Rscript -</code></td></tr> | |
| 171 | <tr><td><code class="verbatim">awk</code></td><td><code class="verbatim">awk -f /dev/stdin</code></td></tr> | |
| 172 | <tr><td><code class="verbatim">dot</code>, <code class="verbatim">plantuml</code>, <code class="verbatim">mermaid</code></td><td><code class="verbatim">dot</code>, <code class="verbatim">plantuml</code>, <code class="verbatim">mmdc</code>; see Graphics below</td></tr> | |
| 173 | <tr><td><code class="verbatim">C</code>, <code class="verbatim">C++</code>, <code class="verbatim">cpp</code>, <code class="verbatim">D</code>, <code class="verbatim">java</code>, <code class="verbatim">fortran</code>, <code class="verbatim">clojure</code></td><td>A compiler, or <code class="verbatim">bb</code> or <code class="verbatim">clojure</code>; see Compiled languages below</td></tr> | |
| 174 | </tbody> | |
| 175 | </table> | |
| 176 | <p>For <code class="verbatim">ruby</code>, <code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">R</code> and <code class="verbatim">awk</code>, <code class="verbatim">:cmd</code> names a different program. These languages always return their standard output, and <code class="verbatim">:var</code> is refused for them.</p> | |
| 177 | <p>Any other language is refused with "No way to run <em>language</em> blocks yet."</p> | |
| 178 | <p>A run that takes longer than five minutes is stopped. Runs in a <code class="verbatim">:session</code> have no time limit.</p> | |
| 179 | <h3 id="compiled-languages">Compiled languages</h3> | |
| 180 | <p>On the Mac, <code class="verbatim">C</code>, <code class="verbatim">C++</code>, <code class="verbatim">cpp</code>, <code class="verbatim">D</code>, <code class="verbatim">java</code>, <code class="verbatim">fortran</code> and <code class="verbatim">clojure</code> blocks run as Org's <code class="verbatim">ob-C</code>, <code class="verbatim">ob-java</code>, <code class="verbatim">ob-fortran</code> and <code class="verbatim">ob-clojure</code> run them. Orgstar writes the body, expanded as tangling writes it (see Tangling below), to a source file in a temporary folder, compiles it and runs the program in the file's folder or <code class="verbatim">:dir</code>, with a newline on standard input. What the compiler prints is dropped.</p> | |
| 181 | <table> | |
| 182 | <thead> | |
| 183 | <tr><th>Language</th><th>Commands</th></tr> | |
| 184 | </thead> | |
| 185 | <tbody> | |
| 186 | <tr><td><code class="verbatim">C</code></td><td><code class="verbatim">gcc -o bin FLAGS src LIBS</code>, then <code class="verbatim">bin CMDLINE</code></td></tr> | |
| 187 | <tr><td><code class="verbatim">C++</code>, <code class="verbatim">cpp</code></td><td><code class="verbatim">g++ -o bin FLAGS src LIBS</code>, then <code class="verbatim">bin CMDLINE</code></td></tr> | |
| 188 | <tr><td><code class="verbatim">D</code></td><td><code class="verbatim">rdmd FLAGS src CMDLINE</code>, which compiles and runs</td></tr> | |
| 189 | <tr><td><code class="verbatim">fortran</code></td><td><code class="verbatim">gfortran -o bin FLAGS src</code>, then <code class="verbatim">bin CMDLINE</code></td></tr> | |
| 190 | <tr><td><code class="verbatim">java</code></td><td><code class="verbatim">javac CMPFLAG Class.java</code>, then <code class="verbatim">java -cp dir CMDLINE Class CMDARGS</code></td></tr> | |
| 191 | <tr><td><code class="verbatim">clojure</code></td><td><code class="verbatim">bb src</code> (babashka) when <code class="verbatim">bb</code> is installed, otherwise <code class="verbatim">clojure -M src</code></td></tr> | |
| 192 | </tbody> | |
| 193 | </table> | |
| 194 | <p>FLAGS is <code class="verbatim">:flags</code>, LIBS is <code class="verbatim">:libs</code> or the inherited <code class="verbatim">LIBS</code> property, and CMDLINE is <code class="verbatim">:cmdline</code>. A Lisp list works for <code class="verbatim">:flags</code> and <code class="verbatim">:libs</code>; its items are joined with spaces.</p> | |
| 195 | <table> | |
| 196 | <thead> | |
| 197 | <tr><th>Argument</th><th>Languages</th><th>Effect</th></tr> | |
| 198 | </thead> | |
| 199 | <tbody> | |
| 200 | <tr><td><code class="verbatim">:flags</code></td><td>C, C++, D, Fortran</td><td>Compiler options.</td></tr> | |
| 201 | <tr><td><code class="verbatim">:libs</code></td><td>C, C++</td><td>Libraries, after the source file, such as <code class="verbatim">-lm</code>.</td></tr> | |
| 202 | <tr><td><code class="verbatim">:cmdline</code></td><td>C, C++, D, Fortran</td><td>The program's arguments.</td></tr> | |
| 203 | <tr><td><code class="verbatim">:cmdline</code></td><td>Java</td><td>Options for <code class="verbatim">java</code>, before the class name.</td></tr> | |
| 204 | <tr><td><code class="verbatim">:cmdargs</code></td><td>Java</td><td>The program's arguments.</td></tr> | |
| 205 | <tr><td><code class="verbatim">:cmpflag</code></td><td>Java</td><td>Options for <code class="verbatim">javac</code>.</td></tr> | |
| 206 | <tr><td><code class="verbatim">:javac</code>, <code class="verbatim">:java</code></td><td>Java</td><td>The compiler and runtime commands, with options; <code class="verbatim">javac</code> and <code class="verbatim">java</code> by default.</td></tr> | |
| 207 | <tr><td><code class="verbatim">:classname</code></td><td>Java</td><td>The class to run; a dotted name gives its package.</td></tr> | |
| 208 | <tr><td><code class="verbatim">:backend</code></td><td>Clojure</td><td><code class="verbatim">babashka</code> runs <code class="verbatim">bb</code>, <code class="verbatim">clojure-cli</code> runs <code class="verbatim">clojure -M</code>.</td></tr> | |
| 209 | <tr><td><code class="verbatim">:includes</code>, <code class="verbatim">:defines</code>, <code class="verbatim">:namespaces</code>, <code class="verbatim">:imports</code>, <code class="verbatim">:main</code>, <code class="verbatim">:prologue</code>, <code class="verbatim">:epilogue</code>, <code class="verbatim">:ns</code>, <code class="verbatim">:var</code></td><td>as for tangling</td><td>What the expansion writes; see Tangling below.</td></tr> | |
| 210 | </tbody> | |
| 211 | </table> | |
| 212 | <p>When <code class="verbatim">:imports</code> is absent, a D block reads the <code class="verbatim">IMPORTS</code> property where it is, and a Fortran block without <code class="verbatim">:includes</code> or <code class="verbatim">:defines</code> reads the <code class="verbatim">INCLUDES</code> and <code class="verbatim">DEFINES</code> properties, as Org does when it runs them. <code class="verbatim">:session</code> is ignored for these languages, as in Org.</p> | |
| 213 | <p>Java's defaults are <code class="verbatim">:results output</code> and <code class="verbatim">:dir .</code> (<code class="verbatim">org-babel-default-header-args:java</code>). The <code class="verbatim">.java</code> and <code class="verbatim">.class</code> files are written in the folder the block runs in, under folders for the class's package (<code class="verbatim">org/ex/Hello.java</code> for <code class="verbatim">:classname org.ex.Hello</code>), and are left there. The class is <code class="verbatim">:classname</code>, the body's own class with its <code class="verbatim">package</code>, or <code class="verbatim">Main</code>.</p> | |
| 214 | <p>Any other Clojure backend is refused: "The cider backend for clojure needs Emacs; Orgstar runs babashka or clojure-cli."</p> | |
| 215 | <p>Before a run, Orgstar checks that each program it needs is on the <code class="verbatim">PATH</code> described above. If not, the block fails with "gcc isn't installed, so C blocks can't run." (<code class="verbatim">g++</code> for C++, <code class="verbatim">rdmd</code>, <code class="verbatim">gfortran</code>, or the commands <code class="verbatim">:javac</code> and <code class="verbatim">:java</code> name). For Clojure without a <code class="verbatim">:backend</code>, the message is "Neither bb nor clojure is installed, so clojure blocks can't run."</p> | |
| 216 | <h3 id="the-trust-prompt">The trust prompt</h3> | |
| 217 | <p>Before a block runs, Orgstar asks "Run this <em>language</em> block? (yes, no, always)", as <code class="verbatim">org-confirm-babel-evaluate</code> does.</p> | |
| 218 | <ul> | |
| 219 | <li><code class="verbatim">yes</code> runs it this once.</li> | |
| 220 | <li><code class="verbatim">no</code> does not run it.</li> | |
| 221 | <li><code class="verbatim">always</code> runs it and remembers the block, so it runs without asking next time.</li> | |
| 222 | </ul> | |
| 223 | <p>A remembered block is identified by the file's path and the exact text of the block. Any change to the block, or moving the file, makes Orgstar ask again. The remembered hashes are kept in <code class="verbatim">trusted.json</code> in Orgstar's Application Support folder (<code class="verbatim">~/Library/Application Support/Orgstar</code> on the Mac). The same file records table formulas you allowed to run Lisp. To forget every choice, delete the file while Orgstar is not running.</p> | |
| 224 | <p>When a block's <code class="verbatim">:var</code> or <code class="verbatim">:stdin</code> refers to other blocks that have to run first, you are asked once for all of them. The prompt covers the block you ran and every block its references reach. If any of those blocks changes while the chain runs, Orgstar stops with "The blocks changed while running; nothing more was run."</p> | |
| 225 | <h3 id="eval"><code class="verbatim">:eval</code></h3> | |
| 226 | <table> | |
| 227 | <thead> | |
| 228 | <tr><th>Value</th><th>Effect</th></tr> | |
| 229 | </thead> | |
| 230 | <tbody> | |
| 231 | <tr><td><code class="verbatim">never</code>, <code class="verbatim">no</code></td><td>The block does not run: "Evaluation of this <em>language</em> code block is disabled."</td></tr> | |
| 232 | <tr><td><code class="verbatim">query</code></td><td>Asks every time, with only <code class="verbatim">yes</code> and <code class="verbatim">no</code>. A block reached through <code class="verbatim">:var</code> with <code class="verbatim">:eval query</code> makes the whole chain ask every time.</td></tr> | |
| 233 | <tr><td>anything else, or absent</td><td>Runs after the trust prompt.</td></tr> | |
| 234 | </tbody> | |
| 235 | </table> | |
| 236 | <p><code class="verbatim">never-export</code> and <code class="verbatim">no-export</code> only stop evaluation during export in Org. Orgstar does not run blocks during export, so with these values the block runs from <code class="verbatim">C-c C-c</code> like any other.</p> | |
| 237 | <h3 id="cancelling-a-run">Cancelling a run</h3> | |
| 238 | <p>On the Mac, Edit ▸ Cancel Running Task (⌘.) stops the running block. Its result is not inserted, and the message area shows "Code block canceled." The same command stops an export or table recalculation running in Emacs (see <a href="12-export.html">Export</a> and <a href="10-tables.html">Tables</a>). With nothing running it shows "Nothing is running". The command is also in the command palette.</p> | |
| 239 | <p>Only one block runs at a time. Starting another block cancels the one that is running.</p> | |
| 240 | <p>Cancelling a block that runs in a <code class="verbatim">:session</code> stops the session's interpreter, so the session's state is lost. The next block in that session starts a new one.</p> | |
| 241 | <p>The iOS app has no cancel command.</p> | |
| 242 | <h2 id="results">Results</h2> | |
| 243 | <p>The result is written after a <code class="verbatim">#+RESULTS:</code> line below the block (<code class="verbatim">org-babel-insert-result</code>). Running again replaces it. A named block's result goes under <code class="verbatim">#+RESULTS: name</code>, wherever that line is in the file. An unnamed block's result is the <code class="verbatim">#+RESULTS:</code> line right after it, past blank lines. The result keeps the block's indentation, so a block inside a list item keeps its result inside the item.</p> | |
| 244 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh</span> | |
| 245 | echo hello | |
| 246 | <span class="keyword control block end org">#+end_src</span> | |
| 247 | </span> | |
| 248 | <span class="keyword other keyword org">#+RESULTS:</span> | |
| 249 | : hello</span></code></pre> | |
| 250 | <p>By default a result is shaped like this:</p> | |
| 251 | <ul> | |
| 252 | <li>Text of fewer than ten lines gets a =: = prefix on each line.</li> | |
| 253 | <li>Text of ten lines or more goes in an <code class="verbatim">#+begin_example</code> block.</li> | |
| 254 | <li>A table becomes an aligned Org table.</li> | |
| 255 | </ul> | |
| 256 | <h3 id="value-or-output">Value or output</h3> | |
| 257 | <table> | |
| 258 | <thead> | |
| 259 | <tr><th>Word</th><th>Result</th></tr> | |
| 260 | </thead> | |
| 261 | <tbody> | |
| 262 | <tr><td><code class="verbatim">value</code></td><td>The value of the block. This is the default.</td></tr> | |
| 263 | <tr><td><code class="verbatim">output</code></td><td>Everything the program printed on standard output.</td></tr> | |
| 264 | </tbody> | |
| 265 | </table> | |
| 266 | <p>What "value" means depends on the language:</p> | |
| 267 | <table> | |
| 268 | <thead> | |
| 269 | <tr><th>Language</th><th>Value</th></tr> | |
| 270 | </thead> | |
| 271 | <tbody> | |
| 272 | <tr><td>Shells, by default</td><td>Standard output, read as a table: tab-separated columns, then comma-separated, then space-separated; a single field is a plain value.</td></tr> | |
| 273 | <tr><td>Shells, <code class="verbatim">:results value</code> written out</td><td>The exit status of the last command.</td></tr> | |
| 274 | <tr><td>Python</td><td>What the block returns. The body runs as a function, so it needs <code class="verbatim">return</code>. <code class="verbatim">:return expr</code> adds a final <code class="verbatim">return expr</code>.</td></tr> | |
| 275 | <tr><td>Python in a <code class="verbatim">:session</code></td><td>The value of the last expression.</td></tr> | |
| 276 | <tr><td>Emacs Lisp</td><td>The value of the last form.</td></tr> | |
| 277 | <tr><td><code class="verbatim">ruby</code>, <code class="verbatim">js</code>, <code class="verbatim">R</code>, <code class="verbatim">awk</code></td><td>Standard output, always.</td></tr> | |
| 278 | <tr><td>C, C++, D</td><td>Standard output without its common indentation, read as a table as for shells.</td></tr> | |
| 279 | <tr><td>Fortran</td><td>The same, with blank space around the output trimmed.</td></tr> | |
| 280 | <tr><td>Java</td><td>With <code class="verbatim">:results value</code>, what the body returns; it runs as <code class="verbatim">main</code>, so it needs <code class="verbatim">return</code>. Lists and arrays become tables, with <code class="verbatim">null</code> rows as rules, and a returned string is written without its quotes. Java's default is <code class="verbatim">:results output</code>.</td></tr> | |
| 281 | <tr><td>Clojure</td><td>The value of the last form as Clojure prints it. A number, or a string without its quotes, is written as that; vectors, lists and maps are written as printed, not as tables.</td></tr> | |
| 282 | </tbody> | |
| 283 | </table> | |
| 284 | <p>Python lists of lists become tables, with <code class="verbatim">None</code> rows as rules. A flat list becomes a one-row table. Emacs Lisp lists become tables the same way, with <code class="verbatim">hline</code> for rules. Numbers are written the way Emacs prints them.</p> | |
| 285 | <h3 id="result-types">Result types</h3> | |
| 286 | <table> | |
| 287 | <thead> | |
| 288 | <tr><th>Word</th><th>Effect</th></tr> | |
| 289 | </thead> | |
| 290 | <tbody> | |
| 291 | <tr><td><code class="verbatim">table</code>, <code class="verbatim">vector</code></td><td>Read the result as a table. This is the default for values.</td></tr> | |
| 292 | <tr><td><code class="verbatim">list</code></td><td>Write a plain list, one =- = item per line or per element.</td></tr> | |
| 293 | <tr><td><code class="verbatim">scalar</code>, <code class="verbatim">verbatim</code></td><td>Write the result as text without reading it as a table.</td></tr> | |
| 294 | <tr><td><code class="verbatim">file</code></td><td>Write a link to a file (see Results in files below).</td></tr> | |
| 295 | </tbody> | |
| 296 | </table> | |
| 297 | <p><code class="verbatim">:results verbatim</code> on an Emacs Lisp value writes it as <code class="verbatim">prin1</code> would, with quotes around strings.</p> | |
| 298 | <p>With <code class="verbatim">:results output list</code>, the list made from the output is written as an example, in lines such as <code class="verbatim">: - a</code>, as Org writes it:</p> | |
| 299 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :results output list</span> | |
| 300 | printf 'a\nb\n' | |
| 301 | <span class="keyword control block end org">#+end_src</span> | |
| 302 | </span> | |
| 303 | <span class="keyword other keyword org">#+RESULTS:</span> | |
| 304 | : - a | |
| 305 | : - b</span></code></pre> | |
| 306 | <h3 id="result-formats">Result formats</h3> | |
| 307 | <table> | |
| 308 | <thead> | |
| 309 | <tr><th>Word</th><th>Written as</th></tr> | |
| 310 | </thead> | |
| 311 | <tbody> | |
| 312 | <tr><td><code class="verbatim">raw</code></td><td>The text as it is, so Org markup in it takes effect.</td></tr> | |
| 313 | <tr><td><code class="verbatim">drawer</code></td><td>Between <code class="verbatim">:results:</code> and <code class="verbatim">:end:</code>.</td></tr> | |
| 314 | <tr><td><code class="verbatim">code</code></td><td>In a <code class="verbatim">#+begin_src</code> block of the block's language.</td></tr> | |
| 315 | <tr><td><code class="verbatim">org</code></td><td>In a <code class="verbatim">#+begin_src org</code> block.</td></tr> | |
| 316 | <tr><td><code class="verbatim">html</code></td><td>In a <code class="verbatim">#+begin_export html</code> block.</td></tr> | |
| 317 | <tr><td><code class="verbatim">latex</code></td><td>In a <code class="verbatim">#+begin_export latex</code> block.</td></tr> | |
| 318 | <tr><td><code class="verbatim">pp</code></td><td>Python: formatted with <code class="verbatim">pprint</code>; written as text.</td></tr> | |
| 319 | </tbody> | |
| 320 | </table> | |
| 321 | <p>Lines that start with <code class="verbatim">*</code> or <code class="verbatim">#+</code> inside <code class="verbatim">code</code>, <code class="verbatim">org</code>, <code class="verbatim">html</code> and <code class="verbatim">latex</code> results are comma-protected.</p> | |
| 322 | <h3 id="inserting">Inserting</h3> | |
| 323 | <table> | |
| 324 | <thead> | |
| 325 | <tr><th>Word</th><th>Effect</th></tr> | |
| 326 | </thead> | |
| 327 | <tbody> | |
| 328 | <tr><td><code class="verbatim">replace</code></td><td>Replace the previous result. This is the default.</td></tr> | |
| 329 | <tr><td><code class="verbatim">append</code></td><td>Add after the previous result.</td></tr> | |
| 330 | <tr><td><code class="verbatim">prepend</code></td><td>Add before the previous result.</td></tr> | |
| 331 | <tr><td><code class="verbatim">silent</code></td><td>Show the output in the message area and write nothing.</td></tr> | |
| 332 | <tr><td><code class="verbatim">none</code>, <code class="verbatim">discard</code></td><td>Write nothing.</td></tr> | |
| 333 | </tbody> | |
| 334 | </table> | |
| 335 | <p>Words from different groups combine: <code class="verbatim">:results output list append</code>. A later word replaces an earlier one from the same group.</p> | |
| 336 | <h3 id="wrap"><code class="verbatim">:wrap</code></h3> | |
| 337 | <p><code class="verbatim">:wrap</code> puts the result in a block, ahead of any format word.</p> | |
| 338 | <table> | |
| 339 | <thead> | |
| 340 | <tr><th>Value</th><th>Wrapped in</th></tr> | |
| 341 | </thead> | |
| 342 | <tbody> | |
| 343 | <tr><td><code class="verbatim">:wrap</code> alone</td><td><code class="verbatim">#+begin_results</code> … <code class="verbatim">#+end_results</code></td></tr> | |
| 344 | <tr><td><code class="verbatim">:wrap example</code></td><td><code class="verbatim">#+begin_example</code> … <code class="verbatim">#+end_example</code></td></tr> | |
| 345 | <tr><td><code class="verbatim">:wrap src python</code></td><td><code class="verbatim">#+begin_src python</code> … <code class="verbatim">#+end_src</code></td></tr> | |
| 346 | <tr><td><code class="verbatim">:wrap export html</code></td><td><code class="verbatim">#+begin_export html</code> … <code class="verbatim">#+end_export</code></td></tr> | |
| 347 | <tr><td><code class="verbatim">:wrap no</code>, <code class="verbatim">:wrap nil</code></td><td>No wrapping</td></tr> | |
| 348 | </tbody> | |
| 349 | </table> | |
| 350 | <p>Inside <code class="verbatim">example</code>, <code class="verbatim">src</code> and <code class="verbatim">export</code> wrappers, lines starting with <code class="verbatim">*</code> or <code class="verbatim">#+</code> are comma-protected.</p> | |
| 351 | <h3 id="results-in-files">Results in files</h3> | |
| 352 | <p>With <code class="verbatim">:results file</code>, the result is a link instead of text.</p> | |
| 353 | <table> | |
| 354 | <thead> | |
| 355 | <tr><th>Header</th><th>Effect</th></tr> | |
| 356 | </thead> | |
| 357 | <tbody> | |
| 358 | <tr><td><code class="verbatim">:file name</code></td><td>Write the result into <code class="verbatim">name</code> and link to it. Without <code class="verbatim">:results file</code>, <code class="verbatim">:file</code> has no effect, except in graphics blocks.</td></tr> | |
| 359 | <tr><td><code class="verbatim">:output-dir dir</code></td><td>Put <code class="verbatim">:file</code> under <code class="verbatim">dir</code>. The folder must exist.</td></tr> | |
| 360 | <tr><td><code class="verbatim">:file-desc text</code></td><td>Give the link a description: <code class="verbatim">[[file:name][text]]</code>. An empty <code class="verbatim">:file-desc</code> uses the file name.</td></tr> | |
| 361 | </tbody> | |
| 362 | </table> | |
| 363 | <p>A relative <code class="verbatim">:file</code> is written in the folder the block ran in: the file's folder, or <code class="verbatim">:dir</code>. Without <code class="verbatim">:file</code>, <code class="verbatim">:results file</code> takes the result itself as the path to link to.</p> | |
| 364 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :results file :file out.txt :file-desc Output</span> | |
| 365 | echo hello | |
| 366 | <span class="keyword control block end org">#+end_src</span> | |
| 367 | </span> | |
| 368 | <span class="keyword other keyword org">#+RESULTS:</span> | |
| 369 | <span class="punctuation definition link org">[[</span><span class="markup underline link org">file:out.txt</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">[</span><span class="string other link title org">Output</span><span class="punctuation definition link org">]]</span></span></code></pre> | |
| 370 | <h2 id="header-arguments">Header arguments</h2> | |
| 371 | <h3 id="where-they-come-from">Where they come from</h3> | |
| 372 | <p>Orgstar merges header arguments in this order, each layer overriding the ones before it (<code class="verbatim">org-babel-get-src-block-info</code>):</p> | |
| 373 | <ol> | |
| 374 | <li><code class="verbatim">#+PROPERTY: header-args …</code> in the file, then <code class="verbatim">header-args</code> properties of the block's headings, from the outermost heading inwards.</li> | |
| 375 | <li><code class="verbatim">header-args:LANG</code> the same way, for blocks in language <code class="verbatim">LANG</code>.</li> | |
| 376 | <li>The arguments on the <code class="verbatim">#+begin_src</code> line.</li> | |
| 377 | <li><code class="verbatim">#+HEADER:</code> lines above the block.</li> | |
| 378 | <li>For a call, the call's arguments (see Calls below).</li> | |
| 379 | </ol> | |
| 380 | <p>A property written with a <code class="verbatim">+</code>, such as <code class="verbatim">header-args+</code>, adds to the value inherited from above instead of replacing it. In a property drawer, <code class="verbatim">:header-args:sh:</code> is one property name, so its value applies only to <code class="verbatim">sh</code> blocks.</p> | |
| 381 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+PROPERTY:</span><span class="string unquoted org"> header-args :results output</span> | |
| 382 | ||
| 383 | <span class="markup heading org"><span class="punctuation definition heading org">*</span> Scripts | |
| 384 | </span>:PROPERTIES: | |
| 385 | :header-args:sh: :dir /tmp | |
| 386 | :END: | |
| 387 | ||
| 388 | <span class="keyword other keyword org">#+HEADER:</span><span class="string unquoted org"> :results verbatim</span> | |
| 389 | <span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :var name="world"</span> | |
| 390 | echo "hello $name" | |
| 391 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 392 | <p>Without any of these, a block has <code class="verbatim">:results replace</code>, <code class="verbatim">:exports code</code>, <code class="verbatim">:session none</code>, <code class="verbatim">:cache no</code>, <code class="verbatim">:noweb no</code>, <code class="verbatim">:hlines no</code> and <code class="verbatim">:tangle no</code>. An inline <code class="verbatim">src_</code> block defaults to <code class="verbatim">:exports results</code> and <code class="verbatim">:hlines yes</code>.</p> | |
| 393 | <h3 id="lisp-in-header-values">Lisp in header values</h3> | |
| 394 | <p>A header value that starts with <code class="verbatim">(</code>, <code class="verbatim">'</code>, <code class="verbatim">`</code> or <code class="verbatim">[</code> and is not in quotes is Lisp, as in <code class="verbatim">org-babel-read</code>. Orgstar evaluates it with its own Emacs Lisp interpreter, which also knows <code class="verbatim">buffer-file-name</code>, <code class="verbatim">default-directory</code>, <code class="verbatim">system-type</code> and the functions <code class="verbatim">expand-file-name</code>, <code class="verbatim">file-name-directory</code>, <code class="verbatim">file-name-nondirectory</code>, <code class="verbatim">file-name-sans-extension</code> and <code class="verbatim">file-name-as-directory</code>.</p> | |
| 395 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :dir (concat "/" "usr") :results output</span> | |
| 396 | pwd | |
| 397 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 398 | <p>A string or number takes the place of the form. Lisp that the interpreter cannot evaluate is refused where it matters: for <code class="verbatim">:var</code> ("is Lisp that only Emacs can evaluate"), <code class="verbatim">:colnames</code> and <code class="verbatim">:rownames</code>, and any header of a <code class="verbatim">:cache yes</code> block.</p> | |
| 399 | <h3 id="header-argument-reference">Header argument reference</h3> | |
| 400 | <table> | |
| 401 | <thead> | |
| 402 | <tr><th>Argument</th><th>Values</th><th>Effect</th></tr> | |
| 403 | </thead> | |
| 404 | <tbody> | |
| 405 | <tr><td><code class="verbatim">:results</code></td><td>see Results above</td><td>How the result is collected, shaped and inserted.</td></tr> | |
| 406 | <tr><td><code class="verbatim">:wrap</code></td><td>block type and parameters</td><td>Wraps the result in a block.</td></tr> | |
| 407 | <tr><td><code class="verbatim">:file</code></td><td>file name</td><td>Where a file result goes; required for graphics.</td></tr> | |
| 408 | <tr><td><code class="verbatim">:output-dir</code></td><td>folder</td><td>Folder for <code class="verbatim">:file</code>.</td></tr> | |
| 409 | <tr><td><code class="verbatim">:file-desc</code></td><td>text</td><td>Description of a file result's link.</td></tr> | |
| 410 | <tr><td><code class="verbatim">:var</code></td><td><code class="verbatim">name=value</code></td><td>Passes a value in (see Variables below).</td></tr> | |
| 411 | <tr><td><code class="verbatim">:colnames</code></td><td><code class="verbatim">yes</code>, <code class="verbatim">no</code>, Lisp list</td><td>Header row of table variables (see Tables in variables below).</td></tr> | |
| 412 | <tr><td><code class="verbatim">:rownames</code></td><td><code class="verbatim">yes</code>, <code class="verbatim">no</code>, Lisp list</td><td>First column of table variables.</td></tr> | |
| 413 | <tr><td><code class="verbatim">:hlines</code></td><td><code class="verbatim">yes</code>, <code class="verbatim">no</code></td><td>Keep rules in table variables.</td></tr> | |
| 414 | <tr><td><code class="verbatim">:separator</code></td><td>text</td><td>Column separator for tables in shell variables; a tab by default.</td></tr> | |
| 415 | <tr><td><code class="verbatim">:hline-string</code></td><td>text</td><td>What a rule becomes in a shell variable with <code class="verbatim">:hlines yes</code>; <code class="verbatim">hline</code> by default.</td></tr> | |
| 416 | <tr><td><code class="verbatim">:dir</code></td><td>folder</td><td>Folder to run in, relative to the file's folder. It must exist.</td></tr> | |
| 417 | <tr><td><code class="verbatim">:session</code></td><td>name, <code class="verbatim">none</code></td><td>Runs in a long-lived interpreter (see Sessions below). Shells and Python only; ignored for the compiled languages.</td></tr> | |
| 418 | <tr><td><code class="verbatim">:stdin</code></td><td>name of a table, list or block</td><td>Feeds the value to standard input. Shells only.</td></tr> | |
| 419 | <tr><td><code class="verbatim">:cmdline</code></td><td>arguments</td><td>Command-line arguments. Shells, <code class="verbatim">dot</code>, <code class="verbatim">plantuml</code>, <code class="verbatim">mermaid</code> and the compiled languages only.</td></tr> | |
| 420 | <tr><td><code class="verbatim">:shebang</code></td><td><code class="verbatim">#!…</code> line</td><td>Runs the block as a script with this first line. Shells only; also used by tangling.</td></tr> | |
| 421 | <tr><td><code class="verbatim">:padline</code></td><td><code class="verbatim">no</code></td><td>No blank line after the shebang of a script, or between tangled blocks.</td></tr> | |
| 422 | <tr><td><code class="verbatim">:python</code></td><td>program</td><td>Python interpreter to use.</td></tr> | |
| 423 | <tr><td><code class="verbatim">:cmd</code></td><td>program</td><td>Interpreter for <code class="verbatim">ruby</code>, <code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">R</code> and <code class="verbatim">awk</code>.</td></tr> | |
| 424 | <tr><td><code class="verbatim">:return</code></td><td>expression</td><td>Python: the value to return.</td></tr> | |
| 425 | <tr><td><code class="verbatim">:cache</code></td><td><code class="verbatim">yes</code>, <code class="verbatim">no</code></td><td>Skip the run when the result is current (see Caching below).</td></tr> | |
| 426 | <tr><td><code class="verbatim">:eval</code></td><td><code class="verbatim">never</code>, <code class="verbatim">no</code>, <code class="verbatim">query</code>, …</td><td>Whether and how to ask before running (see <code class="verbatim">:eval</code> above).</td></tr> | |
| 427 | <tr><td><code class="verbatim">:noweb</code></td><td>see Noweb below</td><td>Expands <code class="verbatim"><<name>></code> references.</td></tr> | |
| 428 | <tr><td><code class="verbatim">:noweb-ref</code></td><td>name</td><td>Makes the block part of <code class="verbatim"><<name>></code>.</td></tr> | |
| 429 | <tr><td><code class="verbatim">:noweb-sep</code></td><td>text</td><td>Separator between blocks joined under one <code class="verbatim">:noweb-ref</code>; a newline by default.</td></tr> | |
| 430 | <tr><td><code class="verbatim">:noweb-prefix</code></td><td><code class="verbatim">no</code></td><td>Do not repeat the text before <code class="verbatim"><<name>></code> on each expanded line.</td></tr> | |
| 431 | <tr><td><code class="verbatim">:exports</code></td><td><code class="verbatim">code</code>, <code class="verbatim">results</code>, <code class="verbatim">both</code>, <code class="verbatim">none</code></td><td>What export shows (see <a href="12-export.html">Export</a>).</td></tr> | |
| 432 | <tr><td><code class="verbatim">:tangle</code></td><td>see Tangling below</td><td>Where tangling writes the block.</td></tr> | |
| 433 | </tbody> | |
| 434 | </table> | |
| 435 | <h3 id="arguments-that-are-refused">Arguments that are refused</h3> | |
| 436 | <p>Orgstar does not run a block whose arguments it would handle differently from Emacs. Instead it says why and runs nothing.</p> | |
| 437 | <table> | |
| 438 | <thead> | |
| 439 | <tr><th>Argument</th><th>Refused for</th><th>Message</th></tr> | |
| 440 | </thead> | |
| 441 | <tbody> | |
| 442 | <tr><td><code class="verbatim">:prologue</code>, <code class="verbatim">:epilogue</code>, <code class="verbatim">:post</code></td><td>every language when running, except <code class="verbatim">:prologue</code> and <code class="verbatim">:epilogue</code> for the compiled languages (tangling uses <code class="verbatim">:prologue</code> and <code class="verbatim">:epilogue</code>)</td><td>"<code class="verbatim">:prologue</code> isn't supported yet; nothing was run."</td></tr> | |
| 443 | <tr><td><code class="verbatim">:stdin</code>, <code class="verbatim">:shebang</code></td><td>languages other than shells</td><td>"<code class="verbatim">:stdin</code> isn't supported yet; nothing was run."</td></tr> | |
| 444 | <tr><td><code class="verbatim">:cmdline</code></td><td>languages other than shells, graphics and the compiled languages</td><td>"<code class="verbatim">:cmdline</code> isn't supported for <em>language</em> yet; nothing was run."</td></tr> | |
| 445 | <tr><td><code class="verbatim">:session</code></td><td>languages other than shells, Python and the compiled languages, which ignore it</td><td>"<code class="verbatim">:session</code> isn't supported for <em>language</em> yet; nothing was run."</td></tr> | |
| 446 | <tr><td><code class="verbatim">:var</code></td><td><code class="verbatim">ruby</code>, <code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">R</code>, <code class="verbatim">awk</code></td><td>"<code class="verbatim">:var</code> isn't supported for <em>language</em> yet."</td></tr> | |
| 447 | </tbody> | |
| 448 | </table> | |
| 449 | <h2 id="variables">Variables</h2> | |
| 450 | <p><code class="verbatim">:var name=value</code> passes a value into the block (<code class="verbatim">org-babel-ref-resolve</code>). One <code class="verbatim">:var</code> can hold several assignments separated by spaces, and you can repeat <code class="verbatim">:var</code>. A later assignment to the same name replaces an earlier one.</p> | |
| 451 | <table> | |
| 452 | <thead> | |
| 453 | <tr><th>Value</th><th>Meaning</th></tr> | |
| 454 | </thead> | |
| 455 | <tbody> | |
| 456 | <tr><td><code class="verbatim">5</code>, <code class="verbatim">2.5</code></td><td>A number.</td></tr> | |
| 457 | <tr><td><code class="verbatim">"two words"</code></td><td>A string. <code class="verbatim">\n</code> and <code class="verbatim">\t</code> in it are a newline and a tab.</td></tr> | |
| 458 | <tr><td><code class="verbatim">'(1 2)</code>, <code class="verbatim">(+ 1 2)</code>, <code class="verbatim">'((1 2) hline (3 4))</code></td><td>Lisp: evaluated to a string, number, list or table.</td></tr> | |
| 459 | <tr><td><code class="verbatim">tbl</code></td><td>The table or plain list under <code class="verbatim">#+NAME: tbl</code> in the same file.</td></tr> | |
| 460 | <tr><td><code class="verbatim">gen</code></td><td>The result of the source block named <code class="verbatim">gen</code>, which runs first.</td></tr> | |
| 461 | <tr><td><code class="verbatim">double(n=4)</code></td><td>The result of the block named <code class="verbatim">double</code>, run with <code class="verbatim">n</code> set to 4.</td></tr> | |
| 462 | </tbody> | |
| 463 | </table> | |
| 464 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> nums</span> | |
| 465 | <span class="markup other table org">| 1 | 2 |</span> | |
| 466 | <span class="markup other table org">| 3 | 4 |</span> | |
| 467 | ||
| 468 | <span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python :var t=nums :var scale=10</span> | |
| 469 | return [[c * scale for c in row] for row in t] | |
| 470 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 471 | <p>A referenced block runs before the block that refers to it, after the one trust prompt that covers them all. A block with <code class="verbatim">:cache yes</code> and a current result gives that result without running. A chain that leads back to itself is refused with "<em>name</em> refers to itself through :var".</p> | |
| 472 | <p>These are not supported and are refused:</p> | |
| 473 | <ul> | |
| 474 | <li>Indexing into a table, such as <code class="verbatim">tbl[1,2]</code>: "References like … aren't supported yet."</li> | |
| 475 | <li>A name that matches nothing in the file: "Can't find … for :var."</li> | |
| 476 | <li>References to other files.</li> | |
| 477 | </ul> | |
| 478 | <p>How a value reaches the code depends on the language:</p> | |
| 479 | <table> | |
| 480 | <thead> | |
| 481 | <tr><th>Language</th><th>Scalars</th><th>Lists</th><th>Tables</th></tr> | |
| 482 | </thead> | |
| 483 | <tbody> | |
| 484 | <tr><td>bash</td><td>quoted string</td><td>indexed array (<code class="verbatim">declare -a</code>)</td><td>two or more columns: associative array keyed by the first column (<code class="verbatim">declare -A</code>); one column: indexed array</td></tr> | |
| 485 | <tr><td>other shells</td><td>quoted string</td><td>one item per line</td><td>rows on lines, cells separated by a tab or <code class="verbatim">:separator</code></td></tr> | |
| 486 | <tr><td>fish</td><td><code class="verbatim">set name 'value'</code></td><td>as other shells</td><td>as other shells</td></tr> | |
| 487 | <tr><td>Python</td><td>literal</td><td>list</td><td>list of lists, <code class="verbatim">None</code> for rules</td></tr> | |
| 488 | <tr><td>Emacs Lisp</td><td><code class="verbatim">let</code>-bound value</td><td>list</td><td>list of lists, <code class="verbatim">hline</code> for rules</td></tr> | |
| 489 | </tbody> | |
| 490 | </table> | |
| 491 | <p>For <code class="verbatim">shell</code> blocks, the bash forms are used when <code class="verbatim">SHELL</code> is bash. C, C++, D, Java, Fortran and Clojure blocks get declarations as their expansion writes them; see Tangling below.</p> | |
| 492 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> kv</span> | |
| 493 | <span class="markup other table org">| a | 1 |</span> | |
| 494 | <span class="markup other table org">| b | 2 |</span> | |
| 495 | ||
| 496 | <span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> bash :var t=kv :results output</span> | |
| 497 | echo ${t[a]} ${t[b]} | |
| 498 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 499 | <h3 id="tables-in-variables">Tables in variables</h3> | |
| 500 | <p>A table passed as a variable loses some of its structure first (<code class="verbatim">org-babel-disassemble-tables</code>):</p> | |
| 501 | <ul> | |
| 502 | <li>Rules are removed, unless <code class="verbatim">:hlines yes</code>.</li> | |
| 503 | <li>The first row is taken off as column names when <code class="verbatim">:colnames yes</code>, or when the table's only rule is under the first row. <code class="verbatim">:colnames no</code> keeps it as data.</li> | |
| 504 | <li>The first column is taken off as row names when <code class="verbatim">:rownames yes</code>.</li> | |
| 505 | </ul> | |
| 506 | <p>If the result is a table of the same width (for columns) or height (for rows), the names are put back on it (<code class="verbatim">org-babel-reassemble-table</code>). Clojure results don't get them back, as in Org. <code class="verbatim">:colnames</code> and <code class="verbatim">:rownames</code> can also be Lisp lists of names to put on the result, such as <code class="verbatim">:colnames '("x" "y")</code>.</p> | |
| 507 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> tbl</span> | |
| 508 | <span class="markup other table org">| a | b |</span> | |
| 509 | <span class="markup other table org">|---+---|</span> | |
| 510 | <span class="markup other table org">| 1 | x |</span> | |
| 511 | <span class="markup other table org">| 2 | y |</span> | |
| 512 | ||
| 513 | <span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python :var t=tbl</span> | |
| 514 | return [r + ["!"] for r in t] | |
| 515 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 516 | <h3 id="standard-input-and-arguments">Standard input and arguments</h3> | |
| 517 | <p>For shell blocks, <code class="verbatim">:stdin name</code> sends a table, list or block result to standard input, a table as tab-separated lines. <code class="verbatim">:cmdline</code> gives the script arguments, and <code class="verbatim">:shebang</code> its first line. With any of the three, the block is written to an executable script and run by the shell (<code class="verbatim">org-babel-sh-evaluate</code>); without <code class="verbatim">:shebang</code>, the first line is <code class="verbatim">#!/usr/bin/env</code> and the shell's name. A block with <code class="verbatim">:stdin</code> or <code class="verbatim">:cmdline</code> runs as a script even with a <code class="verbatim">:session</code>, and leaves the session untouched; <code class="verbatim">:shebang</code> alone runs in the session.</p> | |
| 518 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :cmdline one "two words" :results output</span> | |
| 519 | for a in "$@"; do echo "[$a]"; done | |
| 520 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 521 | <h2 id="sessions">Sessions</h2> | |
| 522 | <p><code class="verbatim">:session name</code> runs the block in an interpreter that stays running, so variables, functions and the working folder carry over to the next block in the same session. Sessions work for shells and Python on the Mac.</p> | |
| 523 | <ul> | |
| 524 | <li><code class="verbatim">:session</code> with no name uses <code class="verbatim">*language*</code>, such as <code class="verbatim">*sh*</code>. <code class="verbatim">:session none</code> runs without one.</li> | |
| 525 | <li>A session belongs to one folder, one interpreter and one name. Blocks in different folders, or with different names, do not share state.</li> | |
| 526 | <li>A session starts in the block's <code class="verbatim">:dir</code>, or the file's folder, the first time it is used.</li> | |
| 527 | <li>A shell session's output is what the block prints. <code class="verbatim">:results value</code> gives the exit status of the last command.</li> | |
| 528 | <li>A Python session runs the block at top level. Its value is the value of the last expression, so <code class="verbatim">return</code> is not used.</li> | |
| 529 | <li>Sessions stop when you quit Orgstar, or when you cancel a block running in one.</li> | |
| 530 | </ul> | |
| 531 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python :session py :results output</span> | |
| 532 | a = 2 | |
| 533 | print("set") | |
| 534 | <span class="keyword control block end org">#+end_src</span> | |
| 535 | </span> | |
| 536 | <span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python :session py</span> | |
| 537 | a * 3 | |
| 538 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 539 | <h2 id="caching">Caching</h2> | |
| 540 | <p>With <code class="verbatim">:cache yes</code>, Orgstar computes a SHA-1 hash of the block's header arguments and expanded body, as <code class="verbatim">org-babel-sha1-hash</code> does, and writes it on the results line: <code class="verbatim">#+RESULTS[hash]:</code>. When you run the block again and the hash matches, nothing runs and the message area shows the cached value ("Cached: …").</p> | |
| 541 | <p>Change the block or its arguments and it runs again. Results inserted with <code class="verbatim">append</code> or <code class="verbatim">prepend</code> carry no hash. Inline blocks are not cached. A cached block that has Lisp in its header arguments the interpreter cannot evaluate is refused.</p> | |
| 542 | <p>The hash of a C, C++, D, Java, Fortran or Clojure block is taken over the body as the language expands it (see Tangling below), with the <code class="verbatim">IMPORTS</code>, <code class="verbatim">INCLUDES</code> and <code class="verbatim">DEFINES</code> properties where the block is, and Java's default header arguments, as Emacs does. A result Emacs wrote for such a block with <code class="verbatim">:cache yes</code> is recognised as current, and <code class="verbatim">C-c C-c</code> shows it.</p> | |
| 543 | <h2 id="noweb">Noweb</h2> | |
| 544 | <p>A noweb reference <code class="verbatim"><<name>></code> in a block's body stands for other code. Whether references expand depends on <code class="verbatim">:noweb</code> and on what is happening:</p> | |
| 545 | <table> | |
| 546 | <thead> | |
| 547 | <tr><th><code class="verbatim">:noweb</code></th><th>Running</th><th>Tangling</th><th>Exporting</th></tr> | |
| 548 | </thead> | |
| 549 | <tbody> | |
| 550 | <tr><td><code class="verbatim">no</code> (default)</td><td>no</td><td>no</td><td>no</td></tr> | |
| 551 | <tr><td><code class="verbatim">yes</code></td><td>expands</td><td>expands</td><td>no</td></tr> | |
| 552 | <tr><td><code class="verbatim">tangle</code></td><td>no</td><td>expands</td><td>no</td></tr> | |
| 553 | <tr><td><code class="verbatim">eval</code></td><td>expands</td><td>no</td><td>no</td></tr> | |
| 554 | <tr><td><code class="verbatim">no-export</code></td><td>expands</td><td>expands</td><td>no</td></tr> | |
| 555 | <tr><td><code class="verbatim">strip-export</code></td><td>expands</td><td>expands</td><td>no</td></tr> | |
| 556 | <tr><td><code class="verbatim">strip-tangle</code></td><td>expands</td><td>removes the references</td><td>no</td></tr> | |
| 557 | </tbody> | |
| 558 | </table> | |
| 559 | <p>Exported code always shows the references as written; see <a href="12-export.html">Export</a>.</p> | |
| 560 | <p><code class="verbatim"><<name>></code> expands to the first of these that exists:</p> | |
| 561 | <ol> | |
| 562 | <li>The contents of the heading whose <code class="verbatim">ID</code> property is <code class="verbatim">name</code>, or whose <code class="verbatim">CUSTOM_ID</code> is <code class="verbatim">name</code> without its leading <code class="verbatim">#</code>.</li> | |
| 563 | <li>The body of the source block named <code class="verbatim">name</code>.</li> | |
| 564 | <li>The bodies of all blocks with <code class="verbatim">:noweb-ref name</code>, joined by each block's <code class="verbatim">:noweb-sep</code> (a newline by default).</li> | |
| 565 | </ol> | |
| 566 | <p>Blocks under a <code class="verbatim">COMMENT</code> heading are skipped. A referenced block expands its own references according to its own <code class="verbatim">:noweb</code>, up to 32 levels deep.</p> | |
| 567 | <p>Text before the reference on its line is repeated before each line the reference brings in, so references inside comments or indented code keep their prefix. <code class="verbatim">:noweb-prefix no</code> turns this off.</p> | |
| 568 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> greeting</span> | |
| 569 | <span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh</span> | |
| 570 | echo hello | |
| 571 | <span class="keyword control block end org">#+end_src</span> | |
| 572 | </span> | |
| 573 | <span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :noweb yes</span> | |
| 574 | <<greeting>> | |
| 575 | echo world | |
| 576 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 577 | <p>A reference that runs a block, <code class="verbatim"><<name()>></code>, is refused: "Noweb references that run a block (…) aren't supported yet; nothing was run."</p> | |
| 578 | <h2 id="calls">Calls</h2> | |
| 579 | <h3 id="call-lines"><code class="verbatim">#+CALL:</code> lines</h3> | |
| 580 | <p><code class="verbatim">#+CALL:</code> runs a named block with other arguments, as Org's library of Babel calls do (<code class="verbatim">org-babel-lob-get-info</code>). Run it with <code class="verbatim">C-c C-c</code> on the line.</p> | |
| 581 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> double</span> | |
| 582 | <span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :var n=2</span> | |
| 583 | echo $((n*2)) | |
| 584 | <span class="keyword control block end org">#+end_src</span> | |
| 585 | </span> | |
| 586 | <span class="keyword other keyword org">#+CALL:</span><span class="string unquoted org"> double(n=5)</span> | |
| 587 | ||
| 588 | <span class="keyword other keyword org">#+RESULTS:</span> | |
| 589 | : 10</span></code></pre> | |
| 590 | <p>The full form is <code class="verbatim">#+CALL: name[inside](arguments) end</code>:</p> | |
| 591 | <ul> | |
| 592 | <li><code class="verbatim">name</code> is the block to run. It must be in the same file.</li> | |
| 593 | <li><code class="verbatim">[inside]</code> holds header arguments applied to the block, such as <code class="verbatim">[:results raw]</code>.</li> | |
| 594 | <li><code class="verbatim">(arguments)</code> are <code class="verbatim">:var</code> assignments, separated by commas.</li> | |
| 595 | <li><code class="verbatim">end</code> holds header arguments for the call's result, such as <code class="verbatim">:results verbatim</code>.</li> | |
| 596 | </ul> | |
| 597 | <p>The call also takes the <code class="verbatim">header-args</code> and <code class="verbatim">header-args:LANG</code> properties, and <code class="verbatim">#+PROPERTY:</code> lines, where the call is, with <code class="verbatim">LANG</code> the called block's language. They apply after the called block's own header arguments and before <code class="verbatim">[inside]</code>, as in Org.</p> | |
| 598 | <p>The result goes under the call. A <code class="verbatim">#+NAME:</code> line above the <code class="verbatim">#+CALL:</code> names the result.</p> | |
| 599 | <h3 id="inline-calls-and-blocks">Inline calls and blocks</h3> | |
| 600 | <p>An inline source block, <code class="verbatim">src_sh{echo hi}</code>, runs with <code class="verbatim">C-c C-c</code> on it. Header arguments go in brackets: <code class="verbatim">src_sh[:var x=3]{echo $x}</code>. The result is written right after the block as a <code class="verbatim">results</code> macro:</p> | |
| 601 | <pre><code class="language-org highlight"><span class="text org">Text src_sh{echo hi} {{{results(<span class="markup raw inline org">=hi=</span>)}}} end.</span></code></pre> | |
| 602 | <p>Running again replaces the macro. With <code class="verbatim">:results raw</code> the result goes in as it is, without the macro. An inline result must be one line, and a table result must be a single cell.</p> | |
| 603 | <p>An inline call, <code class="verbatim">call_double(n=6)</code>, has the same parts as a <code class="verbatim">#+CALL:</code> line: <code class="verbatim">call_name[inside](arguments)[end]</code>. <code class="verbatim">C-c C-c</code> on an inline call runs it, and its result is written after it as a <code class="verbatim">results</code> macro, as for inline blocks. It takes the properties where it is as a <code class="verbatim">#+CALL:</code> line does.</p> | |
| 604 | <h2 id="emacs-lisp-blocks">Emacs Lisp blocks</h2> | |
| 605 | <p>On the Mac, an <code class="verbatim">emacs-lisp</code> or <code class="verbatim">elisp</code> block runs in a new <code class="verbatim">emacs -Q --batch</code> for each run, with lexical binding on. <code class="verbatim">-Q</code> means your init file and packages are not loaded, and nothing carries over between runs. Orgstar looks for Emacs at <code class="verbatim">ORGSTAR_EMACS</code>, then <code class="verbatim">/opt/homebrew/bin/emacs</code>, <code class="verbatim">/usr/local/bin/emacs</code>, <code class="verbatim">/Applications/Emacs.app/Contents/MacOS/Emacs</code>, <code class="verbatim">/run/current-system/sw/bin/emacs</code> and <code class="verbatim">/usr/bin/emacs</code>. Without Emacs, the block fails with "Emacs isn't installed, so Emacs Lisp blocks can't run."</p> | |
| 606 | <p>On iOS, Emacs Lisp blocks run in Orgstar's own Emacs Lisp interpreter. It covers ordinary list, string, number and control forms, <code class="verbatim">princ</code> and <code class="verbatim">message</code>. A block that uses something the interpreter does not have fails with "This block uses Emacs Lisp that runs only in Emacs, on the Mac." A Lisp error fails the run, as it does in Emacs.</p> | |
| 607 | <p>Variables are bound with <code class="verbatim">let</code> around the body. <code class="verbatim">:results output</code> collects what the block prints with <code class="verbatim">princ</code>, <code class="verbatim">prin1</code>, <code class="verbatim">print</code> and <code class="verbatim">terpri</code>.</p> | |
| 608 | <h2 id="graphics">Graphics</h2> | |
| 609 | <p><code class="verbatim">dot</code> (Graphviz), <code class="verbatim">plantuml</code> and <code class="verbatim">mermaid</code> blocks draw a picture into <code class="verbatim">:file</code>, and the result is a link to it. <code class="verbatim">:file</code> is required: "<em>language</em> code blocks need a :file header argument". The file's extension picks the output format; with none, <code class="verbatim">png</code> is used.</p> | |
| 610 | <table> | |
| 611 | <thead> | |
| 612 | <tr><th>Language</th><th>Command</th></tr> | |
| 613 | </thead> | |
| 614 | <tbody> | |
| 615 | <tr><td><code class="verbatim">dot</code></td><td><code class="verbatim">dot -T/ext/ -o file</code></td></tr> | |
| 616 | <tr><td><code class="verbatim">plantuml</code></td><td><code class="verbatim">plantuml -p -t/ext/</code>, output to the file</td></tr> | |
| 617 | <tr><td><code class="verbatim">mermaid</code></td><td><code class="verbatim">mmdc -i input -o file</code></td></tr> | |
| 618 | </tbody> | |
| 619 | </table> | |
| 620 | <p>A <code class="verbatim">plantuml</code> body without an <code class="verbatim">@start…</code> line is wrapped in <code class="verbatim">@startuml</code> and <code class="verbatim">@enduml</code>. <code class="verbatim">:cmdline</code> adds options to the command. The program must be installed and on the <code class="verbatim">PATH</code> described under Languages that run.</p> | |
| 621 | <pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> dot :file graph.svg</span> | |
| 622 | digraph { a -> b } | |
| 623 | <span class="keyword control block end org">#+end_src</span> | |
| 624 | </span> | |
| 625 | <span class="keyword other keyword org">#+RESULTS:</span> | |
| 626 | <span class="punctuation definition link org">[[</span><span class="markup underline link org">file:graph.svg</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">]</span></span></code></pre> | |
| 627 | <h2 id="tangling">Tangling</h2> | |
| 628 | <p>Tangling writes source blocks to the files their <code class="verbatim">:tangle</code> argument names (<code class="verbatim">org-babel-tangle</code>).</p> | |
| 629 | <table> | |
| 630 | <thead> | |
| 631 | <tr><th>Command</th><th>Emacs and Doom</th><th>Mac</th><th>What it tangles</th></tr> | |
| 632 | </thead> | |
| 633 | <tbody> | |
| 634 | <tr><td>Tangle File</td><td><code class="verbatim">C-c C-v t</code>, <code class="verbatim">C-c C-v C-t</code></td><td><code class="verbatim">⌃⌘V</code></td><td>Every block in the file</td></tr> | |
| 635 | <tr><td>Tangle Block</td><td>none</td><td><code class="verbatim">⌃⇧⌘V</code></td><td>The block at the caret (Emacs: <code class="verbatim">C-u C-c C-v t</code>)</td></tr> | |
| 636 | <tr><td>Tangle Block's Target</td><td>none</td><td><code class="verbatim">⌃⌥⌘V</code></td><td>Every block going to the same file as the one at the caret (Emacs: <code class="verbatim">C-u C-u C-c C-v t</code>)</td></tr> | |
| 637 | </tbody> | |
| 638 | </table> | |
| 639 | <p>All three are in the Org menu and the command palette. Tangling uses the text in the editor, saved or not, and the message area reports "Tangled <em>N</em> code blocks from <em>file</em>".</p> | |
| 640 | <h3 id="tangle-and-file-names"><code class="verbatim">:tangle</code> and file names</h3> | |
| 641 | <table> | |
| 642 | <thead> | |
| 643 | <tr><th><code class="verbatim">:tangle</code></th><th>Target</th></tr> | |
| 644 | </thead> | |
| 645 | <tbody> | |
| 646 | <tr><td><code class="verbatim">no</code> (default)</td><td>Not tangled.</td></tr> | |
| 647 | <tr><td><code class="verbatim">yes</code></td><td>The Org file's name with the language's extension, as Org's language files define it (<code class="verbatim">org-babel-tangle-lang-exts</code>): <code class="verbatim">py</code> for <code class="verbatim">python</code>, <code class="verbatim">rb</code> for <code class="verbatim">ruby</code>, <code class="verbatim">pl</code> for <code class="verbatim">perl</code>, <code class="verbatim">cpp</code> for <code class="verbatim">C++</code>, <code class="verbatim">d</code> for <code class="verbatim">D</code>, <code class="verbatim">awk</code>, <code class="verbatim">sed</code>, <code class="verbatim">lua</code>, <code class="verbatim">hs</code> for <code class="verbatim">haskell</code>, <code class="verbatim">java</code>, <code class="verbatim">tex</code> for <code class="verbatim">latex</code>, <code class="verbatim">ly</code> for <code class="verbatim">LilyPond</code>, <code class="verbatim">F90</code> for <code class="verbatim">fortran</code>, <code class="verbatim">clj</code> for <code class="verbatim">clojure</code>, <code class="verbatim">cljs</code> for <code class="verbatim">clojurescript</code>, <code class="verbatim">cs</code> for <code class="verbatim">csharp</code>, <code class="verbatim">groovy</code>, <code class="verbatim">jl</code> for <code class="verbatim">julia</code>, <code class="verbatim">lisp</code>, <code class="verbatim">max</code> for <code class="verbatim">maxima</code>, <code class="verbatim">ml</code> for <code class="verbatim">ocaml</code>, <code class="verbatim">pde</code> for <code class="verbatim">processing</code>, <code class="verbatim">el</code> for <code class="verbatim">emacs-lisp</code> and <code class="verbatim">elisp</code>, and <code class="verbatim">bib</code> for <code class="verbatim">bibtex</code>. Any other language is its own extension (<code class="verbatim">notes.sh</code> for <code class="verbatim">sh</code>).</td></tr> | |
| 648 | <tr><td>a path</td><td>That file, relative to the Org file's folder. <code class="verbatim">~</code> is expanded.</td></tr> | |
| 649 | <tr><td>Lisp</td><td>Evaluated as described under Lisp in header values, with <code class="verbatim">buffer-file-name</code> set to the Org file.</td></tr> | |
| 650 | </tbody> | |
| 651 | </table> | |
| 652 | <p>Blocks under a <code class="verbatim">COMMENT</code> heading, or a heading tagged <code class="verbatim">ARCHIVE</code>, are skipped. Blocks going to the same file are written in the order they appear.</p> | |
| 653 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+PROPERTY:</span><span class="string unquoted org"> header-args:python :tangle script.py</span> | |
| 654 | ||
| 655 | <span class="markup heading org"><span class="punctuation definition heading org">*</span> Tool | |
| 656 | </span>:PROPERTIES: | |
| 657 | :header-args: :tangle bin<span class="markup italic org">/tool.sh :mkdirp yes :shebang "#!/</span>bin/sh" | |
| 658 | :END: | |
| 659 | ||
| 660 | <span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh</span> | |
| 661 | echo tool | |
| 662 | <span class="keyword control block end org">#+end_src</span></span></span></code></pre> | |
| 663 | <h3 id="tangling-arguments">Tangling arguments</h3> | |
| 664 | <table> | |
| 665 | <thead> | |
| 666 | <tr><th>Argument</th><th>Values</th><th>Effect</th></tr> | |
| 667 | </thead> | |
| 668 | <tbody> | |
| 669 | <tr><td><code class="verbatim">:mkdirp</code></td><td><code class="verbatim">yes</code></td><td>Create the target's folder if it is missing.</td></tr> | |
| 670 | <tr><td><code class="verbatim">:tangle-mode</code></td><td><code class="verbatim">(identity #o755)</code>, <code class="verbatim">#o755</code>, <code class="verbatim">o755</code>, <code class="verbatim">rwxr-xr-x</code>, <code class="verbatim">u+x,g-r</code></td><td>Set the file's mode. A symbolic mode starts from <code class="verbatim">644</code>. When several blocks give a mode, the first one counts.</td></tr> | |
| 671 | <tr><td><code class="verbatim">:shebang</code></td><td><code class="verbatim">#!…</code> line</td><td>First line of the file, written once. Makes the file mode <code class="verbatim">755</code> unless <code class="verbatim">:tangle-mode</code> says otherwise.</td></tr> | |
| 672 | <tr><td><code class="verbatim">:padline</code></td><td><code class="verbatim">no</code></td><td>No blank line between this block and the one before it.</td></tr> | |
| 673 | <tr><td><code class="verbatim">:comments</code></td><td><code class="verbatim">no</code>, <code class="verbatim">link</code>, <code class="verbatim">yes</code>, <code class="verbatim">org</code>, <code class="verbatim">both</code>, <code class="verbatim">noweb</code></td><td>Comments around each block (below).</td></tr> | |
| 674 | <tr><td><code class="verbatim">:noweb</code></td><td>see Noweb above</td><td>Expand or strip <code class="verbatim"><<name>></code> references.</td></tr> | |
| 675 | <tr><td><code class="verbatim">:prologue</code>, <code class="verbatim">:epilogue</code></td><td>text</td><td>A line before and after the block's code.</td></tr> | |
| 676 | <tr><td><code class="verbatim">:var</code></td><td>as for running</td><td>Shell scalars become assignments, Python values become assignments, Emacs Lisp values are <code class="verbatim">let</code>-bound. For the languages below, as their Org language files write them.</td></tr> | |
| 677 | <tr><td><code class="verbatim">:no-expand</code></td><td>any</td><td>Write the body without <code class="verbatim">:var</code>, <code class="verbatim">:prologue</code>, <code class="verbatim">:epilogue</code> or the language's wrapping.</td></tr> | |
| 678 | </tbody> | |
| 679 | </table> | |
| 680 | <p>A table in <code class="verbatim">:var</code> loses its first row when its only rule is under that row, or with <code class="verbatim">:colnames yes</code>, and its rules unless <code class="verbatim">:hlines yes</code>, as when the block runs. This holds for every language.</p> | |
| 681 | <p><code class="verbatim">C</code>, <code class="verbatim">C++</code>, <code class="verbatim">cpp</code>, <code class="verbatim">D</code>, <code class="verbatim">java</code>, <code class="verbatim">fortran</code> and <code class="verbatim">clojure</code> blocks are written as Org's <code class="verbatim">org-babel-expand-body:LANG</code> writes them:</p> | |
| 682 | <table> | |
| 683 | <thead> | |
| 684 | <tr><th>Language</th><th>Written</th></tr> | |
| 685 | </thead> | |
| 686 | <tbody> | |
| 687 | <tr><td><code class="verbatim">C</code>, <code class="verbatim">C++</code>, <code class="verbatim">cpp</code></td><td><code class="verbatim">#include</code> lines from <code class="verbatim">:includes</code>, <code class="verbatim">#define</code> lines from <code class="verbatim">:defines</code>, <code class="verbatim">using namespace</code> lines from <code class="verbatim">:namespaces</code>, the <code class="verbatim">:var</code> declarations with table sizes and column-name helpers, then the body between <code class="verbatim">:prologue</code> and <code class="verbatim">:epilogue</code>, wrapped in <code class="verbatim">int main()</code> unless it has a <code class="verbatim">main</code> or <code class="verbatim">:main no</code> is given.</td></tr> | |
| 688 | <tr><td><code class="verbatim">D</code></td><td><code class="verbatim">module mmm;</code>, <code class="verbatim">import</code> lines from <code class="verbatim">:imports</code> (or the <code class="verbatim">IMPORTS</code> property, except when tangling) plus <code class="verbatim">std.stdio</code> and <code class="verbatim">std.conv</code>, the <code class="verbatim">:var</code> declarations, and the body wrapped in <code class="verbatim">int main()</code> as for C.</td></tr> | |
| 689 | <tr><td><code class="verbatim">java</code></td><td>The body between <code class="verbatim">:prologue</code> and <code class="verbatim">:epilogue</code>, wrapped in a <code class="verbatim">main</code> method when it has no method and in a class when it has none. The class is named by <code class="verbatim">:classname</code> or the body's own class; a dotted <code class="verbatim">:classname</code> adds a <code class="verbatim">package</code> line. <code class="verbatim">:imports</code> adds <code class="verbatim">import</code> lines, and <code class="verbatim">:var</code> values become static fields.</td></tr> | |
| 690 | <tr><td><code class="verbatim">fortran</code></td><td><code class="verbatim">#include</code> and <code class="verbatim">#define</code> lines from <code class="verbatim">:includes</code> and <code class="verbatim">:defines</code> (or the <code class="verbatim">INCLUDES</code> and <code class="verbatim">DEFINES</code> properties, except when tangling), then the <code class="verbatim">:var</code> declarations and the body in <code class="verbatim">program main</code>, unless the body has its own <code class="verbatim">program</code> statement (then <code class="verbatim">:var</code> is refused) or <code class="verbatim">:main no</code> is given.</td></tr> | |
| 691 | <tr><td><code class="verbatim">clojure</code></td><td><code class="verbatim">(ns …)</code> from <code class="verbatim">:ns</code>, the body in a <code class="verbatim">let</code> of the <code class="verbatim">:var</code> values, and a printer around it unless <code class="verbatim">:results output</code>.</td></tr> | |
| 692 | </tbody> | |
| 693 | </table> | |
| 694 | <p>With <code class="verbatim">:hlines yes</code>, a table that keeps rules is refused for C, C++, D and Fortran; Java writes <code class="verbatim">null</code> for each rule.</p> | |
| 695 | <p>Block switches also apply. <code class="verbatim">-r</code> removes coderef labels such as <code class="verbatim">(ref:name)</code>, using the format from <code class="verbatim">-l</code> if given. <code class="verbatim">-i</code> keeps the block's indentation. Otherwise common indentation and surrounding blank lines are removed.</p> | |
| 696 | <h3 id="comments">Comments</h3> | |
| 697 | <table> | |
| 698 | <thead> | |
| 699 | <tr><th><code class="verbatim">:comments</code></th><th>Written</th></tr> | |
| 700 | </thead> | |
| 701 | <tbody> | |
| 702 | <tr><td><code class="verbatim">no</code></td><td>The code only.</td></tr> | |
| 703 | <tr><td><code class="verbatim">link</code>, <code class="verbatim">yes</code></td><td>A comment with a link back to the block before the code, and "<em>name</em> ends here" after it.</td></tr> | |
| 704 | <tr><td><code class="verbatim">org</code></td><td>The Org text between the heading (or the previous block) and this block, as a comment.</td></tr> | |
| 705 | <tr><td><code class="verbatim">both</code></td><td>The Org text and the link comments.</td></tr> | |
| 706 | <tr><td><code class="verbatim">noweb</code></td><td>Link comments, plus link comments around each expanded noweb reference.</td></tr> | |
| 707 | </tbody> | |
| 708 | </table> | |
| 709 | <p>The link is relative to the tangled file's folder. <em>name</em> is the block's <code class="verbatim">#+NAME</code>, or the heading's title and the block's number under that heading, such as <code class="verbatim">Setup:2</code>.</p> | |
| 710 | <p>Comments need the language's comment syntax. Orgstar knows it for: <code class="verbatim">emacs-lisp</code>, <code class="verbatim">elisp</code>, <code class="verbatim">lisp</code>, <code class="verbatim">scheme</code>, <code class="verbatim">asm</code> (<code class="verbatim">;;</code>); <code class="verbatim">python</code>, <code class="verbatim">ruby</code>, <code class="verbatim">perl</code>, <code class="verbatim">conf</code>, <code class="verbatim">toml</code>, <code class="verbatim">makefile</code>, <code class="verbatim">awk</code>, <code class="verbatim">tcl</code>, <code class="verbatim">m4</code>, <code class="verbatim">icon</code>, <code class="verbatim">desktop</code> and the shells except <code class="verbatim">fish</code> (<code class="verbatim">#</code>); <code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">java</code>, <code class="verbatim">cpp</code>, <code class="verbatim">C++</code>, <code class="verbatim">objc</code>, <code class="verbatim">csharp</code>, <code class="verbatim">idl</code>, <code class="verbatim">pike</code>, <code class="verbatim">antlr</code>, <code class="verbatim">verilog</code> (<code class="verbatim">//</code>); <code class="verbatim">c</code>, <code class="verbatim">C</code>, <code class="verbatim">css</code> (<code class="verbatim">/* */</code>); <code class="verbatim">lua</code>, <code class="verbatim">sql</code>, <code class="verbatim">sqlite</code>, <code class="verbatim">vhdl</code> (<code class="verbatim">--</code>); <code class="verbatim">latex</code>, <code class="verbatim">tex</code>, <code class="verbatim">prolog</code> (<code class="verbatim">%%</code>); <code class="verbatim">ps</code>, <code class="verbatim">metapost</code> (<code class="verbatim">%</code>); <code class="verbatim">f90</code>, <code class="verbatim">dcl</code> (<code class="verbatim">!</code>); <code class="verbatim">html</code>, <code class="verbatim">xml</code>, <code class="verbatim">nxml</code>, <code class="verbatim">mhtml</code>, <code class="verbatim">sgml</code> (<code class="verbatim"><!-- --></code>); <code class="verbatim">octave</code> (<code class="verbatim">##</code>); <code class="verbatim">pascal</code> (<code class="verbatim">{ }</code>); <code class="verbatim">texinfo</code> (<code class="verbatim">@c</code>); <code class="verbatim">bibtex</code> (<code class="verbatim">@Comment</code>); <code class="verbatim">nroff</code> (<code class="verbatim">\"</code>); <code class="verbatim">bat</code> (<code class="verbatim">rem</code>). For any other language, <code class="verbatim">:comments</code> other than <code class="verbatim">no</code> stops tangling with a message.</p> | |
| 711 | <h3 id="writing-the-files">Writing the files</h3> | |
| 712 | <ul> | |
| 713 | <li>A file whose contents would not change is left alone, so its modification time stays the same.</li> | |
| 714 | <li>A read-only file is replaced.</li> | |
| 715 | <li>Tangling into the Org file itself is refused: "Not allowed to tangle into the same file as self".</li> | |
| 716 | </ul> | |
| 717 | <h3 id="what-tangling-refuses">What tangling refuses</h3> | |
| 718 | <p>Tangling stops, writes nothing and says why when:</p> | |
| 719 | <ul> | |
| 720 | <li><code class="verbatim">:var</code> refers to a source block, which would have to run: "would run a block while tangling".</li> | |
| 721 | <li>A shell block's <code class="verbatim">:var</code> is a table or list.</li> | |
| 722 | <li><code class="verbatim">:var</code> is used in a language other than shells, Python, Emacs Lisp, C, C++, D, Java, Fortran and Clojure.</li> | |
| 723 | <li>A C, C++, D or Fortran block's <code class="verbatim">:var</code> table keeps rules (with <code class="verbatim">:hlines yes</code>), or a value has no type the language takes.</li> | |
| 724 | <li>A Lisp header value cannot be evaluated: "is Lisp tangling can't evaluate yet; nothing was tangled."</li> | |
| 725 | <li><code class="verbatim">:tangle-mode</code> is in a form it does not read.</li> | |
| 726 | <li><code class="verbatim">:comments</code> needs a comment syntax it does not know.</li> | |
| 727 | </ul> | |
| 728 | <h2 id="on-ios">On iOS</h2> | |
| 729 | <ul> | |
| 730 | <li>Only Emacs Lisp blocks run, in Orgstar's own interpreter. Any other language, compiled languages included, fails with "<em>language</em> blocks need the Mac to run." (for example "C blocks need the Mac to run."), and so does an Emacs Lisp block whose <code class="verbatim">:var</code> refers to a block in another language.</li> | |
| 731 | <li>There are no sessions and no graphics.</li> | |
| 732 | <li>The trust prompt works the same way, with its own <code class="verbatim">trusted.json</code> on the device.</li> | |
| 733 | <li>There is no cancel command.</li> | |
| 734 | <li>Tangling works, for files in folders Orgstar can write to.</li> | |
| 735 | <li>Edit Block opens a plain text sheet without highlighting.</li> | |
| 736 | </ul> | |
| 737 | <p>See <a href="14-ios.html">iOS</a> for the rest of the iOS app.</p> | |
| 738 | </main> | |
| 739 | <footer class="site"> | |
| 740 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 741 | </footer> | |
| 742 | </body> | |
| 743 | </html> | |
| \ No newline at end of file | ||
guide/12-export.html added +344
| @@ -0,0 +1,344 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Export · Orgstar</title> | |
| 7 | <meta name="description" content="Exporting Org files from Orgstar to HTML and Markdown, and to PDF, LaTeX, ODT and plain text through Emacs."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Export</h1> | |
| 24 | <p class="lede">Orgstar exports HTML and Markdown itself, and hands PDF, LaTeX, ODT and plain text to Emacs on the Mac.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#exporting-a-file">Exporting a file</a> | |
| 29 | <ul> | |
| 30 | <li><a href="#on-the-mac">On the Mac</a></li> | |
| 31 | <li><a href="#the-export-dialog">The export dialog</a></li> | |
| 32 | <li><a href="#on-ios">On iOS</a></li> | |
| 33 | </ul></li> | |
| 34 | <li><a href="#html-export">HTML export</a> | |
| 35 | <ul> | |
| 36 | <li><a href="#title-author-and-date">Title, author and date</a></li> | |
| 37 | <li><a href="#options">#+OPTIONS</a></li> | |
| 38 | <li><a href="#which-headings-are-exported">Which headings are exported</a></li> | |
| 39 | <li><a href="#the-page-head">The page head</a></li> | |
| 40 | <li><a href="#math">Math</a></li> | |
| 41 | <li><a href="#includes">Includes</a></li> | |
| 42 | <li><a href="#macros">Macros</a></li> | |
| 43 | <li><a href="#footnotes">Footnotes</a></li> | |
| 44 | <li><a href="#tables">Tables</a></li> | |
| 45 | <li><a href="#images-and-links">Images and links</a></li> | |
| 46 | <li><a href="#source-blocks-and-their-results">Source blocks and their results</a></li> | |
| 47 | <li><a href="#other-blocks-and-elements">Other blocks and elements</a></li> | |
| 48 | <li><a href="#citations">Citations</a></li> | |
| 49 | </ul></li> | |
| 50 | <li><a href="#markdown-export">Markdown export</a></li> | |
| 51 | <li><a href="#exporting-through-emacs">Exporting through Emacs</a></li> | |
| 52 | <li><a href="#citations">Citations</a> | |
| 53 | <ul> | |
| 54 | <li><a href="#bibliography-files">Bibliography files</a></li> | |
| 55 | <li><a href="#cite-export">#+cite_export:</a></li> | |
| 56 | <li><a href="#citation-styles">Citation styles</a></li> | |
| 57 | <li><a href="#the-bibliography">The bibliography</a></li> | |
| 58 | </ul></li> | |
| 59 | <li><a href="#what-export-does-not-do">What export does not do</a></li> | |
| 60 | </ul> | |
| 61 | </nav> | |
| 62 | <h2 id="exporting-a-file">Exporting a file</h2> | |
| 63 | <p>Export works on the file in the current editor, using its text as it is now, saved or not. It applies to Org files only; in any other file the command says "Not an org file". Source blocks are never run during export. Results already in the file are exported as they are; see <a href="11-code-blocks.html">Code blocks</a>.</p> | |
| 64 | <h3 id="on-the-mac">On the Mac</h3> | |
| 65 | <table> | |
| 66 | <thead> | |
| 67 | <tr><th>Format</th><th>Command</th><th>Emacs preset</th><th>Doom</th><th>Needs Emacs</th></tr> | |
| 68 | </thead> | |
| 69 | <tbody> | |
| 70 | <tr><td>HTML</td><td>Export to HTML</td><td><code class="verbatim">C-c C-e h h</code></td><td><code class="verbatim">SPC m e h h</code>, <code class="verbatim">C-c C-e h h</code></td><td>no</td></tr> | |
| 71 | <tr><td>HTML, then open it</td><td>Export to HTML and Open</td><td><code class="verbatim">C-c C-e h o</code></td><td><code class="verbatim">SPC m e h o</code>, <code class="verbatim">C-c C-e h o</code></td><td>no</td></tr> | |
| 72 | <tr><td>Markdown</td><td>Export to Markdown</td><td><code class="verbatim">C-c C-e m m</code></td><td><code class="verbatim">SPC m e m m</code>, <code class="verbatim">C-c C-e m m</code></td><td>no</td></tr> | |
| 73 | <tr><td>PDF</td><td>Export to PDF with Emacs</td><td><code class="verbatim">C-c C-e l p</code></td><td><code class="verbatim">SPC m e l p</code>, <code class="verbatim">C-c C-e l p</code></td><td>yes</td></tr> | |
| 74 | <tr><td>LaTeX</td><td>Export to LaTeX with Emacs</td><td><code class="verbatim">C-c C-e l l</code></td><td><code class="verbatim">C-c C-e l l</code></td><td>yes</td></tr> | |
| 75 | <tr><td>ODT</td><td>Export to ODT with Emacs</td><td><code class="verbatim">C-c C-e o o</code></td><td><code class="verbatim">C-c C-e o o</code></td><td>yes</td></tr> | |
| 76 | <tr><td>Plain text</td><td>Export to Plain Text with Emacs</td><td><code class="verbatim">C-c C-e t u</code></td><td><code class="verbatim">C-c C-e t u</code></td><td>yes</td></tr> | |
| 77 | </tbody> | |
| 78 | </table> | |
| 79 | <p>The keys follow Emacs's export dispatcher (<code class="verbatim">org-export-dispatch</code>). <code class="verbatim">C-c C-e</code> on its own is only a prefix: pause after it and the key hints list the formats. The <code class="verbatim">SPC m e</code> keys work in normal state; the <code class="verbatim">C-c C-e</code> keys work in every Doom state. The Mac preset has no keys for the single formats; its <code class="verbatim">⇧⌘E</code> opens the export dialog.</p> | |
| 80 | <p>All seven commands are in File ▸ Export and in the command palette. They write the export beside the Org file, with the same name and the format's extension: <code class="verbatim">.html</code>, <code class="verbatim">.md</code>, <code class="verbatim">.pdf</code>, <code class="verbatim">.tex</code>, <code class="verbatim">.odt</code> or <code class="verbatim">.txt</code>. A file already there is replaced. The message area shows "Exported to <em>name</em>".</p> | |
| 81 | <h3 id="the-export-dialog">The export dialog</h3> | |
| 82 | <p><strong>Export…</strong> in the command palette, or <code class="verbatim">⇧⌘E</code> in the Mac preset, opens a dialog. The Emacs and Doom presets have no key for it; bind <code class="verbatim">app.export-dialog</code> in <code class="verbatim">keymap.toml</code> if you want one (see <a href="03-keys.html">Keys and commands</a>). The dialog has:</p> | |
| 83 | <ul> | |
| 84 | <li><strong>Format</strong>: HTML, Markdown, PDF (Emacs), ODT (Emacs), LaTeX (Emacs) or Plain text (Emacs).</li> | |
| 85 | <li><strong>Destination</strong>: beside the Org file by default. <strong>Choose…</strong> picks another place and name. Changing the format changes the extension.</li> | |
| 86 | <li><strong>Open after export</strong>: opens the file in its default app when the export finishes.</li> | |
| 87 | </ul> | |
| 88 | <p>The dialog remembers the format and the <strong>Open after export</strong> setting.</p> | |
| 89 | <h3 id="on-ios">On iOS</h3> | |
| 90 | <p>The Export menu offers HTML and Markdown. It is under More in the editor, and in the toolbar in the reader. Choosing one opens the share sheet with the exported file, named after the Org file. Send it to another app, or use Save to Files to keep it. The export is the same as on the Mac. PDF, LaTeX, ODT and plain text are not available on iOS.</p> | |
| 91 | <h2 id="html-export">HTML export</h2> | |
| 92 | <p>Orgstar writes a complete HTML page: a small built-in stylesheet that follows the system's light or dark appearance, the title, an author and date line, the table of contents, then the document. It does not use Emacs, and its output is close to, but not the same as, <code class="verbatim">ox-html</code>.</p> | |
| 93 | <h3 id="title-author-and-date">Title, author and date</h3> | |
| 94 | <table> | |
| 95 | <thead> | |
| 96 | <tr><th>Keyword</th><th>Effect</th></tr> | |
| 97 | </thead> | |
| 98 | <tbody> | |
| 99 | <tr><td><code class="verbatim">#+TITLE:</code></td><td>The page title and a top heading. Without one, the file's name is used.</td></tr> | |
| 100 | <tr><td><code class="verbatim">#+AUTHOR:</code></td><td>Shown under the title.</td></tr> | |
| 101 | <tr><td><code class="verbatim">#+DATE:</code></td><td>Shown under the title, after the author, as written.</td></tr> | |
| 102 | </tbody> | |
| 103 | </table> | |
| 104 | <p>Keywords in files named by <code class="verbatim">#+SETUPFILE:</code> count, as they do in Org.</p> | |
| 105 | <h3 id="options"><code class="verbatim">#+OPTIONS</code></h3> | |
| 106 | <table> | |
| 107 | <thead> | |
| 108 | <tr><th>Option</th><th>Values</th><th>Default</th><th>Effect</th></tr> | |
| 109 | </thead> | |
| 110 | <tbody> | |
| 111 | <tr><td><code class="verbatim">toc</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code>, a number</td><td><code class="verbatim">t</code></td><td>Table of contents, to the given depth. <code class="verbatim">t</code> goes to <code class="verbatim">H</code>.</td></tr> | |
| 112 | <tr><td><code class="verbatim">num</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code>, a number</td><td><code class="verbatim">t</code></td><td>Section numbers, to the given depth. <code class="verbatim">t</code> goes to <code class="verbatim">H</code>.</td></tr> | |
| 113 | <tr><td><code class="verbatim">H</code></td><td>a number</td><td><code class="verbatim">3</code></td><td>The deepest heading level the table of contents and numbering count.</td></tr> | |
| 114 | <tr><td><code class="verbatim">tags</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code>, <code class="verbatim">not-in-toc</code></td><td><code class="verbatim">t</code></td><td>Heading tags; <code class="verbatim">not-in-toc</code> leaves them out of the table of contents.</td></tr> | |
| 115 | <tr><td><code class="verbatim">todo</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>TODO keywords in headings.</td></tr> | |
| 116 | <tr><td><code class="verbatim">pri</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">nil</code></td><td>Priority cookies in headings.</td></tr> | |
| 117 | <tr><td><code class="verbatim">tex</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>LaTeX fragments and environments; <code class="verbatim">nil</code> drops them.</td></tr> | |
| 118 | <tr><td><code class="verbatim">title</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>The title heading.</td></tr> | |
| 119 | <tr><td><code class="verbatim">author</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>The author.</td></tr> | |
| 120 | <tr><td><code class="verbatim">date</code></td><td><code class="verbatim">t</code>, <code class="verbatim">nil</code></td><td><code class="verbatim">t</code></td><td>The date.</td></tr> | |
| 121 | </tbody> | |
| 122 | </table> | |
| 123 | <p>A depth for <code class="verbatim">toc</code> or <code class="verbatim">num</code> larger than <code class="verbatim">H</code> is cut to <code class="verbatim">H</code>. Any value other than <code class="verbatim">nil</code> turns an option on. Other <code class="verbatim">#+OPTIONS</code> keys are ignored.</p> | |
| 124 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TITLE:</span><span class="string unquoted org"> Field notes</span> | |
| 125 | <span class="keyword other keyword org">#+AUTHOR:</span><span class="string unquoted org"> Sam</span> | |
| 126 | <span class="keyword other keyword org">#+OPTIONS:</span><span class="string unquoted org"> toc:2 num:nil pri:t ^:{}</span></span></code></pre> | |
| 127 | <h3 id="which-headings-are-exported">Which headings are exported</h3> | |
| 128 | <ul> | |
| 129 | <li>A heading tagged with one of <code class="verbatim">#+EXCLUDE_TAGS</code> (<code class="verbatim">noexport</code> by default) is left out, with everything under it.</li> | |
| 130 | <li>A heading whose title starts with <code class="verbatim">COMMENT</code> is left out.</li> | |
| 131 | <li>A heading tagged <code class="verbatim">ARCHIVE</code> is exported as the heading alone, without its contents.</li> | |
| 132 | <li>If any heading has one of <code class="verbatim">#+SELECT_TAGS</code> (<code class="verbatim">export</code> by default), only those headings, their ancestors and everything under them are exported.</li> | |
| 133 | </ul> | |
| 134 | <p>Each heading gets an <code class="verbatim">id</code> for links: its <code class="verbatim">CUSTOM_ID</code> property, or a slug made from its title. Headings are one level down from Org's: a top-level heading is an <code class="verbatim"><h2></code>, since the title is the <code class="verbatim"><h1></code>.</p> | |
| 135 | <h3 id="the-page-head">The page head</h3> | |
| 136 | <p>Each <code class="verbatim">#+HTML_HEAD:</code> and <code class="verbatim">#+HTML_HEAD_EXTRA:</code> line goes into the page's <code class="verbatim"><head></code> as written, in order. Use them for stylesheets and scripts:</p> | |
| 137 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+HTML_HEAD:</span><span class="string unquoted org"> <link rel="stylesheet" href="notes.css"></span></span></code></pre> | |
| 138 | <p>The built-in stylesheet is always included first. Other <code class="verbatim">#+HTML_…</code> keywords are not used.</p> | |
| 139 | <h3 id="math">Math</h3> | |
| 140 | <p>LaTeX fragments (<code class="verbatim">\(…\)</code>, <code class="verbatim">\[…\]</code>, <code class="verbatim">$…$</code>, <code class="verbatim">$$…$$</code>) and LaTeX environments are left in the page for MathJax. When the page has any, Orgstar adds MathJax 3 from <code class="verbatim">cdn.jsdelivr.net</code>, so the page needs a network connection to show math. Entities such as <code class="verbatim">\alpha</code> become their characters.</p> | |
| 141 | <h3 id="includes">Includes</h3> | |
| 142 | <p><code class="verbatim">#+INCLUDE:</code> inserts another file before export, as <code class="verbatim">org-export-expand-include-keyword</code> does. Paths are relative to the Org file.</p> | |
| 143 | <table> | |
| 144 | <thead> | |
| 145 | <tr><th>Form</th><th>Effect</th></tr> | |
| 146 | </thead> | |
| 147 | <tbody> | |
| 148 | <tr><td><code class="verbatim">#+INCLUDE: "part.org"</code></td><td>The file's contents, read as Org; its includes are expanded too, up to eight levels.</td></tr> | |
| 149 | <tr><td><code class="verbatim">#+INCLUDE: "part.org::*Heading"</code></td><td>Only the subtree with that heading.</td></tr> | |
| 150 | <tr><td><code class="verbatim">#+INCLUDE: "part.org::#custom-id"</code></td><td>Only the subtree with that <code class="verbatim">CUSTOM_ID</code>.</td></tr> | |
| 151 | <tr><td><code class="verbatim">#+INCLUDE: "code.sh" src sh</code></td><td>The file in a source block.</td></tr> | |
| 152 | <tr><td><code class="verbatim">#+INCLUDE: "log.txt" example</code></td><td>The file in an example block.</td></tr> | |
| 153 | <tr><td><code class="verbatim">#+INCLUDE: "page.html" export html</code></td><td>The file in an export block.</td></tr> | |
| 154 | <tr><td><code class="verbatim">quote</code>, <code class="verbatim">verse</code>, <code class="verbatim">center</code>, <code class="verbatim">comment</code></td><td>The file in a block of that kind.</td></tr> | |
| 155 | <tr><td><code class="verbatim">:lines "5-10"</code></td><td>Only those lines; either end may be left out.</td></tr> | |
| 156 | <tr><td><code class="verbatim">:minlevel 2</code></td><td>Shift the included headings so the shallowest is at that level.</td></tr> | |
| 157 | </tbody> | |
| 158 | </table> | |
| 159 | <p>A file that cannot be read is replaced by an empty line.</p> | |
| 160 | <h3 id="macros">Macros</h3> | |
| 161 | <p><code class="verbatim">{{{name(arguments)}}}</code> is replaced before export (<code class="verbatim">org-macro-replace-all</code>).</p> | |
| 162 | <table> | |
| 163 | <thead> | |
| 164 | <tr><th>Macro</th><th>Replaced by</th></tr> | |
| 165 | </thead> | |
| 166 | <tbody> | |
| 167 | <tr><td><code class="verbatim">#+MACRO: name text</code></td><td><code class="verbatim">text</code>, with <code class="verbatim">$1</code>, =$2=… replaced by the arguments.</td></tr> | |
| 168 | <tr><td><code class="verbatim">{{{title}}}</code>, <code class="verbatim">{{{author}}}</code>, <code class="verbatim">{{{date}}}</code>, <code class="verbatim">{{{email}}}</code></td><td>That keyword's value.</td></tr> | |
| 169 | <tr><td><code class="verbatim">{{{keyword(NAME)}}}</code></td><td>The value of <code class="verbatim">#+NAME:</code>.</td></tr> | |
| 170 | <tr><td><code class="verbatim">{{{input-file}}}</code></td><td>The Org file's name.</td></tr> | |
| 171 | <tr><td><code class="verbatim">{{{property(NAME)}}}</code></td><td>The value of property <code class="verbatim">NAME</code> of the entry the macro is in; <code class="verbatim">ITEM</code> gives the heading's title. Empty before the first heading.</td></tr> | |
| 172 | <tr><td><code class="verbatim">{{{property(NAME,SEARCH)}}}</code></td><td>The same for the entry <code class="verbatim">SEARCH</code> finds in this file: <code class="verbatim">*Title</code>, <code class="verbatim">#custom-id</code> or a title.</td></tr> | |
| 173 | <tr><td><code class="verbatim">{{{n}}}</code>, <code class="verbatim">{{{n(name)}}}</code></td><td>A counter, increased at each use. <code class="verbatim">n(name,-)</code> repeats the current value; <code class="verbatim">n(name,5)</code> sets it to 5.</td></tr> | |
| 174 | <tr><td><code class="verbatim">{{{time(format)}}}</code></td><td>The current time, formatted as <code class="verbatim">format-time-string</code> does.</td></tr> | |
| 175 | </tbody> | |
| 176 | </table> | |
| 177 | <p>Arguments are separated by commas; write <code class="verbatim">\,</code> for a literal comma. Macros defined with <code class="verbatim">(eval …)</code>, and macros Orgstar does not know, become empty. <code class="verbatim">#+MACRO:</code> definitions in setup files count.</p> | |
| 178 | <h3 id="footnotes">Footnotes</h3> | |
| 179 | <p>Footnote references, named or inline (<code class="verbatim">[fn:: text]</code>), become numbered superscript links. The notes are collected in a Footnotes section at the end, numbered in the order they are first referenced, each with a link back. A reference without a definition is exported as written.</p> | |
| 180 | <h3 id="tables">Tables</h3> | |
| 181 | <p>An Org table becomes an HTML <code class="verbatim"><table></code>. If it has rules, the rows before the first rule are the header (<code class="verbatim"><thead></code>) and the rest the body. <code class="verbatim">#+CAPTION:</code> gives the table a caption. <code class="verbatim">#+TBLFM:</code> lines are not exported.</p> | |
| 182 | <p>A table.el table (one drawn with <code class="verbatim">+</code>, <code class="verbatim">-</code> and <code class="verbatim">|</code>) becomes a table with each cell's <code class="verbatim">colspan</code> and <code class="verbatim">rowspan</code>, and the lines in a cell joined with line breaks. If its drawing is not a well-formed table, it is exported as preformatted text.</p> | |
| 183 | <h3 id="images-and-links">Images and links</h3> | |
| 184 | <p>A link to an image file without a description becomes an <code class="verbatim"><img></code>. The image types are <code class="verbatim">png</code>, <code class="verbatim">jpg</code>, <code class="verbatim">jpeg</code>, <code class="verbatim">gif</code>, <code class="verbatim">svg</code>, <code class="verbatim">webp</code>, <code class="verbatim">bmp</code>, <code class="verbatim">tif</code>, <code class="verbatim">tiff</code> and <code class="verbatim">avif</code>. <code class="verbatim">#+ATTR_HTML:</code> before the paragraph adds attributes (<code class="verbatim">:width 300 :alt "Map"</code>); without an <code class="verbatim">:alt</code>, the file name is used.</p> | |
| 185 | <p>An image paragraph with <code class="verbatim">#+CAPTION:</code> or <code class="verbatim">#+ATTR_HTML:</code> becomes a <code class="verbatim"><figure></code>; a caption is numbered "Figure 1:", "Figure 2:" and so on.</p> | |
| 186 | <p>Links to <code class="verbatim">.org</code> files point to the <code class="verbatim">.html</code> file of the same name. Links to headings (<code class="verbatim">[[*Heading]]</code>), to <code class="verbatim">CUSTOM_ID</code> targets and to radio targets point to the heading's or target's <code class="verbatim">id</code> on the page. <code class="verbatim">id:</code> links point to <code class="verbatim">#</code> and the ID. Other links are written as they are.</p> | |
| 187 | <h3 id="source-blocks-and-their-results">Source blocks and their results</h3> | |
| 188 | <p>A source block is exported as <code class="verbatim"><pre><code class</code>"language-LANG">=, with the code escaped and its common indentation removed. Orgstar does not color the code; the class lets a script or stylesheet in <code class="verbatim">#+HTML_HEAD</code> highlight it. Noweb references are shown as written. Line-number switches are ignored.</p> | |
| 189 | <p>The block's <code class="verbatim">:exports</code> header argument decides what appears. Orgstar resolves it as running the block would: from the <code class="verbatim">#+begin_src</code> line, <code class="verbatim">#+HEADER:</code> lines, <code class="verbatim">header-args</code> properties and <code class="verbatim">#+PROPERTY:</code> lines (see <a href="11-code-blocks.html">Code blocks</a>). Without one, it is <code class="verbatim">results</code> for <code class="verbatim">dot</code>, <code class="verbatim">plantuml</code>, <code class="verbatim">ditaa</code>, <code class="verbatim">gnuplot</code>, <code class="verbatim">latex</code> and <code class="verbatim">lilypond</code> blocks, as their Org defaults set it, and <code class="verbatim">code</code> for other languages.</p> | |
| 190 | <table> | |
| 191 | <thead> | |
| 192 | <tr><th><code class="verbatim">:exports</code></th><th>Exported</th></tr> | |
| 193 | </thead> | |
| 194 | <tbody> | |
| 195 | <tr><td><code class="verbatim">code</code></td><td>The code.</td></tr> | |
| 196 | <tr><td><code class="verbatim">results</code></td><td>The block's existing <code class="verbatim">#+RESULTS:</code>.</td></tr> | |
| 197 | <tr><td><code class="verbatim">both</code></td><td>The code, then the results.</td></tr> | |
| 198 | <tr><td><code class="verbatim">none</code></td><td>Nothing.</td></tr> | |
| 199 | </tbody> | |
| 200 | </table> | |
| 201 | <p>A <code class="verbatim">#+CALL:</code> line exports its existing results, never the call itself; <code class="verbatim">:exports code</code> or <code class="verbatim">none</code> on the call, or in the <code class="verbatim">header-args</code> properties where the call is, exports nothing. An inline <code class="verbatim">src_</code> block has <code class="verbatim">:exports results</code> by default: the <code class="verbatim">{{{results(…)}}}</code> after it is exported and its code is not. With <code class="verbatim">:exports code</code> the code is exported in <code class="verbatim"><code></code> and the results are not; with <code class="verbatim">both</code>, both. An inline <code class="verbatim">call_</code> never appears itself, and the <code class="verbatim">{{{results(…)}}}</code> after it is always exported, whatever <code class="verbatim">:exports</code> says, as in Org.</p> | |
| 202 | <h3 id="other-blocks-and-elements">Other blocks and elements</h3> | |
| 203 | <table> | |
| 204 | <thead> | |
| 205 | <tr><th>Org</th><th>HTML</th></tr> | |
| 206 | </thead> | |
| 207 | <tbody> | |
| 208 | <tr><td><code class="verbatim">#+begin_example</code></td><td><code class="verbatim"><pre></code></td></tr> | |
| 209 | <tr><td>=: = lines</td><td><code class="verbatim"><pre class</code>"example">=</td></tr> | |
| 210 | <tr><td><code class="verbatim">#+begin_quote</code></td><td><code class="verbatim"><blockquote></code></td></tr> | |
| 211 | <tr><td><code class="verbatim">#+begin_center</code></td><td><code class="verbatim"><div class</code>"center">=</td></tr> | |
| 212 | <tr><td><code class="verbatim">#+begin_verse</code></td><td><code class="verbatim"><p class</code>"verse">=, lines and indentation kept</td></tr> | |
| 213 | <tr><td><code class="verbatim">#+begin_export html</code></td><td>Its contents, as they are</td></tr> | |
| 214 | <tr><td><code class="verbatim">#+begin_export</code> other formats</td><td>Nothing</td></tr> | |
| 215 | <tr><td><code class="verbatim">#+begin_comment</code></td><td>Nothing</td></tr> | |
| 216 | <tr><td><code class="verbatim">#+begin_NAME</code>, any other name</td><td><code class="verbatim"><div class</code>"NAME">= (a special block)</td></tr> | |
| 217 | <tr><td><code class="verbatim">@@html:…@@</code></td><td>Its contents, as they are; other back-ends' snippets are dropped</td></tr> | |
| 218 | <tr><td>Plain, numbered and description lists</td><td><code class="verbatim"><ul></code>, <code class="verbatim"><ol></code>, <code class="verbatim"><dl></code>; checkboxes as <code class="verbatim">[X]</code>, <code class="verbatim">[-]</code>, <code class="verbatim">[ ]</code></td></tr> | |
| 219 | <tr><td>Timestamps</td><td><code class="verbatim"><time datetime</code>"…">=</td></tr> | |
| 220 | <tr><td>Inline tasks</td><td><code class="verbatim"><div class</code>"inlinetask">= with the title in bold</td></tr> | |
| 221 | <tr><td>Dynamic blocks</td><td>Their contents</td></tr> | |
| 222 | <tr><td><code class="verbatim">-----</code></td><td><code class="verbatim"><hr></code></td></tr> | |
| 223 | </tbody> | |
| 224 | </table> | |
| 225 | <p>Comments, drawers, property drawers, planning lines, clock lines and keywords are not exported.</p> | |
| 226 | <h3 id="citations">Citations</h3> | |
| 227 | <p>HTML and Markdown export handle citations the same way; see Citations below.</p> | |
| 228 | <h2 id="markdown-export">Markdown export</h2> | |
| 229 | <p>Markdown export writes GitHub-flavored Markdown:</p> | |
| 230 | <ul> | |
| 231 | <li><code class="verbatim">#+TITLE:</code> becomes a top <code class="verbatim">#</code> heading. Org headings are one level down: <code class="verbatim">*</code> is <code class="verbatim">##</code>. TODO keywords stay in the heading text, and tags are shown as inline code. Priority cookies are left out unless <code class="verbatim">#+OPTIONS</code> has <code class="verbatim">pri:t</code>.</li> | |
| 232 | <li>Source blocks become fenced code blocks with the language; example blocks, =: = lines and table.el tables become fenced blocks without one.</li> | |
| 233 | <li>Tables become pipe tables. A rule after the first row makes it the header; otherwise the header row is empty.</li> | |
| 234 | <li>Checkboxes become task-list items (<code class="verbatim">- [x]</code>, <code class="verbatim">- [ ]</code>).</li> | |
| 235 | <li>Footnotes become <code class="verbatim">[^1]</code> references with the notes at the end.</li> | |
| 236 | <li>Quotes become <code class="verbatim">></code> blocks. Verse lines end with two spaces.</li> | |
| 237 | <li>Images become <code class="verbatim"></code>. Links to <code class="verbatim">.org</code> files, with or without <code class="verbatim">file:</code>, point to the <code class="verbatim">.md</code> file of the same name; a search option after <code class="verbatim">::</code> is dropped.</li> | |
| 238 | <li><code class="verbatim">#+begin_export</code> blocks for <code class="verbatim">markdown</code>, <code class="verbatim">md</code> or <code class="verbatim">html</code>, and <code class="verbatim">@@html:…@@</code> snippets, are copied as they are.</li> | |
| 239 | <li>Underline, subscripts and superscripts are written as HTML tags.</li> | |
| 240 | <li><code class="verbatim">:exports</code> is handled as in HTML export.</li> | |
| 241 | <li>Citations are handled as in HTML export.</li> | |
| 242 | </ul> | |
| 243 | <p>As in HTML export, <code class="verbatim">#+INCLUDE:</code> lines are expanded and macros replaced first, and <code class="verbatim">#+EXCLUDE_TAGS</code>, <code class="verbatim">#+SELECT_TAGS</code>, <code class="verbatim">COMMENT</code> headings and <code class="verbatim">ARCHIVE</code> tags decide which headings are exported (see <em>Which headings are exported</em>). Of the <code class="verbatim">#+OPTIONS</code>, Markdown export reads <code class="verbatim">todo</code>, <code class="verbatim">pri</code>, <code class="verbatim">tags</code>, <code class="verbatim">^</code> and <code class="verbatim">title</code>; the others do not apply. It writes no author or date.</p> | |
| 244 | <h2 id="exporting-through-emacs">Exporting through Emacs</h2> | |
| 245 | <p>On the Mac, PDF, LaTeX, ODT and plain text exports are done by Emacs, with the <code class="verbatim">ox</code> functions Emacs's dispatcher uses:</p> | |
| 246 | <table> | |
| 247 | <thead> | |
| 248 | <tr><th>Format</th><th>Function</th></tr> | |
| 249 | </thead> | |
| 250 | <tbody> | |
| 251 | <tr><td>PDF</td><td><code class="verbatim">org-latex-export-to-pdf</code></td></tr> | |
| 252 | <tr><td>LaTeX</td><td><code class="verbatim">org-latex-export-to-latex</code></td></tr> | |
| 253 | <tr><td>ODT</td><td><code class="verbatim">org-odt-export-to-odt</code></td></tr> | |
| 254 | <tr><td>Plain text</td><td><code class="verbatim">org-ascii-export-to-ascii</code></td></tr> | |
| 255 | </tbody> | |
| 256 | </table> | |
| 257 | <p>Orgstar runs <code class="verbatim">emacs -Q --batch</code> in the Org file's folder. It opens the file, replaces its contents with the editor's current text without saving, and calls the function. Emacs writes the result beside the file, as it would itself; with a destination chosen in the export dialog, Orgstar then moves it there. The message area shows "Exporting with Emacs…" and then "Exported to <em>name</em>".</p> | |
| 258 | <p>What you need:</p> | |
| 259 | <ul> | |
| 260 | <li>Emacs, at <code class="verbatim">ORGSTAR_EMACS</code> or one of <code class="verbatim">/opt/homebrew/bin/emacs</code>, <code class="verbatim">/usr/local/bin/emacs</code>, <code class="verbatim">/Applications/Emacs.app/Contents/MacOS/Emacs</code>, <code class="verbatim">/run/current-system/sw/bin/emacs</code> or <code class="verbatim">/usr/bin/emacs</code>. Without it the export fails with "Emacs isn't installed, so this format can't be exported."</li> | |
| 261 | <li>For PDF, a TeX installation that Emacs's LaTeX export can run. Emacs runs with your <code class="verbatim">PATH</code> plus <code class="verbatim">/opt/homebrew/bin</code>, <code class="verbatim">/usr/local/bin</code>, <code class="verbatim">/Library/TeX/texbin</code>, <code class="verbatim">/usr/bin</code> and <code class="verbatim">/bin</code>, the same as code blocks get, so <code class="verbatim">latexmk</code> and <code class="verbatim">pdflatex</code> from MacTeX or Homebrew are found when Orgstar was opened from the Dock.</li> | |
| 262 | </ul> | |
| 263 | <p>Things to know:</p> | |
| 264 | <ul> | |
| 265 | <li><code class="verbatim">-Q</code> means Emacs does not load your init file. Your LaTeX classes, export settings and packages from it are not used; the export uses Org's defaults and what the file itself sets.</li> | |
| 266 | <li>File-local variables are applied only when Emacs considers them safe.</li> | |
| 267 | <li><code class="verbatim">org-export-use-babel</code> is off, so no source blocks run.</li> | |
| 268 | <li>An export that takes more than two minutes is stopped with "Emacs took too long to export."</li> | |
| 269 | <li>Edit ▸ Cancel Running Task (<code class="verbatim">⌘.</code>) stops the export and shows "Export canceled". Starting another export or table recalculation in Emacs cancels the one that is running.</li> | |
| 270 | <li>If Emacs fails, the message area shows the last line of its error output.</li> | |
| 271 | </ul> | |
| 272 | <p>To use your own Emacs configuration, or formats Orgstar does not list, export from Emacs itself; see <a href="15-alongside-emacs.html">Alongside Emacs</a>.</p> | |
| 273 | <h2 id="citations">Citations</h2> | |
| 274 | <p>HTML and Markdown export process citations as Org's <code class="verbatim">basic</code> citation processor does (<code class="verbatim">oc-basic</code>).</p> | |
| 275 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+bibliography:</span><span class="string unquoted org"> refs.bib</span> | |
| 276 | <span class="keyword other keyword org">#+cite_export:</span><span class="string unquoted org"> basic author-year</span> | |
| 277 | ||
| 278 | As shown in [cite:@smith2020], and again [cite/t:@smith2020; see @lee2019 p. 4]. | |
| 279 | ||
| 280 | <span class="keyword other keyword org">#+print_bibliography:</span></span></code></pre> | |
| 281 | <h3 id="bibliography-files">Bibliography files</h3> | |
| 282 | <p>Each <code class="verbatim">#+bibliography:</code> line names one file, relative to the Org file, optionally in quotes. A file ending in <code class="verbatim">.json</code> is read as CSL-JSON; anything else is read as BibTeX, with <code class="verbatim">@string</code> abbreviations expanded and <code class="verbatim">@comment</code> and <code class="verbatim">@preamble</code> skipped. You can have several <code class="verbatim">#+bibliography:</code> lines; for a key in more than one file, the first file wins.</p> | |
| 283 | <h3 id="cite-export"><code class="verbatim">#+cite_export:</code></h3> | |
| 284 | <p><code class="verbatim">#+cite_export: PROCESSOR [BIBLIOGRAPHY-STYLE [CITATION-STYLE]]</code>.</p> | |
| 285 | <ul> | |
| 286 | <li>With no <code class="verbatim">#+cite_export:</code>, or with <code class="verbatim">basic</code>, citations are processed.</li> | |
| 287 | <li>With any other processor, such as <code class="verbatim">csl</code> or <code class="verbatim">biblatex</code>, Orgstar leaves citations as they are written.</li> | |
| 288 | <li>The citation style, which may include a variant (<code class="verbatim">text/bare</code>), is the default for citations that do not name one.</li> | |
| 289 | </ul> | |
| 290 | <h3 id="citation-styles">Citation styles</h3> | |
| 291 | <p>A citation is <code class="verbatim">[cite:…]</code> or <code class="verbatim">[cite/style:…]</code> or <code class="verbatim">[cite/style/variant:…]</code>, holding one or more <code class="verbatim">@key</code> references separated by <code class="verbatim">;</code>. Each reference may have its own prefix and suffix, and the whole citation a common prefix and suffix.</p> | |
| 292 | <table> | |
| 293 | <thead> | |
| 294 | <tr><th>Style</th><th>Output</th></tr> | |
| 295 | </thead> | |
| 296 | <tbody> | |
| 297 | <tr><td>default (none given)</td><td><code class="verbatim">(Author, Year)</code></td></tr> | |
| 298 | <tr><td><code class="verbatim">author</code>, <code class="verbatim">a</code></td><td><code class="verbatim">Author</code></td></tr> | |
| 299 | <tr><td><code class="verbatim">noauthor</code>, <code class="verbatim">na</code></td><td><code class="verbatim">(Year)</code></td></tr> | |
| 300 | <tr><td><code class="verbatim">text</code>, <code class="verbatim">t</code></td><td><code class="verbatim">Author (Year)</code></td></tr> | |
| 301 | <tr><td><code class="verbatim">note</code>, <code class="verbatim">ft</code></td><td>A footnote holding the <code class="verbatim">text</code> form</td></tr> | |
| 302 | <tr><td><code class="verbatim">numeric</code>, <code class="verbatim">nb</code></td><td><code class="verbatim">(1)</code>, numbered by the cited works sorted by author; three or more in a row as <code class="verbatim">1-3</code></td></tr> | |
| 303 | <tr><td><code class="verbatim">nocite</code>, <code class="verbatim">n</code></td><td>Nothing; the work is still listed in the bibliography</td></tr> | |
| 304 | </tbody> | |
| 305 | </table> | |
| 306 | <table> | |
| 307 | <thead> | |
| 308 | <tr><th>Variant</th><th>Effect</th></tr> | |
| 309 | </thead> | |
| 310 | <tbody> | |
| 311 | <tr><td><code class="verbatim">bare</code>, <code class="verbatim">b</code></td><td>No parentheses</td></tr> | |
| 312 | <tr><td><code class="verbatim">caps</code>, <code class="verbatim">c</code></td><td>Capitalized author</td></tr> | |
| 313 | <tr><td><code class="verbatim">bare-caps</code>, <code class="verbatim">bc</code></td><td>Both</td></tr> | |
| 314 | </tbody> | |
| 315 | </table> | |
| 316 | <p>Works by the same author in the same year get <code class="verbatim">a</code>, <code class="verbatim">b</code>, … after the year. A key not found in any bibliography file shows as <code class="verbatim">??</code> and <code class="verbatim">????</code>. Citations in the title are dropped.</p> | |
| 317 | <p>For <code class="verbatim">note</code> citations, the blank before the citation is removed and punctuation right after it moves in front of the footnote mark, as <code class="verbatim">org-cite-adjust-note</code> does.</p> | |
| 318 | <h3 id="the-bibliography">The bibliography</h3> | |
| 319 | <p><code class="verbatim">#+print_bibliography:</code> is replaced by an entry for every cited work, sorted by author. The bibliography style from <code class="verbatim">#+cite_export:</code> sets the form:</p> | |
| 320 | <table> | |
| 321 | <thead> | |
| 322 | <tr><th>Bibliography style</th><th>Entry</th></tr> | |
| 323 | </thead> | |
| 324 | <tbody> | |
| 325 | <tr><td>default</td><td><code class="verbatim">Author (Year). /Title/, Publisher.</code></td></tr> | |
| 326 | <tr><td><code class="verbatim">plain</code></td><td><code class="verbatim">Surnames. Title, Publisher, Year.</code></td></tr> | |
| 327 | <tr><td><code class="verbatim">numeric</code></td><td><code class="verbatim">[1] Author, /Title/, Publisher, Year.</code></td></tr> | |
| 328 | </tbody> | |
| 329 | </table> | |
| 330 | <p>The publisher part comes from the <code class="verbatim">publisher</code>, <code class="verbatim">journal</code>, <code class="verbatim">institution</code> or <code class="verbatim">school</code> field. Without <code class="verbatim">#+print_bibliography:</code> no bibliography is written.</p> | |
| 331 | <h2 id="what-export-does-not-do">What export does not do</h2> | |
| 332 | <ul> | |
| 333 | <li>There is no subtree export, body-only export, or asynchronous export; each command exports the whole file.</li> | |
| 334 | <li><code class="verbatim">#+EXPORT_FILE_NAME:</code> is not used by HTML and Markdown export.</li> | |
| 335 | <li>Source blocks are not run, and noweb references are not expanded.</li> | |
| 336 | <li>HTML export does not color source code.</li> | |
| 337 | <li>Export settings in the dialog are not per file.</li> | |
| 338 | </ul> | |
| 339 | </main> | |
| 340 | <footer class="site"> | |
| 341 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 342 | </footer> | |
| 343 | </body> | |
| 344 | </html> | |
| \ No newline at end of file | ||
guide/13-configuration.html added +601
| @@ -0,0 +1,601 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Configuration · Orgstar</title> | |
| 7 | <meta name="description" content="The Settings window, the files in ~/.config/orgstar, in-file settings, importing from Emacs, themes and fonts."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Configuration</h1> | |
| 24 | <p class="lede">Every setting lives in a text file you can edit, and most of them also appear in the Settings window.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#where-settings-live">Where settings live</a> | |
| 29 | <ul> | |
| 30 | <li><a href="#opening-config-toml">Opening config.toml</a></li> | |
| 31 | <li><a href="#problems-in-the-files">Problems in the files</a></li> | |
| 32 | </ul></li> | |
| 33 | <li><a href="#the-settings-window">The Settings window</a> | |
| 34 | <ul> | |
| 35 | <li><a href="#general">General</a></li> | |
| 36 | <li><a href="#editing">Editing</a></li> | |
| 37 | <li><a href="#appearance">Appearance</a></li> | |
| 38 | <li><a href="#agenda">Agenda</a></li> | |
| 39 | <li><a href="#capture">Capture</a></li> | |
| 40 | <li><a href="#settings-only-in-config-toml">Settings only in config.toml</a></li> | |
| 41 | </ul></li> | |
| 42 | <li><a href="#config-toml-reference">config.toml reference</a> | |
| 43 | <ul> | |
| 44 | <li><a href="#top-level">Top level</a></li> | |
| 45 | <li><a href="#org-agenda-prefix-format">[org-agenda-prefix-format]</a></li> | |
| 46 | <li><a href="#theme">[theme]</a></li> | |
| 47 | <li><a href="#orgstar">[orgstar]</a></li> | |
| 48 | <li><a href="#an-example">An example</a></li> | |
| 49 | <li><a href="#names-from-earlier-versions">Names from earlier versions</a></li> | |
| 50 | </ul></li> | |
| 51 | <li><a href="#keymap-toml-and-capture-toml">keymap.toml and capture.toml</a></li> | |
| 52 | <li><a href="#in-file-settings">In-file settings</a> | |
| 53 | <ul> | |
| 54 | <li><a href="#keywords-orgstar-reads">Keywords Orgstar reads</a></li> | |
| 55 | <li><a href="#startup-options">#+STARTUP options</a></li> | |
| 56 | <li><a href="#setup-files">Setup files</a></li> | |
| 57 | </ul></li> | |
| 58 | <li><a href="#import-from-emacs">Import from Emacs</a> | |
| 59 | <ul> | |
| 60 | <li><a href="#running-it">Running it</a></li> | |
| 61 | <li><a href="#doom-emacs">Doom Emacs</a></li> | |
| 62 | <li><a href="#what-it-reads">What it reads</a></li> | |
| 63 | <li><a href="#how-variables-map">How variables map</a></li> | |
| 64 | <li><a href="#limits-of-the-lisp-reader">Limits of the Lisp reader</a></li> | |
| 65 | </ul></li> | |
| 66 | <li><a href="#themes">Themes</a> | |
| 67 | <ul> | |
| 68 | <li><a href="#theme-files">Theme files</a></li> | |
| 69 | <li><a href="#color-keys">Color keys</a></li> | |
| 70 | </ul></li> | |
| 71 | <li><a href="#appearance">Appearance</a></li> | |
| 72 | <li><a href="#fonts">Fonts</a></li> | |
| 73 | </ul> | |
| 74 | </nav> | |
| 75 | <h2 id="where-settings-live">Where settings live</h2> | |
| 76 | <p>Orgstar keeps its settings in a configuration folder:</p> | |
| 77 | <ul> | |
| 78 | <li><code class="verbatim">$XDG_CONFIG_HOME/orgstar</code> when <code class="verbatim">XDG_CONFIG_HOME</code> is set and not empty,</li> | |
| 79 | <li>otherwise <code class="verbatim">~/.config/orgstar</code>.</li> | |
| 80 | </ul> | |
| 81 | <p>The environment variable <code class="verbatim">ORGSTAR_CONFIG_DIR</code> overrides both. If a file is missing from the configuration folder but exists in <code class="verbatim">~/Library/Application Support/Orgstar</code> (where earlier versions kept it), Orgstar reads it from there, and reloads it when you edit it there.</p> | |
| 82 | <p>The folder holds these files:</p> | |
| 83 | <table> | |
| 84 | <thead> | |
| 85 | <tr><th>File</th><th>What it holds</th><th>Written by Orgstar</th></tr> | |
| 86 | </thead> | |
| 87 | <tbody> | |
| 88 | <tr><td><code class="verbatim">config.toml</code></td><td>Every setting of the Settings window, and the theme</td><td>Yes, when you change a setting</td></tr> | |
| 89 | <tr><td><code class="verbatim">keymap.toml</code></td><td>Your key bindings, on top of the preset</td><td>Only by Import from Emacs</td></tr> | |
| 90 | <tr><td><code class="verbatim">capture.toml</code></td><td>Capture templates</td><td>Only by Import from Emacs</td></tr> | |
| 91 | <tr><td><code class="verbatim">views.toml</code></td><td>Saved agenda views</td><td>No</td></tr> | |
| 92 | <tr><td><code class="verbatim">default-theme.toml</code></td><td>The default theme's colors, for reference</td><td>Yes, at every launch</td></tr> | |
| 93 | </tbody> | |
| 94 | </table> | |
| 95 | <p><code class="verbatim">config.toml</code> is the source of truth. The Settings window writes each change into it, keeping your comments and the order of lines, and edits you make to the file apply while Orgstar runs. If the file doesn't exist at launch, Orgstar creates it with every setting at its current value and a comment after each one.</p> | |
| 96 | <p>When you add the folder to a dotfiles repository, keep <code class="verbatim">default-theme.toml</code> out of it or ignore its changes: Orgstar rewrites it whenever its contents differ from the built-in theme.</p> | |
| 97 | <h3 id="opening-config-toml">Opening config.toml</h3> | |
| 98 | <ul> | |
| 99 | <li>Orgstar ▸ Edit Config File (<code class="verbatim">⌥⌘,</code>) opens <code class="verbatim">config.toml</code> as a buffer in the main window. The command palette has the same command as Edit Config File.</li> | |
| 100 | <li>Settings ▸ General has three buttons for the file: Edit in Orgstar, Open with Default App, and Show in Finder.</li> | |
| 101 | </ul> | |
| 102 | <p>Saving the buffer applies the file, the same as saving it from another editor.</p> | |
| 103 | <h3 id="problems-in-the-files">Problems in the files</h3> | |
| 104 | <p>If <code class="verbatim">config.toml</code> has a line Orgstar can't use, the problem shows in the message line under the editor, with a count when there are more. Each problem names the file and the key:</p> | |
| 105 | <ul> | |
| 106 | <li><code class="verbatim">config.toml: unknown setting editor.foo</code></li> | |
| 107 | <li><code class="verbatim">config.toml: org-log-done must be one of nil, time, note</code></li> | |
| 108 | <li><code class="verbatim">config.toml: org-agenda-start-day must look like "-3d" or "+0d"</code></li> | |
| 109 | <li><code class="verbatim">config.toml: theme.light.background must be a color such as "#1f2328"</code></li> | |
| 110 | </ul> | |
| 111 | <p>A file that isn't valid TOML is reported with its parse error, and none of it applies. <code class="verbatim">keymap.toml</code>, <code class="verbatim">capture.toml</code> and <code class="verbatim">views.toml</code> report their problems the same way when they are read.</p> | |
| 112 | <h2 id="the-settings-window">The Settings window</h2> | |
| 113 | <p>Open it with Orgstar ▸ Settings (<code class="verbatim">⌘,</code>). It has five panes. Each control writes the <code class="verbatim">config.toml</code> key named in the tables below; the config.toml reference below gives the type and the Emacs variable.</p> | |
| 114 | <h3 id="general">General</h3> | |
| 115 | <table> | |
| 116 | <thead> | |
| 117 | <tr><th>Control</th><th>Choices</th><th>Default</th><th>Key</th></tr> | |
| 118 | </thead> | |
| 119 | <tbody> | |
| 120 | <tr><td>config.toml: Edit in Orgstar</td><td>Opens the file in the main window</td><td></td><td></td></tr> | |
| 121 | <tr><td>config.toml: Open with Default App</td><td>Opens the file in the app macOS uses for <code class="verbatim">.toml</code></td><td></td><td></td></tr> | |
| 122 | <tr><td>config.toml: Show in Finder</td><td>Selects the file in Finder</td><td></td><td></td></tr> | |
| 123 | <tr><td>Emacs: Import from Emacs…</td><td>Opens the import sheet; see Import from Emacs below</td><td></td><td></td></tr> | |
| 124 | <tr><td>Save files</td><td>Automatically, when typing stops; Only with File ▸ Save (<code class="verbatim">⌘S</code>)</td><td>Automatically</td><td><code class="verbatim">save</code></td></tr> | |
| 125 | <tr><td>Keys</td><td>Emacs; Mac; Doom (Vim keys)</td><td>Emacs</td><td><code class="verbatim">keymap</code></td></tr> | |
| 126 | <tr><td>Show hidden files and folders</td><td>On or off</td><td>On</td><td><code class="verbatim">show-hidden-files</code></td></tr> | |
| 127 | <tr><td>Option as Meta</td><td>Left Option; Right Option; Both; Neither</td><td>Left Option</td><td><code class="verbatim">option-as-meta</code></td></tr> | |
| 128 | </tbody> | |
| 129 | </table> | |
| 130 | <p>Automatic saving writes a file one second after you stop typing. The keymap presets and <code class="verbatim">keymap.toml</code> are covered in <a href="03-keys.html">Keys and commands</a>.</p> | |
| 131 | <h3 id="editing">Editing</h3> | |
| 132 | <table> | |
| 133 | <thead> | |
| 134 | <tr><th>Control</th><th>Choices or range</th><th>Default</th><th>Key</th></tr> | |
| 135 | </thead> | |
| 136 | <tbody> | |
| 137 | <tr><td>Tags</td><td>Aligned to end at column 77; One space after the title</td><td>Aligned (<code class="verbatim">-77</code>)</td><td><code class="verbatim">org-tags-column</code></td></tr> | |
| 138 | <tr><td>M-RET adds the new heading after the subtree</td><td>On or off</td><td>On</td><td><code class="verbatim">org-insert-heading-respect-content</code></td></tr> | |
| 139 | <tr><td>M-RET splits the line at the caret</td><td>On or off</td><td>Off</td><td><code class="verbatim">org-M-RET-may-split-line</code></td></tr> | |
| 140 | <tr><td>Lists can use letters (a. b. c.)</td><td>On or off</td><td>On</td><td><code class="verbatim">org-list-allow-alphabetical</code></td></tr> | |
| 141 | <tr><td>M-q fills to column N</td><td>40 to 200</td><td>80</td><td><code class="verbatim">fill-column</code></td></tr> | |
| 142 | <tr><td>Long lines run off the edge instead of wrapping (org-startup-truncated)</td><td>On or off</td><td>Off</td><td><code class="verbatim">org-startup-truncated</code></td></tr> | |
| 143 | <tr><td>Emacs hides emphasis markers (org-hide-emphasis-markers)</td><td>On or off</td><td>On</td><td><code class="verbatim">org-hide-emphasis-markers</code></td></tr> | |
| 144 | <tr><td>Emacs shows entities as characters (org-pretty-entities)</td><td>On or off</td><td>On</td><td><code class="verbatim">org-pretty-entities</code></td></tr> | |
| 145 | <tr><td>Default TODO keywords</td><td>Text in <code class="verbatim">#+TODO</code> syntax, one sequence per line</td><td>See below</td><td><code class="verbatim">org-todo-keywords</code></td></tr> | |
| 146 | </tbody> | |
| 147 | </table> | |
| 148 | <p>The two "Emacs hides" and "Emacs shows" switches describe your Emacs, not Orgstar's display. Tag alignment, table alignment and <code class="verbatim">M-q</code> measure text the way your Emacs displays it, so a file edited in both keeps the same layout. Set them to match your Emacs configuration. They also control whether Orgstar hides markers and shows entities when markup is hidden.</p> | |
| 149 | <p>The Tags picker offers two values. <code class="verbatim">config.toml</code> accepts any integer; with a value other than <code class="verbatim">-77</code> or <code class="verbatim">0</code> the picker shows no selection.</p> | |
| 150 | <p>The long-lines switch applies to files as they open; View ▸ Truncate or Wrap Long Lines switches the file in front.</p> | |
| 151 | <p>Default TODO keywords apply to files without a <code class="verbatim">#+TODO</code> line. Orgstar reads them at launch, so a change takes effect after you quit and reopen Orgstar.</p> | |
| 152 | <h3 id="appearance">Appearance</h3> | |
| 153 | <table> | |
| 154 | <thead> | |
| 155 | <tr><th>Control</th><th>Range</th><th>Default</th><th>Key</th></tr> | |
| 156 | </thead> | |
| 157 | <tbody> | |
| 158 | <tr><td>Font</td><td>System monospaced, or any installed monospaced family</td><td>System monospaced</td><td><code class="verbatim">font</code></td></tr> | |
| 159 | <tr><td>Size</td><td>8 to 36 pt</td><td>13 pt</td><td><code class="verbatim">font-size</code></td></tr> | |
| 160 | <tr><td>Line spacing</td><td>0 to 16 pt</td><td>2 pt</td><td><code class="verbatim">line-spacing</code></td></tr> | |
| 161 | <tr><td>Headings grow by N pt a level</td><td>0 to 8 pt</td><td>1 pt</td><td><code class="verbatim">heading-size-step</code></td></tr> | |
| 162 | <tr><td>Colors: Edit in config.toml</td><td>Opens <code class="verbatim">config.toml</code></td><td></td><td></td></tr> | |
| 163 | <tr><td>Colors: Show Default Theme</td><td>Opens <code class="verbatim">default-theme.toml</code></td><td></td><td></td></tr> | |
| 164 | </tbody> | |
| 165 | </table> | |
| 166 | <p>See Themes and Fonts below.</p> | |
| 167 | <h3 id="agenda">Agenda</h3> | |
| 168 | <table> | |
| 169 | <thead> | |
| 170 | <tr><th>Control</th><th>Range</th><th>Default</th><th>Key</th></tr> | |
| 171 | </thead> | |
| 172 | <tbody> | |
| 173 | <tr><td>Agenda shows N days</td><td>1 to 366</td><td>10</td><td><code class="verbatim">org-agenda-span</code></td></tr> | |
| 174 | <tr><td>Agenda starts N days before today</td><td>0 to 14 days before</td><td>3 days</td><td><code class="verbatim">org-agenda-start-day</code></td></tr> | |
| 175 | <tr><td>Include files in subfolders</td><td>On or off</td><td>Off</td><td><code class="verbatim">agenda-include-subfolders</code></td></tr> | |
| 176 | <tr><td>Notify before timed agenda entries</td><td>On or off</td><td>On</td><td><code class="verbatim">reminders</code></td></tr> | |
| 177 | <tr><td>N minutes before</td><td>0 to 120</td><td>12</td><td><code class="verbatim">appt-message-warning-time</code></td></tr> | |
| 178 | <tr><td>Ask what to do with idle time while clocked in</td><td>On or off</td><td>Off</td><td><code class="verbatim">org-clock-idle-time</code></td></tr> | |
| 179 | <tr><td>After N minutes without keyboard or mouse input</td><td>1 to 240</td><td>15 when turned on</td><td><code class="verbatim">org-clock-idle-time</code></td></tr> | |
| 180 | <tr><td>Remember N recently clocked entries</td><td>1 to 35</td><td>5</td><td><code class="verbatim">org-clock-history-length</code></td></tr> | |
| 181 | </tbody> | |
| 182 | </table> | |
| 183 | <p>An entry's <code class="verbatim">APPT_WARNTIME</code> property overrides the lead time. The agenda is covered in <a href="07-agenda.html">The agenda</a>.</p> | |
| 184 | <p>Turning on the idle question sets <code class="verbatim">org-clock-idle-time</code> to 15 minutes; turning it off sets it to <code class="verbatim">0</code>. The minutes stepper is disabled while the question is off. Idle time and the clock history are covered in <a href="06-dates-and-clocking.html">Dates and clocking</a>.</p> | |
| 185 | <h3 id="capture">Capture</h3> | |
| 186 | <table> | |
| 187 | <thead> | |
| 188 | <tr><th>Control</th><th>Default</th><th>Key</th></tr> | |
| 189 | </thead> | |
| 190 | <tbody> | |
| 191 | <tr><td>⌃⌥Space opens Capture from any app</td><td>On</td><td><code class="verbatim">global-capture-hotkey</code></td></tr> | |
| 192 | </tbody> | |
| 193 | </table> | |
| 194 | <p>The footer shows the path of <code class="verbatim">capture.toml</code>. Templates are covered in <a href="08-capture.html">Capture</a>.</p> | |
| 195 | <h3 id="settings-only-in-config-toml">Settings only in config.toml</h3> | |
| 196 | <p>These settings have no control in the Settings window. Some are in the View menu.</p> | |
| 197 | <table> | |
| 198 | <thead> | |
| 199 | <tr><th>Key</th><th>Also in</th></tr> | |
| 200 | </thead> | |
| 201 | <tbody> | |
| 202 | <tr><td><code class="verbatim">org-log-done</code></td><td></td></tr> | |
| 203 | <tr><td><code class="verbatim">org-log-reschedule</code></td><td></td></tr> | |
| 204 | <tr><td><code class="verbatim">org-log-redeadline</code></td><td></td></tr> | |
| 205 | <tr><td><code class="verbatim">org-log-into-drawer</code></td><td></td></tr> | |
| 206 | <tr><td><code class="verbatim">org-startup-indented</code></td><td></td></tr> | |
| 207 | <tr><td><code class="verbatim">org-hide-leading-stars</code></td><td></td></tr> | |
| 208 | <tr><td><code class="verbatim">org-startup-align-all-tables</code></td><td></td></tr> | |
| 209 | <tr><td><code class="verbatim">org-startup-with-inline-images</code></td><td></td></tr> | |
| 210 | <tr><td><code class="verbatim">org-cycle-hide-drawer-startup</code></td><td></td></tr> | |
| 211 | <tr><td><code class="verbatim">org-cycle-hide-block-startup</code></td><td></td></tr> | |
| 212 | <tr><td><code class="verbatim">org-use-speed-commands</code></td><td></td></tr> | |
| 213 | <tr><td><code class="verbatim">spell-check</code></td><td></td></tr> | |
| 214 | <tr><td><code class="verbatim">electric-pair-mode</code></td><td></td></tr> | |
| 215 | <tr><td><code class="verbatim">display-line-numbers-type</code></td><td>View ▸ Show Line Numbers (<code class="verbatim">⇧⌘L</code>)</td></tr> | |
| 216 | <tr><td><code class="verbatim">tab-bar</code></td><td>View ▸ Show Tab Bar</td></tr> | |
| 217 | <tr><td><code class="verbatim">show-markup</code></td><td>View ▸ Show Markup (<code class="verbatim">⇧⌘M</code>)</td></tr> | |
| 218 | <tr><td><code class="verbatim">ignored-folders</code></td><td></td></tr> | |
| 219 | <tr><td><code class="verbatim">[org-agenda-prefix-format]</code></td><td></td></tr> | |
| 220 | <tr><td><code class="verbatim">theme-file</code></td><td></td></tr> | |
| 221 | </tbody> | |
| 222 | </table> | |
| 223 | <h2 id="config-toml-reference">config.toml reference</h2> | |
| 224 | <p>Settings that mirror an Emacs variable sit at the top of the file under that variable's name. The agenda prefix formats are in <code class="verbatim">[org-agenda-prefix-format]</code>, type and theme in <code class="verbatim">[theme]</code>, and the settings Emacs has no variable for in <code class="verbatim">[orgstar]</code>.</p> | |
| 225 | <p>A key you remove from the file goes back to its default. A key that isn't in the table below is reported as unknown.</p> | |
| 226 | <h3 id="top-level">Top level</h3> | |
| 227 | <table> | |
| 228 | <thead> | |
| 229 | <tr><th>Key</th><th>Type</th><th>Default</th><th>Effect</th></tr> | |
| 230 | </thead> | |
| 231 | <tbody> | |
| 232 | <tr><td><code class="verbatim">fill-column</code></td><td>integer</td><td><code class="verbatim">80</code></td><td>The column <code class="verbatim">M-q</code> fills to. Mirrors <code class="verbatim">fill-column</code>.</td></tr> | |
| 233 | <tr><td><code class="verbatim">org-tags-column</code></td><td>integer</td><td><code class="verbatim">-77</code></td><td>Negative: tags end at that column. <code class="verbatim">0</code>: one space between title and tags. Mirrors <code class="verbatim">org-tags-column</code>.</td></tr> | |
| 234 | <tr><td><code class="verbatim">org-insert-heading-respect-content</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td><code class="verbatim">M-RET</code> adds the new heading after the current subtree. Mirrors <code class="verbatim">org-insert-heading-respect-content</code>.</td></tr> | |
| 235 | <tr><td><code class="verbatim">org-M-RET-may-split-line</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td><code class="verbatim">M-RET</code> in the middle of a line splits it at the caret. Mirrors the <code class="verbatim">default</code> entry of <code class="verbatim">org-M-RET-may-split-line</code>.</td></tr> | |
| 236 | <tr><td><code class="verbatim">org-list-allow-alphabetical</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td><code class="verbatim">a.</code>, <code class="verbatim">b)</code>, <code class="verbatim">A.</code> are list bullets. Mirrors <code class="verbatim">org-list-allow-alphabetical</code>.</td></tr> | |
| 237 | <tr><td><code class="verbatim">org-hide-emphasis-markers</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Your Emacs hides <code class="verbatim">*bold*</code> and <code>=code=</code> markers; Orgstar hides them when markup is hidden and measures text without them. Mirrors <code class="verbatim">org-hide-emphasis-markers</code>.</td></tr> | |
| 238 | <tr><td><code class="verbatim">org-pretty-entities</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Your Emacs shows <code class="verbatim">\alpha</code> as α and lowers <code class="verbatim">x_{1}</code>; Orgstar does the same when markup is hidden. Mirrors <code class="verbatim">org-pretty-entities</code>.</td></tr> | |
| 239 | <tr><td><code class="verbatim">org-todo-keywords</code></td><td>string</td><td>see below</td><td>Keywords for files without <code class="verbatim">#+TODO</code>, in <code class="verbatim">#+TODO</code> syntax; separate sequences with <code class="verbatim">\n</code>. Letters in parentheses turn on fast selection. Read at launch. Mirrors <code class="verbatim">org-todo-keywords</code>.</td></tr> | |
| 240 | <tr><td><code class="verbatim">org-log-done</code></td><td>string</td><td><code class="verbatim">"nil"</code></td><td><code class="verbatim">nil</code>, <code class="verbatim">time</code> (a <code class="verbatim">CLOSED</code> timestamp) or <code class="verbatim">note</code> (<code class="verbatim">CLOSED</code> and a note). Mirrors <code class="verbatim">org-log-done</code>.</td></tr> | |
| 241 | <tr><td><code class="verbatim">org-log-reschedule</code></td><td>string</td><td><code class="verbatim">"nil"</code></td><td><code class="verbatim">nil</code>, <code class="verbatim">time</code> or <code class="verbatim">note</code>: log changing or removing a <code class="verbatim">SCHEDULED</code> date. Mirrors <code class="verbatim">org-log-reschedule</code>.</td></tr> | |
| 242 | <tr><td><code class="verbatim">org-log-redeadline</code></td><td>string</td><td><code class="verbatim">"nil"</code></td><td><code class="verbatim">nil</code>, <code class="verbatim">time</code> or <code class="verbatim">note</code>: log changing or removing a <code class="verbatim">DEADLINE</code>. Mirrors <code class="verbatim">org-log-redeadline</code>.</td></tr> | |
| 243 | <tr><td><code class="verbatim">org-log-into-drawer</code></td><td>string</td><td><code class="verbatim">""</code></td><td>The drawer state notes go in. <code class="verbatim">"LOGBOOK"</code> is Emacs's <code class="verbatim">t</code>; <code class="verbatim">""</code> puts them under the heading. Mirrors <code class="verbatim">org-log-into-drawer</code>.</td></tr> | |
| 244 | <tr><td><code class="verbatim">org-startup-indented</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Indent bodies under their headings, as <code class="verbatim">org-indent-mode</code>. <code class="verbatim">#+STARTUP: indent</code> / <code class="verbatim">noindent</code> override it. Mirrors <code class="verbatim">org-startup-indented</code>.</td></tr> | |
| 245 | <tr><td><code class="verbatim">org-hide-leading-stars</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Show only a heading's last star, without indentation. <code class="verbatim">#+STARTUP: hidestars</code> / <code class="verbatim">showstars</code> override it. Mirrors <code class="verbatim">org-hide-leading-stars</code>.</td></tr> | |
| 246 | <tr><td><code class="verbatim">org-startup-align-all-tables</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Align every table when a file opens. <code class="verbatim">#+STARTUP: align</code> / <code class="verbatim">noalign</code> override it. Mirrors <code class="verbatim">org-startup-align-all-tables</code>.</td></tr> | |
| 247 | <tr><td><code class="verbatim">org-startup-truncated</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Long lines run off the right edge instead of wrapping. Mirrors <code class="verbatim">org-startup-truncated</code>.</td></tr> | |
| 248 | <tr><td><code class="verbatim">spell-check</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Check spelling while typing, outside code, links, dates, tags and keywords.</td></tr> | |
| 249 | <tr><td><code class="verbatim">electric-pair-mode</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Type brackets, <code class="verbatim"><></code> and quotes in pairs. Mirrors <code class="verbatim">electric-pair-mode</code>.</td></tr> | |
| 250 | <tr><td><code class="verbatim">org-startup-with-inline-images</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Show image links as images when a file opens. <code class="verbatim">#+STARTUP: inlineimages</code> / <code class="verbatim">noinlineimages</code> override it. Mirrors <code class="verbatim">org-startup-with-inline-images</code>.</td></tr> | |
| 251 | <tr><td><code class="verbatim">org-use-speed-commands</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Single keys at the start of a heading line run commands (<code class="verbatim">n</code>, <code class="verbatim">p</code>, <code class="verbatim">t</code>, <code class="verbatim">c</code>, …). Mirrors <code class="verbatim">org-use-speed-commands</code>.</td></tr> | |
| 252 | <tr><td><code class="verbatim">org-cycle-hide-drawer-startup</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Fold drawers when a file opens. <code class="verbatim">#+STARTUP: hidedrawers</code> / <code class="verbatim">nohidedrawers</code> override it. Mirrors <code class="verbatim">org-cycle-hide-drawer-startup</code>.</td></tr> | |
| 253 | <tr><td><code class="verbatim">org-cycle-hide-block-startup</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Fold blocks when a file opens. <code class="verbatim">#+STARTUP: hideblocks</code> / <code class="verbatim">nohideblocks</code> override it. Mirrors <code class="verbatim">org-cycle-hide-block-startup</code>.</td></tr> | |
| 254 | <tr><td><code class="verbatim">display-line-numbers-type</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Line numbers in the editor's gutter. Orgstar numbers lines absolutely; there is no relative or visual mode.</td></tr> | |
| 255 | <tr><td><code class="verbatim">org-agenda-span</code></td><td>integer</td><td><code class="verbatim">10</code></td><td>Days the agenda shows. Mirrors <code class="verbatim">org-agenda-span</code>.</td></tr> | |
| 256 | <tr><td><code class="verbatim">org-agenda-start-day</code></td><td>string</td><td><code class="verbatim">"-3d"</code></td><td>The agenda's first day relative to today, as <code class="verbatim">"-3d"</code> or <code class="verbatim">"+0d"</code>. Only day offsets are accepted. Mirrors <code class="verbatim">org-agenda-start-day</code>.</td></tr> | |
| 257 | <tr><td><code class="verbatim">appt-message-warning-time</code></td><td>integer</td><td><code class="verbatim">12</code></td><td>Minutes of warning before timed entries. An entry's <code class="verbatim">APPT_WARNTIME</code> property overrides it. Mirrors <code class="verbatim">appt-message-warning-time</code>.</td></tr> | |
| 258 | <tr><td><code class="verbatim">org-clock-idle-time</code></td><td>integer</td><td><code class="verbatim">0</code></td><td>Minutes without keyboard or mouse input, with a clock running, before Orgstar asks what to do with the idle time. <code class="verbatim">0</code> never asks (Emacs's <code class="verbatim">nil</code>). Mac only. Mirrors <code class="verbatim">org-clock-idle-time</code>.</td></tr> | |
| 259 | <tr><td><code class="verbatim">org-clock-history-length</code></td><td>integer</td><td><code class="verbatim">5</code></td><td>How many recently clocked entries Orgstar remembers. Mirrors <code class="verbatim">org-clock-history-length</code>.</td></tr> | |
| 260 | </tbody> | |
| 261 | </table> | |
| 262 | <p>The default <code class="verbatim">org-todo-keywords</code> is the first sequence of Doom Emacs's default:</p> | |
| 263 | <pre><code class="language-toml highlight"><span class="source toml"><span class="variable other key toml">org-todo-keywords</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) | DONE(d) KILL(k)<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 264 | <p>The startup settings (<code class="verbatim">org-startup-*</code>, <code class="verbatim">org-hide-leading-stars</code>, <code class="verbatim">org-cycle-hide-*-startup</code>) apply when a file opens. Files already open keep their state until you open them again.</p> | |
| 265 | <h3 id="org-agenda-prefix-format">[org-agenda-prefix-format]</h3> | |
| 266 | <table> | |
| 267 | <thead> | |
| 268 | <tr><th>Key</th><th>Type</th><th>Default</th><th>Effect</th></tr> | |
| 269 | </thead> | |
| 270 | <tbody> | |
| 271 | <tr><td><code class="verbatim">agenda</code></td><td>string</td><td><code class="verbatim">" %i %-12:c%?-12t% s"</code></td><td>Prefix of lines in the day view</td></tr> | |
| 272 | <tr><td><code class="verbatim">todo</code></td><td>string</td><td><code class="verbatim">" %i %-12:c"</code></td><td>Prefix of lines in the TODO list</td></tr> | |
| 273 | <tr><td><code class="verbatim">tags</code></td><td>string</td><td><code class="verbatim">" %i %-12:c"</code></td><td>Prefix of tag and property matches</td></tr> | |
| 274 | </tbody> | |
| 275 | </table> | |
| 276 | <p>These mirror the entries of <code class="verbatim">org-agenda-prefix-format</code>. In the format, <code class="verbatim">%c</code> is the category, <code class="verbatim">%t</code> the time, <code class="verbatim">%s</code> the scheduled or deadline note, <code class="verbatim">%e</code> the effort, <code class="verbatim">%l</code> the level, <code class="verbatim">%b</code> the outline path, <code class="verbatim">%T</code> the item's last tag (inherited tags included), and a number such as <code class="verbatim">%-12</code> pads. See <a href="07-agenda.html">The agenda</a>.</p> | |
| 277 | <h3 id="theme">[theme]</h3> | |
| 278 | <table> | |
| 279 | <thead> | |
| 280 | <tr><th>Key</th><th>Type</th><th>Default</th><th>Effect</th></tr> | |
| 281 | </thead> | |
| 282 | <tbody> | |
| 283 | <tr><td><code class="verbatim">font</code></td><td>string</td><td><code class="verbatim">""</code></td><td>A font family. <code class="verbatim">""</code> uses the system's monospaced font.</td></tr> | |
| 284 | <tr><td><code class="verbatim">font-size</code></td><td>integer</td><td><code class="verbatim">13</code></td><td>Points.</td></tr> | |
| 285 | <tr><td><code class="verbatim">line-spacing</code></td><td>integer</td><td><code class="verbatim">2</code></td><td>Points between lines.</td></tr> | |
| 286 | <tr><td><code class="verbatim">heading-size-step</code></td><td>integer</td><td><code class="verbatim">1</code></td><td>Points a heading is larger than the level below. Level 4 and deeper are body size.</td></tr> | |
| 287 | <tr><td><code class="verbatim">theme-file</code></td><td>string</td><td><code class="verbatim">""</code></td><td>A theme in its own file in the configuration folder, applied under the colors in <code class="verbatim">config.toml</code>.</td></tr> | |
| 288 | </tbody> | |
| 289 | </table> | |
| 290 | <p>Any other key in <code class="verbatim">[theme]</code> is a color; see Themes below.</p> | |
| 291 | <h3 id="orgstar">[orgstar]</h3> | |
| 292 | <table> | |
| 293 | <thead> | |
| 294 | <tr><th>Key</th><th>Type</th><th>Default</th><th>Effect</th></tr> | |
| 295 | </thead> | |
| 296 | <tbody> | |
| 297 | <tr><td><code class="verbatim">save</code></td><td>string</td><td><code class="verbatim">"automatic"</code></td><td><code class="verbatim">automatic</code> (one second after typing stops) or <code class="verbatim">explicit</code> (only with <code class="verbatim">⌘S</code>).</td></tr> | |
| 298 | <tr><td><code class="verbatim">keymap</code></td><td>string</td><td><code class="verbatim">"emacs"</code></td><td><code class="verbatim">emacs</code>, <code class="verbatim">mac</code> or <code class="verbatim">doom</code>. Your own bindings go in <code class="verbatim">keymap.toml</code>.</td></tr> | |
| 299 | <tr><td><code class="verbatim">option-as-meta</code></td><td>string</td><td><code class="verbatim">"left"</code></td><td>Which Option key is Meta: <code class="verbatim">left</code>, <code class="verbatim">right</code>, <code class="verbatim">both</code> or <code class="verbatim">none</code>.</td></tr> | |
| 300 | <tr><td><code class="verbatim">tab-bar</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>A tab for each open buffer above the editor.</td></tr> | |
| 301 | <tr><td><code class="verbatim">show-markup</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>Show link brackets and emphasis markers.</td></tr> | |
| 302 | <tr><td><code class="verbatim">show-hidden-files</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>List dotfiles and dot folders in your folders.</td></tr> | |
| 303 | <tr><td><code class="verbatim">ignored-folders</code></td><td>string</td><td>see below</td><td>Folder names never listed or searched, separated by spaces.</td></tr> | |
| 304 | <tr><td><code class="verbatim">agenda-include-subfolders</code></td><td>boolean</td><td><code class="verbatim">false</code></td><td>The agenda reads org files in subfolders too.</td></tr> | |
| 305 | <tr><td><code class="verbatim">reminders</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td>Notify before timed entries.</td></tr> | |
| 306 | <tr><td><code class="verbatim">global-capture-hotkey</code></td><td>boolean</td><td><code class="verbatim">true</code></td><td><code class="verbatim">⌃⌥Space</code> opens Capture from any app.</td></tr> | |
| 307 | </tbody> | |
| 308 | </table> | |
| 309 | <p>The default <code class="verbatim">ignored-folders</code> is:</p> | |
| 310 | <pre><code class="language-toml highlight"><span class="source toml"><span class="variable other key toml">ignored-folders</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>.Spotlight-V100 .Trash .build .bzr .cache .fseventsd .git .gradle .hg .jj .mypy_cache .next .pytest_cache .stfolder .stversions .svn .terraform .tox .venv node_modules<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 311 | <h3 id="an-example">An example</h3> | |
| 312 | <pre><code class="language-toml highlight"><span class="source toml"><span class="variable other key toml">fill-column</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">72</span> | |
| 313 | <span class="variable other key toml">org-tags-column</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">0</span> | |
| 314 | <span class="variable other key toml">org-todo-keywords</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>TODO(t) NEXT(n) WAIT(w@/!) | DONE(d!) CANCELED(c@)<span class="punctuation definition string end toml">"</span></span> | |
| 315 | <span class="variable other key toml">org-log-done</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>time<span class="punctuation definition string end toml">"</span></span> | |
| 316 | <span class="variable other key toml">org-log-into-drawer</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>LOGBOOK<span class="punctuation definition string end toml">"</span></span> | |
| 317 | <span class="variable other key toml">org-startup-truncated</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span> | |
| 318 | <span class="variable other key toml">org-agenda-span</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">7</span> | |
| 319 | <span class="variable other key toml">org-agenda-start-day</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>+0d<span class="punctuation definition string end toml">"</span></span> | |
| 320 | ||
| 321 | <span class="punctuation definition table toml">[</span><span class="entity name section toml">theme</span><span class="punctuation definition table toml">]</span> | |
| 322 | <span class="variable other key toml">font</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>JetBrains Mono<span class="punctuation definition string end toml">"</span></span> | |
| 323 | <span class="variable other key toml">font-size</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">14</span> | |
| 324 | <span class="variable other key toml">link</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>#0a7ea4<span class="punctuation definition string end toml">"</span></span> | |
| 325 | ||
| 326 | <span class="punctuation definition table toml">[</span><span class="entity name section toml">theme.todo</span><span class="punctuation definition table toml">]</span> | |
| 327 | <span class="variable other key toml">WAIT</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>#bf8700<span class="punctuation definition string end toml">"</span></span> | |
| 328 | ||
| 329 | <span class="punctuation definition table toml">[</span><span class="entity name section toml">orgstar</span><span class="punctuation definition table toml">]</span> | |
| 330 | <span class="variable other key toml">keymap</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>doom<span class="punctuation definition string end toml">"</span></span> | |
| 331 | <span class="variable other key toml">save</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>explicit<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 332 | <h3 id="names-from-earlier-versions">Names from earlier versions</h3> | |
| 333 | <p>Earlier versions used keys such as <code class="verbatim">editor.fill-column</code> and <code class="verbatim">agenda.span</code>. Orgstar still reads them. At launch, each such key in the file is renamed in place to its current name and moved to its current section; the rest of the file, and the comments on those lines, stay as they are. When a setting is in the file under both names, the current name wins and the old line is removed. A section the move leaves empty is removed. A file that lacks a whole section (such as <code class="verbatim">[theme]</code>) gets that section added at the end.</p> | |
| 334 | <h2 id="keymap-toml-and-capture-toml">keymap.toml and capture.toml</h2> | |
| 335 | <p><code class="verbatim">keymap.toml</code> holds <code class="verbatim">[[bind]]</code> tables with <code class="verbatim">keys</code>, <code class="verbatim">command</code>, and optionally <code class="verbatim">mode</code> and <code class="verbatim">when</code>. They layer over the preset chosen in Keys. Orgstar reloads the file when it changes. See <a href="03-keys.html">Keys and commands</a>.</p> | |
| 336 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">bind</span><span class="punctuation definition table array toml">]]</span> | |
| 337 | <span class="variable other key toml">keys</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>C-c a<span class="punctuation definition string end toml">"</span></span> | |
| 338 | <span class="variable other key toml">command</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>app.agenda<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 339 | <p><code class="verbatim">capture.toml</code> holds <code class="verbatim">[[template]]</code> tables. Without the file, Orgstar uses two templates: <code class="verbatim">t</code> (Personal todo, under <code class="verbatim">Inbox</code> in <code class="verbatim">todo.org</code>) and <code class="verbatim">n</code> (Personal notes, under <code class="verbatim">Inbox</code> in <code class="verbatim">notes.org</code>). See <a href="08-capture.html">Capture</a>.</p> | |
| 340 | <p><code class="verbatim">views.toml</code> holds <code class="verbatim">[[view]]</code> tables for the agenda; see <a href="07-agenda.html">The agenda</a>.</p> | |
| 341 | <h2 id="in-file-settings">In-file settings</h2> | |
| 342 | <p>Keyword lines in a file set options for that file, as in Emacs. Orgstar reads them outside blocks; for <code class="verbatim">#+STARTUP</code> only keyword lines count, so a <code class="verbatim">#+STARTUP</code> line inside a paragraph or a block changes nothing: not folding, logging or inline images.</p> | |
| 343 | <h3 id="keywords-orgstar-reads">Keywords Orgstar reads</h3> | |
| 344 | <table> | |
| 345 | <thead> | |
| 346 | <tr><th>Keyword</th><th>Effect</th></tr> | |
| 347 | </thead> | |
| 348 | <tbody> | |
| 349 | <tr><td><code class="verbatim">#+TODO</code>, <code class="verbatim">#+SEQ_TODO</code></td><td>A TODO sequence: active keywords, a bar, then done keywords. Without the bar, the last word is the done state. <code class="verbatim">NAME(k)</code> gives a fast-selection key, <code class="verbatim">NAME(k!/@)</code> logging on entering and leaving. Any TODO line replaces the default keywords.</td></tr> | |
| 350 | <tr><td><code class="verbatim">#+TYP_TODO</code></td><td>A type sequence. As in Org, type sequences come first, then <code class="verbatim">#+TODO</code>, then <code class="verbatim">#+SEQ_TODO</code>.</td></tr> | |
| 351 | <tr><td><code class="verbatim">#+PRIORITIES</code></td><td>Three values: highest, lowest, default, as <code class="verbatim">A C B</code> or <code class="verbatim">1 5 3</code>. The default is <code class="verbatim">A C B</code>.</td></tr> | |
| 352 | <tr><td><code class="verbatim">#+STARTUP</code></td><td>Startup options; see below.</td></tr> | |
| 353 | <tr><td><code class="verbatim">#+TAGS</code></td><td>Tags for fast tag selection with <code class="verbatim">C-c C-q</code>, with keys as <code class="verbatim">work(w)</code>, groups in <code class="verbatim">{ }</code> and tag groups in <code class="verbatim">[ ]</code>. Without <code class="verbatim">#+TAGS</code>, <code class="verbatim">C-c C-q</code> offers the tags used in the file.</td></tr> | |
| 354 | <tr><td><code class="verbatim">#+FILETAGS</code></td><td>Tags every heading in the file inherits, as <code class="verbatim">:work:project:</code>.</td></tr> | |
| 355 | <tr><td><code class="verbatim">#+PROPERTY</code></td><td>A file-wide property, as <code class="verbatim">#+PROPERTY: header-args :results output</code>. <code class="verbatim">NAME+</code> appends to the value.</td></tr> | |
| 356 | <tr><td><code class="verbatim">#+CATEGORY</code></td><td>The file's category in the agenda. Without it the category is the file name.</td></tr> | |
| 357 | <tr><td><code class="verbatim">#+ARCHIVE</code></td><td>Where <code class="verbatim">C-c C-x C-a</code> archives to. The default is <code class="verbatim">%s_archive::</code>.</td></tr> | |
| 358 | <tr><td><code class="verbatim">#+COLUMNS</code></td><td>The default column view format.</td></tr> | |
| 359 | <tr><td><code class="verbatim">#+LINK</code></td><td>A link abbreviation, as <code class="verbatim">#+LINK: gh https://github.com/%s</code>.</td></tr> | |
| 360 | <tr><td><code class="verbatim">#+CONSTANTS</code></td><td>Constants for table formulas, as <code class="verbatim">#+CONSTANTS: c=299792458 pi=3.14</code>.</td></tr> | |
| 361 | <tr><td><code class="verbatim">#+SETUPFILE</code></td><td>A file whose keyword lines count as this file's; see below.</td></tr> | |
| 362 | <tr><td><code class="verbatim">#+TITLE</code>, <code class="verbatim">#+AUTHOR</code>, <code class="verbatim">#+DESCRIPTION</code></td><td>Used by export, Quick Look and Spotlight.</td></tr> | |
| 363 | <tr><td><code class="verbatim">#+OPTIONS</code>, <code class="verbatim">#+MACRO</code>, <code class="verbatim">#+INCLUDE</code>, <code class="verbatim">#+EXCLUDE_TAGS</code>, <code class="verbatim">#+SELECT_TAGS</code></td><td>Export settings; see <a href="12-export.html">Export</a>.</td></tr> | |
| 364 | </tbody> | |
| 365 | </table> | |
| 366 | <pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+TODO:</span><span class="string unquoted org"> TODO(t) NEXT(n) WAIT(w@/!) | DONE(d!) CANCELED(c@)</span> | |
| 367 | <span class="keyword other keyword org">#+PRIORITIES:</span><span class="string unquoted org"> A E C</span> | |
| 368 | <span class="keyword other keyword org">#+STARTUP:</span><span class="string unquoted org"> content logdrawer</span> | |
| 369 | <span class="keyword other keyword org">#+FILETAGS:</span><span class="string unquoted org"> :work:</span> | |
| 370 | <span class="keyword other keyword org">#+CATEGORY:</span><span class="string unquoted org"> acme</span></span></code></pre> | |
| 371 | <p>After you change a keyword line, press <code class="verbatim">C-c C-c</code> on it to read the file's settings again, as <code class="verbatim">org-mode-restart</code> does in Emacs. Changes to <code class="verbatim">#+TODO</code>, <code class="verbatim">#+SEQ_TODO</code>, <code class="verbatim">#+TYP_TODO</code> and <code class="verbatim">#+PRIORITIES</code> apply as you type.</p> | |
| 372 | <h3 id="startup-options">#+STARTUP options</h3> | |
| 373 | <table> | |
| 374 | <thead> | |
| 375 | <tr><th>Option</th><th>Effect</th></tr> | |
| 376 | </thead> | |
| 377 | <tbody> | |
| 378 | <tr><td><code class="verbatim">overview</code>, <code class="verbatim">fold</code></td><td>Only top-level headings show when the file opens.</td></tr> | |
| 379 | <tr><td><code class="verbatim">content</code></td><td>All headings show, no bodies.</td></tr> | |
| 380 | <tr><td><code class="verbatim">showall</code>, <code class="verbatim">nofold</code></td><td>Everything shows.</td></tr> | |
| 381 | <tr><td><code class="verbatim">show2levels</code> … <code class="verbatim">show5levels</code> (any <code class="verbatim">showNlevels</code>)</td><td>Headings down to level N show.</td></tr> | |
| 382 | <tr><td><code class="verbatim">showeverything</code></td><td>Everything shows, including drawers and blocks; <code class="verbatim">VISIBILITY</code> properties are ignored.</td></tr> | |
| 383 | <tr><td><code class="verbatim">hidedrawers</code>, <code class="verbatim">nohidedrawers</code></td><td>Fold or don't fold drawers at startup.</td></tr> | |
| 384 | <tr><td><code class="verbatim">hideblocks</code>, <code class="verbatim">nohideblocks</code></td><td>Fold or don't fold blocks at startup.</td></tr> | |
| 385 | <tr><td><code class="verbatim">indent</code>, <code class="verbatim">noindent</code></td><td>Virtual indentation on or off.</td></tr> | |
| 386 | <tr><td><code class="verbatim">hidestars</code>, <code class="verbatim">showstars</code></td><td>Hide leading stars or show them.</td></tr> | |
| 387 | <tr><td><code class="verbatim">align</code>, <code class="verbatim">noalign</code></td><td>Align every table when the file opens, or don't.</td></tr> | |
| 388 | <tr><td><code class="verbatim">inlineimages</code>, <code class="verbatim">noinlineimages</code></td><td>Show image links as images, or don't.</td></tr> | |
| 389 | <tr><td><code class="verbatim">shrink</code></td><td>Shrink table columns that have a width cookie.</td></tr> | |
| 390 | <tr><td><code class="verbatim">logdone</code>, <code class="verbatim">lognotedone</code>, <code class="verbatim">nologdone</code></td><td>Record a time, a note, or nothing when an entry becomes done.</td></tr> | |
| 391 | <tr><td><code class="verbatim">logrepeat</code>, <code class="verbatim">lognoterepeat</code>, <code class="verbatim">nologrepeat</code></td><td>The same, when a repeating entry is completed.</td></tr> | |
| 392 | <tr><td><code class="verbatim">logreschedule</code>, <code class="verbatim">lognotereschedule</code>, <code class="verbatim">nologreschedule</code></td><td>The same, when a scheduled date changes.</td></tr> | |
| 393 | <tr><td><code class="verbatim">logredeadline</code>, <code class="verbatim">lognoteredeadline</code>, <code class="verbatim">nologredeadline</code></td><td>The same, when a deadline changes.</td></tr> | |
| 394 | <tr><td><code class="verbatim">logdrawer</code>, <code class="verbatim">nologdrawer</code></td><td>Notes go in <code class="verbatim">LOGBOOK</code>, or under the heading.</td></tr> | |
| 395 | </tbody> | |
| 396 | </table> | |
| 397 | <p>After the startup visibility, Orgstar applies each heading's <code class="verbatim">VISIBILITY</code> property and folds subtrees tagged <code class="verbatim">ARCHIVE</code>, unless <code class="verbatim">showeverything</code> is set.</p> | |
| 398 | <p>Completion offers every option of <code class="verbatim">org-startup-options</code>. Options not in the table above, such as <code class="verbatim">odd</code>, <code class="verbatim">entitiespretty</code>, <code class="verbatim">latexpreview</code>, <code class="verbatim">constSI</code> and the footnote options, are accepted and ignored.</p> | |
| 399 | <h3 id="setup-files">Setup files</h3> | |
| 400 | <p><code class="verbatim">#+SETUPFILE: path</code> reads the keyword lines of another file and treats them as if they were in this file, before its own lines. This follows <code class="verbatim">org--collect-keywords-1</code> in Org:</p> | |
| 401 | <ul> | |
| 402 | <li>A relative path is relative to the folder of the file that names it. <code class="verbatim">~</code> expands to your home folder. Quotes around the path are removed.</li> | |
| 403 | <li>A setup file can name further setup files; each is read once, and a file never reads itself.</li> | |
| 404 | <li>URLs (anything starting with <code class="verbatim">scheme://</code>) aren't fetched.</li> | |
| 405 | <li>A setup file that can't be read, or isn't UTF-8, is skipped without a message.</li> | |
| 406 | </ul> | |
| 407 | <p>Keywords from setup files count for TODO keywords, priorities, <code class="verbatim">#+STARTUP</code>, <code class="verbatim">#+TAGS</code>, <code class="verbatim">#+FILETAGS</code>, <code class="verbatim">#+PROPERTY</code>, <code class="verbatim">#+CATEGORY</code>, <code class="verbatim">#+ARCHIVE</code>, <code class="verbatim">#+COLUMNS</code>, <code class="verbatim">#+LINK</code>, <code class="verbatim">#+CONSTANTS</code> and export. Orgstar reads setup files when a file opens, when you press <code class="verbatim">C-c C-c</code> on a keyword line, and when the file changes on disk. If you edit only the setup file, press <code class="verbatim">C-c C-c</code> on a keyword line of each open file that uses it.</p> | |
| 408 | <h2 id="import-from-emacs">Import from Emacs</h2> | |
| 409 | <p>Import from Emacs reads your Emacs or Doom Emacs configuration and offers to carry its org settings, folders, capture templates and key bindings over. Nothing changes until you choose Import.</p> | |
| 410 | <h3 id="running-it">Running it</h3> | |
| 411 | <ol> | |
| 412 | <li>Open Settings ▸ General and click Import from Emacs…, or run Import from Emacs… from the command palette (<code class="verbatim">⇧⌘P</code>).</li> | |
| 413 | <li>Orgstar looks for a configuration in these places, in order, and reads the first it finds: <code class="verbatim">$DOOMDIR</code>, <code class="verbatim">~/.config/doom</code>, <code class="verbatim">~/.doom.d</code>, <code class="verbatim">~/.config/emacs</code>, <code class="verbatim">~/.emacs.d</code>, <code class="verbatim">~/.emacs</code>. A folder counts when it holds <code class="verbatim">init.el</code>, <code class="verbatim">config.el</code> or <code class="verbatim">custom.el</code>. Doom's own installation folder (one with <code class="verbatim">lisp/doom.el</code>) is skipped.</li> | |
| 414 | <li>To read another configuration, click Choose… and pick a file or a folder. For a folder, Orgstar reads <code class="verbatim">init.el</code>, <code class="verbatim">config.el</code> and <code class="verbatim">custom.el</code> in it.</li> | |
| 415 | <li>The sheet lists what it found under Settings, Folders, Capture templates and Key bindings, each with the line it came from (<code class="verbatim">config.el:27</code>, or <code class="verbatim">Doom default</code>). Everything is selected; clear what you don't want.</li> | |
| 416 | <li>Click Import. The sheet then summarizes what was imported and any problems.</li> | |
| 417 | </ol> | |
| 418 | <p>What Import does with each kind of item:</p> | |
| 419 | <ul> | |
| 420 | <li>Settings are written to <code class="verbatim">config.toml</code>.</li> | |
| 421 | <li>Folders are added to the sidebar if they exist and aren't there already.</li> | |
| 422 | <li>Capture templates are appended to <code class="verbatim">capture.toml</code>, except those whose key is already in the file.</li> | |
| 423 | <li>Key bindings are appended to <code class="verbatim">keymap.toml</code>, except those already in the file with the same keys, command and state. Running the import again adds no duplicates.</li> | |
| 424 | </ul> | |
| 425 | <p>The Not imported section lists what Orgstar read but can't use, with the reason: settings it has no equivalent for, values it can't work out without running Emacs, bindings to code rather than a command, and files it couldn't read. The footer counts variables that aren't about org, which are left alone.</p> | |
| 426 | <p>A literate configuration (<code class="verbatim">config.org</code>) isn't read. Point Choose… at the <code class="verbatim">config.el</code> it tangles to.</p> | |
| 427 | <h3 id="doom-emacs">Doom Emacs</h3> | |
| 428 | <p>A configuration counts as Doom when it contains <code class="verbatim">(doom!</code>, <code class="verbatim">(map! = or =(after! =. Orgstar then also reads Doom's own org defaults, from the Doom installation in =$EMACSDIR</code>, <code class="verbatim">~/.config/emacs</code> or <code class="verbatim">~/.emacs.d</code>: <code class="verbatim">modules/lang/org/config.el</code> and <code class="verbatim">lisp/doom-emacs.el</code>. Your configuration overrides them. Doom defaults Orgstar has no use for are counted in the footer rather than listed.</p> | |
| 429 | <p>A Doom configuration, or any configuration that enables <code class="verbatim">evil</code>, adds <code class="verbatim">keymap = "doom"</code>.</p> | |
| 430 | <h3 id="what-it-reads">What it reads</h3> | |
| 431 | <p>Orgstar reads the configuration as Lisp data; it never runs it. It looks at these forms:</p> | |
| 432 | <table> | |
| 433 | <thead> | |
| 434 | <tr><th>Form</th><th>What Orgstar takes</th></tr> | |
| 435 | </thead> | |
| 436 | <tbody> | |
| 437 | <tr><td><code class="verbatim">setq</code>, <code class="verbatim">setq-default</code>, <code class="verbatim">setq!</code>, <code class="verbatim">setopt</code>, <code class="verbatim">csetq</code></td><td>Each variable and value</td></tr> | |
| 438 | <tr><td><code class="verbatim">defvar</code>, <code class="verbatim">defcustom</code></td><td>The value, below every other assignment</td></tr> | |
| 439 | <tr><td><code class="verbatim">custom-set-variables</code></td><td>Each quoted <code class="verbatim">(variable value)</code></td></tr> | |
| 440 | <tr><td><code class="verbatim">after!</code>, <code class="verbatim">with-eval-after-load</code>, <code class="verbatim">eval-after-load</code></td><td>The forms inside, ranked above plain assignments</td></tr> | |
| 441 | <tr><td><code class="verbatim">use-package</code>, <code class="verbatim">use-package!</code></td><td>Forms in <code class="verbatim">:config</code> and <code class="verbatim">:init</code>, and pairs in <code class="verbatim">:custom</code></td></tr> | |
| 442 | <tr><td><code class="verbatim">progn</code>, <code class="verbatim">when</code>, <code class="verbatim">unless</code>, <code class="verbatim">if</code>, <code class="verbatim">let</code>, <code class="verbatim">let*</code>, <code class="verbatim">with-no-warnings</code></td><td>The forms inside. Conditions aren't evaluated, so every branch is read.</td></tr> | |
| 443 | <tr><td><code class="verbatim">map!</code> (Doom)</td><td>Bindings, with <code class="verbatim">:leader</code> (<code class="verbatim">SPC</code>), <code class="verbatim">:localleader</code> (<code class="verbatim">SPC m</code>), <code class="verbatim">:prefix</code>, and state keywords such as <code class="verbatim">:n</code>, <code class="verbatim">:i</code>, <code class="verbatim">:v</code>, <code class="verbatim">:nv</code></td></tr> | |
| 444 | <tr><td><code class="verbatim">define-key</code>, <code class="verbatim">keymap-set</code>, <code class="verbatim">global-set-key</code>, <code class="verbatim">keymap-global-set</code></td><td>Bindings</td></tr> | |
| 445 | <tr><td><code class="verbatim">evil-define-key</code>, <code class="verbatim">evil-define-key*</code></td><td>Bindings in the <code class="verbatim">normal</code>, <code class="verbatim">insert</code> or <code class="verbatim">visual</code> state</td></tr> | |
| 446 | </tbody> | |
| 447 | </table> | |
| 448 | <p>When a variable is set more than once, the last assignment wins, with assignments inside <code class="verbatim">after!</code> and similar forms winning over plain ones, and those over Doom's defaults.</p> | |
| 449 | <p>Orgstar works out a value when it is a literal, a quoted or backquoted form (with <code class="verbatim">,</code> and <code class="verbatim">,@</code>), a variable set earlier in the configuration, or a call to <code class="verbatim">list</code>, <code class="verbatim">concat</code>, <code class="verbatim">expand-file-name</code>, <code class="verbatim">file-name-concat</code> or <code class="verbatim">file-name-as-directory</code> on such values. Anything else, such as a function call or a value computed from the environment, is listed under Not imported as worked out when Emacs runs.</p> | |
| 450 | <p>Only variables whose names start with <code class="verbatim">org-</code>, <code class="verbatim">appt-</code>, <code class="verbatim">display-line-numbers</code>, <code class="verbatim">fill-column</code>, <code class="verbatim">evil-</code>, <code class="verbatim">doom-font</code>, <code class="verbatim">doom-variable-pitch-font</code>, <code class="verbatim">doom-theme</code> or <code class="verbatim">calendar-week-start-day</code> are considered.</p> | |
| 451 | <h3 id="how-variables-map">How variables map</h3> | |
| 452 | <table> | |
| 453 | <thead> | |
| 454 | <tr><th>Emacs variable</th><th>Becomes</th></tr> | |
| 455 | </thead> | |
| 456 | <tbody> | |
| 457 | <tr><td><code class="verbatim">fill-column</code>, <code class="verbatim">org-tags-column</code>, <code class="verbatim">appt-message-warning-time</code></td><td>The same key, when the value is a number</td></tr> | |
| 458 | <tr><td><code class="verbatim">org-insert-heading-respect-content</code>, <code class="verbatim">org-list-allow-alphabetical</code>, <code class="verbatim">org-hide-emphasis-markers</code>, <code class="verbatim">org-pretty-entities</code>, <code class="verbatim">org-cycle-hide-drawer-startup</code>, <code class="verbatim">org-cycle-hide-block-startup</code>, <code class="verbatim">org-use-speed-commands</code>, <code class="verbatim">org-startup-with-inline-images</code>, <code class="verbatim">org-startup-indented</code>, <code class="verbatim">org-hide-leading-stars</code>, <code class="verbatim">org-startup-align-all-tables</code>, <code class="verbatim">org-startup-truncated</code></td><td>The same key: <code class="verbatim">nil</code> or an empty list is <code class="verbatim">false</code>, anything else <code class="verbatim">true</code></td></tr> | |
| 459 | <tr><td><code class="verbatim">org-hide-drawer-startup</code>, <code class="verbatim">org-hide-block-startup</code></td><td><code class="verbatim">org-cycle-hide-drawer-startup</code>, <code class="verbatim">org-cycle-hide-block-startup</code></td></tr> | |
| 460 | <tr><td><code class="verbatim">org-M-RET-may-split-line</code></td><td><code class="verbatim">org-M-RET-may-split-line</code>, from the <code class="verbatim">default</code> entry of an alist; other per-context entries aren't supported</td></tr> | |
| 461 | <tr><td><code class="verbatim">org-agenda-prefix-format</code></td><td><code class="verbatim">[org-agenda-prefix-format]</code>: a string sets all three views; an alist sets <code class="verbatim">agenda</code>, <code class="verbatim">todo</code> and <code class="verbatim">tags</code></td></tr> | |
| 462 | <tr><td><code class="verbatim">org-log-done</code>, <code class="verbatim">org-log-reschedule</code>, <code class="verbatim">org-log-redeadline</code></td><td>The same key: <code class="verbatim">nil</code>, <code class="verbatim">time</code> (also <code class="verbatim">t</code>) or <code class="verbatim">note</code></td></tr> | |
| 463 | <tr><td><code class="verbatim">org-log-into-drawer</code></td><td>A string as given; <code class="verbatim">t</code> becomes <code class="verbatim">"LOGBOOK"</code>; <code class="verbatim">nil</code> becomes <code class="verbatim">""</code></td></tr> | |
| 464 | <tr><td><code class="verbatim">display-line-numbers-type</code></td><td><code class="verbatim">true</code> unless <code class="verbatim">nil</code>; <code class="verbatim">relative</code> and <code class="verbatim">visual</code> become absolute numbers</td></tr> | |
| 465 | <tr><td><code class="verbatim">org-agenda-span</code></td><td>A number, or <code class="verbatim">day</code> (1), <code class="verbatim">week</code> (7), <code class="verbatim">fortnight</code> (14), <code class="verbatim">month</code> (30), <code class="verbatim">year</code> (365)</td></tr> | |
| 466 | <tr><td><code class="verbatim">org-clock-idle-time</code></td><td>Minutes; <code class="verbatim">nil</code> becomes <code class="verbatim">0</code> (never)</td></tr> | |
| 467 | <tr><td><code class="verbatim">org-clock-history-length</code></td><td>The same key, when the value is a positive number</td></tr> | |
| 468 | <tr><td><code class="verbatim">org-agenda-start-day</code></td><td>A day offset such as <code class="verbatim">"-3d"</code>; <code class="verbatim">nil</code> becomes <code class="verbatim">"+0d"</code>. Other forms aren't supported.</td></tr> | |
| 469 | <tr><td><code class="verbatim">org-todo-keywords</code></td><td><code class="verbatim">org-todo-keywords</code>, one line per sequence. Keywords with spaces are left out; <code class="verbatim">type</code> sequences are read as sequences.</td></tr> | |
| 470 | <tr><td><code class="verbatim">org-directory</code></td><td>A folder to add</td></tr> | |
| 471 | <tr><td><code class="verbatim">org-agenda-files</code></td><td>A folder for each entry; for a <code class="verbatim">.org</code> file, its folder</td></tr> | |
| 472 | <tr><td><code class="verbatim">org-capture-templates</code></td><td>Templates for <code class="verbatim">capture.toml</code>; see below</td></tr> | |
| 473 | <tr><td><code class="verbatim">doom-font</code></td><td><code class="verbatim">font</code> and <code class="verbatim">font-size</code>, from <code class="verbatim">(font-spec :family … :size …)</code> or <code class="verbatim">"Family-14"</code></td></tr> | |
| 474 | <tr><td><code class="verbatim">doom-variable-pitch-font</code></td><td>Not imported: Orgstar uses one font</td></tr> | |
| 475 | <tr><td><code class="verbatim">doom-theme</code></td><td>Not imported: set colors under <code class="verbatim">[theme]</code></td></tr> | |
| 476 | <tr><td><code class="verbatim">evil-mode</code> in use, or Doom</td><td><code class="verbatim">keymap = "doom"</code></td></tr> | |
| 477 | </tbody> | |
| 478 | </table> | |
| 479 | <p>Any other <code class="verbatim">org-</code> or <code class="verbatim">appt-</code> variable is listed as having no equivalent.</p> | |
| 480 | <p>Capture templates are imported when their type is <code class="verbatim">entry</code>, <code class="verbatim">item</code>, <code class="verbatim">checkitem</code>, <code class="verbatim">plain</code> or <code class="verbatim">table-line</code>, their template is a string, and their target is <code class="verbatim">file</code>, <code class="verbatim">file+headline</code>, <code class="verbatim">file+olp</code>, <code class="verbatim">file+olp+datetree</code>, <code class="verbatim">file+datetree</code>, <code class="verbatim">file+weektree</code>, <code class="verbatim">id</code> or <code class="verbatim">clock</code>. The properties <code class="verbatim">:prepend</code>, <code class="verbatim">:immediate-finish</code>, <code class="verbatim">:jump-to-captured</code>, <code class="verbatim">:clock-in</code>, <code class="verbatim">:clock-keep</code>, <code class="verbatim">:clock-resume</code>, <code class="verbatim">:empty-lines</code>, <code class="verbatim">:empty-lines-before</code>, <code class="verbatim">:empty-lines-after</code>, <code class="verbatim">:tree-type</code> (<code class="verbatim">day</code>, <code class="verbatim">week</code>, <code class="verbatim">month</code>) and <code class="verbatim">:table-line-pos</code> carry over; others are listed as left out. Template groups (a key and a name only) are skipped.</p> | |
| 481 | <p>Key bindings are imported when the command is one Orgstar has a counterpart for, such as <code class="verbatim">org-todo</code>, <code class="verbatim">org-schedule</code>, <code class="verbatim">org-refile</code>, <code class="verbatim">org-capture</code> or <code class="verbatim">save-buffer</code>. The clock commands <code class="verbatim">org-clock-in</code>, <code class="verbatim">org-clock-out</code>, <code class="verbatim">org-clock-cancel</code>, <code class="verbatim">org-clock-goto</code>, <code class="verbatim">org-clock-in-last</code>, <code class="verbatim">org-resolve-clocks</code> and <code class="verbatim">org-clock-mark-default-task</code> map to Clock In, Clock Out, Cancel Clock, Go to Clocked Entry, Clock In to Last Entry, Resolve Open Clocks… and Mark as Default Clock Task. Keys must be a string or <code class="verbatim">(kbd "…")</code>; bindings with key vectors such as <code class="verbatim">[f5]</code> are skipped. In a Doom configuration, bindings without a state go to the <code class="verbatim">normal</code> state.</p> | |
| 482 | <h3 id="limits-of-the-lisp-reader">Limits of the Lisp reader</h3> | |
| 483 | <ul> | |
| 484 | <li>Comments (<code class="verbatim">;</code>) are skipped. Strings understand <code class="verbatim">\n</code>, <code class="verbatim">\t</code>, <code class="verbatim">\"</code> and line continuations; other escapes give the character itself.</li> | |
| 485 | <li><code class="verbatim">#'</code> reads as <code class="verbatim">function</code>. Other <code class="verbatim">#</code> syntax is read as a symbol, so forms using it aren't understood.</li> | |
| 486 | <li>A syntax error anywhere in a file, such as an unclosed parenthesis, stops that file from being read at all. The error and its line show under Not imported.</li> | |
| 487 | <li>Macros other than those in the table above are not expanded, and functions are not called. Settings made by code you wrote (a <code class="verbatim">defun</code> that calls <code class="verbatim">setq</code>, a hook) aren't found.</li> | |
| 488 | </ul> | |
| 489 | <h2 id="themes">Themes</h2> | |
| 490 | <p>Orgstar has one built-in theme, the default theme, with light and dark colors after GitHub's light and dark themes. You change it by setting colors in <code class="verbatim">config.toml</code>, or by keeping a theme in its own file.</p> | |
| 491 | <p>Colors are strings in the form <code class="verbatim">"#rrggbb"</code> or <code class="verbatim">"#rrggbbaa"</code>. They go in these tables:</p> | |
| 492 | <table> | |
| 493 | <thead> | |
| 494 | <tr><th>Table</th><th>Effect</th></tr> | |
| 495 | </thead> | |
| 496 | <tbody> | |
| 497 | <tr><td><code class="verbatim">[theme]</code></td><td>Sets a color for both light and dark appearance</td></tr> | |
| 498 | <tr><td><code class="verbatim">[theme.light]</code></td><td>Sets a color for light appearance only</td></tr> | |
| 499 | <tr><td><code class="verbatim">[theme.dark]</code></td><td>Sets a color for dark appearance only</td></tr> | |
| 500 | <tr><td><code class="verbatim">[theme.todo]</code></td><td>Colors TODO keywords by name, in both appearances, as <code class="verbatim">org-todo-keyword-faces</code></td></tr> | |
| 501 | </tbody> | |
| 502 | </table> | |
| 503 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">theme</span><span class="punctuation definition table toml">]</span> | |
| 504 | <span class="variable other key toml">heading-1</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>#005cc5<span class="punctuation definition string end toml">"</span></span> | |
| 505 | ||
| 506 | <span class="punctuation definition table toml">[</span><span class="entity name section toml">theme.dark</span><span class="punctuation definition table toml">]</span> | |
| 507 | <span class="variable other key toml">background</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>#1e1e1e<span class="punctuation definition string end toml">"</span></span> | |
| 508 | <span class="variable other key toml">foreground</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>#d4d4d4<span class="punctuation definition string end toml">"</span></span> | |
| 509 | ||
| 510 | <span class="punctuation definition table toml">[</span><span class="entity name section toml">theme.todo</span><span class="punctuation definition table toml">]</span> | |
| 511 | <span class="variable other key toml">WAIT</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>#bf8700<span class="punctuation definition string end toml">"</span></span> | |
| 512 | <span class="variable other key toml">PROJ</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>#8250df<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 513 | <p>A keyword without its own color uses <code class="verbatim">todo</code> or <code class="verbatim">done</code>.</p> | |
| 514 | <p><code class="verbatim">default-theme.toml</code> in the configuration folder lists every color key with the default theme's values, light and dark. Settings ▸ Appearance ▸ Show Default Theme opens it. Copy lines from it into <code class="verbatim">config.toml</code>; edits to <code class="verbatim">default-theme.toml</code> itself are overwritten at the next launch.</p> | |
| 515 | <h3 id="theme-files">Theme files</h3> | |
| 516 | <p>To keep a theme in its own file, put it in the configuration folder with the same tables (<code class="verbatim">[theme]</code>, <code class="verbatim">[theme.light]</code>, <code class="verbatim">[theme.dark]</code>, <code class="verbatim">[theme.todo]</code>) and name it in <code class="verbatim">config.toml</code>:</p> | |
| 517 | <pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">theme</span><span class="punctuation definition table toml">]</span> | |
| 518 | <span class="variable other key toml">theme-file</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">"</span>solarized.toml<span class="punctuation definition string end toml">"</span></span></span></code></pre> | |
| 519 | <p>The colors stack in this order, each over the one before: the default theme, the theme file, then the colors in <code class="verbatim">config.toml</code>. The path is relative to the configuration folder and may name a subfolder, as <code class="verbatim">themes/solarized.toml</code>. Orgstar reloads the theme file when it changes. Only colors are read from a theme file; <code class="verbatim">font</code> and the other type keys in its <code class="verbatim">[theme]</code> table are ignored.</p> | |
| 520 | <h3 id="color-keys">Color keys</h3> | |
| 521 | <table> | |
| 522 | <thead> | |
| 523 | <tr><th>Key</th><th>Colors</th></tr> | |
| 524 | </thead> | |
| 525 | <tbody> | |
| 526 | <tr><td><code class="verbatim">background</code></td><td>the editor's background</td></tr> | |
| 527 | <tr><td><code class="verbatim">foreground</code></td><td>body text</td></tr> | |
| 528 | <tr><td><code class="verbatim">cursor</code></td><td>the caret</td></tr> | |
| 529 | <tr><td><code class="verbatim">selection</code></td><td>selected text's background</td></tr> | |
| 530 | <tr><td><code class="verbatim">heading-1</code> … <code class="verbatim">heading-7</code></td><td>headings of that level</td></tr> | |
| 531 | <tr><td><code class="verbatim">heading-8</code></td><td>level 8 and deeper headings</td></tr> | |
| 532 | <tr><td><code class="verbatim">todo</code></td><td>TODO keywords not yet done</td></tr> | |
| 533 | <tr><td><code class="verbatim">done</code></td><td>DONE keywords</td></tr> | |
| 534 | <tr><td><code class="verbatim">priority</code></td><td><code class="verbatim">[#A]</code> cookies</td></tr> | |
| 535 | <tr><td><code class="verbatim">tags</code></td><td><code class="verbatim">:tags:</code></td></tr> | |
| 536 | <tr><td><code class="verbatim">link</code></td><td>links</td></tr> | |
| 537 | <tr><td><code class="verbatim">timestamp</code></td><td>timestamps</td></tr> | |
| 538 | <tr><td><code class="verbatim">code</code></td><td><code class="verbatim">~code~</code> and inline source</td></tr> | |
| 539 | <tr><td><code class="verbatim">verbatim</code></td><td><code>=verbatim=</code></td></tr> | |
| 540 | <tr><td><code class="verbatim">inline-background</code></td><td>behind <code class="verbatim">~code~</code> and <code>=verbatim=</code></td></tr> | |
| 541 | <tr><td><code class="verbatim">markup</code></td><td>link brackets and emphasis markers</td></tr> | |
| 542 | <tr><td><code class="verbatim">comment</code></td><td>comments</td></tr> | |
| 543 | <tr><td><code class="verbatim">keyword</code></td><td><code class="verbatim">#+KEYWORD</code> lines</td></tr> | |
| 544 | <tr><td><code class="verbatim">metadata</code></td><td>planning lines, drawers, properties and clocks</td></tr> | |
| 545 | <tr><td><code class="verbatim">special</code></td><td>footnotes, statistics cookies, targets, macros and LaTeX</td></tr> | |
| 546 | <tr><td><code class="verbatim">block-background</code></td><td>the band behind blocks</td></tr> | |
| 547 | <tr><td><code class="verbatim">block-delimiter</code></td><td><code class="verbatim">#+begin_</code> and <code class="verbatim">#+end_</code> lines</td></tr> | |
| 548 | <tr><td><code class="verbatim">table</code></td><td>tables</td></tr> | |
| 549 | <tr><td><code class="verbatim">line-number</code></td><td>line numbers</td></tr> | |
| 550 | <tr><td><code class="verbatim">line-number-current</code></td><td>the caret's line number</td></tr> | |
| 551 | <tr><td><code class="verbatim">syntax-keyword</code></td><td>code: keywords</td></tr> | |
| 552 | <tr><td><code class="verbatim">syntax-string</code></td><td>code: strings</td></tr> | |
| 553 | <tr><td><code class="verbatim">syntax-comment</code></td><td>code: comments</td></tr> | |
| 554 | <tr><td><code class="verbatim">syntax-function</code></td><td>code: functions</td></tr> | |
| 555 | <tr><td><code class="verbatim">syntax-type</code></td><td>code: types and modules</td></tr> | |
| 556 | <tr><td><code class="verbatim">syntax-number</code></td><td>code: numbers, constants and escapes</td></tr> | |
| 557 | <tr><td><code class="verbatim">syntax-property</code></td><td>code: properties, attributes and tags</td></tr> | |
| 558 | <tr><td><code class="verbatim">syntax-label</code></td><td>code: labels</td></tr> | |
| 559 | <tr><td><code class="verbatim">sidebar-background</code></td><td>the folder sidebar and the outline</td></tr> | |
| 560 | <tr><td><code class="verbatim">sidebar-foreground</code></td><td>file and heading names there</td></tr> | |
| 561 | <tr><td><code class="verbatim">sidebar-header</code></td><td>folder names there</td></tr> | |
| 562 | <tr><td><code class="verbatim">modeline-background</code></td><td>the modeline and message line</td></tr> | |
| 563 | <tr><td><code class="verbatim">modeline-foreground</code></td><td>modeline text</td></tr> | |
| 564 | <tr><td><code class="verbatim">modeline-highlight</code></td><td>the outline path and the clock in the modeline</td></tr> | |
| 565 | <tr><td><code class="verbatim">state-normal</code></td><td>the NORMAL tag (Doom keys)</td></tr> | |
| 566 | <tr><td><code class="verbatim">state-insert</code></td><td>the INSERT tag</td></tr> | |
| 567 | <tr><td><code class="verbatim">state-visual</code></td><td>the VISUAL and V-LINE tags</td></tr> | |
| 568 | <tr><td><code class="verbatim">agenda-background</code></td><td>the agenda and board</td></tr> | |
| 569 | <tr><td><code class="verbatim">agenda-date</code></td><td>agenda day headers</td></tr> | |
| 570 | <tr><td><code class="verbatim">agenda-today</code></td><td>today's header and the current time</td></tr> | |
| 571 | <tr><td><code class="verbatim">agenda-time</code></td><td>times and the time grid</td></tr> | |
| 572 | <tr><td><code class="verbatim">agenda-category</code></td><td>categories</td></tr> | |
| 573 | <tr><td><code class="verbatim">agenda-deadline</code></td><td>deadlines due</td></tr> | |
| 574 | <tr><td><code class="verbatim">agenda-upcoming</code></td><td>deadlines coming up</td></tr> | |
| 575 | <tr><td><code class="verbatim">agenda-scheduled</code></td><td>scheduled items</td></tr> | |
| 576 | <tr><td><code class="verbatim">agenda-scheduled-past</code></td><td>items scheduled on an earlier day</td></tr> | |
| 577 | <tr><td><code class="verbatim">habit-clear</code></td><td>habit graph: not due yet</td></tr> | |
| 578 | <tr><td><code class="verbatim">habit-ready</code></td><td>habit graph: due</td></tr> | |
| 579 | <tr><td><code class="verbatim">habit-alert</code></td><td>habit graph: due today, last chance</td></tr> | |
| 580 | <tr><td><code class="verbatim">habit-overdue</code></td><td>habit graph: overdue</td></tr> | |
| 581 | </tbody> | |
| 582 | </table> | |
| 583 | <p>The default theme leaves <code class="verbatim">sidebar-background</code>, <code class="verbatim">sidebar-foreground</code>, <code class="verbatim">sidebar-header</code>, <code class="verbatim">modeline-background</code>, <code class="verbatim">modeline-foreground</code> and <code class="verbatim">agenda-background</code> unset, so those parts keep the standard macOS look. Set them to color those parts too. In the views around the editor (sidebar, modeline, agenda), a color you set for one appearance only leaves the other appearance to the system. In the editor, a color set for one appearance only takes the default theme's color in the other.</p> | |
| 584 | <p>An unknown color key, a value that isn't a color, or an unknown table such as <code class="verbatim">[theme.solarized]</code> is reported as a problem and skipped.</p> | |
| 585 | <h2 id="appearance">Appearance</h2> | |
| 586 | <p>Orgstar follows the system's light or dark appearance (System Settings ▸ Appearance). There is no setting to fix one appearance; to use the same colors in both, set them under <code class="verbatim">[theme]</code> rather than <code class="verbatim">[theme.light]</code> or <code class="verbatim">[theme.dark]</code>.</p> | |
| 587 | <h2 id="fonts">Fonts</h2> | |
| 588 | <p>The editor uses one font for everything: body text, headings, code and tables. Choose it in Settings ▸ Appearance or with <code class="verbatim">font</code> under <code class="verbatim">[theme]</code>.</p> | |
| 589 | <ul> | |
| 590 | <li>The Font menu lists installed monospaced families. <code class="verbatim">config.toml</code> accepts any family name; a family that isn't installed falls back to the system's monospaced font. Tags and tables line up in columns, so a proportional font misaligns them.</li> | |
| 591 | <li><code class="verbatim">font-size</code> is the body size, at least 6 points.</li> | |
| 592 | <li>Headings are bold. Level 1 is <code class="verbatim">font-size</code> plus three times <code class="verbatim">heading-size-step</code>, level 2 plus two times, level 3 plus one time; level 4 and deeper are body size. Set <code class="verbatim">heading-size-step = 0</code> for one size throughout.</li> | |
| 593 | <li><code class="verbatim">line-spacing</code> adds space between lines, in points.</li> | |
| 594 | </ul> | |
| 595 | <p>On iPhone and iPad, the editor and reader use the same theme, read from the synced configuration folder. <code class="verbatim">font</code> applies when the family is installed on the device, otherwise the system's monospaced font is used, and <code class="verbatim">font-size</code> is the size at the default Dynamic Type setting, scaled with the size chosen on the device. The <code class="verbatim">selection</code> color, the <code class="verbatim">cursor</code> color and the <code class="verbatim">syntax-*</code> colors apply there too. See <a href="14-ios.html">iPhone and iPad</a>.</p> | |
| 596 | </main> | |
| 597 | <footer class="site"> | |
| 598 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 599 | </footer> | |
| 600 | </body> | |
| 601 | </html> | |
| \ No newline at end of file | ||
guide/14-ios.html added +327
| @@ -0,0 +1,327 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>iPhone and iPad · Orgstar</title> | |
| 7 | <meta name="description" content="The iOS app: folders, reading and editing, search, the agenda, capture, clocking, reminders, export and settings."> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>iPhone and iPad</h1> | |
| 24 | <p class="lede">Orgstar for iPhone and iPad reads and edits the same org files as the Mac, with the agenda, capture and search.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#overview">Overview</a></li> | |
| 29 | <li><a href="#folders-and-file-access">Folders and file access</a></li> | |
| 30 | <li><a href="#the-reader">The reader</a></li> | |
| 31 | <li><a href="#the-editor">The editor</a> | |
| 32 | <ul> | |
| 33 | <li><a href="#saving">Saving</a></li> | |
| 34 | <li><a href="#themes-and-display">Themes and display</a></li> | |
| 35 | <li><a href="#the-key-bar">The key bar</a></li> | |
| 36 | <li><a href="#commands">Commands</a></li> | |
| 37 | <li><a href="#hardware-keyboard">Hardware keyboard</a></li> | |
| 38 | </ul></li> | |
| 39 | <li><a href="#search">Search</a></li> | |
| 40 | <li><a href="#the-agenda">The agenda</a></li> | |
| 41 | <li><a href="#capture">Capture</a> | |
| 42 | <ul> | |
| 43 | <li><a href="#from-the-share-sheet">From the share sheet</a></li> | |
| 44 | <li><a href="#from-shortcuts">From Shortcuts</a></li> | |
| 45 | </ul></li> | |
| 46 | <li><a href="#clocking">Clocking</a></li> | |
| 47 | <li><a href="#reminders">Reminders</a></li> | |
| 48 | <li><a href="#export">Export</a></li> | |
| 49 | <li><a href="#code-blocks-and-tables">Code blocks and tables</a></li> | |
| 50 | <li><a href="#conflicts-and-versions">Conflicts and versions</a></li> | |
| 51 | <li><a href="#settings">Settings</a></li> | |
| 52 | <li><a href="#spotlight-and-quick-look">Spotlight and Quick Look</a></li> | |
| 53 | <li><a href="#what-the-mac-has-that-ios-doesn-t">What the Mac has that iOS doesn't</a></li> | |
| 54 | </ul> | |
| 55 | </nav> | |
| 56 | <h2 id="overview">Overview</h2> | |
| 57 | <p>The app has four tabs:</p> | |
| 58 | <dl> | |
| 59 | <dt>Agenda</dt> | |
| 60 | <dd>the agenda over your folders, with capture.</dd> | |
| 61 | <dt>Folders</dt> | |
| 62 | <dd>the folders of org files you added, and their files.</dd> | |
| 63 | <dt>Settings</dt> | |
| 64 | <dd>where the app's settings come from.</dd> | |
| 65 | <dt>Search</dt> | |
| 66 | <dd>file names and the words of headings.</dd> | |
| 67 | </dl> | |
| 68 | <p>Files open in a reader first. The Edit button in the reader opens the editor. Both use the same open file, so an edit in the editor shows in the reader when you go back.</p> | |
| 69 | <h2 id="folders-and-file-access">Folders and file access</h2> | |
| 70 | <p>Orgstar on iOS works on folders you choose, in iCloud Drive or in another app's storage (for example a folder kept by a Syncthing client).</p> | |
| 71 | <ol> | |
| 72 | <li>Open the Folders tab and tap Add Folder (the folder icon with a plus).</li> | |
| 73 | <li>Choose a folder in the picker.</li> | |
| 74 | </ol> | |
| 75 | <p>Orgstar keeps access to the folder across launches. Each folder appears as a section listing its <code class="verbatim">.org</code> files by their path inside the folder. Remove Folder at the end of a section removes it from Orgstar; the files stay where they are.</p> | |
| 76 | <p>Files that iCloud hasn't downloaded to the device yet appear in grey with a cloud icon. Orgstar asks iCloud to download them and lists them as files once they arrive.</p> | |
| 77 | <p>Orgstar sees changes made by iCloud and by apps that use the system's file coordination, and reads every folder again each time you return to the app, since not every sync app reports its changes. An open file takes in changes from disk as described in <a href="15-alongside-emacs.html">Working alongside Emacs and other tools</a>.</p> | |
| 78 | <p>There is no way to open a single file from the Files app. Add the folder that contains it.</p> | |
| 79 | <h2 id="the-reader">The reader</h2> | |
| 80 | <p>Tap a file in Folders, Search or the agenda to read it.</p> | |
| 81 | <ul> | |
| 82 | <li>Tap a heading to fold or unfold it, as <code class="verbatim">TAB</code> cycles it on the Mac. A chevron marks headings with content.</li> | |
| 83 | <li>The file opens with the visibility its <code class="verbatim">#+STARTUP</code> line asks for, then each heading's <code class="verbatim">VISIBILITY</code> property when <code class="verbatim">#+STARTUP</code> sets a visibility. Drawers and blocks are folded as <code class="verbatim">org-cycle-hide-drawer-startup</code> and <code class="verbatim">org-cycle-hide-block-startup</code> say, or as the file's <code class="verbatim">#+STARTUP</code> says (<code class="verbatim">hidedrawers</code>, <code class="verbatim">nohideblocks</code> and the like).</li> | |
| 84 | <li>Text is styled as in the editor, in the theme's colours, font, size, line spacing and heading sizes, on the theme's background: TODO keywords, priorities, tags, emphasis, code, timestamps, links, and the code in src blocks. Text can be selected and copied.</li> | |
| 85 | <li>The reader follows the editor's display settings (see Themes and display below): Show Markup, hidden emphasis markers, pretty entities, indentation, leading stars, inline images and truncated lines. Tables show at full width, without narrowed columns.</li> | |
| 86 | <li>Tap a link to follow it. Links to headings and files in your folders open in the reader; web links open in the browser.</li> | |
| 87 | <li>The toolbar has Outline (a list of headings to jump to), Export, and Edit.</li> | |
| 88 | </ul> | |
| 89 | <h2 id="the-editor">The editor</h2> | |
| 90 | <p>Tap Edit in the reader. The title shows the buffer name, with <code class="verbatim">•</code> while there are unsaved changes. The tab bar is hidden while you edit.</p> | |
| 91 | <p>The editor folds headings, drawers and blocks, styles text with the theme from the configuration folder (see Themes and display below), and runs the same Org commands as the Mac. Autocorrection, smart quotes and smart dashes are off; spell checking follows <code class="verbatim">spell-check</code> in <code class="verbatim">config.toml</code> and is off by default.</p> | |
| 92 | <p>The toolbar has:</p> | |
| 93 | <dl> | |
| 94 | <dt>Conflict</dt> | |
| 95 | <dd>shown while the file and your edits conflict; opens the conflict sheet.</dd> | |
| 96 | <dt></dt> | |
| 97 | <dd>Undo</dd> | |
| 98 | <dt>More</dt> | |
| 99 | <dd>Commands, Clock In, Show Markup, Recent Entries, Export, Sync Conflict Copies, and Recovered Versions.</dd> | |
| 100 | </dl> | |
| 101 | <p>Messages from commands show at the top of the editor for a few seconds; tap one to dismiss it.</p> | |
| 102 | <h3 id="saving">Saving</h3> | |
| 103 | <p>The iOS app always saves automatically: one second after you stop typing, when you leave the editor, and when the app goes to the background. The <code class="verbatim">save</code> setting doesn't apply on iOS.</p> | |
| 104 | <p>Files that aren't valid UTF-8 open read-only; commands that would change them say so.</p> | |
| 105 | <h3 id="themes-and-display">Themes and display</h3> | |
| 106 | <p>The editor and the reader use the theme set in the configuration folder's <code class="verbatim">config.toml</code>, stacked as on the Mac: the default theme, then the theme file named by <code class="verbatim">theme-file</code>, then the colours in <code class="verbatim">[theme]</code>, <code class="verbatim">[theme.light]</code>, <code class="verbatim">[theme.dark]</code> and <code class="verbatim">[theme.todo]</code>. Colours follow the system's light or dark appearance. Problems in the theme show in the Settings tab with the other problems. A change to <code class="verbatim">config.toml</code> or the theme file applies as it syncs, to open editors too. See <a href="13-configuration.html">Configuration</a> for the colour keys.</p> | |
| 107 | <dl> | |
| 108 | <dt>Font</dt> | |
| 109 | <dd><code class="verbatim">font</code> when that family is installed on the device, otherwise the system's monospaced font.</dd> | |
| 110 | <dt>Size</dt> | |
| 111 | <dd><code class="verbatim">font-size</code> is the size at the default Dynamic Type setting, 13 pt by default. Text grows and shrinks with the text size chosen in the system Settings app.</dd> | |
| 112 | <dt>Line spacing and headings</dt> | |
| 113 | <dd><code class="verbatim">line-spacing</code> and <code class="verbatim">heading-size-step</code> apply as on the Mac.</dd> | |
| 114 | <dt>Caret and selection</dt> | |
| 115 | <dd>the selection highlight takes the theme's <code class="verbatim">selection</code> colour, over block bands too; the caret and the selection handles take <code class="verbatim">cursor</code>.</dd> | |
| 116 | </dl> | |
| 117 | <p>The editor and the reader apply these display settings; only the editor aligns tables when a file opens. The startup settings (<code class="verbatim">org-cycle-hide-*-startup</code>, <code class="verbatim">org-startup-*</code>, <code class="verbatim">org-hide-leading-stars</code>) apply when a file opens, and a <code class="verbatim">#+STARTUP</code> keyword in the file overrides them, as on the Mac.</p> | |
| 118 | <table> | |
| 119 | <thead> | |
| 120 | <tr><th>Setting</th><th>In the iOS editor</th><th><code class="verbatim">#+STARTUP</code></th></tr> | |
| 121 | </thead> | |
| 122 | <tbody> | |
| 123 | <tr><td><code class="verbatim">show-markup</code></td><td>Link brackets and targets, and emphasis markers, show</td><td></td></tr> | |
| 124 | <tr><td><code class="verbatim">org-hide-emphasis-markers</code></td><td>Emphasis markers hide while markup is hidden</td><td></td></tr> | |
| 125 | <tr><td><code class="verbatim">org-pretty-entities</code></td><td>Entities and sub- and superscripts show as characters while markup is hidden</td><td></td></tr> | |
| 126 | <tr><td><code class="verbatim">org-cycle-hide-drawer-startup</code></td><td>Drawers start folded</td><td><code class="verbatim">hidedrawers</code>, <code class="verbatim">nohidedrawers</code></td></tr> | |
| 127 | <tr><td><code class="verbatim">org-cycle-hide-block-startup</code></td><td>Blocks start folded</td><td><code class="verbatim">hideblocks</code>, <code class="verbatim">nohideblocks</code></td></tr> | |
| 128 | <tr><td><code class="verbatim">org-startup-indented</code></td><td>Bodies are indented under their headings</td><td><code class="verbatim">indent</code>, <code class="verbatim">noindent</code></td></tr> | |
| 129 | <tr><td><code class="verbatim">org-hide-leading-stars</code></td><td>Without indentation, only a heading's last star shows</td><td><code class="verbatim">hidestars</code>, <code class="verbatim">showstars</code></td></tr> | |
| 130 | <tr><td><code class="verbatim">org-startup-with-inline-images</code></td><td>Image links show as images</td><td><code class="verbatim">inlineimages</code>, <code class="verbatim">noinlineimages</code></td></tr> | |
| 131 | <tr><td><code class="verbatim">org-startup-align-all-tables</code></td><td>Every table is aligned</td><td><code class="verbatim">align</code>, <code class="verbatim">noalign</code></td></tr> | |
| 132 | <tr><td><code class="verbatim">org-startup-truncated</code></td><td>Long lines run off the right edge, and the editor scrolls sideways</td><td></td></tr> | |
| 133 | </tbody> | |
| 134 | </table> | |
| 135 | <p>While markup is hidden, the line with the caret shows its markup, so you can edit it. More ▸ Show Markup, or Show or Hide Markup in Commands, switches markup in every editor and in the reader. The switch lasts until <code class="verbatim">show-markup</code> in <code class="verbatim">config.toml</code> changes; then the file's value applies.</p> | |
| 136 | <p>The visibility from <code class="verbatim">#+STARTUP</code> applies first, then each heading's <code class="verbatim">VISIBILITY</code> property. As on the Mac, <code class="verbatim">VISIBILITY</code> properties apply only when <code class="verbatim">#+STARTUP</code> sets a visibility (<code class="verbatim">overview</code>, <code class="verbatim">content</code>, <code class="verbatim">showall</code> and the like).</p> | |
| 137 | <p>An image line shows its image, and the link text is hidden except on the caret's line. <code class="verbatim">#+ATTR_ORG: :width N</code> sets the width in points; images are never wider than the editor. Show or Hide Inline Images in Commands, or <code class="verbatim">C-c C-x C-v</code> on a hardware keyboard, switches images in the open file. Truncate or Wrap Long Lines in Commands, or <code class="verbatim">C-x x t</code>, switches long lines. See <a href="02-the-editor.html">The editor</a> for which lines show as images.</p> | |
| 138 | <p>Code in src blocks is highlighted in the theme's <code class="verbatim">syntax-*</code> colours, as on the Mac (see <a href="11-code-blocks.html">Code blocks</a>).</p> | |
| 139 | <p>Table columns with width cookies narrow as on the Mac: <code class="verbatim">#+STARTUP: shrink</code> narrows them when the file opens, and Shrink or Expand Table Column (<code class="verbatim">C-c TAB</code>), Shrink Table Columns with Widths and Expand Table Columns are in Commands when the caret is in a table. See <a href="10-tables.html">Tables</a>.</p> | |
| 140 | <h3 id="the-key-bar">The key bar</h3> | |
| 141 | <p>A bar above the on-screen keyboard has buttons for Org's keys. Each does what its Emacs key does at the caret, so the arrows promote and demote headings, indent list items, or move table columns, depending on where the caret is. Scroll the bar sideways for more.</p> | |
| 142 | <table> | |
| 143 | <thead> | |
| 144 | <tr><th>Button</th><th>Key</th></tr> | |
| 145 | </thead> | |
| 146 | <tbody> | |
| 147 | <tr><td>Commands</td><td>the command list</td></tr> | |
| 148 | <tr><td>Fold</td><td><code class="verbatim">TAB</code></td></tr> | |
| 149 | <tr><td>Overview</td><td><code class="verbatim">S-TAB</code></td></tr> | |
| 150 | <tr><td>Promote</td><td><code class="verbatim">M-<left></code></td></tr> | |
| 151 | <tr><td>Demote</td><td><code class="verbatim">M-<right></code></td></tr> | |
| 152 | <tr><td>Move up</td><td><code class="verbatim">M-<up></code></td></tr> | |
| 153 | <tr><td>Move down</td><td><code class="verbatim">M-<down></code></td></tr> | |
| 154 | <tr><td>New heading or item</td><td><code class="verbatim">M-RET</code></td></tr> | |
| 155 | <tr><td>TODO</td><td><code class="verbatim">C-c C-t</code></td></tr> | |
| 156 | <tr><td>Act at point</td><td><code class="verbatim">C-c C-c</code></td></tr> | |
| 157 | <tr><td>Schedule</td><td><code class="verbatim">C-c C-s</code></td></tr> | |
| 158 | <tr><td>Deadline</td><td><code class="verbatim">C-c C-d</code></td></tr> | |
| 159 | <tr><td>Tags</td><td><code class="verbatim">C-c C-q</code></td></tr> | |
| 160 | <tr><td>Open link</td><td><code class="verbatim">C-c C-o</code></td></tr> | |
| 161 | <tr><td>Hide keyboard</td><td></td></tr> | |
| 162 | </tbody> | |
| 163 | </table> | |
| 164 | <h3 id="commands">Commands</h3> | |
| 165 | <p>Commands (in the key bar or More) lists every command that applies at the caret, with its Emacs key. Type to narrow the list. The command runs once the list closes.</p> | |
| 166 | <p>When a command asks a question, a sheet opens:</p> | |
| 167 | <ul> | |
| 168 | <li>Text questions have a field, and a list of choices that narrows as you type. For tags, choosing a tag adds it to what you typed.</li> | |
| 169 | <li>Date questions have a calendar as well as the field; Org's date syntax (<code class="verbatim">+2d</code>, <code class="verbatim">fri</code>, <code class="verbatim">14:00</code>) works in the field.</li> | |
| 170 | <li>Fast selection (TODO keywords and tags with keys) lists each option with its key. For tags, tap several and then Done; inherited tags are listed below.</li> | |
| 171 | </ul> | |
| 172 | <p>Cancel answers nothing, as <code class="verbatim">C-g</code> does.</p> | |
| 173 | <p><code class="verbatim">C-c '</code> on a block, and <code class="verbatim">C-c `</code> on a table field, open the text in a sheet of its own; Save puts it back.</p> | |
| 174 | <h3 id="hardware-keyboard">Hardware keyboard</h3> | |
| 175 | <p>With a hardware keyboard, the editor uses the Emacs keymap, whatever <code class="verbatim">keymap</code> is set to on the Mac. <code class="verbatim">keymap.toml</code> isn't read on iOS.</p> | |
| 176 | <ul> | |
| 177 | <li>Option works as Meta when it begins a binding (<code class="verbatim">M-RET</code>, <code class="verbatim">M-<left></code>). Otherwise Option types characters as usual.</li> | |
| 178 | <li>Command shortcuts are the system's.</li> | |
| 179 | <li>Keys the keymap leaves to the text system stay with iOS. These include the editing keys <code class="verbatim">C-a</code>, <code class="verbatim">C-e</code>, <code class="verbatim">C-k</code> and similar, which iOS handles itself.</li> | |
| 180 | <li>After a prefix such as <code class="verbatim">C-c</code>, the message line shows <code class="verbatim">C-c-</code> while it waits for the next key. An unbound sequence shows <code class="verbatim">… is undefined</code>.</li> | |
| 181 | <li>A sequence bound to a command that can't run at the caret, or that the iOS app doesn't have, shows why, as on the Mac: the command's own message (such as <code class="verbatim">Not on a heading</code>), or <code class="verbatim">Not available on iOS yet</code>.</li> | |
| 182 | </ul> | |
| 183 | <p>See <a href="03-keys.html">Keys and commands</a> for the Emacs bindings.</p> | |
| 184 | <h2 id="search">Search</h2> | |
| 185 | <p>The Search tab finds:</p> | |
| 186 | <dl> | |
| 187 | <dt>Files</dt> | |
| 188 | <dd>up to eight org files whose path matches what you type, ranked as Quick Open ranks them on the Mac.</dd> | |
| 189 | <dt>Headings</dt> | |
| 190 | <dd>headings whose title or text contains your words, including unsaved edits in the open file.</dd> | |
| 191 | </dl> | |
| 192 | <p>Tap a result to open it in the reader. A heading result opens at that heading.</p> | |
| 193 | <h2 id="the-agenda">The agenda</h2> | |
| 194 | <p>The Agenda tab shows the agenda over all your folders, with the span and start day from the settings (10 days from 3 days ago by default). Pull down to refresh it.</p> | |
| 195 | <dl> | |
| 196 | <dt>Views (the calendar icon)</dt> | |
| 197 | <dd>the built-in views and those in <code class="verbatim">views.toml</code>, Tags and Properties… (a match such as <code class="verbatim">+work-home</code> or <code class="verbatim">TODO</code>"WAIT"=), and in the day view, Today, Earlier and Later.</dd> | |
| 198 | <dt>Filter</dt> | |
| 199 | <dd>keep or leave out tags and categories of the entries shown, or type a filter as Org's <code class="verbatim">/</code> takes it: <code class="verbatim">+keep</code> and <code class="verbatim">-drop</code> tags or categories, <code class="verbatim"><0:30</code> for effort, <code class="verbatim">/regexp/</code>. The status line shows the filter in use.</dd> | |
| 200 | <dt></dt> | |
| 201 | <dd>Tap an entry to read it, at its heading.</dd> | |
| 202 | <dt></dt> | |
| 203 | <dd>Swipe a TODO entry to the left to mark it done with the first done keyword of its sequence, as the file defines its keywords (with the default keywords, its <code class="verbatim">#+TODO</code> lines and its setup files).</dd> | |
| 204 | <dt></dt> | |
| 205 | <dd>Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile…, and Archive….</dd> | |
| 206 | </dl> | |
| 207 | <p>Commands from the agenda change the file directly when it isn't open, and through the editor when it is. If the heading changed since the agenda was built, nothing runs.</p> | |
| 208 | <p>See <a href="07-agenda.html">The agenda</a> for the views and matches.</p> | |
| 209 | <h2 id="capture">Capture</h2> | |
| 210 | <p>Tap Capture (the pencil icon) in the Agenda or Folders tab.</p> | |
| 211 | <ol> | |
| 212 | <li>Choose a template. The first template is selected.</li> | |
| 213 | <li>Answer the template's questions (<code class="verbatim">%^{…}</code>, <code class="verbatim">%^g</code>, <code class="verbatim">%^t</code> and the like), then tap Continue. A template without questions skips this step.</li> | |
| 214 | <li>Edit the text. The caret is where <code class="verbatim">%?</code> was.</li> | |
| 215 | <li>Tap File.</li> | |
| 216 | </ol> | |
| 217 | <p>Templates come from <code class="verbatim">capture.toml</code> in the configuration folder (see Settings below). Without one, the two default templates apply. A template with <code class="verbatim">immediate-finish</code> files as soon as its questions are answered, and one with <code class="verbatim">jump-to-captured</code> opens the captured entry. <code class="verbatim">%^g</code> offers the target file's tags as choices.</p> | |
| 218 | <p><code class="verbatim">org-protocol://capture</code> links opened on the device open the capture sheet with the link's template, URL, title and text. When the link names a template key that <code class="verbatim">capture.toml</code> doesn't have, the sheet starts on the first template and shows <code class="verbatim">No capture template "x"</code> with the key.</p> | |
| 219 | <h3 id="from-the-share-sheet">From the share sheet</h3> | |
| 220 | <p>Orgstar appears in the share sheet of other apps for a web link or text.</p> | |
| 221 | <ol> | |
| 222 | <li>Share a page or text and choose Orgstar.</li> | |
| 223 | <li>Choose a template, edit the link's title, and add text.</li> | |
| 224 | <li>Tap Capture.</li> | |
| 225 | </ol> | |
| 226 | <p>The share extension doesn't file the entry itself. It leaves it for the app, which opens its capture sheet with the link and text the next time it becomes active. Several shared items open one after another. If the extension shows "Orgstar's shared folder isn't available", the app and its extension can't share data, and Capture is disabled.</p> | |
| 227 | <h3 id="from-shortcuts">From Shortcuts</h3> | |
| 228 | <p>Shortcuts has a Capture to Orgstar action, and Siri responds to "Capture to Orgstar". The action takes:</p> | |
| 229 | <dl> | |
| 230 | <dt>Text</dt> | |
| 231 | <dd>the text to capture, available to the template as <code class="verbatim">%i</code>.</dd> | |
| 232 | <dt>Template Key</dt> | |
| 233 | <dd>a key from <code class="verbatim">capture.toml</code>; empty uses the first template.</dd> | |
| 234 | </dl> | |
| 235 | <p>The action files the entry without showing the capture sheet, and saves the file at once. Questions in the template take their default answers, and <code class="verbatim">%c</code> (the clipboard) is empty, because reading the clipboard would ask for permission on every run. The action returns "Captured with" and the template's name.</p> | |
| 236 | <p>See <a href="08-capture.html">Capture</a> for the template format.</p> | |
| 237 | <h2 id="clocking">Clocking</h2> | |
| 238 | <p>Clock in from the editor (More ▸ Clock In, or Clock In in Commands) or from an agenda entry's menu. While a clock runs, a bar above the tab bar shows the entry and the time so far as <code class="verbatim">H:MM</code>, updated every 30 seconds. Tap the bar for:</p> | |
| 239 | <ul> | |
| 240 | <li>Clock Out</li> | |
| 241 | <li>Cancel Clock</li> | |
| 242 | <li>Go to Clocked Entry</li> | |
| 243 | <li>Recent Entries</li> | |
| 244 | <li>Clock Report</li> | |
| 245 | </ul> | |
| 246 | <p>Recent Entries, in the bar and in the editor's More menu, lists the recently clocked entries; tap one to clock in to it. It also has Clock In to Recent Entry… and Go to Recent Clocked Entry…, and is disabled until you have clocked in once. Commands has Clock In to Recent Entry…, Clock In to Last Entry, Go to Recent Clocked Entry…, Mark as Default Clock Task and Resolve Open Clocks….</p> | |
| 247 | <p>Clock questions open in a sheet: the task selection and the resolution keys as lists to tap, and minutes or a date and time as a field. Cancel answers nothing, as <code class="verbatim">q</code> does. Clocking in with no clock running first asks about open clocks in your folders, from the editor, an agenda entry's Clock In or a capture template with <code class="verbatim">clock-in</code>; Resolve Open Clocks… asks about every open clock. Both work as on the Mac.</p> | |
| 248 | <p>The iOS app has no idle detection, so <code class="verbatim">org-clock-idle-time</code> doesn't apply. <code class="verbatim">org-clock-history-length</code> does.</p> | |
| 249 | <p>Clock Report shows the time per day and heading for the files you choose. It starts with the files that contain clock lines. Turn on Limit dates to choose a range. The share button sends the report as text.</p> | |
| 250 | <p>See <a href="06-dates-and-clocking.html">Dates and clocking</a>.</p> | |
| 251 | <h2 id="reminders">Reminders</h2> | |
| 252 | <p>With <code class="verbatim">reminders</code> on, Orgstar schedules a notification before each timed agenda entry in the next week, <code class="verbatim">appt-message-warning-time</code> minutes ahead (or the entry's <code class="verbatim">APPT_WARNTIME</code>). Tap a notification to open its entry. Notifications show while the app is open too.</p> | |
| 253 | <p>iOS lets an app schedule at most 64 notifications, and Orgstar schedules more only while it runs. It updates them when files or settings change, when you return to the app, and every hour while it is open. The agenda's status line says how far ahead reminders are set ("Reminders are set through …"), or that notifications are off for Orgstar in the system Settings app.</p> | |
| 254 | <h2 id="export">Export</h2> | |
| 255 | <p>Export (in the reader's toolbar and the editor's More menu) offers HTML and Markdown. Either opens the share sheet with a file named after the org file, which you can send to another app or keep with Save to Files. The export reads the file's setup files and follows its export keywords, as the Mac's HTML and Markdown export does.</p> | |
| 256 | <p>PDF, ODT, LaTeX and plain-text export need Emacs and aren't available on iOS. See <a href="12-export.html">Export</a>.</p> | |
| 257 | <h2 id="code-blocks-and-tables">Code blocks and tables</h2> | |
| 258 | <p><code class="verbatim">C-c C-c</code> on a source block asks whether to run it (yes, no, or always for this block), as on the Mac.</p> | |
| 259 | <p>On iOS, only Emacs Lisp blocks run. Orgstar evaluates them with its own Emacs Lisp interpreter, which covers a subset of the language. Other results:</p> | |
| 260 | <ul> | |
| 261 | <li>A block in another language: "<em>language</em> blocks need the Mac to run."</li> | |
| 262 | <li>Emacs Lisp the interpreter doesn't have: "This block uses Emacs Lisp that runs only in Emacs, on the Mac."</li> | |
| 263 | </ul> | |
| 264 | <p>Table formulas that Orgstar computes itself work on iOS. A table whose formulas need Emacs reports "This table needs Emacs, which runs on the Mac", with the reason, and isn't changed.</p> | |
| 265 | <p>Tangling (<code class="verbatim">C-c C-v t</code>, in Commands) works on iOS and writes the tangled files next to the org file, or where <code class="verbatim">:tangle</code> says.</p> | |
| 266 | <p>See <a href="11-code-blocks.html">Code blocks</a> and <a href="10-tables.html">Tables</a>.</p> | |
| 267 | <h2 id="conflicts-and-versions">Conflicts and versions</h2> | |
| 268 | <p>When a file changes on disk while you have unsaved edits, Orgstar merges the change into your edits. When the changes overlap, the conflict sheet opens. It shows the difference (lines marked - are on disk, + in your version) and offers:</p> | |
| 269 | <dl> | |
| 270 | <dt>Keep Mine</dt> | |
| 271 | <dd>write your version over the disk version.</dd> | |
| 272 | <dt>Use Disk Version</dt> | |
| 273 | <dd>replace your edits with the disk version.</dd> | |
| 274 | <dt>Merge with Markers</dt> | |
| 275 | <dd>put both versions in the editor, with conflicting lines between <code class="verbatim"><<<<<<<</code> and <code class="verbatim">>>>>>>></code> markers, to fix and save.</dd> | |
| 276 | <dt>Later</dt> | |
| 277 | <dd>decide later. The Conflict button in the toolbar opens the sheet again. Nothing is saved until you decide.</dd> | |
| 278 | </dl> | |
| 279 | <p>The version you don't keep goes to the recovery folder.</p> | |
| 280 | <p>More ▸ Sync Conflict Copies lists Syncthing's conflict copies of the file (<code class="verbatim">name.sync-conflict-…</code>), each compared with the file, with Keep File, Merge and Use Copy. The copy goes to the recovery folder and is removed. When a file with conflict copies opens in the editor, a message says how many there are.</p> | |
| 281 | <p>More ▸ Recovered Versions lists the versions of the file kept in the recovery folder, newest first, each compared with the editor's text. Restore puts a version's text in the editor as an edit you can undo.</p> | |
| 282 | <p>See <a href="15-alongside-emacs.html">Working alongside Emacs and other tools</a> for how merging and recovery work.</p> | |
| 283 | <h2 id="settings">Settings</h2> | |
| 284 | <p>The iOS app has no settings of its own. It reads them from a configuration folder: a folder holding <code class="verbatim">config.toml</code> and <code class="verbatim">capture.toml</code>, such as a copy of the Mac's <code class="verbatim">~/.config/orgstar</code> synced through iCloud Drive or another app.</p> | |
| 285 | <ol> | |
| 286 | <li>Open the Settings tab.</li> | |
| 287 | <li>Tap Choose Folder… and choose the folder.</li> | |
| 288 | </ol> | |
| 289 | <p>Changes to the files apply as they sync, and again each time you return to the app. Problems in the files show in red under the folder. "No config.toml in <em>folder</em>; the defaults apply" means the folder has no <code class="verbatim">config.toml</code>.</p> | |
| 290 | <p>Stop Using This Folder returns every setting to its default.</p> | |
| 291 | <p>The In use section shows the TODO keywords, the agenda span and start (for example <code class="verbatim">10 days, starting 3 days before today</code>), the reminder lead time, the capture template keys, the theme (<code class="verbatim">Default</code>, or the theme file's name), and the font with its size. When <code class="verbatim">font</code> names a family that isn't installed on the device, Font shows the system's font with a note, as <code class="verbatim">System monospaced, 13 pt (JetBrains Mono isn't installed)</code>.</p> | |
| 292 | <p>These settings from <code class="verbatim">config.toml</code> apply on iOS:</p> | |
| 293 | <ul> | |
| 294 | <li><code class="verbatim">org-todo-keywords</code>, <code class="verbatim">org-list-allow-alphabetical</code></li> | |
| 295 | <li><code class="verbatim">org-tags-column</code>, <code class="verbatim">org-insert-heading-respect-content</code>, <code class="verbatim">org-M-RET-may-split-line</code>, <code class="verbatim">fill-column</code></li> | |
| 296 | <li><code class="verbatim">org-hide-emphasis-markers</code> and <code class="verbatim">org-pretty-entities</code>, for what hidden markup shows and for how tag and table alignment and filling measure text, as on the Mac</li> | |
| 297 | <li><code class="verbatim">show-markup</code>, <code class="verbatim">org-startup-indented</code>, <code class="verbatim">org-hide-leading-stars</code>, <code class="verbatim">org-startup-with-inline-images</code>, <code class="verbatim">org-startup-align-all-tables</code>, <code class="verbatim">org-startup-truncated</code>, <code class="verbatim">org-cycle-hide-drawer-startup</code>, <code class="verbatim">org-cycle-hide-block-startup</code></li> | |
| 298 | <li><code class="verbatim">[theme]</code> (<code class="verbatim">font</code>, <code class="verbatim">font-size</code>, <code class="verbatim">line-spacing</code>, <code class="verbatim">heading-size-step</code>, <code class="verbatim">theme-file</code> and colours), <code class="verbatim">[theme.light]</code>, <code class="verbatim">[theme.dark]</code>, <code class="verbatim">[theme.todo]</code></li> | |
| 299 | <li><code class="verbatim">org-log-done</code>, <code class="verbatim">org-log-reschedule</code>, <code class="verbatim">org-log-redeadline</code>, <code class="verbatim">org-log-into-drawer</code></li> | |
| 300 | <li><code class="verbatim">org-use-speed-commands</code>, with a hardware keyboard</li> | |
| 301 | <li><code class="verbatim">electric-pair-mode</code>, <code class="verbatim">spell-check</code></li> | |
| 302 | <li><code class="verbatim">org-agenda-span</code>, <code class="verbatim">org-agenda-start-day</code>, <code class="verbatim">agenda-include-subfolders</code></li> | |
| 303 | <li><code class="verbatim">reminders</code>, <code class="verbatim">appt-message-warning-time</code></li> | |
| 304 | <li><code class="verbatim">org-clock-history-length</code></li> | |
| 305 | </ul> | |
| 306 | <p><code class="verbatim">capture.toml</code> and <code class="verbatim">views.toml</code> in the folder apply too. Other settings, including <code class="verbatim">keymap</code>, <code class="verbatim">save</code> and <code class="verbatim">org-clock-idle-time</code>, don't apply on iOS. See <a href="13-configuration.html">Configuration</a>.</p> | |
| 307 | <h2 id="spotlight-and-quick-look">Spotlight and Quick Look</h2> | |
| 308 | <p>Orgstar adds the org files in your folders to Spotlight with their title (<code class="verbatim">#+TITLE</code>, else the file name), author, description, tags, headings and text. A file is indexed again when it changes. Tap a Spotlight result to open the file in Orgstar's reader.</p> | |
| 309 | <p>Quick Look in the Files app shows org files as the HTML export renders them.</p> | |
| 310 | <h2 id="what-the-mac-has-that-ios-doesn-t">What the Mac has that iOS doesn't</h2> | |
| 311 | <ul> | |
| 312 | <li>Running code blocks in languages other than Emacs Lisp, Emacs Lisp beyond Orgstar's interpreter, and tables that need Emacs.</li> | |
| 313 | <li>PDF, ODT, LaTeX and plain-text export.</li> | |
| 314 | <li>The Mac and Doom keymaps, Vim keys, and <code class="verbatim">keymap.toml</code>.</li> | |
| 315 | <li>Idle detection while a clock runs.</li> | |
| 316 | <li>Import from Emacs.</li> | |
| 317 | <li>The board, column view, the backlinks pane, and the buffer list and tab bar.</li> | |
| 318 | <li>The global capture hotkey and the Settings window.</li> | |
| 319 | <li>Explicit saving.</li> | |
| 320 | </ul> | |
| 321 | <p>Commands the iOS app can't carry out show a message instead, such as "Not available on iOS yet" or "<em>Command</em> isn't available on iPhone and iPad." Only tables that need Emacs say that Emacs is needed. Commands that only appear on the Mac, such as Refile from the editor, aren't listed in Commands; refile and archive from the agenda instead.</p> | |
| 322 | </main> | |
| 323 | <footer class="site"> | |
| 324 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 325 | </footer> | |
| 326 | </body> | |
| 327 | </html> | |
| \ No newline at end of file | ||
guide/15-alongside-emacs.html added +271
| @@ -0,0 +1,271 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Working alongside Emacs and other tools · Orgstar</title> | |
| 7 | <meta name="description" content="How Orgstar reads and writes files shared with Emacs and sync tools, merges outside changes, keeps recovery versions, calls Emacs, and differs from…"> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Working alongside Emacs and other tools</h1> | |
| 24 | <p class="lede">Orgstar works on plain org files in ordinary folders, so Emacs, other apps and sync tools can work on the same files.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#how-orgstar-treats-files">How Orgstar treats files</a> | |
| 29 | <ul> | |
| 30 | <li><a href="#bytes-on-disk">Bytes on disk</a></li> | |
| 31 | <li><a href="#encodings">Encodings</a></li> | |
| 32 | <li><a href="#how-a-save-works">How a save works</a></li> | |
| 33 | <li><a href="#automatic-and-explicit-saving">Automatic and explicit saving</a></li> | |
| 34 | </ul></li> | |
| 35 | <li><a href="#changes-made-outside-orgstar">Changes made outside Orgstar</a> | |
| 36 | <ul> | |
| 37 | <li><a href="#the-conflict-sheet">The conflict sheet</a></li> | |
| 38 | </ul></li> | |
| 39 | <li><a href="#sync-tools">Sync tools</a> | |
| 40 | <ul> | |
| 41 | <li><a href="#icloud-drive">iCloud Drive</a></li> | |
| 42 | <li><a href="#syncthing">Syncthing</a></li> | |
| 43 | <li><a href="#dropbox-and-other-tools">Dropbox and other tools</a></li> | |
| 44 | <li><a href="#files-orgstar-ignores">Files Orgstar ignores</a></li> | |
| 45 | </ul></li> | |
| 46 | <li><a href="#recovery-versions">Recovery versions</a></li> | |
| 47 | <li><a href="#features-that-use-emacs-on-the-mac">Features that use Emacs on the Mac</a> | |
| 48 | <ul> | |
| 49 | <li><a href="#how-emacs-is-found">How Emacs is found</a></li> | |
| 50 | <li><a href="#what-emacs-sees">What Emacs sees</a></li> | |
| 51 | </ul></li> | |
| 52 | <li><a href="#quick-look">Quick Look</a></li> | |
| 53 | <li><a href="#spotlight">Spotlight</a></li> | |
| 54 | <li><a href="#finder">Finder</a></li> | |
| 55 | <li><a href="#org-protocol-and-shortcuts">org-protocol and Shortcuts</a></li> | |
| 56 | <li><a href="#compatibility-notes">Compatibility notes</a> | |
| 57 | <ul> | |
| 58 | <li><a href="#defaults-that-differ-from-emacs">Defaults that differ from Emacs</a></li> | |
| 59 | <li><a href="#known-differences-from-emacs-org">Known differences from Emacs Org</a></li> | |
| 60 | </ul></li> | |
| 61 | </ul> | |
| 62 | </nav> | |
| 63 | <h2 id="how-orgstar-treats-files">How Orgstar treats files</h2> | |
| 64 | <h3 id="bytes-on-disk">Bytes on disk</h3> | |
| 65 | <p>Orgstar edits the file's text directly; there is no separate document format. When it saves, text you didn't change is written back exactly as it was read:</p> | |
| 66 | <ul> | |
| 67 | <li>A file with no changes is never rewritten.</li> | |
| 68 | <li>Untouched lines keep their bytes, including trailing whitespace, tabs, and the presence or absence of a final newline.</li> | |
| 69 | <li>Line endings are kept as they are. A file with CRLF line endings keeps them, and on the Mac the modeline shows <code class="verbatim">CRLF</code> for such a file. Orgstar doesn't convert line endings; new lines that Orgstar's commands insert end with LF.</li> | |
| 70 | </ul> | |
| 71 | <h3 id="encodings">Encodings</h3> | |
| 72 | <p>Orgstar edits UTF-8 files, with or without a byte order mark. A file that starts with a BOM keeps it.</p> | |
| 73 | <p>A file that isn't valid UTF-8 (UTF-16, Latin-1, or a file with invalid bytes) opens read-only. The window's subtitle says "Read-only: not UTF-8", undecodable bytes show as replacement characters, and commands that would change the file report that it "isn't UTF-8, so it can't be changed". Orgstar never converts such a file.</p> | |
| 74 | <h3 id="how-a-save-works">How a save works</h3> | |
| 75 | <p>Saving replaces the file through a temporary file in the same folder (named <code class="verbatim">.name.org.orgstar-…</code>), under the system's file coordination, so iCloud and other coordinating apps see a complete file. The steps are:</p> | |
| 76 | <ol> | |
| 77 | <li>Read the file on disk. If it changed since Orgstar last read or wrote it, keep both versions in the recovery folder and merge the change into your edits (see below).</li> | |
| 78 | <li>Read the file again. If it changed in the meantime, start over, up to three times.</li> | |
| 79 | <li>Replace the file. If another program replaced it between the check and the write, its version goes to the recovery folder and is merged into your edits.</li> | |
| 80 | <li>Read the file back. If it changed right after the write, Orgstar's version goes to the recovery folder and the new disk version is merged in.</li> | |
| 81 | </ol> | |
| 82 | <p>Emacs and Syncthing don't use file coordination, so these checks can't lock them out. They narrow the window in which two writers can collide, and every version a save displaces is kept in the recovery folder.</p> | |
| 83 | <p>If the file keeps changing through all three attempts, the save fails with an error and your edits stay unsaved.</p> | |
| 84 | <h3 id="automatic-and-explicit-saving">Automatic and explicit saving</h3> | |
| 85 | <p>With <code class="verbatim">save = "automatic"</code> (the default), Orgstar saves a file one second after you stop typing. With <code class="verbatim">"explicit"</code>, only <code class="verbatim">⌘S</code> (Save) and <code class="verbatim">⌥⌘S</code> (Save All) save. See <a href="13-configuration.html">Configuration</a>. The iOS app always saves automatically.</p> | |
| 86 | <h2 id="changes-made-outside-orgstar">Changes made outside Orgstar</h2> | |
| 87 | <p>Orgstar watches your folders. On the Mac it uses FSEvents; on iOS it is told of changes by file coordination and reads the folders again when you return to the app. When a file that is open in Orgstar changes on disk:</p> | |
| 88 | <ul> | |
| 89 | <li>If you have no unsaved edits in it, Orgstar reloads it. Undo history for the file is cleared.</li> | |
| 90 | <li>If you have unsaved edits, Orgstar merges the disk version into them and saves the result.</li> | |
| 91 | <li>If the changes conflict, nothing is saved and the conflict sheet opens.</li> | |
| 92 | </ul> | |
| 93 | <p>The merge is a line-based three-way merge between the version Orgstar last read or wrote, your edits, and the disk version. A run of lines changed on one side only takes that side; changed the same way on both, it is taken once; changed differently on both, it is a conflict. Lines keep their endings, so CRLF files and a missing final newline survive a merge. A disk version that isn't valid UTF-8 always conflicts.</p> | |
| 94 | <p>After a reload or merge, Orgstar also reads the file's setup files again.</p> | |
| 95 | <h3 id="the-conflict-sheet">The conflict sheet</h3> | |
| 96 | <p>The sheet shows what differs, with lines marked - on disk and + in your version, and offers:</p> | |
| 97 | <table> | |
| 98 | <thead> | |
| 99 | <tr><th>Button</th><th>Effect</th></tr> | |
| 100 | </thead> | |
| 101 | <tbody> | |
| 102 | <tr><td>Keep Mine</td><td>Writes your version over the disk version. The disk version goes to the recovery folder.</td></tr> | |
| 103 | <tr><td>Use Disk Version</td><td>Loads the disk version. Your version goes to the recovery folder.</td></tr> | |
| 104 | <tr><td>Merge with Markers</td><td>Puts both sets of changes in the buffer, with conflicting lines between <code class="verbatim"><<<<<<< yours</code> and <code class="verbatim">>>>>>>> disk</code> markers, as <code class="verbatim">git merge</code> leaves them. Edit and save. Your version as it was goes to the recovery folder.</td></tr> | |
| 105 | <tr><td>Decide Later</td><td>Closes the sheet. Automatic saving stops for the file until you decide; the Conflict button in the toolbar opens the sheet again.</td></tr> | |
| 106 | </tbody> | |
| 107 | </table> | |
| 108 | <p>On the Mac, Revert to File on Disk (in the command palette) loads the disk version at any time; unsaved changes go to the recovery folder.</p> | |
| 109 | <h2 id="sync-tools">Sync tools</h2> | |
| 110 | <h3 id="icloud-drive">iCloud Drive</h3> | |
| 111 | <p>Orgstar reads and writes files under file coordination, which is how iCloud expects apps to work. Files iCloud hasn't downloaded yet (<code class="verbatim">.name.org.icloud</code> placeholders) aren't indexed; Orgstar asks iCloud to download them and indexes them when they arrive. On iOS they appear in the Folders tab with a cloud icon until then.</p> | |
| 112 | <h3 id="syncthing">Syncthing</h3> | |
| 113 | <p>Syncthing writes files without file coordination. Orgstar sees its changes through file watching and merges them as described above.</p> | |
| 114 | <ul> | |
| 115 | <li>Syncthing's temporary files (<code class="verbatim">.syncthing.*</code>) are ignored.</li> | |
| 116 | <li>Its folders <code class="verbatim">.stfolder</code> and <code class="verbatim">.stversions</code> are in the default <code class="verbatim">ignored-folders</code>.</li> | |
| 117 | <li>Conflict copies (<code class="verbatim">name.sync-conflict-YYYYMMDD-HHMMSS-ID.org</code>) are listed in the sidebar but never indexed, so they don't appear in the agenda, search or ID links.</li> | |
| 118 | </ul> | |
| 119 | <p>When a file with conflict copies opens, a message says how many there are. Resolve Sync Conflicts… in the command palette (More ▸ Sync Conflict Copies on iOS) lists each copy against the file, with lines marked - in the file and + in the copy:</p> | |
| 120 | <table> | |
| 121 | <thead> | |
| 122 | <tr><th>Button</th><th>Effect</th></tr> | |
| 123 | </thead> | |
| 124 | <tbody> | |
| 125 | <tr><td>Keep File</td><td>Leaves the file as it is.</td></tr> | |
| 126 | <tr><td>Use Copy</td><td>Replaces the buffer's text with the copy's, as an edit you can undo.</td></tr> | |
| 127 | <tr><td>Merge with Markers</td><td>Puts every difference between the file and the copy between conflict markers in the buffer. There is no common base, so every difference is marked.</td></tr> | |
| 128 | </tbody> | |
| 129 | </table> | |
| 130 | <p>Each choice then moves the copy to the recovery folder and deletes it from the folder.</p> | |
| 131 | <h3 id="dropbox-and-other-tools">Dropbox and other tools</h3> | |
| 132 | <p>Any program that writes files in your folders is treated the same way: Orgstar sees the change, reloads or merges, and keeps displaced versions. Programs that write through file coordination (iCloud, File Provider apps on iOS) are seen as they write; others are seen through FSEvents on the Mac and when you return to the app on iOS.</p> | |
| 133 | <h3 id="files-orgstar-ignores">Files Orgstar ignores</h3> | |
| 134 | <p>When scanning folders, Orgstar skips Emacs lock files (<code class="verbatim">.#name</code>), backups (<code class="verbatim">name~</code>) and auto-save files (<code class="verbatim">#name#</code>), its own temporary and backup files (names containing <code class="verbatim">.orgstar-</code>), <code class="verbatim">.DS_Store</code>, <code class="verbatim">.localized</code>, and the folders in <code class="verbatim">ignored-folders</code>. With <code class="verbatim">show-hidden-files = false</code>, every dotfile and dot folder is skipped. Orgstar doesn't create or honour Emacs lock files.</p> | |
| 135 | <h2 id="recovery-versions">Recovery versions</h2> | |
| 136 | <p>Every version a save, a merge or a conflict resolution displaces is kept in the recovery folder:</p> | |
| 137 | <ul> | |
| 138 | <li>on the Mac, <code class="verbatim">~/Library/Application Support/Orgstar/Recovery</code> (or <code class="verbatim">$ORGSTAR_DATA_DIR/Recovery</code>),</li> | |
| 139 | <li>on iOS, the app's own Application Support folder.</li> | |
| 140 | </ul> | |
| 141 | <p>Each file has a subfolder named from a hash of its path, holding its last 20 kept versions. A version's file name has a timestamp, a label and the file's name. The labels are:</p> | |
| 142 | <table> | |
| 143 | <thead> | |
| 144 | <tr><th>Label</th><th>Kept when</th></tr> | |
| 145 | </thead> | |
| 146 | <tbody> | |
| 147 | <tr><td><code class="verbatim">external</code></td><td>A version written by another program was replaced or merged</td></tr> | |
| 148 | <tr><td><code class="verbatim">local</code></td><td>Orgstar's version was replaced, or set aside by Use Disk Version, Merge with Markers or Restore</td></tr> | |
| 149 | <tr><td><code class="verbatim">sync-conflict</code></td><td>A Syncthing conflict copy was resolved</td></tr> | |
| 150 | </tbody> | |
| 151 | </table> | |
| 152 | <p>Recovery Versions… in the command palette (More ▸ Recovered Versions on iOS) lists the open file's kept versions, newest first, each compared with the buffer (lines marked - in the buffer, + in the kept version). Restore puts a version's text in the buffer as an edit you can undo; the buffer as it was goes to the recovery folder first. On the Mac, Show in Finder selects the version's file.</p> | |
| 153 | <h2 id="features-that-use-emacs-on-the-mac">Features that use Emacs on the Mac</h2> | |
| 154 | <p>Some features run Emacs in batch mode on the Mac. Everything else works without Emacs installed.</p> | |
| 155 | <table> | |
| 156 | <thead> | |
| 157 | <tr><th>Feature</th><th>What runs</th></tr> | |
| 158 | </thead> | |
| 159 | <tbody> | |
| 160 | <tr><td>Emacs Lisp source blocks (<code class="verbatim">emacs-lisp</code>, <code class="verbatim">elisp</code>)</td><td>The block, in <code class="verbatim">emacs -Q --batch</code></td></tr> | |
| 161 | <tr><td>Table formulas outside what Orgstar computes itself</td><td><code class="verbatim">org-table-recalculate</code> on a copy of the file; the table's new text replaces the old one if the table didn't change meanwhile</td></tr> | |
| 162 | <tr><td>Lisp table formulas that Orgstar's Emacs Lisp interpreter can't evaluate</td><td>The same; Orgstar first asks whether to run Lisp (yes, no, always)</td></tr> | |
| 163 | <tr><td>Export to PDF, ODT, LaTeX and plain text</td><td><code class="verbatim">org-latex-export-to-pdf</code>, <code class="verbatim">org-odt-export-to-odt</code>, <code class="verbatim">org-latex-export-to-latex</code> or <code class="verbatim">org-ascii-export-to-ascii</code></td></tr> | |
| 164 | </tbody> | |
| 165 | </table> | |
| 166 | <p>HTML and Markdown export don't use Emacs. See <a href="11-code-blocks.html">Code blocks</a>, <a href="10-tables.html">Tables</a> and <a href="12-export.html">Export</a>.</p> | |
| 167 | <h3 id="how-emacs-is-found">How Emacs is found</h3> | |
| 168 | <p>Orgstar uses the first of these that is an executable file:</p> | |
| 169 | <ol> | |
| 170 | <li>the path in the environment variable <code class="verbatim">ORGSTAR_EMACS</code>,</li> | |
| 171 | <li><code class="verbatim">/opt/homebrew/bin/emacs</code>,</li> | |
| 172 | <li><code class="verbatim">/usr/local/bin/emacs</code>,</li> | |
| 173 | <li><code class="verbatim">/Applications/Emacs.app/Contents/MacOS/Emacs</code>,</li> | |
| 174 | <li><code class="verbatim">/run/current-system/sw/bin/emacs</code>,</li> | |
| 175 | <li><code class="verbatim">/usr/bin/emacs</code>.</li> | |
| 176 | </ol> | |
| 177 | <p>An app started from the Dock doesn't see your shell's <code class="verbatim">PATH</code>, which is why Orgstar looks in fixed places. Without Emacs, these features report "Emacs isn't installed, so …" and change nothing.</p> | |
| 178 | <h3 id="what-emacs-sees">What Emacs sees</h3> | |
| 179 | <ul> | |
| 180 | <li>Emacs runs with <code class="verbatim">-Q</code>: your <code class="verbatim">init.el</code>, packages and customizations aren't loaded. Org and the exporters are the versions bundled with that Emacs.</li> | |
| 181 | <li>Orgstar writes a snapshot of the buffer to a temporary folder and runs Emacs on it, so unsaved edits are included. The working directory is the file's folder.</li> | |
| 182 | <li>File-local variables marked safe apply (<code class="verbatim">enable-local-variables</code> is <code class="verbatim">:safe</code>).</li> | |
| 183 | <li>Export doesn't run source blocks (<code class="verbatim">org-export-use-babel</code> is <code class="verbatim">nil</code>). The exported file is written next to the org file, as Emacs writes it, or moved to the place you chose.</li> | |
| 184 | <li>For export and table recalculation, Emacs gets your <code class="verbatim">PATH</code> with <code class="verbatim">/opt/homebrew/bin</code>, <code class="verbatim">/usr/local/bin</code>, <code class="verbatim">/Library/TeX/texbin</code>, <code class="verbatim">/usr/bin</code> and <code class="verbatim">/bin</code> added, as source blocks do, so the programs it starts, such as <code class="verbatim">pdflatex</code>, are found when Orgstar was opened from the Dock.</li> | |
| 185 | <li>PDF export needs a LaTeX installation that Org's LaTeX exporter can run.</li> | |
| 186 | <li>A table recalculation that takes more than 60 seconds, or an export that takes more than 120 seconds, is stopped. Source blocks have a limit of 300 seconds. <code class="verbatim">⌘.</code> (Cancel Running Task) stops a running block, export or table recalculation sooner.</li> | |
| 187 | </ul> | |
| 188 | <h2 id="quick-look">Quick Look</h2> | |
| 189 | <p>Orgstar includes a Quick Look extension for org files (<code class="verbatim">.org</code> and <code class="verbatim">.org_archive</code>). Pressing Space on an org file in Finder, or in the Files app on iOS, shows the file as the HTML export renders it, with its <code class="verbatim">#+SETUPFILE</code> keywords applied. The preview reads only UTF-8 files.</p> | |
| 190 | <p>Inside Orgstar, selecting a file in the sidebar that isn't text shows a Quick Look preview, with Open with Default App and Show in Finder below it.</p> | |
| 191 | <h2 id="spotlight">Spotlight</h2> | |
| 192 | <p>On the Mac, Orgstar includes a Spotlight importer for org files. Spotlight indexes each file's text, its title (<code class="verbatim">#+TITLE</code>, else the file name), <code class="verbatim">#+AUTHOR</code>, <code class="verbatim">#+DESCRIPTION</code>, and its tags (<code class="verbatim">#+FILETAGS</code> and heading tags) and headings as keywords. The importer reads only UTF-8 files.</p> | |
| 193 | <p>On iOS, the app adds the files in your folders to Spotlight itself; see <a href="14-ios.html">iPhone and iPad</a>.</p> | |
| 194 | <h2 id="finder">Finder</h2> | |
| 195 | <p>Orgstar declares the <code class="verbatim">org.orgmode.org</code> file type for the extensions <code class="verbatim">.org</code> and <code class="verbatim">.org_archive</code>, and registers as an editor for it, and as an alternate editor for plain text. Double-clicking an org file in Finder, dropping files on Orgstar's Dock icon, or running <code class="verbatim">open -a Orgstar file.org</code> opens each file as a buffer. Files opened while Orgstar is starting open once its window is ready. To make Orgstar the app that opens org files, use Finder's Get Info ▸ Open with ▸ Change All.</p> | |
| 196 | <h2 id="org-protocol-and-shortcuts">org-protocol and Shortcuts</h2> | |
| 197 | <p>Orgstar registers the <code class="verbatim">org-protocol:</code> URL scheme on the Mac and iOS, and handles two sub-protocols, in both the <code class="verbatim">?key=value</code> form and the older <code class="verbatim">:/a/b/c</code> form:</p> | |
| 198 | <ul> | |
| 199 | <li><code class="verbatim">org-protocol://capture</code> opens Capture with the link's template, URL, title and body.</li> | |
| 200 | <li><code class="verbatim">org-protocol://store-link</code> stores the link for <code class="verbatim">C-c C-l</code> and copies it to the clipboard. This is Mac only; the iOS app handles only <code class="verbatim">capture</code>.</li> | |
| 201 | </ul> | |
| 202 | <p>Other sub-protocols, such as <code class="verbatim">open-source</code>, show "Orgstar handles org-protocol capture and store-link".</p> | |
| 203 | <p>The Shortcuts action Capture to Orgstar, on the Mac and iOS, files text with a capture template without opening the capture window. See <a href="08-capture.html">Capture</a>.</p> | |
| 204 | <h2 id="compatibility-notes">Compatibility notes</h2> | |
| 205 | <h3 id="defaults-that-differ-from-emacs">Defaults that differ from Emacs</h3> | |
| 206 | <p>Orgstar's defaults follow a common Doom Emacs setup rather than plain Emacs in several places. If you use plain Emacs on the same files, set these in <code class="verbatim">config.toml</code> to match your Emacs, or use Import from Emacs; see <a href="13-configuration.html">Configuration</a>.</p> | |
| 207 | <table> | |
| 208 | <thead> | |
| 209 | <tr><th>Setting</th><th>Orgstar default</th><th>Plain Emacs default</th></tr> | |
| 210 | </thead> | |
| 211 | <tbody> | |
| 212 | <tr><td><code class="verbatim">fill-column</code></td><td>80</td><td>70</td></tr> | |
| 213 | <tr><td><code class="verbatim">org-todo-keywords</code></td><td><code class="verbatim">TODO PROJ LOOP STRT WAIT HOLD IDEA</code>, done <code class="verbatim">DONE KILL</code></td><td><code class="verbatim">TODO</code>, done <code class="verbatim">DONE</code></td></tr> | |
| 214 | <tr><td><code class="verbatim">org-insert-heading-respect-content</code></td><td><code class="verbatim">true</code></td><td><code class="verbatim">nil</code></td></tr> | |
| 215 | <tr><td><code class="verbatim">org-M-RET-may-split-line</code></td><td><code class="verbatim">false</code></td><td><code class="verbatim">t</code></td></tr> | |
| 216 | <tr><td><code class="verbatim">org-list-allow-alphabetical</code></td><td><code class="verbatim">true</code></td><td><code class="verbatim">nil</code></td></tr> | |
| 217 | <tr><td><code class="verbatim">org-hide-emphasis-markers</code></td><td><code class="verbatim">true</code></td><td><code class="verbatim">nil</code></td></tr> | |
| 218 | <tr><td><code class="verbatim">org-pretty-entities</code></td><td><code class="verbatim">true</code></td><td><code class="verbatim">nil</code></td></tr> | |
| 219 | <tr><td><code class="verbatim">org-startup-indented</code></td><td><code class="verbatim">true</code></td><td><code class="verbatim">nil</code></td></tr> | |
| 220 | <tr><td><code class="verbatim">org-startup-truncated</code></td><td><code class="verbatim">false</code></td><td><code class="verbatim">t</code></td></tr> | |
| 221 | <tr><td><code class="verbatim">electric-pair-mode</code></td><td><code class="verbatim">true</code></td><td>off</td></tr> | |
| 222 | <tr><td><code class="verbatim">org-agenda-span</code></td><td>10 days</td><td>a week</td></tr> | |
| 223 | <tr><td><code class="verbatim">org-agenda-start-day</code></td><td><code class="verbatim">"-3d"</code></td><td>today</td></tr> | |
| 224 | </tbody> | |
| 225 | </table> | |
| 226 | <p><code class="verbatim">org-hide-emphasis-markers</code> and <code class="verbatim">org-pretty-entities</code> matter for files you also edit in Emacs: Orgstar aligns tags and tables, and fills paragraphs, by the width text has on screen in your Emacs. If they don't match your Emacs, tags and tables that Orgstar aligns look misaligned in Emacs.</p> | |
| 227 | <p>These behave as Emacs's defaults and can't be changed: <code class="verbatim">org-log-repeat</code> is <code class="verbatim">time</code>, fast TODO selection is on when keywords have keys, priorities are <code class="verbatim">A</code> to <code class="verbatim">C</code> with <code class="verbatim">B</code> as default unless <code class="verbatim">#+PRIORITIES</code> says otherwise, and <code class="verbatim">org-use-sub-superscripts</code> is <code class="verbatim">{}</code> for display (only <code class="verbatim">x_{1}</code> and <code class="verbatim">x^{2}</code> are lowered and raised).</p> | |
| 228 | <h3 id="known-differences-from-emacs-org">Known differences from Emacs Org</h3> | |
| 229 | <p>Orgstar refuses some things with a message rather than doing something different from Emacs. These are the ones found in the current version.</p> | |
| 230 | <p>Code blocks (see <a href="11-code-blocks.html">Code blocks</a>):</p> | |
| 231 | <ul> | |
| 232 | <li><code class="verbatim">:cmdline</code> is supported only for shells, <code class="verbatim">dot</code>, <code class="verbatim">plantuml</code>, <code class="verbatim">mermaid</code> and C, C++, D, Java, Fortran and Clojure.</li> | |
| 233 | <li><code class="verbatim">:post</code> isn't supported; <code class="verbatim">:prologue</code> and <code class="verbatim">:epilogue</code> only for C, C++, D, Java, Fortran and Clojure; <code class="verbatim">:stdin</code> and <code class="verbatim">:shebang</code> only for shells.</li> | |
| 234 | <li><code class="verbatim">:session</code> is supported only for shells and Python. C, C++, D, Java, Fortran and Clojure ignore it, as in Org.</li> | |
| 235 | <li>Clojure runs with babashka or the Clojure CLI only; other <code class="verbatim">:backend</code> values are refused.</li> | |
| 236 | <li><code class="verbatim">:var</code> isn't supported for Ruby, JavaScript, R and awk blocks.</li> | |
| 237 | <li>Header arguments, <code class="verbatim">:var</code> values and <code class="verbatim">:cache</code> that need Lisp evaluated by Emacs are refused when Orgstar's interpreter can't evaluate them: "… is Lisp that only Emacs can evaluate; nothing was run."</li> | |
| 238 | <li>Noweb references that run a block aren't supported.</li> | |
| 239 | <li>Tangling refuses <code class="verbatim">:var</code> that would run a block, and tables and lists in <code class="verbatim">:var</code> for some languages.</li> | |
| 240 | <li>On iOS, only Emacs Lisp blocks run.</li> | |
| 241 | </ul> | |
| 242 | <p>Links (see <a href="09-links.html">Links</a>):</p> | |
| 243 | <ul> | |
| 244 | <li>Coderef links (<code class="verbatim">[[(ref)]]</code>) and regexp search links (<code class="verbatim">[[/regexp/]]</code>) aren't supported.</li> | |
| 245 | <li><code class="verbatim">shell:</code> and <code class="verbatim">elisp:</code> links aren't run.</li> | |
| 246 | </ul> | |
| 247 | <p>Capture templates (see <a href="08-capture.html">Capture</a>):</p> | |
| 248 | <ul> | |
| 249 | <li><code class="verbatim">%(</code> escapes, which run Emacs Lisp, aren't supported.</li> | |
| 250 | <li><code class="verbatim">%[file]</code> escapes aren't supported.</li> | |
| 251 | </ul> | |
| 252 | <p>Tables and dynamic blocks (see <a href="10-tables.html">Tables</a> and <a href="06-dates-and-clocking.html">Dates and clocking</a>):</p> | |
| 253 | <ul> | |
| 254 | <li>Formulas outside Orgstar's own calculator go to Emacs on the Mac and are refused on iOS.</li> | |
| 255 | <li>Clock tables support the scopes <code class="verbatim">nil</code>, <code class="verbatim">file</code>, <code class="verbatim">subtree</code> and <code class="verbatim">treeN</code>; other scopes, <code class="verbatim">:match</code> and <code class="verbatim">:step</code> aren't supported.</li> | |
| 256 | <li>Dynamic blocks other than <code class="verbatim">clocktable</code> and <code class="verbatim">columnview</code> aren't supported. Column views of other files aren't supported.</li> | |
| 257 | </ul> | |
| 258 | <p>Other:</p> | |
| 259 | <ul> | |
| 260 | <li><code class="verbatim">C-c C-q</code> before the first heading (setting file tags) isn't supported.</li> | |
| 261 | <li>Priority ranges that aren't letters or numbers are refused.</li> | |
| 262 | <li><code class="verbatim">#+SETUPFILE</code> URLs aren't fetched.</li> | |
| 263 | <li>Most <code class="verbatim">#+STARTUP</code> options for footnotes, entities, LaTeX previews, numbering and odd levels are accepted and ignored; see <a href="13-configuration.html">Configuration</a>.</li> | |
| 264 | <li><code class="verbatim">display-line-numbers-type</code> has no relative or visual mode.</li> | |
| 265 | </ul> | |
| 266 | </main> | |
| 267 | <footer class="site"> | |
| 268 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 269 | </footer> | |
| 270 | </body> | |
| 271 | </html> | |
| \ No newline at end of file | ||
guide/index.html added +107
| @@ -0,0 +1,107 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Manual · Orgstar</title> | |
| 7 | <meta name="description" content=""> | |
| 8 | <link rel="icon" href="../favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="../theme.css"> | |
| 10 | <link rel="stylesheet" href="../syntax.css"> | |
| 11 | <link rel="stylesheet" href="../style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="../index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="../install.html">Install</a> | |
| 18 | <a href="../quickstart.html">Quick start</a> | |
| 19 | <a href="#">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Manual</h1> | |
| 24 | ||
| 25 | <ul class="post-list"> | |
| 26 | <li> | |
| 27 | <a href="../guide/01-files-and-folders.html">Files, folders and buffers</a> | |
| 28 | <p class="excerpt">Adding folders, opening files, working with buffers, searching, saving, and how Orgstar handles changes made outside it.</p> | |
| 29 | <span class="reading-time">19 min read</span> | |
| 30 | </li> | |
| 31 | <li> | |
| 32 | <a href="../guide/02-the-editor.html">The editor</a> | |
| 33 | <p class="excerpt">How the editor displays org text, folds it, reports state in the modeline and echo area, completes, checks spelling, pairs brackets, wraps lines and undoes.</p> | |
| 34 | <span class="reading-time">18 min read</span> | |
| 35 | </li> | |
| 36 | <li> | |
| 37 | <a href="../guide/03-keys.html">Keys and commands</a> | |
| 38 | <p class="excerpt">The three key presets, prefix keys and key hints, the echo area, the command palette, Option as Meta, keymap.toml, Vim editing in the Doom preset, and every binding.</p> | |
| 39 | <span class="reading-time">57 min read</span> | |
| 40 | </li> | |
| 41 | <li> | |
| 42 | <a href="../guide/04-outlines.html">Outlines and structure</a> | |
| 43 | <p class="excerpt">Headings, subtrees, plain lists, checkboxes, blocks, drawers, properties, column view, footnotes, refiling and archiving.</p> | |
| 44 | <span class="reading-time">29 min read</span> | |
| 45 | </li> | |
| 46 | <li> | |
| 47 | <a href="../guide/05-todos-and-tags.html">TODOs and tags</a> | |
| 48 | <p class="excerpt">TODO keywords, state logging, priorities, tags and progress cookies in Orgstar.</p> | |
| 49 | <span class="reading-time">11 min read</span> | |
| 50 | </li> | |
| 51 | <li> | |
| 52 | <a href="../guide/06-dates-and-clocking.html">Dates, scheduling and clocking</a> | |
| 53 | <p class="excerpt">Timestamps, the date prompt, SCHEDULED and DEADLINE, repeating tasks, effort, clocking, clock tables, habits and reminders in Orgstar.</p> | |
| 54 | <span class="reading-time">22 min read</span> | |
| 55 | </li> | |
| 56 | <li> | |
| 57 | <a href="../guide/07-agenda.html">The agenda</a> | |
| 58 | <p class="excerpt">The agenda window, the TODO list, tag and property matches, saved views, filters, reminders and the board.</p> | |
| 59 | <span class="reading-time">21 min read</span> | |
| 60 | </li> | |
| 61 | <li> | |
| 62 | <a href="../guide/08-capture.html">Capture</a> | |
| 63 | <p class="excerpt">Capture templates, the capture window, date trees, org-protocol, Shortcuts and the iOS share sheet.</p> | |
| 64 | <span class="reading-time">16 min read</span> | |
| 65 | </li> | |
| 66 | <li> | |
| 67 | <a href="../guide/09-links.html">Links</a> | |
| 68 | <p class="excerpt">Link syntax, the link types Orgstar follows, storing and inserting links, IDs, backlinks and inline images.</p> | |
| 69 | <span class="reading-time">12 min read</span> | |
| 70 | </li> | |
| 71 | <li> | |
| 72 | <a href="../guide/10-tables.html">Tables</a> | |
| 73 | <p class="excerpt">Creating and editing Org tables, column widths, import and export, and spreadsheet formulas.</p> | |
| 74 | <span class="reading-time">19 min read</span> | |
| 75 | </li> | |
| 76 | <li> | |
| 77 | <a href="../guide/11-code-blocks.html">Code blocks</a> | |
| 78 | <p class="excerpt">Source blocks in Orgstar: highlighting, editing, running with Babel, results, header arguments, noweb and tangling.</p> | |
| 79 | <span class="reading-time">28 min read</span> | |
| 80 | </li> | |
| 81 | <li> | |
| 82 | <a href="../guide/12-export.html">Export</a> | |
| 83 | <p class="excerpt">Exporting Org files from Orgstar to HTML and Markdown, and to PDF, LaTeX, ODT and plain text through Emacs.</p> | |
| 84 | <span class="reading-time">14 min read</span> | |
| 85 | </li> | |
| 86 | <li> | |
| 87 | <a href="../guide/13-configuration.html">Configuration</a> | |
| 88 | <p class="excerpt">The Settings window, the files in ~/.config/orgstar, in-file settings, importing from Emacs, themes and fonts.</p> | |
| 89 | <span class="reading-time">24 min read</span> | |
| 90 | </li> | |
| 91 | <li> | |
| 92 | <a href="../guide/14-ios.html">iPhone and iPad</a> | |
| 93 | <p class="excerpt">The iOS app: folders, reading and editing, search, the agenda, capture, clocking, reminders, export and settings.</p> | |
| 94 | <span class="reading-time">18 min read</span> | |
| 95 | </li> | |
| 96 | <li> | |
| 97 | <a href="../guide/15-alongside-emacs.html">Working alongside Emacs and other tools</a> | |
| 98 | <p class="excerpt">How Orgstar reads and writes files shared with Emacs and sync tools, merges outside changes, keeps recovery versions, calls Emacs, and differs from Emacs Org.</p> | |
| 99 | <span class="reading-time">13 min read</span> | |
| 100 | </li> | |
| 101 | </ul> | |
| 102 | </main> | |
| 103 | <footer class="site"> | |
| 104 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 105 | </footer> | |
| 106 | </body> | |
| 107 | </html> | |
| \ No newline at end of file | ||
index.html added +62
| @@ -0,0 +1,62 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Orgstar · Orgstar</title> | |
| 7 | <meta name="description" content="A native macOS and iOS editor for org-mode files."> | |
| 8 | <link rel="icon" href="favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="theme.css"> | |
| 10 | <link rel="stylesheet" href="syntax.css"> | |
| 11 | <link rel="stylesheet" href="style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="install.html">Install</a> | |
| 18 | <a href="quickstart.html">Quick start</a> | |
| 19 | <a href="guide/index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Orgstar</h1> | |
| 24 | <p class="lede">Orgstar edits org files in place, alongside Emacs and the sync tools you already use.</p> | |
| 25 | <p>Orgstar is an editor for <a href="https://orgmode.org">Org mode</a> files on the Mac, with an app for iPhone and iPad. It reads and writes the same plain-text files Emacs does, behaves the way Org does where the two overlap, and leaves every byte you didn't change as it was.</p> | |
| 26 | <p>On the Mac you get the editor with Emacs, Mac or Doom (Vim) keys, the agenda and a board view, capture templates, clocking, tables with formulas, code blocks and tangling, and export to HTML and Markdown (and to other formats through Emacs, if it is installed). The iOS app has the editor, agenda, capture, search, clocking, reminders, export and tangling.</p> | |
| 27 | <h2 id="start-here">Start here</h2> | |
| 28 | <ul> | |
| 29 | <li><a href="install.html">Install</a>: build the app from source.</li> | |
| 30 | <li><a href="quickstart.html">Quick start</a>: add a folder, open a file, and the first keys to learn.</li> | |
| 31 | <li>The manual, below: every feature, chapter by chapter.</li> | |
| 32 | </ul> | |
| 33 | <h2 id="the-manual">The manual</h2> | |
| 34 | <ol> | |
| 35 | <li><a href="guide/01-files-and-folders.html">Files, folders and buffers</a></li> | |
| 36 | <li><a href="guide/02-the-editor.html">The editor</a></li> | |
| 37 | <li><a href="guide/03-keys.html">Keys and commands</a></li> | |
| 38 | <li><a href="guide/04-outlines.html">Outlines and structure</a></li> | |
| 39 | <li><a href="guide/05-todos-and-tags.html">TODOs and tags</a></li> | |
| 40 | <li><a href="guide/06-dates-and-clocking.html">Dates, scheduling and clocking</a></li> | |
| 41 | <li><a href="guide/07-agenda.html">The agenda</a></li> | |
| 42 | <li><a href="guide/08-capture.html">Capture</a></li> | |
| 43 | <li><a href="guide/09-links.html">Links</a></li> | |
| 44 | <li><a href="guide/10-tables.html">Tables</a></li> | |
| 45 | <li><a href="guide/11-code-blocks.html">Code blocks</a></li> | |
| 46 | <li><a href="guide/12-export.html">Export</a></li> | |
| 47 | <li><a href="guide/13-configuration.html">Configuration</a></li> | |
| 48 | <li><a href="guide/14-ios.html">iPhone and iPad</a></li> | |
| 49 | <li><a href="guide/15-alongside-emacs.html">Working alongside Emacs and other tools</a></li> | |
| 50 | </ol> | |
| 51 | <h2 id="principles">Principles</h2> | |
| 52 | <ul> | |
| 53 | <li><strong>The files are the source of truth.</strong> There is no database of your notes. Orgstar keeps an index for search and the agenda, rebuilt from the files whenever they change.</li> | |
| 54 | <li><strong>Only your edits are written.</strong> Saving rewrites the bytes you changed and nothing else: indentation, line endings, encoding marks and unusual spacing elsewhere stay.</li> | |
| 55 | <li><strong>Org's behaviour, not a lookalike.</strong> Commands follow what Org 9.8 does, and are checked against Emacs in the test suite. Where Orgstar can't do something the way Org would, it says so and leaves the file alone rather than guessing.</li> | |
| 56 | </ul> | |
| 57 | </main> | |
| 58 | <footer class="site"> | |
| 59 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 60 | </footer> | |
| 61 | </body> | |
| 62 | </html> | |
| \ No newline at end of file | ||
install.html added +72
| @@ -0,0 +1,72 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Install · Orgstar</title> | |
| 7 | <meta name="description" content="Building Orgstar for the Mac and the iOS Simulator from source."> | |
| 8 | <link rel="icon" href="favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="theme.css"> | |
| 10 | <link rel="stylesheet" href="syntax.css"> | |
| 11 | <link rel="stylesheet" href="style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="#">Install</a> | |
| 18 | <a href="quickstart.html">Quick start</a> | |
| 19 | <a href="guide/index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Install</h1> | |
| 24 | <p class="lede">Orgstar is built from source; there are no prebuilt downloads yet.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#requirements">Requirements</a></li> | |
| 29 | <li><a href="#the-mac-app">The Mac app</a></li> | |
| 30 | <li><a href="#the-ios-app">The iOS app</a></li> | |
| 31 | <li><a href="#updating">Updating</a></li> | |
| 32 | <li><a href="#uninstalling">Uninstalling</a></li> | |
| 33 | </ul> | |
| 34 | </nav> | |
| 35 | <h2 id="requirements">Requirements</h2> | |
| 36 | <ul> | |
| 37 | <li>macOS 26 or later.</li> | |
| 38 | <li>Xcode 27 (the Swift 6.2 toolchain).</li> | |
| 39 | <li>Optional: GNU Emacs, for the features that hand work to it on the Mac (Emacs Lisp code blocks that need full Emacs, Lisp table formulas the built-in interpreter can't run, and export to PDF, LaTeX, ODT and other formats). See <a href="guide/15-alongside-emacs.html">Working alongside Emacs and other tools</a>.</li> | |
| 40 | </ul> | |
| 41 | <h2 id="the-mac-app">The Mac app</h2> | |
| 42 | <pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">git</span></span><span class="meta function-call arguments shell"> clone https://gitbay.org/krz/orgstar.git</span> | |
| 43 | <span class="meta function-call shell"><span class="support function cd shell">cd</span></span><span class="meta function-call arguments shell"> orgstar</span> | |
| 44 | <span class="meta function-call shell"><span class="variable function shell">scripts/build-app.sh</span></span> | |
| 45 | <span class="meta function-call shell"><span class="variable function shell">open</span></span><span class="meta function-call arguments shell"> .build/app/Orgstar.app</span></span></code></pre> | |
| 46 | <p><code class="verbatim">scripts/build-app.sh</code> builds a release binary and assembles <code class="verbatim">.build/app/Orgstar.app</code> with its Quick Look and Spotlight extensions, signed ad hoc for use on your own Mac. Move it to <code class="verbatim">/Applications</code> to keep it. Pass a version number as the first argument to stamp the bundle (<code class="verbatim">scripts/build-app.sh 1.0.0</code>); the default is <code class="verbatim">0.1.0</code>.</p> | |
| 47 | <p>Once the app has been launched, Finder opens <code class="verbatim">.org</code> files with it, Quick Look shows them formatted, and Spotlight indexes their headings and text.</p> | |
| 48 | <h2 id="the-ios-app">The iOS app</h2> | |
| 49 | <p>The iOS app (iOS 26 or later) is built with Xcode from <code class="verbatim">ios/Orgstar.xcodeproj</code>:</p> | |
| 50 | <ol> | |
| 51 | <li>Open <code class="verbatim">ios/Orgstar.xcodeproj</code>.</li> | |
| 52 | <li>Select the <strong>Orgstar iOS</strong> target, then Signing & Capabilities, and choose your team. Change the bundle identifiers (<code class="verbatim">sh.krz.orgstar</code> and the two extensions' <code class="verbatim">.share</code> and <code class="verbatim">.quicklook</code>) and the App Group (<code class="verbatim">group.sh.krz.orgstar</code>) to ones your team can register.</li> | |
| 53 | <li>Choose your iPhone or iPad (or a Simulator) as the destination and Run (<code class="verbatim">⌘R</code>).</li> | |
| 54 | </ol> | |
| 55 | <p>On a device, Developer Mode must be on (Settings ▸ Privacy & Security ▸ Developer Mode).</p> | |
| 56 | <p>For the Simulator without opening Xcode:</p> | |
| 57 | <pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">scripts/build-ios-app.sh</span></span> | |
| 58 | <span class="meta function-call shell"><span class="variable function shell">xcrun</span></span><span class="meta function-call arguments shell"> simctl install booted .build/ios-app/Orgstar.app</span></span></code></pre> | |
| 59 | <p>See <a href="guide/14-ios.html">iPhone and iPad</a> for what it does.</p> | |
| 60 | <h2 id="updating">Updating</h2> | |
| 61 | <p>Pull and build again:</p> | |
| 62 | <pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">git</span></span><span class="meta function-call arguments shell"> pull</span> | |
| 63 | <span class="meta function-call shell"><span class="variable function shell">scripts/build-app.sh</span></span></span></code></pre> | |
| 64 | <p>Your settings live in <code class="verbatim">~/.config/orgstar/</code> and survive rebuilds.</p> | |
| 65 | <h2 id="uninstalling">Uninstalling</h2> | |
| 66 | <p>Delete <code class="verbatim">Orgstar.app</code>. To remove your settings as well, delete <code class="verbatim">~/.config/orgstar/</code>. Your org files are never stored inside the app.</p> | |
| 67 | </main> | |
| 68 | <footer class="site"> | |
| 69 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 70 | </footer> | |
| 71 | </body> | |
| 72 | </html> | |
| \ No newline at end of file | ||
quickstart.html added +93
| @@ -0,0 +1,93 @@ | ||
| 1 | <!DOCTYPE html> | |
| 2 | <html lang="en"> | |
| 3 | <head> | |
| 4 | <meta charset="utf-8"> | |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 6 | <title>Quick start · Orgstar</title> | |
| 7 | <meta name="description" content="From a fresh install to editing, scheduling and seeing your agenda."> | |
| 8 | <link rel="icon" href="favicon.svg" type="image/svg+xml"> | |
| 9 | <link rel="stylesheet" href="theme.css"> | |
| 10 | <link rel="stylesheet" href="syntax.css"> | |
| 11 | <link rel="stylesheet" href="style.css"> | |
| 12 | </head> | |
| 13 | <body> | |
| 14 | <header class="site"> | |
| 15 | <a class="site-title" href="index.html">Orgstar</a> | |
| 16 | <nav> | |
| 17 | <a href="install.html">Install</a> | |
| 18 | <a href="#">Quick start</a> | |
| 19 | <a href="guide/index.html">Manual</a> | |
| 20 | </nav> | |
| 21 | </header> | |
| 22 | <main> | |
| 23 | <h1>Quick start</h1> | |
| 24 | <p class="lede">Add a folder of org files, open one, and learn the handful of keys you need first.</p> | |
| 25 | <nav class="toc" aria-label="On this page"> | |
| 26 | <h2>On this page</h2> | |
| 27 | <ul> | |
| 28 | <li><a href="#add-a-folder">Add a folder</a></li> | |
| 29 | <li><a href="#choose-your-keys">Choose your keys</a></li> | |
| 30 | <li><a href="#open-a-file">Open a file</a></li> | |
| 31 | <li><a href="#write-an-outline">Write an outline</a></li> | |
| 32 | <li><a href="#see-your-agenda">See your agenda</a></li> | |
| 33 | <li><a href="#capture-a-thought">Capture a thought</a></li> | |
| 34 | <li><a href="#search">Search</a></li> | |
| 35 | <li><a href="#next">Next</a></li> | |
| 36 | </ul> | |
| 37 | </nav> | |
| 38 | <h2 id="add-a-folder">Add a folder</h2> | |
| 39 | <p>Choose File ▸ Add Folder… (<code class="verbatim">⇧⌘O</code>) and pick the folder that holds your org files. It appears in the sidebar, and Orgstar indexes every org file under it for search, the agenda and links. You can add several folders. Nothing is copied or moved.</p> | |
| 40 | <p>If you don't have org files yet, add an empty folder and create <code class="verbatim">notes.org</code> in it from Finder or the sidebar.</p> | |
| 41 | <h2 id="choose-your-keys">Choose your keys</h2> | |
| 42 | <p>Open Orgstar ▸ Settings… (<code class="verbatim">⌘,</code>) and pick <strong>Keys</strong> under General:</p> | |
| 43 | <ul> | |
| 44 | <li><strong>Emacs</strong>: Org's own bindings, <code class="verbatim">C-c C-t</code> and friends. The default.</li> | |
| 45 | <li><strong>Mac</strong>: standard Mac editing keys, with Org commands on <code class="verbatim">⌃⌘</code> combinations.</li> | |
| 46 | <li><strong>Doom (Vim keys)</strong>: modal editing as in Doom Emacs, with <code class="verbatim">SPC</code> as the leader.</li> | |
| 47 | </ul> | |
| 48 | <p><a href="guide/03-keys.html">Keys and commands</a> lists every binding in each preset. If you already use Emacs, Settings ▸ General ▸ Import from Emacs… reads your configuration: TODO keywords, agenda files, capture templates and more (see <a href="guide/13-configuration.html">Configuration</a>).</p> | |
| 49 | <h2 id="open-a-file">Open a file</h2> | |
| 50 | <p><code class="verbatim">⌘P</code> (Quick Open) finds a file by name; the sidebar works too. Open files become buffers: the tab bar and Switch to Buffer move between them.</p> | |
| 51 | <h2 id="write-an-outline">Write an outline</h2> | |
| 52 | <p>Type a heading and some text:</p> | |
| 53 | <pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Projects | |
| 54 | </span><span class="markup heading org"><span class="punctuation definition heading org">**</span> <span class="keyword other todo org">TODO</span> Write the report | |
| 55 | </span>SCHEDULED: <span class="constant other timestamp org"><2026-10-09 Fri></span> | |
| 56 | Draft the summary first. | |
| 57 | <span class="markup heading org"><span class="punctuation definition heading org">**</span> Reading list | |
| 58 | </span><span class="punctuation definition list org">- </span><span class="constant language checkbox org">[ ]</span> The Org manual | |
| 59 | <span class="punctuation definition list org">- </span><span class="constant language checkbox org">[ ]</span> This manual</span></code></pre> | |
| 60 | <p>With the Emacs keys:</p> | |
| 61 | <table> | |
| 62 | <thead> | |
| 63 | <tr><th>Key</th><th>What it does</th></tr> | |
| 64 | </thead> | |
| 65 | <tbody> | |
| 66 | <tr><td><code class="verbatim">TAB</code> on a heading</td><td>Fold or unfold it (cycles through folded, children, everything).</td></tr> | |
| 67 | <tr><td><code class="verbatim">S-TAB</code></td><td>Cycle the whole file the same way.</td></tr> | |
| 68 | <tr><td><code class="verbatim">M-RET</code></td><td>New heading (or list item) at the same level.</td></tr> | |
| 69 | <tr><td><code class="verbatim">M-<left></code> / <code class="verbatim">M-<right></code></td><td>Promote or demote the heading.</td></tr> | |
| 70 | <tr><td><code class="verbatim">C-c C-t</code></td><td>Cycle the TODO state.</td></tr> | |
| 71 | <tr><td><code class="verbatim">C-c C-s</code> / <code class="verbatim">C-c C-d</code></td><td>Schedule, or set a deadline, with the date picker.</td></tr> | |
| 72 | <tr><td><code class="verbatim">C-c C-c</code></td><td>Context action: toggle a checkbox, align a table, run a code block.</td></tr> | |
| 73 | </tbody> | |
| 74 | </table> | |
| 75 | <p>With the Mac preset, the Org commands are on <code class="verbatim">⌃⌘</code> keys (<code class="verbatim">⌃⌘T</code> cycles TODO, <code class="verbatim">⌃⌘S</code> schedules, <code class="verbatim">⌃⌘X</code> is the context action); with Doom, they're under <code class="verbatim">SPC m</code> (<code class="verbatim">SPC m t</code>, <code class="verbatim">SPC m d s</code>).</p> | |
| 76 | <p>The <a href="guide/02-the-editor.html">editor chapter</a> covers how Org markup is shown and hidden, and <a href="guide/04-outlines.html">Outlines and structure</a> covers headings and lists.</p> | |
| 77 | <h2 id="see-your-agenda">See your agenda</h2> | |
| 78 | <p>Window ▸ Agenda (<code class="verbatim">⇧⌘A</code>) shows what is scheduled or due across every indexed file, day by day, and the TODO list. Select an item to jump to it. See <a href="guide/07-agenda.html">The agenda</a>.</p> | |
| 79 | <h2 id="capture-a-thought">Capture a thought</h2> | |
| 80 | <p><code class="verbatim">⇧⌘N</code> opens capture from anywhere in the app. Until you define your own templates (in <code class="verbatim">~/.config/orgstar/capture.toml</code>, or imported from Emacs), there are two: <code class="verbatim">t</code> files a TODO and <code class="verbatim">n</code> a note, each under an <code class="verbatim">Inbox</code> heading in <code class="verbatim">todo.org</code> or <code class="verbatim">notes.org</code> in your first folder. See <a href="guide/08-capture.html">Capture</a>.</p> | |
| 81 | <h2 id="search">Search</h2> | |
| 82 | <p><code class="verbatim">⇧⌘F</code> searches the text of every indexed file. Results open at the matching line.</p> | |
| 83 | <h2 id="next">Next</h2> | |
| 84 | <ul> | |
| 85 | <li>The command palette (<code class="verbatim">⇧⌘P</code>) lists every command with its key.</li> | |
| 86 | <li>The <a href="index.html">chapter list</a> goes through every feature.</li> | |
| 87 | </ul> | |
| 88 | </main> | |
| 89 | <footer class="site"> | |
| 90 | Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>. | |
| 91 | </footer> | |
| 92 | </body> | |
| 93 | </html> | |
| \ No newline at end of file | ||
style.css added +6
| @@ -0,0 +1,6 @@ | ||
| 1 | /* Code blocks dark in both colour schemes, matching base16-ocean.dark. */ | |
| 2 | :root { | |
| 3 | --orgo-code-bg: #2b303b; | |
| 4 | --orgo-code-fg: #c0c5ce; | |
| 5 | --orgo-code-rule: #1f232b; | |
| 6 | } | |
syntax.css added +160
| @@ -0,0 +1,160 @@ | ||
| 1 | /* | |
| 2 | * theme "Base16 Ocean Dark" generated by syntect | |
| 3 | */ | |
| 4 | ||
| 5 | .code { | |
| 6 | color: #c0c5ce; | |
| 7 | background-color: #2b303b; | |
| 8 | } | |
| 9 | ||
| 10 | .variable.parameter.function { | |
| 11 | color: #c0c5ce; | |
| 12 | } | |
| 13 | .comment, .punctuation.definition.comment { | |
| 14 | color: #65737e; | |
| 15 | } | |
| 16 | .punctuation.definition.string, .punctuation.definition.variable, .punctuation.definition.string, .punctuation.definition.parameters, .punctuation.definition.string, .punctuation.definition.array { | |
| 17 | color: #c0c5ce; | |
| 18 | } | |
| 19 | .none { | |
| 20 | color: #c0c5ce; | |
| 21 | } | |
| 22 | .keyword.operator { | |
| 23 | color: #c0c5ce; | |
| 24 | } | |
| 25 | .keyword { | |
| 26 | color: #b48ead; | |
| 27 | } | |
| 28 | .variable, .variable.other.dollar.only.js { | |
| 29 | color: #bf616a; | |
| 30 | } | |
| 31 | .entity.name.function, .meta.require, .support.function.any-method, .variable.function { | |
| 32 | color: #8fa1b3; | |
| 33 | } | |
| 34 | .support.class, .entity.name.class, .entity.name.type.class { | |
| 35 | color: #ebcb8b; | |
| 36 | } | |
| 37 | .meta.class { | |
| 38 | color: #eff1f5; | |
| 39 | } | |
| 40 | .keyword.other.special-method { | |
| 41 | color: #8fa1b3; | |
| 42 | } | |
| 43 | .storage { | |
| 44 | color: #b48ead; | |
| 45 | } | |
| 46 | .support.function { | |
| 47 | color: #96b5b4; | |
| 48 | } | |
| 49 | .string, .constant.other.symbol, .entity.other.inherited-class { | |
| 50 | color: #a3be8c; | |
| 51 | } | |
| 52 | .constant.numeric { | |
| 53 | color: #d08770; | |
| 54 | } | |
| 55 | .none { | |
| 56 | color: #d08770; | |
| 57 | } | |
| 58 | .none { | |
| 59 | color: #d08770; | |
| 60 | } | |
| 61 | .constant { | |
| 62 | color: #d08770; | |
| 63 | } | |
| 64 | .entity.name.tag { | |
| 65 | color: #bf616a; | |
| 66 | } | |
| 67 | .entity.other.attribute-name { | |
| 68 | color: #d08770; | |
| 69 | } | |
| 70 | .entity.other.attribute-name.id, .punctuation.definition.entity { | |
| 71 | color: #8fa1b3; | |
| 72 | } | |
| 73 | .meta.selector { | |
| 74 | color: #b48ead; | |
| 75 | } | |
| 76 | .none { | |
| 77 | color: #d08770; | |
| 78 | } | |
| 79 | .markup.heading .punctuation.definition.heading, .entity.name.section { | |
| 80 | color: #8fa1b3; | |
| 81 | } | |
| 82 | .keyword.other.unit { | |
| 83 | color: #d08770; | |
| 84 | } | |
| 85 | .markup.bold, .punctuation.definition.bold { | |
| 86 | color: #ebcb8b; | |
| 87 | font-weight: bold; | |
| 88 | } | |
| 89 | .markup.italic, .punctuation.definition.italic { | |
| 90 | color: #b48ead; | |
| 91 | font-style: italic; | |
| 92 | } | |
| 93 | .markup.raw.inline { | |
| 94 | color: #a3be8c; | |
| 95 | } | |
| 96 | .string.other.link { | |
| 97 | color: #bf616a; | |
| 98 | } | |
| 99 | .meta.link { | |
| 100 | color: #d08770; | |
| 101 | } | |
| 102 | .meta.image { | |
| 103 | color: #d08770; | |
| 104 | } | |
| 105 | .markup.list { | |
| 106 | color: #bf616a; | |
| 107 | } | |
| 108 | .markup.quote { | |
| 109 | color: #d08770; | |
| 110 | } | |
| 111 | .meta.separator { | |
| 112 | color: #c0c5ce; | |
| 113 | background-color: #4f5b66; | |
| 114 | } | |
| 115 | .markup.inserted, .markup.inserted.git_gutter { | |
| 116 | color: #a3be8c; | |
| 117 | } | |
| 118 | .markup.deleted, .markup.deleted.git_gutter { | |
| 119 | color: #bf616a; | |
| 120 | } | |
| 121 | .markup.changed, .markup.changed.git_gutter { | |
| 122 | color: #b48ead; | |
| 123 | } | |
| 124 | .markup.ignored, .markup.ignored.git_gutter { | |
| 125 | color: #4f5b66; | |
| 126 | } | |
| 127 | .markup.untracked, .markup.untracked.git_gutter { | |
| 128 | color: #4f5b66; | |
| 129 | } | |
| 130 | .constant.other.color { | |
| 131 | color: #96b5b4; | |
| 132 | } | |
| 133 | .string.regexp { | |
| 134 | color: #96b5b4; | |
| 135 | } | |
| 136 | .constant.character.escape { | |
| 137 | color: #96b5b4; | |
| 138 | } | |
| 139 | .punctuation.section.embedded, .variable.interpolation { | |
| 140 | color: #ab7967; | |
| 141 | } | |
| 142 | .invalid.illegal { | |
| 143 | color: #2b303b; | |
| 144 | background-color: #bf616a; | |
| 145 | } | |
| 146 | .markup.deleted.git_gutter { | |
| 147 | color: #f92672; | |
| 148 | } | |
| 149 | .markup.inserted.git_gutter { | |
| 150 | color: #a6e22e; | |
| 151 | } | |
| 152 | .markup.changed.git_gutter { | |
| 153 | color: #967efb; | |
| 154 | } | |
| 155 | .markup.ignored.git_gutter { | |
| 156 | color: #565656; | |
| 157 | } | |
| 158 | .markup.untracked.git_gutter { | |
| 159 | color: #565656; | |
| 160 | } | |
theme.css added +248
| @@ -0,0 +1,248 @@ | ||
| 1 | /* orgo built-in theme: docs | |
| 2 | * | |
| 3 | * A documentation site: a guide read in order, with a contents block that matters, code | |
| 4 | * blocks that carry as much of the meaning as the prose, and a `#+LEDE:` line under the | |
| 5 | * title. Cooler and more technical than `blog`, narrower and more designed than `wiki`. | |
| 6 | * | |
| 7 | * Every colour is a custom property on :root, so a stylesheet of your own loaded after | |
| 8 | * this one can retheme the site by redefining a handful of values. */ | |
| 9 | ||
| 10 | :root { | |
| 11 | --orgo-ink: #1c1f24; | |
| 12 | --orgo-muted: #5b6472; | |
| 13 | --orgo-rule: #dfe3e8; | |
| 14 | --orgo-accent: #0b5fa5; | |
| 15 | --orgo-surface: #f6f8fa; | |
| 16 | --orgo-bg: #ffffff; | |
| 17 | --orgo-measure: 42rem; | |
| 18 | --orgo-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; | |
| 19 | --orgo-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; | |
| 20 | /* These three colour code *blocks* only; inline code follows the page. A block keeps | |
| 21 | a light surface in both colour schemes, because syntax.css is coloured by | |
| 22 | `highlight.theme` and that default (InspiredGitHub) is light. To let blocks follow | |
| 23 | prefers-color-scheme, set `highlight.theme_dark` to a dark theme and override these | |
| 24 | three in a dark query of your own. */ | |
| 25 | --orgo-todo: #b02a37; | |
| 26 | --orgo-done: #2c7a4b; | |
| 27 | --orgo-code-bg: #f6f8fa; | |
| 28 | --orgo-code-fg: #323232; | |
| 29 | --orgo-code-rule: #e3e7ec; | |
| 30 | } | |
| 31 | ||
| 32 | @media (prefers-color-scheme: dark) { | |
| 33 | :root { | |
| 34 | --orgo-ink: #dee3ea; | |
| 35 | --orgo-muted: #9aa4b2; | |
| 36 | --orgo-rule: #2b3138; | |
| 37 | --orgo-accent: #79b8ff; | |
| 38 | --orgo-surface: #171a1f; | |
| 39 | --orgo-todo: #f0909a; | |
| 40 | --orgo-done: #74c795; | |
| 41 | --orgo-bg: #0f1216; | |
| 42 | } | |
| 43 | } | |
| 44 | ||
| 45 | * { box-sizing: border-box; } | |
| 46 | ||
| 47 | body { | |
| 48 | margin: 0; | |
| 49 | background: var(--orgo-bg); | |
| 50 | color: var(--orgo-ink); | |
| 51 | font: 16px/1.65 var(--orgo-font); | |
| 52 | /* A bare URL or a long identifier must wrap, not widen the page on a phone. */ | |
| 53 | overflow-wrap: break-word; | |
| 54 | } | |
| 55 | ||
| 56 | /* Header ------------------------------------------------------------------- */ | |
| 57 | ||
| 58 | body > header { | |
| 59 | position: sticky; | |
| 60 | top: 0; | |
| 61 | z-index: 1; | |
| 62 | background: var(--orgo-bg); | |
| 63 | border-bottom: 1px solid var(--orgo-rule); | |
| 64 | padding: 1rem 1.5rem; | |
| 65 | display: flex; | |
| 66 | flex-wrap: wrap; | |
| 67 | gap: .5rem 1.5rem; | |
| 68 | align-items: baseline; | |
| 69 | } | |
| 70 | ||
| 71 | .site-title { | |
| 72 | font-weight: 700; | |
| 73 | font-size: 1.05rem; | |
| 74 | color: var(--orgo-ink); | |
| 75 | text-decoration: none; | |
| 76 | } | |
| 77 | ||
| 78 | body > header nav { display: flex; flex-wrap: wrap; gap: 1.25rem; } | |
| 79 | body > header nav a { | |
| 80 | color: var(--orgo-muted); | |
| 81 | text-decoration: none; | |
| 82 | padding-bottom: .15rem; | |
| 83 | border-bottom: 2px solid transparent; | |
| 84 | } | |
| 85 | body > header nav a:hover { color: var(--orgo-ink); border-bottom-color: var(--orgo-accent); } | |
| 86 | ||
| 87 | /* Page body ---------------------------------------------------------------- */ | |
| 88 | ||
| 89 | main { | |
| 90 | max-width: var(--orgo-measure); | |
| 91 | margin: 0 auto; | |
| 92 | padding: 2.5rem 1.5rem 5rem; | |
| 93 | } | |
| 94 | ||
| 95 | h1 { font-size: 2rem; line-height: 1.2; letter-spacing: -0.02em; margin: 0 0 .5rem; } | |
| 96 | h2 { font-size: 1.35rem; letter-spacing: -0.01em; margin: 2.75rem 0 .75rem; } | |
| 97 | h3 { font-size: 1.1rem; margin: 2rem 0 .5rem; } | |
| 98 | h4, h5, h6 { font-size: 1rem; margin: 1.5rem 0 .5rem; } | |
| 99 | ||
| 100 | [class^="section-number-"] { color: var(--orgo-muted); font-weight: 400; } | |
| 101 | ||
| 102 | a { color: var(--orgo-accent); } | |
| 103 | ||
| 104 | /* `#+LEDE:` reaches the layout as page.keywords.lede; page.date as the byline. */ | |
| 105 | p.lede { font-size: 1.1rem; color: var(--orgo-muted); margin-top: 0; } | |
| 106 | p.page-date { color: var(--orgo-muted); font-size: .9rem; } | |
| 107 | ||
| 108 | img, video { max-width: 100%; height: auto; } | |
| 109 | ||
| 110 | figure { margin: 1.75rem 0; } | |
| 111 | figcaption { color: var(--orgo-muted); font-size: .9rem; margin-top: .4rem; } | |
| 112 | .figure-number, .table-number { font-weight: 600; } | |
| 113 | ||
| 114 | /* A quote block reads as a note or a caution in a documentation site. */ | |
| 115 | blockquote { | |
| 116 | margin: 1.5rem 0; | |
| 117 | padding: .75rem 1rem; | |
| 118 | background: var(--orgo-surface); | |
| 119 | border-left: 3px solid var(--orgo-accent); | |
| 120 | border-radius: 0 4px 4px 0; | |
| 121 | color: var(--orgo-muted); | |
| 122 | } | |
| 123 | blockquote > :first-child { margin-top: 0; } | |
| 124 | blockquote > :last-child { margin-bottom: 0; } | |
| 125 | ||
| 126 | hr { border: 0; border-top: 1px solid var(--orgo-rule); margin: 2.5rem 0; } | |
| 127 | ||
| 128 | .center { text-align: center; } | |
| 129 | .verse { font-family: var(--orgo-mono); white-space: pre-wrap; } | |
| 130 | ||
| 131 | dt { font-weight: 600; margin-top: .75rem; font-family: var(--orgo-mono); font-size: .95rem; } | |
| 132 | dd { margin: 0 0 0 1.5rem; } | |
| 133 | ||
| 134 | /* Code --------------------------------------------------------------------- */ | |
| 135 | ||
| 136 | /* Inline code is prose furniture, so it follows the page rather than the code blocks. */ | |
| 137 | code { | |
| 138 | font: .875em/1.5 var(--orgo-mono); | |
| 139 | background: var(--orgo-surface); | |
| 140 | color: inherit; | |
| 141 | padding: .1em .35em; | |
| 142 | border-radius: 3px; | |
| 143 | } | |
| 144 | ||
| 145 | pre { | |
| 146 | background: var(--orgo-code-bg); | |
| 147 | color: var(--orgo-code-fg); | |
| 148 | border: 1px solid var(--orgo-code-rule); | |
| 149 | border-radius: 6px; | |
| 150 | padding: .9rem 1.1rem; | |
| 151 | font-size: .9rem; | |
| 152 | line-height: 1.55; | |
| 153 | overflow-x: auto; | |
| 154 | } | |
| 155 | ||
| 156 | pre code { background: none; color: inherit; padding: 0; } | |
| 157 | ||
| 158 | /* Tables ------------------------------------------------------------------- */ | |
| 159 | ||
| 160 | table { | |
| 161 | border-collapse: collapse; | |
| 162 | width: 100%; | |
| 163 | margin: 1.5rem 0; | |
| 164 | display: block; | |
| 165 | overflow-x: auto; | |
| 166 | } | |
| 167 | caption { text-align: left; color: var(--orgo-muted); font-size: .9rem; padding-bottom: .4rem; } | |
| 168 | th, td { text-align: left; padding: .5rem .75rem; border-bottom: 1px solid var(--orgo-rule); } | |
| 169 | th { | |
| 170 | font-size: .8rem; | |
| 171 | text-transform: uppercase; | |
| 172 | letter-spacing: .05em; | |
| 173 | color: var(--orgo-muted); | |
| 174 | } | |
| 175 | ||
| 176 | /* Org-specific markup ------------------------------------------------------ */ | |
| 177 | ||
| 178 | .tag { | |
| 179 | font: .72rem/1.6 var(--orgo-mono); | |
| 180 | color: var(--orgo-muted); | |
| 181 | background: var(--orgo-surface); | |
| 182 | border: 1px solid var(--orgo-rule); | |
| 183 | border-radius: 999px; | |
| 184 | padding: .05em .6em; | |
| 185 | vertical-align: middle; | |
| 186 | } | |
| 187 | ||
| 188 | .todo, .done { font: .72rem/1.6 var(--orgo-mono); letter-spacing: .04em; } | |
| 189 | .todo { color: var(--orgo-todo); } | |
| 190 | .done { color: var(--orgo-done); } | |
| 191 | .priority { color: var(--orgo-muted); font-family: var(--orgo-mono); font-size: .8em; } | |
| 192 | ||
| 193 | time.timestamp { color: var(--orgo-muted); font-family: var(--orgo-mono); font-size: .9em; } | |
| 194 | ||
| 195 | li.on, li.trans { color: var(--orgo-muted); } | |
| 196 | li.on { text-decoration: line-through; } | |
| 197 | ||
| 198 | .footnotes { margin-top: 3rem; font-size: .9rem; color: var(--orgo-muted); } | |
| 199 | .footnote-ref a { text-decoration: none; } | |
| 200 | ||
| 201 | /* Table of contents: a card, because in a guide it is navigation ----------- */ | |
| 202 | ||
| 203 | nav.toc { | |
| 204 | background: var(--orgo-surface); | |
| 205 | border: 1px solid var(--orgo-rule); | |
| 206 | border-radius: 6px; | |
| 207 | padding: .75rem 1.25rem 1rem; | |
| 208 | margin: 1.75rem 0 2.5rem; | |
| 209 | } | |
| 210 | nav.toc h2 { | |
| 211 | font-size: .8rem; | |
| 212 | text-transform: uppercase; | |
| 213 | letter-spacing: .06em; | |
| 214 | color: var(--orgo-muted); | |
| 215 | margin: .25rem 0 .5rem; | |
| 216 | } | |
| 217 | nav.toc ul { margin: 0; padding-left: 1.1rem; } | |
| 218 | nav.toc li { margin: .15rem 0; } | |
| 219 | ||
| 220 | /* Listing pages: a guide's contents page, a tag index ---------------------- */ | |
| 221 | ||
| 222 | ul.post-list { list-style: none; padding: 0; } | |
| 223 | ul.post-list > li { padding: 1rem 0; border-bottom: 1px solid var(--orgo-rule); } | |
| 224 | ul.post-list a { font-weight: 600; font-size: 1.05rem; } | |
| 225 | ul.post-list time { color: var(--orgo-muted); font-size: .9rem; } | |
| 226 | p.excerpt { margin: .35rem 0 .2rem; color: var(--orgo-muted); } | |
| 227 | span.reading-time { font-size: .85rem; color: var(--orgo-muted); } | |
| 228 | ||
| 229 | ul.tag-list { list-style: none; padding: 0; display: flex; flex-wrap: wrap; gap: .6rem 1.25rem; } | |
| 230 | ||
| 231 | nav.pagination { | |
| 232 | display: flex; | |
| 233 | gap: 1rem; | |
| 234 | align-items: baseline; | |
| 235 | margin-top: 2.5rem; | |
| 236 | color: var(--orgo-muted); | |
| 237 | font-size: .9rem; | |
| 238 | } | |
| 239 | ||
| 240 | /* Footer ------------------------------------------------------------------- */ | |
| 241 | ||
| 242 | body > footer { | |
| 243 | border-top: 1px solid var(--orgo-rule); | |
| 244 | padding: 1.5rem; | |
| 245 | color: var(--orgo-muted); | |
| 246 | font-size: .9rem; | |
| 247 | text-align: center; | |
| 248 | } | |