guide/02-the-editor.html
351 lines · 37915 bytes
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">
348Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>.
349</footer>
350</body>
351</html>