User manual !156

merged merged by cmc on 2026-10-08 03:18 UTC · krz/orgstar:user-manual into main

24 files changed, +7226 −0

Layout: unified · split

docs/manual/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>

docs/manual/guide/01-files-and-folders.org added +313

		@@ -0,0 +1,313 @@
	1	#+TITLE: Files, folders and buffers
	2	#+DESCRIPTION: Adding folders, opening files, working with buffers, searching, saving, and how Orgstar handles changes made outside it.
	3	#+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.
	4
	5	* The window
	6
	7	Orgstar has one main window, titled with the name of the buffer it shows. From left to right it holds:
	8
	9	- the sidebar, listing the folders you added and the files in them;
	10	- the outline pane, listing the headings of the open file, with the backlinks pane under it;
	11	- the editor, with the optional tab bar above it and the modeline and echo area below it;
	12	- the inspector, hidden by default, showing column view and clocked time.
	13
	14	The toolbar holds a button that shows or hides the outline pane, a progress indicator while Orgstar indexes your folders, the running clock (see [[file:06-dates-and-clocking.org][Dates and clocking]]), a =Conflict= button when the open file has a conflict (see /Conflicts/ below), and the search field.
	15
	16	The window title is the buffer name (see /Buffer names/ below). When the open file is not UTF-8, the subtitle reads =Read-only: not UTF-8=. The close button shows the unsaved-changes dot while any open buffer has unsaved edits.
	17
	18	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 =⌘P=.
	19
	20	The Agenda, Board, Clock Report and Capture windows are separate; they are covered in [[file:07-agenda.org][Agenda]], [[file:06-dates-and-clocking.org][Dates and clocking]] and [[file:08-capture.org][Capture]]. Closing the main window quits Orgstar when no other window is open.
	21
	22	** Menus and the command palette
	23
	24	Most commands are in the menu bar. The =Org= menu lists every org command, each with the keys that run it in the current keymap; it is disabled when no file is open.
	25
	26	File ▸ Command Palette… (=⇧⌘P=; =M-x= in the Emacs and Doom presets; =SPC := 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 =Return= to run the top match or click one. =Escape= closes it. Text movement and editing commands (forward character, kill line and so on) are not listed; they are only on keys.
	27
	28	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….
	29
	30	** Showing and hiding panes
	31
	32	\| Menu item \| Shortcut \| Palette title \|
	33	\|------------------------------------------+----------+----------------------------------\|
	34	\| View ▸ Show or Hide Outline \| \| Show or Hide Outline \|
	35	\| View ▸ Show or Hide Backlinks \| \| Show or Hide Backlinks \|
	36	\| View ▸ Show or Hide Columns and Clock \| =⌥⌘I= \| Show or Hide Columns and Clock \|
	37	\| View ▸ Show Tab Bar \| \| Show or Hide Tab Bar \|
	38
	39	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.
	40
	41	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).
	42
	43	* Folders
	44
	45	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.
	46
	47	** Adding a folder
	48
	49	Choose File ▸ Add Folder… (=⇧⌘O=), or click =+= 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.
	50
	51	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 =Can't find the folder PATH.= Adding a folder that is already in the sidebar does nothing.
	52
	53	Orgstar keeps the list of folders, the index and recovery versions in =~/Library/Application Support/Orgstar=.
	54
	55	** Removing a folder
	56
	57	Click =−= at the bottom of the sidebar and choose the folder, or right-click the folder's header and choose Remove from Sidebar…. Confirm with =Remove=. The folder and its files stay on disk; only Orgstar's index entries for them are removed.
	58
	59	** What the sidebar lists
	60
	61	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.
	62
	63	The sidebar lists every file in the folder, not only org files, with an icon for its kind:
	64
	65	\| Icon \| File \|
	66	\|-----------------------+------------------------------------------------------------\|
	67	\| document \| =.org= \|
	68	\| archive box \| =.org_archive= \|
	69	\| orange warning sign \| a Syncthing conflict copy (see /Syncthing conflict copies/ below) \|
	70	\| photo \| an image \|
	71	\| rich document \| a PDF \|
	72	\| play button \| audio or video \|
	73	\| =</>= \| source code or a script \|
	74	\| plain document \| other text \|
	75	\| cloud with arrow \| an iCloud file still downloading (see /iCloud/ below) \|
	76
	77	Some files are never listed or indexed:
	78
	79	- Emacs backups (names ending in =~=), auto-save files (names starting with =#=) and lock files (=.#name=);
	80	- Syncthing's temporary files (=.syncthing.*=);
	81	- Orgstar's own temporary files (names containing =.orgstar-=);
	82	- =.DS_Store= and =.localized=;
	83	- anything inside these folders: =.git=, =.hg=, =.svn=, =.jj=, =.bzr=, =.stfolder=, =.stversions=, =.Trash=, =.Spotlight-V100=, =.fseventsd=, =.build=, =.venv=, =.cache=, =.tox=, =.mypy_cache=, =.pytest_cache=, =.gradle=, =.next=, =.terraform= and =node_modules=.
	84
	85	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 =ignored-folders= in =config.toml= to folder names separated by spaces; there is no control for it in Settings. See [[file:13-configuration.org][Configuration]].
	86
	87	#+BEGIN_SRC toml
	88	[orgstar]
	89	show-hidden-files = true
	90	ignored-folders = ".git .hg node_modules build"
	91	#+END_SRC
	92
	93	Only org files (=.org= and =.org_archive=) are read by the index. Other files are listed and can be opened, but their contents are not searched.
	94
	95	** Creating, renaming and trashing files
	96
	97	Right-click a file or folder in the sidebar for:
	98
	99	- New File… — creates a file in that folder (for a file, in the folder holding it). A name without an extension gets =.org=. A name like =projects/house= creates the =projects= folder too. Names can't start with =/= or contain =..=. The new file opens.
	100	- Rename… — renames the file or folder in place. The new name can't contain =/=. 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.
	101	- Show in Finder.
	102	- Move to Trash… — moves the file or folder to the Trash after you confirm. Open buffers of it close without saving. You can put it back from the Trash in Finder.
	103
	104	Right-click a root's header for New File…, Expand or Collapse, Show in Finder and Remove from Sidebar….
	105
	106	* Opening files
	107
	108	Click a file in the sidebar to open it. Other ways:
	109
	110	- Quick Open: File ▸ Quick Open… (=⌘P=; =C-x C-f= in the Emacs and Doom presets; =SPC SPC=, =SPC .= or =SPC f f= 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. Press =Return= to open the top match or click any match; =Escape= closes the list. Syncthing conflict copies are left out.
	111	- Finder: open an org file from Finder, with =open file.org= 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.
	112	- Links: following a =file:= link or an ID link opens the target file; see [[file:09-links.org][Links]].
	113	- Doom ex command: =:e FILE= opens =FILE=, relative to the current file's folder; =~= is expanded. A file that doesn't exist is reported as =No file FILE=.
	114
	115	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 /Saving/ below).
	116
	117	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.
	118
	119	** Files that aren't org
	120
	121	How a file opens depends on what it is:
	122
	123	- Org files (=.org=, =.org_archive=) open in the editor with org editing.
	124	- Text files 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 =Not an org file=, and the outline pane shows "No outline" when you turn it on. Files in these languages get syntax highlighting: shell (=.sh=, =.bash=, =.zsh=, =.zshrc=, =.bashrc=, =.profile=), Python, Emacs Lisp, C, C++, R, JavaScript, Java, Scheme, Clojure, Haskell, Rust, Go, Ruby, JSON, YAML, TOML and Lua.
	125	- Everything else (images, PDFs, audio, video, archives, binary files) shows a Quick Look preview in place of the editor, with =Open with Default App= and =Show in Finder= buttons below it. The preview is not a buffer.
	126
	127	Text files from Finder use Orgstar only if you choose it with Open With, since Orgstar is not their default app.
	128
	129	* Buffers
	130
	131	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 =find-buffer-visiting= does.
	132
	133	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.
	134
	135	** Buffer commands
	136
	137	\| Command \| Menu, or palette \| Mac \| Emacs preset \| Doom (normal state) \|
	138	\|---------------------+----------------------------------+-------------------+------------------------------+-------------------------------------------\|
	139	\| Switch to Buffer… \| Window ▸ Switch to Buffer… \| \| =C-x b=, =C-x C-b= \| =SPC b b=, =SPC b B=, =SPC ,=, =:b=, =:ls= \|
	140	\| Next Buffer \| Window ▸ Next Buffer \| =⇧⌘]=, =⌃Tab= \| =⇧⌘]=, =C-x <right>= \| =SPC b n=, =SPC b ]=, =] b=, =:bn= \|
	141	\| Previous Buffer \| Window ▸ Previous Buffer \| =⇧⌘[=, =⌃⇧Tab= \| =⇧⌘[=, =C-x <left>= \| =SPC b p=, =SPC b [=, =[ b=, =:bp= \|
	142	\| Last Buffer \| palette \| \| \| =SPC `= \|
	143	\| Close Buffer \| File ▸ Close Buffer \| =⌘W= \| =⌘W=, =C-x k= \| =SPC b k=, =SPC b d=, =:bd= \|
	144	\| Close Other Buffers \| palette \| \| \| =SPC b O= \|
	145	\| Close All Buffers \| palette \| \| \| =SPC b K= \|
	146
	147	Menu shortcuts (=⇧⌘]=, =⌘W= and the others) work in every preset. The Doom preset also has the Emacs preset's =C-x= keys in every state. The Mac preset's =⌃Tab= and =⌃⇧Tab= are in addition to the menu shortcuts.
	148
	149	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, =Tab= to complete the top choice, =Return= to switch, =Escape= to cancel.
	150
	151	Close Buffer closes the current buffer and shows the buffer you showed before it. With no buffer open, =⌘W= closes the window. In other windows (Agenda, Board and so on) =⌘W= closes that window. File ▸ Close Window (=⇧⌘W=) closes the window in front.
	152
	153	When you close buffers with unsaved edits, what happens depends on the save mode (see /Saving/ below): in automatic mode they are saved first; in explicit mode Orgstar asks =Save=, =Don't Save= or =Cancel= (=Save All= for several files). A buffer whose save fails or conflicts stays open.
	154
	155	** Buffer names
	156
	157	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 =post-forward-angle-brackets=:
	158
	159	#+BEGIN_SRC text
	160	notes.org<work>
	161	notes.org<home>
	162	notes.org<archive/2024>
	163	#+END_SRC
	164
	165	These names show in the window title, the tab bar and Switch to Buffer.
	166
	167	** The tab bar
	168
	169	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 =tab-bar= in =config.toml=.
	170
	171	- Click a tab to show its buffer. Hover to see the file's full path.
	172	- Click =×= to close a buffer. A dot replaces the =×= while the buffer has unsaved edits; clicking it also closes the buffer, with the same unsaved-changes handling as Close Buffer.
	173
	174	* Searching your notes
	175
	176	The search field in the toolbar searches every org file in your folders. Click it or choose Edit ▸ Search Notes (=⇧⌘F=; =SPC /= or =SPC s p= in Doom normal state) and type.
	177
	178	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.
	179
	180	How matching works:
	181
	182	- Orgstar searches heading titles and the text under each heading, in =.org= and =.org_archive= files. Text before the first heading and files that aren't org are not searched. Syncthing conflict copies are not searched.
	183	- Each word you type matches words that start with it: =proj= finds =project= and =projection=.
	184	- Every word must match within the same heading.
	185	- Up to 50 results show, best matches first.
	186	- Open buffers with unsaved edits are searched as they are in the buffer, not as they are on disk.
	187
	188	To find text inside the open file, use Edit ▸ Find (see [[file:02-the-editor.org][The editor]]).
	189
	190	* The outline pane
	191
	192	The outline pane lists the headings of the open org file, indented by level. Headings without a title show as =(untitled)=. 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".
	193
	194	The outline follows your edits after a short pause in typing.
	195
	196	** Backlinks
	197
	198	Under the outline, the backlinks pane lists headings in your folders that link to the current file (=Links to this file=) and to the heading at the caret (=Links to= 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 [[file:09-links.org][Links]].
	199
	200	** Inspector
	201
	202	View ▸ Show or Hide Columns and Clock (=⌥⌘I=) opens a pane on the right with column view and clocked time for the file or the current subtree. See [[file:04-outlines.org][Outlines]] and [[file:06-dates-and-clocking.org][Dates and clocking]].
	203
	204	* Saving
	205
	206	Settings ▸ General ▸ Save files has two modes; the =config.toml= setting is =save= in =[orgstar]=.
	207
	208	- Automatically, when typing stops (=automatic=, the default). Each buffer saves one second after its last change, including buffers that are not showing. Quitting and closing buffers save without asking.
	209	- Only with File ▸ Save (⌘S) (=explicit=). Nothing is written until you save. Closing a buffer or quitting with unsaved edits asks first.
	210
	211	\| Command \| Menu \| Shortcut \| Emacs preset \| Doom \|
	212	\|----------+----------------------+----------+--------------+--------------------------------------\|
	213	\| Save \| File ▸ Save \| =⌘S= \| =C-x C-s= \| =SPC f s=, =SPC b s=, =:w=; =:wq= and =:x= save and close the window \|
	214	\| Save All \| File ▸ Save All \| =⌥⌘S= \| =C-x s= \| =SPC b S= \|
	215
	216	Save is disabled for a read-only file. Save All is disabled when nothing is unsaved.
	217
	218	The modeline shows a dot while the current buffer has unsaved edits. Buffers with unsaved edits show a dot in the tab bar.
	219
	220	** How a save works
	221
	222	Orgstar does not assume it is the only program writing your files. Emacs, Syncthing, iCloud and Git may change them too. Each save:
	223
	224	1. 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 /External changes/ below). If they conflict with yours, nothing is written and the buffer has a conflict.
	225	2. 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.
	226	3. 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.
	227
	228	Every version a save displaces goes to recovery first (see /Recovery versions/ below). Reads and writes go through macOS file coordination, so iCloud and other coordinating programs see a consistent file.
	229
	230	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.
	231
	232	* External changes
	233
	234	Orgstar watches the files in your folders. When a file with an open buffer changes on disk:
	235
	236	- If the buffer has no unsaved edits, it reloads. The caret and folds stay where they were, mapped through the change.
	237	- 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.
	238	- If both sides changed the same lines differently, the buffer has a conflict.
	239
	240	Reloading or merging clears the buffer's undo history.
	241
	242	If an open file is deleted on disk, its buffer stays open with its text. Saving it writes the file again.
	243
	244	To throw away your unsaved edits and load the file as it is on disk, run Revert to File on Disk from the palette (=:e= in Doom). Your edits go to recovery.
	245
	246	** Conflicts
	247
	248	When a buffer conflicts with its file, automatic saving stops for that buffer, the =Conflict= button appears in the toolbar, and the conflict sheet opens. The sheet shows the differences: lines marked =-= are on disk, lines marked =+= are in your version, with three lines of context around each change. Choose:
	249
	250	\| Button \| What it does \|
	251	\|--------------------+------------------------------------------------------------------------------------------------------------------\|
	252	\| Keep Mine \| Writes your version over the file. The disk version goes to recovery. This is the default button. \|
	253	\| Use Disk Version \| Loads the file as it is on disk. Your version goes to recovery. \|
	254	\| Merge with Markers \| Puts both sets of changes in the buffer, as =git merge= leaves a conflict: non-conflicting changes merged, conflicting lines between markers. Your version as it was goes to recovery. \|
	255	\| Decide Later \| Closes the sheet. The conflict stays; click =Conflict= in the toolbar to reopen it. \|
	256
	257	After Merge with Markers the buffer holds blocks like this, which you edit and save:
	258
	259	#+BEGIN_SRC text
	260	<<<<<<< yours
	261	- [ ] Call the plumber on Monday
	262	=======
	263	- [X] Call the plumber
	264	>>>>>>> disk
	265	#+END_SRC
	266
	267	While a conflict is unresolved, saving that buffer does nothing except reopen the sheet.
	268
	269	** Syncthing conflict copies
	270
	271	When two devices change a file before Syncthing syncs them, Syncthing keeps one version as a conflict copy beside the file, named like =notes.sync-conflict-20260301-142233-ABCDEF7.org=. 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.
	272
	273	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 =-= are in the file (as the buffer holds it) and lines marked =+= are in the copy. Then choose:
	274
	275	\| Button \| What it does \|
	276	\|--------------------+------------------------------------------------------------------------------------\|
	277	\| Keep File \| Leaves the buffer as it is. \|
	278	\| Use Copy \| Replaces the buffer's text with the copy's. \|
	279	\| Merge with Markers \| 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. \|
	280
	281	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.
	282
	283	** Recovery versions
	284
	285	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 =~/Library/Application Support/Orgstar/Recovery=.
	286
	287	Run Recovery Versions… from the palette to see the open file's versions, newest first, each with its date and why it was kept:
	288
	289	\| Label \| Meaning \|
	290	\|-------------------------+-------------------------------------------------\|
	291	\| Your version, replaced \| Your buffer, before it was replaced \|
	292	\| Disk version, replaced \| The file on disk, before Orgstar wrote over it \|
	293	\| Sync conflict copy \| A Syncthing conflict copy you resolved \|
	294
	295	Select a version to see how it differs from the buffer (=-= in the buffer, =+= in the kept version). =Restore= puts the kept version's text in the buffer as one edit, which undo reverses; the buffer as it was goes to recovery first. =Show in Finder= reveals the kept file.
	296
	297	** iCloud
	298
	299	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.
	300
	301	* Encodings and line endings
	302
	303	Orgstar edits UTF-8 files, with or without a byte order mark.
	304
	305	- 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 =Read-only: not UTF-8=, the modeline shows =Read-only=, and commands that would change it report =This file is read-only.= Orgstar never writes such a file, and refiling or archiving into it is refused.
	306	- A file with a UTF-8 byte order mark keeps it when saved; the modeline shows =BOM=.
	307	- A file containing CRLF line endings shows =CRLF= in the modeline. Existing line endings are kept.
	308
	309	Orgstar does not convert between encodings or line endings.
	310
	311	* On iOS
	312
	313	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 [[file:14-ios.org][iOS]].

docs/manual/guide/02-the-editor.org added +325

		@@ -0,0 +1,325 @@
	1	#+TITLE: The editor
	2	#+DESCRIPTION: 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.
	3	#+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.
	4
	5	* What the editor shows
	6
	7	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.
	8
	9	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.
	10
	11	** Markup
	12
	13	View ▸ Show Markup (=⇧⌘M=; palette: Show or Hide Markup) is off by default. While it is off:
	14
	15	- Link brackets and targets are hidden, so =[[https://orgmode.org][Org]]= shows as an underlined =Org=, as with =org-link-descriptive=.
	16	- Emphasis markers (the =*= of bold, the === of verbatim and so on) are hidden when =org-hide-emphasis-markers= is on, which is the default.
	17	- Entities and sub- and superscripts are drawn as characters when =org-pretty-entities= is on, which is the default (see /Entities/ below).
	18
	19	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 =config.toml= setting is =show-markup= in =[orgstar]=.
	20
	21	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 =config.toml= as =org-hide-emphasis-markers= and =org-pretty-entities=. They also tell Orgstar how wide your Emacs displays text, so tag alignment, table alignment and =M-q= produce the same file Emacs would. Set them to match your Emacs.
	22
	23	** Styling
	24
	25	- Headings are bold and coloured by level (eight colours, as =org-level-1= to =org-level-8=). 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).
	26	- TODO and DONE keywords are bold, in the TODO or DONE colour, or a colour you set for that keyword.
	27	- Priorities, tags, timestamps, comments, keywords (=#+TITLE:= and the like), planning lines and drawers, block delimiters and tables each have a colour; footnotes, targets, macros and LaTeX share one.
	28	- Bold, italic, underline and strike-through are drawn as such; verbatim and code get their own colour and background.
	29	- Links are underlined.
	30	- Blocks (=#+BEGIN_…= to =#+END_…=), dynamic blocks and fixed-width lines are drawn on a shaded band across the whole width of the editor, as Emacs extends the =org-block= face. Code in src blocks is highlighted for its language (see [[file:11-code-blocks.org][Code blocks]]).
	31	- A folded heading shows an ellipsis after its line.
	32
	33	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 =config.toml=. See [[file:13-configuration.org][Configuration]]. Use a monospaced font: tags and tables line up by columns.
	34
	35	** Indentation and stars
	36
	37	Org files display as =org-indent-mode= 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.
	38
	39	Body lines that wrap continue under their own text: past leading spaces, and past a list item's bullet and checkbox, as =adaptive-wrap= does.
	40
	41	\| Setting \| Default \| What it does \|
	42	\|-----------------------------------------+---------+----------------------------------------------------------------------\|
	43	\| =org-startup-indented= \| on \| Indent bodies under their headings. =#+STARTUP: indent= or =noindent= overrides it per file. \|
	44	\| =org-hide-leading-stars= \| off \| Without indentation, show only a heading's last star. =#+STARTUP: hidestars= or =showstars= overrides it. \|
	45
	46	With both off, headings show all their stars and bodies start at the left margin. Both settings are in =config.toml= only, and are read when a file opens.
	47
	48	** Entities
	49
	50	When =org-pretty-entities= is on and Show Markup is off:
	51
	52	- An entity such as =\alpha= or =\to= is drawn as its character (=α=, =→=), taking one column.
	53	- =x_{1}= and =x^{2}= are drawn lowered and raised, without their markers. Braces are required: =x_1= is left as typed.
	54
	55	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.
	56
	57	** Inline images
	58
	59	Org ▸ Show or Hide Inline Images (=C-c C-x C-v= in the Emacs and Doom presets), as =org-toggle-inline-images= does, draws images in place of their links. The echo area reports how many images it displayed.
	60
	61	A line shows as an image when it holds nothing but a link to an image file with no description:
	62
	63	#+BEGIN_SRC org
	64	#+ATTR_ORG: :width 400
	65	[[file:images/diagram.png]]
	66	#+END_SRC
	67
	68	- Recognised extensions: =png=, =jpg=, =jpeg=, =gif=, =svg=, =webp=, =tif=, =tiff=, =bmp=, =heic=, =avif=.
	69	- Paths are relative to the file's folder; =~= is expanded. Remote URLs are not displayed.
	70	- =#+ATTR_ORG: :width N= sets the width in points. Images are never wider than the editor.
	71	- The link text is hidden while its image shows, except on the caret's line.
	72
	73	To show images when a file opens, add =#+STARTUP: inlineimages= to the file, or set =org-startup-with-inline-images = true= in =config.toml=. =#+STARTUP: noinlineimages= turns it off for one file.
	74
	75	** What isn't rendered
	76
	77	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.
	78
	79	* Folding
	80
	81	Headings, drawers and blocks fold as in Org. Folding is display only and isn't saved in the file.
	82
	83	** Cycling
	84
	85	\| Action \| Emacs and Mac presets \| Doom \| Org command \|
	86	\|--------------------------------+-----------------------+------------------------------------------------------+----------------------\|
	87	\| Cycle the heading or element at the caret \| =TAB= \| =TAB=, =z a=, =z c=, =z o= in normal state; =TAB= in visual state \| =org-cycle= \|
	88	\| Cycle the whole file \| =S-TAB= \| =S-TAB=, =z A= in normal state; =S-TAB= in visual state \| =org-global-cycle= \|
	89
	90	The palette titles are Cycle Visibility and Cycle Global Visibility; both are also in the Org menu.
	91
	92	=TAB= 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. =TAB= 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 =TAB= does what it otherwise would: in a table it moves to the next field, and in plain text it inserts a tab.
	93
	94	In Doom's insert state, =TAB= and =S-TAB= on a heading demote and promote it, and on a list item indent and outdent it, as Doom's =+org-indent-maybe-h= does. Use normal state to fold.
	95
	96	=S-TAB= cycles the whole file through three states, starting at the first:
	97
	98	1. Overview: top-level headings only.
	99	2. Contents: every heading, no bodies.
	100	3. Show all: everything, with blocks opened. Drawers stay folded.
	101
	102	Overview and contents also fold drawers before the first heading.
	103
	104	Clicking a heading's stars cycles that heading, as =TAB= does on it.
	105
	106	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.
	107
	108	** Folding when a file opens
	109
	110	With no =#+STARTUP= visibility option, a file opens with every heading shown. Drawers start folded (=org-cycle-hide-drawer-startup=, on by default); blocks start open (=org-cycle-hide-block-startup=, off by default). Both settings are in =config.toml=.
	111
	112	=#+STARTUP= options a file can set:
	113
	114	\| Option \| Effect when the file opens \|
	115	\|----------------------------------------+-------------------------------------------------------------\|
	116	\| =overview=, =fold= \| Top-level headings only \|
	117	\| =content= \| Every heading, no bodies \|
	118	\| =showall=, =nofold= \| Everything \|
	119	\| =show2levels=, =show3levels=, … \| Headings down to that level, no bodies \|
	120	\| =showeverything= \| Everything, including drawers and blocks; =VISIBILITY= properties are ignored \|
	121	\| =hidedrawers=, =nohidedrawers= \| Fold or open drawers \|
	122	\| =hideblocks=, =nohideblocks= \| Fold or open blocks \|
	123	\| =indent=, =noindent= \| Indent bodies under headings, or not \|
	124	\| =hidestars=, =showstars= \| Hide all stars but the last, or not \|
	125	\| =inlineimages=, =noinlineimages= \| Show image links as images, or not \|
	126	\| =align=, =noalign= \| Align every table, or not (=org-startup-align-all-tables=) \|
	127	\| =shrink= \| Narrow table columns that have width cookies \|
	128
	129	#+BEGIN_SRC org
	130	#+STARTUP: content hideblocks
	131	#+END_SRC
	132
	133	When the file sets a visibility (=overview=, =content=, =showall=, =showNlevels= and the like, but not =showeverything=), Orgstar then applies each heading's =VISIBILITY= property and folds subtrees tagged =ARCHIVE=, as =org-cycle-set-visibility-according-to-property= and =org-cycle-hide-archived-subtrees= do. =VISIBILITY= takes =folded=, =children=, =content= or =all=:
	134
	135	#+BEGIN_SRC org
	136	,* Reference
	137	:PROPERTIES:
	138	:VISIBILITY: folded
	139	:END:
	140	#+END_SRC
	141
	142	=#+STARTUP= options are read from the file and from any =#+SETUPFILE= it names, and take effect when the file opens. To apply changed options to an open file, close its buffer and open it again.
	143
	144	Narrowing to a subtree or block, and sparse trees, also hide text; see [[file:04-outlines.org][Outlines]].
	145
	146	* The modeline
	147
	148	The line under the editor shows, from the left:
	149
	150	\| Item \| Shown when \| What it shows \|
	151	\|----------------------------+------------------------------------+-------------------------------------------------------------------\|
	152	\| Evil state \| Doom preset \| =NORMAL=, =INSERT=, =VISUAL=, =V-LINE= or =V-BLOCK=, on a coloured tag \|
	153	\| Unsaved dot \| the buffer has unsaved edits \| a small dot \|
	154	\| Outline path \| the caret is under a heading \| the headings containing the caret, outermost first, as =Projects › House › Roof= \|
	155	\| Running clock \| a clock is running \| elapsed time and the clocked heading; click for Clock Out, Cancel Clock and Go to Clocked Entry \|
	156	\| Selection counts \| text is selected \| lines, words and characters in the selection, as =count-words-region= \|
	157	\| Line and column \| always \| =LINE:COLUMN= of the caret (the end of the selection) \|
	158	\| Word count \| always \| words in the whole file, as =count-words= \|
	159	\| Encoding notes \| the file differs from UTF-8 with LF \| =Read-only=, =BOM= and =CRLF=, in orange \|
	160	\| Git branch \| the file is in a Git repository \| the checked-out branch, or the first 7 characters of the commit when detached \|
	161
	162	Lines count from 1. Columns count from 0, as Emacs's =column-number-mode= 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.
	163
	164	The word count follows edits after a pause. The Git branch is read from the repository's =HEAD= file without running =git=, and checked again every 5 seconds; worktrees and submodules are followed.
	165
	166	The running clock is covered in [[file:06-dates-and-clocking.org][Dates and clocking]]; the evil states in [[file:03-keys.org][Keys and commands]].
	167
	168	* The echo area
	169
	170	The line under the modeline is the echo area, as Emacs's minibuffer. It shows:
	171
	172	- Messages from commands, such as =Stored: …= or =Not an org file=. A message stays for 4 seconds.
	173	- A pending key prefix. After =C-c= it shows =C-c-=. If you pause for about 0.6 seconds, a grid of the keys that can follow appears, each with the command it runs, or =+prefix= for a further prefix, as =which-key= shows them. =C-g= cancels the prefix and shows =Quit=. A sequence that isn't bound shows, for example, =C-c z is undefined=.
	174	- Prompts, when a command asks a question.
	175
	176	** Prompts
	177
	178	A prompt shows its question and a text field, which takes the keyboard.
	179
	180	- Type an answer and press =Return=.
	181	- 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. =Tab= completes the field to the first match. =Return= accepts the first match when the prompt requires one of its choices, and the typed text otherwise. Clicking a choice accepts it.
	182	- Prompts that take several values, such as tags separated by colons, complete only the part after the last separator.
	183	- =Escape= cancels the prompt; the command reports =Quit=.
	184
	185	Date prompts also show a date picker, and =S-<left>=, =S-<right>=, =S-<up>= and =S-<down>= move the date by a day or a week; see [[file:06-dates-and-clocking.org][Dates and clocking]]. TODO keywords and tags with fast-selection keys show a key menu instead of a text field; see [[file:05-todos-and-tags.org][TODOs and tags]].
	186
	187	When a prompt closes, the keyboard goes back to the editor.
	188
	189	* Completion
	190
	191	Complete at Point (=completion-at-point=) completes the word before the caret from what Org knows at that position.
	192
	193	\| Preset \| Key \|
	194	\|--------+----------------------------------------------------------\|
	195	\| Emacs \| =C-M-i= \|
	196	\| Doom \| =C-SPC= or =C-@= 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 \|
	197	\| Mac \| no key; run Complete at Point from the palette, or bind one in =keymap.toml= \|
	198
	199	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.
	200
	201	\| Key \| In the list \|
	202	\|-----------------------------+----------------------------------------------------------------------------\|
	203	\| =C-n=, =<down>=, =C-j= \| Next candidate; past the last one the selection goes back to what you typed \|
	204	\| =C-p=, =<up>=, =C-k= \| Previous candidate \|
	205	\| =TAB= \| Insert the selected candidate; with none selected, insert the part all candidates share \|
	206	\| =RET= \| Insert the selected candidate; with none selected, close the list and insert a newline \|
	207	\| =ESC= \| Close the list; the key then does what it otherwise would \|
	208	\| =C-g= \| Close the list \|
	209
	210	The list follows what you type and closes when nothing matches. Candidates are those that start with what you typed.
	211
	212	What is completed, by position:
	213
	214	\| Where \| Candidates \|
	215	\|----------------------------------------------+----------------------------------------------------------------\|
	216	\| =#+= at the start of a line \| keyword names (=TITLE=, =STARTUP=, =OPTIONS=, …), in upper and lower case \|
	217	\| After =#+STARTUP:= \| startup options \|
	218	\| After =#+OPTIONS:= \| export options \|
	219	\| After =#+DATE:= \| today's date as a timestamp \|
	220	\| After =#+EXCLUDE_TAGS:=, =#+SELECT_TAGS:=, =#+LANGUAGE:=, =#+PRIORITIES:= \| the usual values \|
	221	\| =<= and a letter at the start of a line \| structure templates (=<s= for a src block and so on); see [[file:11-code-blocks.org][Code blocks]] \|
	222	\| After =#+BEGIN_SRC= \| languages, then header arguments \|
	223	\| After =#+BEGIN: clocktable= \| clock table options \|
	224	\| After =[[= \| link types and the file's link abbreviations \|
	225	\| After =[[*= \| heading titles in the file \|
	226	\| After =\= \| entity names \|
	227	\| After =:= at the end of a heading \| tags: those in =#+TAGS=, or else tags used in the file and across your folders \|
	228	\| After the stars of an empty heading \| TODO keywords \|
	229	\| =:= at the start of a line in a property drawer \| property names the entry doesn't have yet \|
	230	\| =:= at the start of a line elsewhere \| drawer names \|
	231
	232	Elsewhere, Complete at Point reports =No match=. Completion is for org files only.
	233
	234	* Electric pairs
	235
	236	Typing an opening bracket inserts its closing partner, as =electric-pair-mode= does. The pairs are =()=, =[]=, ={}=, =<>= and a pair of double quotes.
	237
	238	- Typing a closing character in front of the same closer moves over it instead of inserting another, skipping whitespace before it.
	239	- =DEL= between an empty pair deletes both.
	240	- =RET= between a pair opens a blank line between them.
	241	- With text selected, typing an opening or closing character, or a double quote, wraps the selection.
	242	- No pair is inserted where it would leave the brackets unbalanced (=electric-pair-preserve-balance=).
	243
	244	Electric pairs are on by default and work in org files only. Set =electric-pair-mode = false= in =config.toml= to turn them off. Plain Emacs has them off; Doom pairs with smartparens.
	245
	246	* Spell checking
	247
	248	Spell checking is off by default. Turn it on for the current buffer with Check Spelling While Typing from the palette (=SPC t s= in Doom normal state); the echo area says whether it is now on or off. To have it on in every file, set =spell-check = true= in =config.toml=.
	249
	250	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.
	251
	252	Orgstar never corrects spelling on its own; automatic spelling correction, text replacement and smart quotes and dashes are off.
	253
	254	On iOS, spell checking is always on.
	255
	256	* Wrapping and filling
	257
	258	Long lines wrap at the edge of the editor by default. Truncate or Wrap Long Lines (=toggle-truncate-lines=) 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.
	259
	260	\| Preset \| Key \|
	261	\|--------+------------------------------\|
	262	\| Emacs \| =C-x x t= \|
	263	\| Doom \| =SPC t w= in normal state \|
	264	\| Mac \| palette only \|
	265
	266	To truncate lines in every file, set =org-startup-truncated = true= in =config.toml=. The default is to wrap, as Doom does; Emacs's own default is to truncate.
	267
	268	Wrapping is display only. To rewrap the text of a paragraph, use Org ▸ Fill Paragraph (=org-fill-paragraph=), which breaks the paragraph's lines at the fill column: =M-q= in the Emacs preset, =⌃⌘P= in the Mac preset, the Org menu or palette in Doom. The fill column is Settings ▸ Editing ▸ "M-q fills to column N" (80 by default, 40 to 200), or =fill-column= in =config.toml=. Orgstar has no auto-fill: lines are not broken as you type.
	269
	270	* View toggles
	271
	272	\| Toggle \| Menu \| Keys \| Default \| =config.toml= \| Scope \|
	273	\|-------------------------------+-------------------------------+-------------------------------------------------+---------+----------------------------------+----------------\|
	274	\| Show Markup \| View ▸ Show Markup \| =⇧⌘M= \| off \| =show-markup= \| every buffer \|
	275	\| Show Line Numbers \| View ▸ Show Line Numbers \| =⇧⌘L= \| on \| =display-line-numbers-type= \| every buffer \|
	276	\| Inline images \| Org ▸ Show or Hide Inline Images \| =C-c C-x C-v= (Emacs, Doom) \| off \| =org-startup-with-inline-images= \| current buffer \|
	277	\| Spell checking \| palette \| =SPC t s= (Doom) \| off \| =spell-check= \| current buffer \|
	278	\| Truncate long lines \| palette \| =C-x x t= (Emacs), =SPC t w= (Doom) \| off \| =org-startup-truncated= \| current buffer \|
	279
	280	Toggles that apply to the current buffer last until it closes; the =config.toml= setting decides how each file starts. Changing those settings, and =org-startup-indented= and =org-hide-leading-stars=, affects files opened afterwards, not buffers already open.
	281
	282	** Line numbers
	283
	284	Line numbers show in a margin left of the text, as =display-line-numbers-mode= 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.
	285
	286	* Themes
	287
	288	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 =config.toml=, under =[theme]= for both appearances, =[theme.light]= and =[theme.dark]= for one, and =[theme.todo]= for colours of TODO keywords. Settings ▸ Appearance ▸ Show Default Theme opens =default-theme.toml=, which lists every colour with its default value. Changes apply while Orgstar runs. See [[file:13-configuration.org][Configuration]].
	289
	290	* Undo
	291
	292	Each buffer has its own undo history, kept while other buffers show.
	293
	294	\| Action \| Menu \| Mac \| Emacs preset \| Doom (normal state) \|
	295	\|--------+-------------+---------+---------------------------+---------------------\|
	296	\| Undo \| Edit ▸ Undo \| =⌘Z= \| =⌘Z=, =C-/=, =C-_=, =C-x u= \| =u= \|
	297	\| Redo \| Edit ▸ Redo \| =⇧⌘Z= \| =⇧⌘Z= \| =C-r= \|
	298
	299	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.
	300
	301	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 [[file:01-files-and-folders.org][Files, folders and buffers]]. The Emacs preset has no redo key other than =⇧⌘Z=, and undo is linear, not Emacs's undo tree.
	302
	303	* Finding text in a file
	304
	305	Edit ▸ Find opens the find bar above the text.
	306
	307	\| Menu item \| Shortcut \| Emacs preset \| Doom \|
	308	\|-----------------------------------+----------+-------------------+-----------------------\|
	309	\| Edit ▸ Find ▸ Find… \| =⌘F= \| =C-s=, =C-r= \| =SPC s s= \|
	310	\| Edit ▸ Find ▸ Find and Replace… \| =⌥⌘F= \| =M-%= \| \|
	311	\| Edit ▸ Find ▸ Find Next \| =⌘G= \| \| \|
	312	\| Edit ▸ Find ▸ Find Previous \| =⇧⌘G= \| \| \|
	313	\| Edit ▸ Find ▸ Use Selection for Find \| =⌘E= \| \| \|
	314
	315	In the Emacs preset =C-s= and =C-r= open the find bar; they are not incremental search. In Doom, =:s/PATTERN/REPLACEMENT/= and =:%s/…/…/= with the =g= and =i= flags substitute with regular expressions on the current line or in the whole file.
	316
	317	To search all your files, use the toolbar's search field; see [[file:01-files-and-folders.org][Files, folders and buffers]].
	318
	319	* Accessibility
	320
	321	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.
	322
	323	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".
	324
	325	The editor keeps the system's keyboard navigation and text editing; the presets only add bindings. See [[file:03-keys.org][Keys and commands]].

docs/manual/guide/03-keys.org added +1014

		@@ -0,0 +1,1014 @@
	1	#+TITLE: Keys and commands
	2	#+DESCRIPTION: 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.
	3	#+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.
	4
	5	* Commands and keymaps
	6
	7	Each action has a command id such as =org.todo.cycle= and a title such as /Cycle TODO State/. 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 =keymap.toml= on top of the one you choose.
	8
	9	Ids starting with =org.= are Org commands and run only in Org files. Ids starting with =edit.= are text-system actions (movement, killing, find). Ids starting with =app.= are carried out by the app: saving, buffers, windows, export. =editor.= ids change how the editor behaves. The [[*Key reference][key reference]] at the end of this chapter lists every bound command with its keys in each preset.
	10
	11	* Choosing a preset
	12
	13	Choose a preset in Settings ▸ General ▸ Keys, or with =keymap= in the =[orgstar]= table of =config.toml= (see [[file:13-configuration.org][Configuration]]). The change applies at once.
	14
	15	\| Preset \| =config.toml= value \| What it is \|
	16	\|-+-+-\|
	17	\| Emacs \| ="emacs"= \| Emacs and Org keys: =C-f=, =C-k=, =C-x C-s=, =C-c C-t=, =M-RET=, =M-<left>=. The default. \|
	18	\| Mac \| ="mac"= \| Standard macOS text keys stay as they are. Org commands use Control-Command chords (=⌃⌘T=, =⌃⌘←=), which macOS text editing leaves free. \|
	19	\| Doom (Vim keys) \| ="doom"= \| Modal editing as in Doom Emacs with evil and evil-org: normal, insert and visual states, the =SPC= leader and =SPC m= local leader, plus the Emacs preset's Org keys in every state. \|
	20
	21	The Mac preset binds fewer commands than the others. It has no keys for links, export, agenda, capture, clocking, narrowing, sorting, properties, footnotes, code blocks or =C-c C-c=. Run those from the Org menu, from the command palette (=⇧⌘P=), from a menu shortcut (Agenda =⇧⌘A=, Capture =⇧⌘N=), or bind them yourself in =keymap.toml=.
	22
	23	The Mac preset binds Set Tags to =⌃⌘Q=, which is also the macOS Lock Screen shortcut. macOS takes that key first, so give Set Tags another key in =keymap.toml= (for example =C-s-g= for =⌃⌘G=) or run it from the Org menu.
	24
	25	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: =⌥←=, =⌘←=, =⇧= with arrows to select, and the Control keys the macOS text system provides (=⌃A=, =⌃E=, =⌃K= and so on). Menu shortcuts such as =⌘S= and =⌘F= work in every preset; see [[*Menu shortcuts][Menu shortcuts]].
	26
	27	* Option as Meta
	28
	29	Emacs notation writes Meta as =M-=. On a Mac keyboard Meta is the Option key, but Option also types characters such as =é= and =ø=. Settings ▸ General ▸ Option as Meta picks which Option keys act as Meta:
	30
	31	\| Choice \| =config.toml= (=option-as-meta= in =[orgstar]=) \| Effect \|
	32	\|-+-+-\|
	33	\| Left Option \| ="left"= \| The left Option key is Meta; the right one types characters. The default. \|
	34	\| Right Option \| ="right"= \| The right Option key is Meta. \|
	35	\| Both \| ="both"= \| Both are Meta; Option no longer types special characters in the editor. \|
	36	\| Neither \| ="none"= \| Option always types characters. Plain =M-= keys such as =M-f= cannot be typed; chords that also use Control or Command still work. \|
	37
	38	Option pressed together with Control or Command always counts as Meta, whatever this setting says, so chords such as =C-M-i= (=⌃⌥I=) and the Mac preset's =⌃⌥⌘←= always work.
	39
	40	* How keys reach commands
	41
	42	** Contexts
	43
	44	One key can run different commands depending on where the caret is. In the Emacs preset =M-<right>= 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.
	45
	46	\| Context \| Holds when \|
	47	\|-+-\|
	48	\| =heading= \| The caret is on a heading line. \|
	49	\| =item= \| The caret is inside a list item. \|
	50	\| =table= \| The caret is inside a table. \|
	51	\| =tblfm= \| The caret is on a =#+TBLFM:= line. \|
	52	\| =timestamp= \| The caret is on a timestamp. \|
	53	\| =property= \| The caret is on a property line in a property drawer. \|
	54	\| =src= \| The caret is inside a src block. \|
	55	\| =dblock= \| The caret is on the =#+BEGIN:= line of a dynamic block. \|
	56	\| =fold-line= \| The caret is on the first or last line of a drawer or block, where =TAB= folds it. \|
	57	\| =region= \| Text is selected. \|
	58	\| =speed= \| Speed keys are on, nothing is selected, and the caret is at the very start of a heading line. See [[*Speed keys][Speed keys]]. \|
	59
	60	When no binding for a key applies:
	61
	62	- In the Emacs and Mac presets, a single key goes to the text system and does what it normally does. =TAB= outside a heading, drawer edge or table types a tab; =S-<right>= on plain text extends the selection.
	63	- 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").
	64	- In the Doom preset the keys go on to the Vim engine (see [[*Vim editing (Doom preset)][Vim editing]]).
	65
	66	In a file that is not an Org file, =org.= commands never apply, so their keys fall through as above.
	67
	68	** Prefix keys and key hints
	69
	70	A prefix is a key that starts longer sequences, such as =C-c=, =C-c C-x=, =C-x n= or, in the Doom preset, =SPC= and =SPC m=. After a prefix, Orgstar waits for the next key and shows the keys typed so far in the echo area, followed by a dash: =C-c C-x-=.
	71
	72	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 =+prefix= when it leads to a longer sequence. This is Orgstar's version of =which-key=. The hints follow the current keymap, including your =keymap.toml=, and in the Doom preset the current evil state. A hint shows the highest-priority command for the key, which may not be the one that runs at the caret when the key has several contexts (=C-c C-c= is the common case).
	73
	74	=C-g= during a prefix cancels it; in the Emacs and Mac presets the echo area shows =Quit=. A sequence that nothing binds shows, for example, =C-c z is undefined= in the Emacs and Mac presets.
	75
	76	A key bound by itself cannot also be a prefix. When a keymap binds both =C-c= and =C-c C-t=, =C-c= always waits for the next key, so the binding for =C-c= alone never runs.
	77
	78	* The echo area
	79
	80	The echo area is the line at the bottom of the window, below the modeline. It shows, in order of priority:
	81
	82	- 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. =Return= answers, =Esc= cancels. When the question has choices, they are listed above the field and filtered as you type with fuzzy matching; =Tab= completes the best match. Date questions show a calendar, and =S-<left>=, =S-<right>=, =S-<up>= and =S-<down>= move the date by a day or a week, as in =org-read-date=.
	83	- Fast selection for TODO keywords and tags when the file defines keys for them (see [[file:05-todos-and-tags.org][TODOs and tags]]).
	84	- The pending prefix, such as =C-c C-x-=.
	85	- The last message from a command or from the keymap, for four seconds.
	86
	87	In the Doom preset the modeline shows the evil state as a tag: =NORMAL=, =INSERT=, =VISUAL=, =V-LINE= or =V-BLOCK=. See [[file:02-the-editor.org][The editor]] for the rest of the modeline.
	88
	89	* The command palette
	90
	91	The palette lists every command by title with its keys in the current keymap. Open it with:
	92
	93	- =⇧⌘P= or File ▸ Command Palette… in every preset,
	94	- =M-x= in the Emacs and Doom presets (=execute-extended-command=),
	95	- =SPC := in Doom normal state.
	96
	97	Type part of a title; matching is fuzzy and the best matches come first. =Return= runs the top match, a click runs any row, and =Esc= 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.
	98
	99	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.
	100
	101	The Org menu in the menu bar lists every =org.= command with its keys in the current keymap, and is a way to find a key without the palette.
	102
	103	* Menu shortcuts
	104
	105	These come from the menu bar and work in every preset. In the Doom preset, keys with =⌘= always go to the menus.
	106
	107	\| Menu \| Item \| Key \|
	108	\|-+-+-\|
	109	\| Orgstar \| Settings… \| =⌘,= \|
	110	\| Orgstar \| Edit Config File \| =⌥⌘,= \|
	111	\| File \| Add Folder… \| =⇧⌘O= \|
	112	\| File \| Quick Open… \| =⌘P= \|
	113	\| File \| Command Palette… \| =⇧⌘P= \|
	114	\| File \| Capture… \| =⇧⌘N= \|
	115	\| File \| Close Buffer (closes other windows themselves) \| =⌘W= \|
	116	\| File \| Close Window \| =⇧⌘W= \|
	117	\| File \| Save \| =⌘S= \|
	118	\| File \| Save All \| =⌥⌘S= \|
	119	\| Edit ▸ Find \| Find… \| =⌘F= \|
	120	\| Edit ▸ Find \| Find and Replace… \| =⌥⌘F= \|
	121	\| Edit ▸ Find \| Find Next \| =⌘G= \|
	122	\| Edit ▸ Find \| Find Previous \| =⇧⌘G= \|
	123	\| Edit ▸ Find \| Use Selection for Find \| =⌘E= \|
	124	\| Edit \| Cancel Running Block \| =⌘.= \|
	125	\| Edit \| Search Notes \| =⇧⌘F= \|
	126	\| View \| Show Markup \| =⇧⌘M= \|
	127	\| View \| Show Line Numbers \| =⇧⌘L= \|
	128	\| View \| Show or Hide Columns and Clock \| =⌥⌘I= or =⌥⌘O= (see below) \|
	129	\| Window \| Agenda \| =⇧⌘A= \|
	130	\| Window \| Board \| =⇧⌘B= \|
	131	\| Window \| Next Buffer \| =⇧⌘]= \|
	132	\| Window \| Previous Buffer \| =⇧⌘[= \|
	133
	134	View ▸ Show or Hide Outline, Show or Hide Backlinks and Show Tab Bar, Window ▸ Switch to Buffer…, and the items of File ▸ Export have no shortcut. The Columns and Clock item declares both =⌥⌘I= and =⌥⌘O=, and only one of them takes effect.
	135
	136	With Settings ▸ Capture ▸ "⌃⌥Space opens Capture from any app" on (the default), =⌃⌥Space= opens the Capture window from any application (see [[file:08-capture.org][Capture]]).
	137
	138	* Speed keys
	139
	140	With =org-use-speed-commands= set to =true= in =config.toml=, single letters typed at the very start of a heading line, before the stars, run commands instead of inserting text (=org-speed-commands=). Anywhere else the letters type as usual. The setting is off by default and has no checkbox in Settings.
	141
	142	Speed keys work in the Emacs and Mac presets, and in the Doom preset in insert state. The full list is in the [[*Speed keys reference][speed keys reference]].
	143
	144	* Customizing keys: keymap.toml
	145
	146	Your own bindings go in =keymap.toml= in the configuration folder: =$XDG_CONFIG_HOME/orgstar/keymap.toml= when =XDG_CONFIG_HOME= is set, otherwise =~/.config/orgstar/keymap.toml=. 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 =~/Library/Application Support/Orgstar/=, that copy is read until one exists in the configuration folder; changes to it are not picked up automatically, so run Reload Keymap after editing it.
	147
	148	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 =mode=.
	149
	150	** Format
	151
	152	The file is a list of =[[bind]]= tables, one per binding:
	153
	154	#+BEGIN_SRC toml
	155	# C-c t cycles the TODO keyword.
	156	[[bind]]
	157	keys = "C-c t"
	158	command = "org.todo.cycle"
	159	#+END_SRC
	160
	161	\| Field \| Required \| Meaning \|
	162	\|-+-+-\|
	163	\| =keys= \| yes \| The key sequence, in Emacs notation, chords separated by spaces. \|
	164	\| =command= \| yes \| A command id, or ="none"= to unbind. \|
	165	\| =when= \| no \| A context from the table in [[*Contexts][Contexts]]. Without it the binding holds everywhere. \|
	166	\| =mode= \| no \| An evil state for the Doom preset: ="normal"=, ="insert"= or ="visual"=. \|
	167
	168	The [[Key reference][key reference]] gives each command's id after its title. Commands no preset binds are listed under [[Unbound commands][Unbound commands]]. A typo in a command id is not caught when the file loads; pressing the key shows =Unknown command= and the id.
	169
	170	Orgstar reads a subset of TOML: =[[bind]]= headers, =key = value= lines, basic ="..."= and literal ='...'= strings, =true= and =false=, integers, and =#= comments. Arrays, inline tables and multi-line strings are not supported.
	171
	172	** Key notation
	173
	174	\| Notation \| Key \|
	175	\|-+-\|
	176	\| =C-= \| Control (=⌃=) \|
	177	\| =M-= \| Meta: Option (=⌥=), as set in [[*Option as Meta][Option as Meta]] \|
	178	\| =S-= \| Shift (=⇧=) \|
	179	\| =s-= \| Command (=⌘=) \|
	180	\| =a=, =%=, =/= \| A single character \|
	181	\| =TAB=, =RET=, =SPC=, =ESC=, =DEL= \| Tab, Return, Space, Escape, Delete (backspace) \|
	182	\| =<left>=, =<right>=, =<up>=, =<down>= \| Arrow keys \|
	183	\| =<home>=, =<end>=, =<prior>=, =<next>= \| Home, End, Page Up, Page Down \|
	184	\| =<delete>= \| Forward delete (=⌦=) \|
	185	\| =<f1>= to =<f12>= \| Function keys \|
	186
	187	Modifiers combine: =C-M-s-<left>= is =⌃⌥⌘←=. =<tab>=, =<return>=, =<escape>= and =<backspace>= are accepted as other names for =TAB=, =RET=, =ESC= and =DEL=, and =<backtab>= for =S-TAB=.
	188
	189	Shift with a letter is written as the capital letter: =S-a= and =A= are the same key, and so are =C-S-h= and =C-H=. With other keys Shift stays a modifier: =S-TAB=, =S-<up>=, =M-S-RET=.
	190
	191	A backslash in a basic string must be doubled. These two lines are the same key, =⌃⌘\=:
	192
	193	#+BEGIN_SRC toml
	194	keys = "C-s-\\"
	195	keys = 'C-s-\'
	196	#+END_SRC
	197
	198	** Priority
	199
	200	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 =when= therefore takes its keys everywhere, hiding every context-specific preset binding for them. A binding with =when= is tried first only in its context; elsewhere the preset's bindings still apply.
	201
	202	#+BEGIN_SRC toml
	203	# M-RET in a table inserts a row; on headings and items it does what the preset says.
	204	[[bind]]
	205	keys = "M-RET"
	206	command = "org.table.insert-row"
	207	when = "table"
	208	#+END_SRC
	209
	210	** Unbinding
	211
	212	Set =command= to ="none"= to remove a key. A ="none"= binding without =when= hides every earlier binding of exactly those keys, so the key goes to the text system (or, in the Doom preset, to Vim):
	213
	214	#+BEGIN_SRC toml
	215	# Leave C-t to macOS's transpose and C-k to its kill.
	216	[[bind]]
	217	keys = "C-t"
	218	command = "none"
	219	[[bind]]
	220	keys = "C-k"
	221	command = "none"
	222	#+END_SRC
	223
	224	Limitations:
	225
	226	- A ="none"= binding with =when= has no effect. You cannot unbind a key in one context only; bind it to another command in that context instead.
	227	- Unbinding a prefix does not remove the longer sequences under it. Unbinding =C-c C-x= leaves =C-c C-x C-i= and the rest working. Unbind each sequence you want gone.
	228
	229	** Doom states
	230
	231	In the Doom preset every binding belongs to a state. A binding without =mode= never runs in the Doom preset, and a binding with =mode= never runs in the Emacs or Mac preset. =mode = "visual"= covers visual, visual-line and visual-block. To bind a key in more than one state, write one table per state:
	232
	233	#+BEGIN_SRC toml
	234	# SPC n a opens the agenda.
	235	[[bind]]
	236	keys = "SPC n a"
	237	command = "app.agenda"
	238	mode = "normal"
	239
	240	# C-c n inserts a heading in normal and insert state.
	241	[[bind]]
	242	keys = "C-c n"
	243	command = "org.heading.insert"
	244	mode = "normal"
	245	[[bind]]
	246	keys = "C-c n"
	247	command = "org.heading.insert"
	248	mode = "insert"
	249	#+END_SRC
	250
	251	=mode= is not checked when the file loads. Any value other than =normal=, =insert= or =visual= (including =visual-line=) makes a binding that never runs.
	252
	253	** More examples
	254
	255	#+BEGIN_SRC toml
	256	# Mac preset: ⌃⌘L inserts a link, ⌃⌘E opens the export sheet, ⌃⌘X runs C-c C-c.
	257	[[bind]]
	258	keys = "C-s-l"
	259	command = "org.link.insert"
	260	[[bind]]
	261	keys = "C-s-e"
	262	command = "app.export-dialog"
	263	[[bind]]
	264	keys = "C-s-x"
	265	command = "org.ctrl-c-ctrl-c"
	266
	267	# Emacs preset: C-c b opens the board, C-c r reloads this file.
	268	[[bind]]
	269	keys = "C-c b"
	270	command = "app.board"
	271	[[bind]]
	272	keys = "C-c r"
	273	command = "app.reload-keymap"
	274
	275	#+END_SRC
	276
	277	** Reloading and errors
	278
	279	Orgstar watches the configuration folder and reloads =keymap.toml= when you save it. It also reloads when you change the preset, and when you run Reload Keymap (=app.reload-keymap=, in the palette, and =SPC h r r= in Doom normal state), which shows =Keymap reloaded=.
	280
	281	Problems are reported in the echo area with the line number, for example =keymap.toml: line 12: unknown context tabel (and 1 more)=. A binding with bad or missing =keys=, a missing =command=, an unknown =when=, or a table other than =[[bind]]= 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.
	282
	283	** Importing from Emacs
	284
	285	Settings ▸ General ▸ Import from Emacs… reads your Emacs or Doom configuration and offers, among other things, the key bindings it finds: =global-set-key=, =keymap-global-set=, =define-key=, =keymap-set=, =evil-define-key= and Doom's =map!= with =:leader=, =:localleader=, state keywords and =:prefix=. Bindings to commands Orgstar has are appended to =keymap.toml= under a =# Imported from Emacs.= comment. See [[file:15-alongside-emacs.org][Alongside Emacs]].
	286
	287	* Vim editing (Doom preset)
	288
	289	The Doom preset edits modally, as Doom Emacs does with =evil=, =evil-org=, =evil-surround=, =evil-snipe= and =evil-nerd-commenter=. 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.
	290
	291	** How keys are handled
	292
	293	Each key goes first to the keymap for the current state, then to the Vim engine:
	294
	295	1. Keys with =⌘= go to the menus.
	296	2. If a Vim command is half typed (after =d=, ="a=, =3= and so on), the key goes to Vim.
	297	3. Otherwise the keymap gets the key. A prefix such as =SPC=, =g=, =z=, =[=, =]=, =C-c= or =C-x= 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.
	298	4. Anything the keymap does not take goes to Vim, as typed. In insert state, keys Vim does not handle are typed as text.
	299
	300	Two consequences:
	301
	302	- Keymap commands do not take counts or registers. Once you type a count or a register, the following keys go straight to Vim, so =3gj= moves three screen lines even in an Org file, where =gj= alone moves by headings.
	303	- A sequence the keymap does not complete is replayed into Vim. =SPC= followed by a key the leader does not bind runs Vim's =SPC= (move right) and then that key, instead of reporting the sequence as undefined.
	304
	305	** States
	306
	307	\| State \| Enter with \| Leave with \|
	308	\|-+-+-\|
	309	\| Normal \| =ESC=, =C-[= or =C-g= from insert state; =ESC= from visual \| — \|
	310	\| Insert \| =i=, =a=, =I=, =A=, =o=, =O=, =c= commands, =cc=, =C=, block =I=, =A=, =c= \| =ESC=, =C-[=, =C-g= \|
	311	\| Visual \| =v= \| =v=, =ESC= \|
	312	\| Visual line \| =V= \| =V=, =ESC= \|
	313	\| Visual block \| =C-v= \| =C-v=, =ESC= \|
	314
	315	Leaving insert state moves the caret back one character, as in Vim. A mouse click leaves visual state. In the keymap, ="visual"= is the state name for all three visual states.
	316
	317	In insert state, =C-w= deletes the word before the caret and =C-u= 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 (=TAB= and =S-TAB= on headings, items and tables, =C-t= and =C-d=, =C-S-h/j/k/l=, =C-SPC= for completion) and ordinary typing.
	318
	319	** Motions
	320
	321	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.
	322
	323	\| Keys \| Moves \|
	324	\|-+-\|
	325	\| =h=, =l=, =<left>=, =<right>=, =DEL= \| Left, right; =DEL= is =h=. Stays on the line. \|
	326	\| =j=, =k=, =<down>=, =<up>= \| Down, up, keeping the column. \|
	327	\| =gj=, =gk= \| Down, up by screen lines in wrapped text. In Org files the keymap takes =g j= and =g k= first; see below. \|
	328	\| =+=, =-=, =RET= \| First non-blank of the next or previous line. In Org files =RET= runs Act at Point instead. \|
	329	\| =w=, =b=, =e=, =ge= \| Next word start, previous word start, word end, previous word end. \|
	330	\| =W=, =B=, =E=, =gE= \| The same for blank-separated WORDs. \|
	331	\| =0=, =<home>= \| Start of the line. \|
	332	\| =^= \| First non-blank of the line. \|
	333	\| =$=, =<end>= \| End of the line; with a count, of the line count − 1 lines down. \|
	334	\| =g_= \| Last non-blank of the line. \|
	335	\| =gg=, =G= \| First line, last line; with a count, that line. The column is kept (=evil-start-of-line= nil). \|
	336	\| =f= /x/, =F= /x/, =t= /x/, =T= /x/ \| To, or to just before, the next or previous /x/ on the line. \|
	337	\| =;=, =,= \| Repeats the last =f=, =F=, =t= or =T=, forward or reversed. \|
	338	\| =s= /xy/, =S= /xy/ \| evil-snipe: to the next or previous /xy/ on the line. All-lowercase /xy/ matches case-insensitively. Not available after an operator. \|
	339	\| =%= \| The bracket matching the next =()=, =[]= or ={}= on the line. \|
	340	\| ={=, =}= \| Previous, next blank line. \|
	341	\| =/=, =?= \| Asks in the echo area for a regular expression and searches forward or backward, wrapping around the file. \|
	342	\| =n=, =N= \| Repeats the last search in the same or the opposite direction. \|
	343	\| =*=, =#= \| Searches forward or backward for the whole word under the caret. \|
	344	\| =C-d=, =C-u= \| Down, up 15 lines; with a count, that many lines. \|
	345	\| ='= /a/, =`= /a/ \| To mark /a/: its line's first non-blank, or its exact position. See [[*Marks and jumps][Marks and jumps]]. \|
	346
	347	Search patterns are ICU regular expressions as macOS uses them, close to PCRE; Emacs and Vim regexp syntax such as =$...$= or =\<= does not work. =:noh= is accepted and does nothing; searches are not highlighted.
	348
	349	=H=, =M= and =L= are not implemented.
	350
	351	** Operators
	352
	353	\| Keys \| Does \|
	354	\|-+-\|
	355	\| =d= /motion/ \| Deletes. =dd= deletes lines. \|
	356	\| =c= /motion/ \| Deletes and enters insert state. =cc= keeps the line's indentation; =cw= changes to the end of the word, as =ce=. \|
	357	\| =y= /motion/ \| Yanks (copies). =yy= yanks lines. \|
	358	\| =>= /motion/, =<= /motion/ \| Indents or outdents lines by 8 spaces (=evil-shift-width=, which Doom sets to Org's =tab-width=). =>>= and =<<= act on lines. \|
	359	\| =g~= /motion/, =gu= /motion/, =gU= /motion/ \| Toggles case, lowercases, uppercases. =g~~=, =guu=, =gUU= act on lines. \|
	360	\| =gc= /motion/ \| Comments or uncomments lines with =#= (=evilnc-comment-operator=). =gcc= acts on lines. See [[*Commenting][Commenting]]. \|
	361
	362	Counts multiply: =2d3w= deletes six words. Doubling an operator with a count acts on that many lines: =3dd=.
	363
	364	Single-key changes:
	365
	366	\| Keys \| Does \|
	367	\|-+-\|
	368	\| =x=, =<delete>= \| Deletes the character under the caret (count: that many, within the line). \|
	369	\| =X= \| Deletes the character before the caret. \|
	370	\| =D=, =C= \| Deletes, or changes, to the end of the line. \|
	371	\| =Y= \| Yanks to the end of the line (=evil-want-Y-yank-to-eol=, as Doom sets it). \|
	372	\| =p=, =P= \| Pastes after or before the caret; whole lines go below or above the current line. A count pastes that many times. \|
	373	\| =J= \| Joins the next line (count: that many lines) with one space. \|
	374	\| =~= \| Toggles the case of the character under the caret and moves right. \|
	375	\| =r= /x/ \| Replaces the character under the caret (count: that many) with /x/; =r RET= splits the line. \|
	376	\| =u=, =C-r= \| Undo, redo, with counts. \|
	377	\| =.= \| Repeats the last change. \|
	378	\| =ZZ= \| Saves the file. It does not close anything. \|
	379	\| =ZQ= \| Not available; shows a message. \|
	380
	381	=o= and =O= 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.
	382
	383	** Text objects
	384
	385	After an operator, or in visual state to select, =i= takes the inner object and =a= the object with its surrounding space or delimiters.
	386
	387	\| Keys \| Object \|
	388	\|-+-\|
	389	\| =iw=, =aw=, =iW=, =aW= \| Word, WORD. \|
	390	\| =i"=, =a"=, =i'=, =a'=, =i`=, =a`= \| Quoted text on the line. \|
	391	\| =i(=, =a(=, =i)=, =a)=, =ib=, =ab= \| Parentheses. \|
	392	\| =i[=, =a[=, =i]=, =a]= \| Square brackets. \|
	393	\| =i{=, =a{=, =i}=, =a}=, =iB=, =aB= \| Braces. \|
	394	\| =i<=, =a<=, =i>=, =a>= \| Angle brackets. \|
	395	\| =ip=, =ap= \| Paragraph: lines up to a blank line. \|
	396	\| =ie=, =ae= \| Org object at the caret: emphasis, a link, a timestamp, a footnote reference, an entity, a macro and the like (=evil-org-inner-object=, =evil-org-an-object=). =ie= on emphasis takes the text inside the markers, on a link its description. With no object at the caret, the element. \|
	397	\| =iE=, =aE= \| Org element: a paragraph, a list, a table, a block, a drawer (=evil-org-inner-element=, =evil-org-an-element=). \|
	398	\| =ir=, =ar= \| Org greater element: the list, table, drawer, block or section that contains the element (=evil-org-inner-greater-element=, =evil-org-a-greater-element=). \|
	399	\| =iR=, =aR= \| Org subtree: =aR= is the heading and its subtree, =iR= its contents without the heading line (=evil-org-inner-subtree=, =evil-org-a-subtree=). \|
	400
	401	Tag objects (=it=, =at=) and sentence objects (=is=, =as=) are not available.
	402
	403	** Counts and registers
	404
	405	A count is digits before a command; =0= only counts after another digit. A register is ="= and a name before the count and command: ="ayy=, ="a3dd=, ="ap=.
	406
	407	\| Register \| Holds \|
	408	\|-+-\|
	409	\| ="a= to ="z= \| Named registers. Yanking or deleting into =A= to =Z= appends to the lowercase one. Writing to a named register leaves the clipboard alone. \|
	410	\| ="0= \| The last yank. \|
	411	\| =""=, ="+=, ="*= \| The system clipboard. This is the unnamed register: every yank, delete and change without a register goes to the clipboard, and =p= without a register pastes from it. \|
	412	\| ="_= \| The black hole: deletes without saving the text. \|
	413
	414	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 ="1= to ="9=, and the read-only registers such as ="%=, are not available.
	415
	416	Named registers, the yank register, marks, macros and the jump list belong to the buffer: each open file has its own set, and they are gone when the buffer closes or Orgstar quits. Only the clipboard is shared.
	417
	418	** Repeat
	419
	420	=.= repeats the last change made in normal state, including text typed in insert state that the change began: =ciwfoo ESC= then =.= changes the next word to =foo=. A count before =.= replaces the original count.
	421
	422	Changes made from visual or visual-block state, visual =S= surrounds, and keymap commands (such as =M-l= or =SPC m t=) are not repeated by =.=.
	423
	424	** Macros
	425
	426	\| Keys \| Does \|
	427	\|-+-\|
	428	\| =q= /a/ \| Starts recording keys into macro register /a/ (a letter or digit). The echo area shows =Defining keyboard macro…=. \|
	429	\| =q= \| Stops recording: =Keyboard macro defined=. \|
	430	\| =@= /a/ \| Plays macro /a/. A count plays it that many times. \|
	431	\| =@@= \| Plays the last macro played. \|
	432
	433	A macro replays the keys you typed, including keymap commands, leader keys and insert-state typing. Keys with =⌘= are not recorded. Macros are kept apart from text registers: ="ap= does not paste a macro, and ="ay= does not change one. Macros can call macros up to 20 deep.
	434
	435	** Marks and jumps
	436
	437	=m= /a/ sets mark /a/ (any letter) at the caret. Marks move with the text as you edit. ='= /a/ goes to the first non-blank of the mark's line, =`= /a/ to its exact position. =''= and =``= go back to where the last jump started.
	438
	439	Jumps are =G=, =gg=, =%=, ={=, =}=, =n=, =N=, =*=, =#=, ='=, =`=, and searches with =/= and =?=. Each jump adds its starting point to the jump list, which keeps the last 100. =C-o= goes back through the list and =C-i= forward again. A new jump after =C-o= drops the places you went back past.
	440
	441	Uppercase marks are per buffer like lowercase ones; there are no file marks.
	442
	443	** Visual states
	444
	445	=v= selects characters, =V= whole lines, =C-v= a rectangular block. Motions and text objects extend the selection; =o= moves the caret to the other end. =gv= in normal state selects the last visual selection again.
	446
	447	In visual and visual-line state:
	448
	449	\| Keys \| Does \|
	450	\|-+-\|
	451	\| =d=, =x= \| Deletes the selection. \|
	452	\| =c= \| Deletes it and enters insert state. \|
	453	\| =y= \| Yanks it. \|
	454	\| =>=, =<= \| Indents or outdents its lines. \|
	455	\| =~=, =u=, =U=, =g~=, =gu=, =gU= \| Toggles case, lowercases, uppercases. \|
	456	\| =gc= \| Comments or uncomments its lines. \|
	457	\| =J= \| Joins its lines. \|
	458	\| =p=, =P= \| Replaces it with the clipboard or a register; the replaced text goes to the clipboard. \|
	459	\| =S= /x/ \| Surrounds it with /x/ (see below). Linewise selections get the delimiters on lines of their own. \|
	460	\| =v=, =V=, =C-v= \| Switches to another visual state, or leaves when it is the current one. \|
	461	\| =TAB=, =S-TAB= \| Cycles visibility, as in normal state. \|
	462
	463	The Emacs preset's Org keys (=C-c ...=, =M-h/j/k/l=, =M-<left>= and so on) also work in visual state.
	464
	465	In visual-block state:
	466
	467	\| Keys \| Does \|
	468	\|-+-\|
	469	\| Motions, =o=, =O= \| Change the block; =o= and =O= move the caret to the opposite corner. \|
	470	\| =$= \| Extends every line of the block to its end. \|
	471	\| =d=, =x= \| Deletes the block. \|
	472	\| =y= \| Yanks the block's lines, joined by newlines. \|
	473	\| =c= \| Deletes the block and enters insert state; what you type is copied to every line when you press =ESC=. \|
	474	\| =I=, =A= \| Inserts before or after the block on every line. =A= pads short lines with spaces; after =$=, it appends at each line's end. \|
	475	\| =r= /x/ \| Replaces every character of the block with /x/. \|
	476	\| =~=, =u=, =U= \| Toggles case, lowercases, uppercases the block. \|
	477	\| =>=, =<= \| Indents or outdents the block's lines. \|
	478	\| =v=, =V= \| Switches to visual or visual-line state. \|
	479
	480	Block =I=, =A= and =c= 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.
	481
	482	** Surround
	483
	484	As =evil-surround=:
	485
	486	\| Keys \| Does \|
	487	\|-+-\|
	488	\| =ys= /motion/ /x/ \| Surrounds the motion's text with /x/: =ys$*= makes the rest of the line bold. Trailing blanks stay outside. \|
	489	\| =ys= =i= /obj/ /x/, =ys= =a= /obj/ /x/ \| Surrounds a text object: ~ysiw=~ wraps the word in ~=~ for verbatim. \|
	490	\| =yss= /x/ \| Surrounds the line, from its first non-blank. \|
	491	\| =ds= /x/ \| Deletes the surrounding /x/. With an opening bracket, the blanks inside go too. \|
	492	\| =cs= /x/ /y/ \| Changes the surrounding /x/ to /y/. \|
	493	\| =S= /x/ (visual) \| Surrounds the selection. \|
	494
	495	\| /x/ \| Delimiters \|
	496	\|-+-\|
	497	\| =(=, =[=, ={=, =<= \| The pair with a space inside each: =( text )=. \|
	498	\| =)=, =b= \| =(text)= \|
	499	\| =]=, =r= \| =[text]= \|
	500	\| =}=, =B= \| ={text}= \|
	501	\| =>=, =a= \| =<text>= \|
	502	\| =SPC= \| A space on each side. \|
	503	\| Any other character \| That character on both sides: =*=, =/=, =_=, =+=, ~=~, =~=, ="=, ='=. \|
	504
	505	For =ds= and =cs=, brackets are found across lines; any other character is matched on the caret's line. Tags (=t=) and functions (=f=) are not supported.
	506
	507	** Commenting
	508
	509	=gc= with a motion or text object, =gcc= for lines, and =gc= in visual state toggle Org comments. Lines get =#= 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 =comment-or-uncomment-region= in Org, as =evilnc-comment-operator= runs it.
	510
	511	** Org keys in normal state
	512
	513	Besides the leader, the preset binds these evil-org and Doom keys in normal state. =TAB=, =S-TAB= and =RET= in normal state, and the Emacs preset's Org keys in every state, are listed in the [[*Key reference][key reference]].
	514
	515	\| Keys \| Command \|
	516	\|-+-\|
	517	\| =TAB= \| Cycle Visibility (=org-cycle=). Also in visual state. \|
	518	\| =S-TAB= \| Cycle Global Visibility. Also in visual and insert state. \|
	519	\| =RET= \| Act at Point (=+org/dwim-at-point=). \|
	520	\| =z a=, =z c=, =z o= \| Cycle Visibility. All three cycle; there is no separate open and close. \|
	521	\| =z A= \| Cycle Global Visibility. \|
	522	\| =g h= \| Up to Parent Heading. \|
	523	\| =g j=, =g k= \| Next or previous heading at the same level. evil-org moves by element here; Orgstar moves by heading only. In files that are not Org files these keys fall through to Vim's screen-line motions. \|
	524	\| =] h=, =[ h= \| Next or previous heading at the same level. \|
	525	\| =] b=, =[ b= \| Next or previous buffer. \|
	526	\| =M-h=, =M-j=, =M-k=, =M-l= \| =M-<left>=, =M-<down>=, =M-<up>=, =M-<right>=: promote, move down, move up, demote on headings; the same for items; move columns and rows in tables. Also in insert and visual state. \|
	527	\| =M-H=, =M-J=, =M-K=, =M-L= \| The =M-S-= arrow forms: subtree promote and demote, table row and column insert and delete. Also in insert and visual state. \|
	528	\| =C-S-h=, =C-S-j=, =C-S-k=, =C-S-l= \| The =S-= arrow forms: TODO keyword, priority, timestamp and property value changes. Also in insert state. \|
	529
	530	** The leader
	531
	532	=SPC= in normal state is Doom's leader and =SPC m= its local leader for Org. Pause after =SPC= to see the key hints.
	533
	534	\| Keys \| Command \|
	535	\|-+-\|
	536	\| =SPC ,= \| Switch to Buffer… (=app.buffer.switch=) \|
	537	\| =SPC .= \| Quick Open… (=app.quick-open=) \|
	538	\| =SPC /= \| Search Notes (=app.search=) \|
	539	\| =SPC := \| Command Palette… (=app.palette=) \|
	540	\| =SPC `= \| Last Buffer (=app.buffer.last=) \|
	541	\| =SPC b B= \| Switch to Buffer… (=app.buffer.switch=) \|
	542	\| =SPC b K= \| Close All Buffers (=app.buffer.kill-all=) \|
	543	\| =SPC b O= \| Close Other Buffers (=app.buffer.kill-others=) \|
	544	\| =SPC b S= \| Save All Buffers (=app.save-all=) \|
	545	\| =SPC b [= \| Previous Buffer (=app.buffer.previous=) \|
	546	\| =SPC b ]= \| Next Buffer (=app.buffer.next=) \|
	547	\| =SPC b b= \| Switch to Buffer… (=app.buffer.switch=) \|
	548	\| =SPC b d= \| Close Buffer (=app.buffer.kill=) \|
	549	\| =SPC b k= \| Close Buffer (=app.buffer.kill=) \|
	550	\| =SPC b n= \| Next Buffer (=app.buffer.next=) \|
	551	\| =SPC b p= \| Previous Buffer (=app.buffer.previous=) \|
	552	\| =SPC b s= \| Save (=app.save=) \|
	553	\| =SPC f f= \| Quick Open… (=app.quick-open=) \|
	554	\| =SPC f s= \| Save (=app.save=) \|
	555	\| =SPC h r r= \| Reload Keymap (=app.reload-keymap=) \|
	556	\| =SPC n l= \| Store Link (=org.link.store=) \|
	557	\| =SPC o a= \| Agenda (=app.agenda=) \|
	558	\| =SPC q q= \| Quit Orgstar (=app.quit=) \|
	559	\| =SPC s p= \| Search Notes (=app.search=) \|
	560	\| =SPC s s= \| Find (=edit.find=) \|
	561	\| =SPC SPC= \| Quick Open… (=app.quick-open=) \|
	562	\| =SPC t s= \| Check Spelling While Typing (=editor.toggle-spell-check=) \|
	563	\| =SPC t w= \| Truncate or Wrap Long Lines (=editor.toggle-truncate-lines=) \|
	564	\| =SPC X= \| Capture… (=app.capture=) \|
	565	\| =SPC z t= \| Clock Report (=app.clock.report=) \|
	566	\| =SPC m '= \| Edit Block (=org.edit-special=) \|
	567	\| =SPC m .= \| Go to Heading… (=org.goto=) \|
	568	\| =SPC m A= \| Archive Subtree (=app.archive=) \|
	569	\| =SPC m b -= \| Insert Table Rule (=org.table.insert-hline=) \|
	570	\| =SPC m b a= \| Align Table (=org.table.align=) \|
	571	\| =SPC m b d c= \| Delete Table Column (=org.table.delete-column=) \|
	572	\| =SPC m b d r= \| Delete Table Row (=org.table.kill-row=) \|
	573	\| =SPC m b i c= \| Insert Table Column (=org.table.insert-column=) \|
	574	\| =SPC m b i h= \| Insert Table Rule (=org.table.insert-hline=) \|
	575	\| =SPC m b i r= \| Insert Table Row (=org.table.insert-row=) \|
	576	\| =SPC m b r= \| Recalculate Table (=org.table.recalc-all=) \|
	577	\| =SPC m c E= \| Set Effort (=org.effort.set=) \|
	578	\| =SPC m c R= \| Clock Report (=app.clock.report=) \|
	579	\| =SPC m c c= \| Cancel Clock (=app.clock.cancel=) \|
	580	\| =SPC m c g= \| Go to Clocked Entry (=app.clock.goto=) \|
	581	\| =SPC m c i= \| Clock In (=app.clock.in=) \|
	582	\| =SPC m c o= \| Clock Out (=app.clock.out=) \|
	583	\| =SPC m d T= \| Insert Inactive Timestamp (=org.timestamp.inactive=) \|
	584	\| =SPC m d d= \| Set Deadline (=org.deadline=) \|
	585	\| =SPC m d s= \| Schedule (=org.schedule=) \|
	586	\| =SPC m d t= \| Insert Timestamp (=org.timestamp.active=) \|
	587	\| =SPC m e h h= \| Export to HTML (=app.export.html=) \|
	588	\| =SPC m e h o= \| Export to HTML and Open (=app.export.html-open=) \|
	589	\| =SPC m e l p= \| Export to PDF with Emacs (=app.export.pdf=) \|
	590	\| =SPC m e m m= \| Export to Markdown (=app.export.markdown=) \|
	591	\| =SPC m h= \| Toggle Heading (=org.heading.toggle=) \|
	592	\| =SPC m i= \| Toggle Item (=org.item.toggle=) \|
	593	\| =SPC m l i= \| Store ID Link (=org.id.store-link=) \|
	594	\| =SPC m l l= \| Insert Link… (=org.link.insert=) \|
	595	\| =SPC m l s= \| Store Link (=org.link.store=) \|
	596	\| =SPC m o= \| Set Property… (=org.property.read-and-set=) \|
	597	\| =SPC m p d= \| Lower Priority (=org.priority.down=) \|
	598	\| =SPC m p p= \| Set Priority… (=org.priority.set=) \|
	599	\| =SPC m p u= \| Raise Priority (=org.priority.up=) \|
	600	\| =SPC m q= \| Set Tags (=org.tags.set=) \|
	601	\| =SPC m r r= \| Refile… (=app.refile=) \|
	602	\| =SPC m s A= \| Archive Subtree (=app.archive=) \|
	603	\| =SPC m s N= \| Widen (=org.widen=) \|
	604	\| =SPC m s S= \| Sort Entries (=org.sort=) \|
	605	\| =SPC m s a= \| Toggle ARCHIVE Tag (=org.archive.toggle-tag=) \|
	606	\| =SPC m s c= \| Clone Subtree with Time Shift (=org.subtree.clone=) \|
	607	\| =SPC m s d= \| Cut Subtree (=org.subtree.cut=) \|
	608	\| =SPC m s h= \| Promote Subtree (=org.subtree.promote=) \|
	609	\| =SPC m s j= \| Move Subtree Down (=org.subtree.down=) \|
	610	\| =SPC m s k= \| Move Subtree Up (=org.subtree.up=) \|
	611	\| =SPC m s l= \| Demote Subtree (=org.subtree.demote=) \|
	612	\| =SPC m s n= \| Narrow to Subtree (=org.narrow.subtree=) \|
	613	\| =SPC m s r= \| Refile… (=app.refile=) \|
	614	\| =SPC m s s= \| Sparse Tree… (=org.sparse-tree=) \|
	615	\| =SPC m t= \| Cycle TODO State (=org.todo.cycle=) \|
	616	\| =SPC m x= \| Toggle Checkbox (=org.checkbox.toggle=) \|
	617
	618	** Ex commands
	619
	620	=:= opens a prompt in the echo area. Orgstar understands these:
	621
	622	\| Command \| Does \|
	623	\|-+-\|
	624	\| =:w=, =:write= \| Saves the file. \|
	625	\| =:q=, =:quit=, =:q!= \| Closes the window. Closing the last window quits Orgstar, which asks about unsaved changes as usual. \|
	626	\| =:wq=, =:wq!=, =:x= \| Saves, then closes the window. \|
	627	\| =:e= /file/, =:edit= /file/ \| Opens /file/, relative to the current file's folder; =~= is expanded. \|
	628	\| =:e=, =:e!=, =:edit=, =:edit!= \| Reloads the file from disk; unsaved changes go to the recovery versions. \|
	629	\| =:bn=, =:bnext= \| Next buffer. \|
	630	\| =:bp=, =:bprevious=, =:bN=, =:bNext= \| Previous buffer. \|
	631	\| =:bd=, =:bdelete=, =:bd!=, =:bw=, =:bwipeout= \| Closes the buffer. \|
	632	\| =:b=, =:buffer=, =:ls=, =:buffers=, =:files= \| Asks for a buffer to switch to. \|
	633	\| =:= /N/ \| Goes to line /N/. \|
	634	\| =:s/= /pattern/ =/= /replacement/ =/= /flags/ \| Replaces on the current line. Flags: =g= for every match on the line, =i= to ignore case. =\1= in the replacement is the first group. \|
	635	\| =:%s/= /pattern/ =/= /replacement/ =/= /flags/ \| The same on every line. \|
	636	\| =:noh=, =:nohlsearch= \| Accepted; does nothing. \|
	637
	638	Anything else shows =Not an editor command=. Ranges other than =%=, the =c= flag, =:g=, =:normal= and =:set= are not available, and =:= does not work in visual state.
	639
	640	** Not available
	641
	642	Things evil users may reach for that Orgstar does not have: =H=, =M=, =L=, =zz=, =zt= and the other scroll and fold =z= commands except =za=, =zc=, =zo= and =zA=; =C-a= and =C-x= to increment numbers; =gi=, =g;=, =gJ=; replace state (=R=); =&=; =q:=; the numbered and read-only registers; repeating evil-snipe with =;= or =,=; tag and sentence text objects. =C-d= and =C-u= move a fixed 15 lines rather than half the window.
	643
	644	* Keys in other windows
	645
	646	The block editor, opened by Edit Block (=C-c '=) or Edit Table Field (=C-c `=), is a plain editor with its own two bindings in every preset: =C-c '= or =⌘↩= saves and returns, =Esc= or =C-c C-k= leaves without saving. It does not use the Doom preset's Vim editing or your =keymap.toml=. See [[file:11-code-blocks.org][Code blocks]].
	647
	648	The Agenda window has its own keys, modelled on =org-agenda-mode=, which =keymap.toml= does not change:
	649
	650	\| Key \| Does \|
	651	\|-+-\|
	652	\| =RET= \| Opens the selected entry. \|
	653	\| =f=, =b= \| Next or previous span (agenda views). \|
	654	\| =.= \| Back to today (agenda views). \|
	655	\| =/= \| Filter by tags, categories, effort and regexp (=+cat-tag<0:10-/regexp/=). \|
	656	\| =\= \| Tag filter (=+tag-tag=). \|
	657	\| ~=~ \| Regexp filter (=-re= drops matches). \|
	658	\| =_= \| Effort filter (=<0:30=, =>1:00=, ~=1:00~). \|
	659	\| =<= \| Filter to the selected entry's category, or clear the category filter. \|
	660	\| \vert{} \| Removes every filter. \|
	661	\| =l= \| Log mode on or off (agenda views). \|
	662	\| =g=, =r= \| Rebuilds the views. \|
	663	\| =t= \| Cycle TODO State. \|
	664	\| =+=, =-= \| Raise or lower priority. \|
	665	\| =:= \| Set tags. \|
	666	\| =S-<right>=, =S-<left>= \| Moves the entry's timestamp a day later or earlier. \|
	667	\| =I=, =O=, =X= \| Clock in, clock out, cancel the clock. \|
	668	\| =$= \| Archives the entry. \|
	669	\| =m=, =u=, =U= \| Marks, unmarks, unmarks all entries for bulk actions. \|
	670	\| =B= \| Bulk action on the marked entries. \|
	671	\| =C-c C-t= \| Cycle TODO State. \|
	672	\| =C-c C-s=, =C-c C-d= \| Schedule, set deadline. \|
	673	\| =C-c C-q= \| Set tags. \|
	674	\| =C-c C-w= \| Refile. \|
	675	\| =C-c $=, =C-c C-x C-s= \| Archive. \|
	676
	677	See [[file:07-agenda.org][Agenda]] for what these do. In the Capture window, typing a template's key picks it, =⌘↩= files the entry and =Esc= cancels; see [[file:08-capture.org][Capture]].
	678
	679	* iOS and iPadOS
	680
	681	With a hardware keyboard, the iOS app runs the Emacs preset's bindings, whatever preset the Mac uses. It does not read =keymap.toml= and has no Vim editing.
	682
	683	- Option acts as Meta when the key starts a binding (=M-RET=, =M-<left>=); otherwise Option types characters as usual.
	684	- Keys with =⌘= are left to iOS.
	685	- Movement and editing keys bound to =edit.= commands (=C-a=, =C-e=, =C-k= and so on) are left to the iOS text system, except undo.
	686	- Of the =app.= commands only clock in, clock out, cancel clock and go to clocked entry run from keys. Other =app.= keys, and editor commands such as narrowing, do nothing.
	687	- A pending prefix shows as a message, without key hints.
	688
	689	The on-screen key bar's buttons run what their Emacs keys run at the caret (Fold is =TAB=, Promote is =M-<left>=, TODO is =C-c C-t=). See [[file:14-ios.org][iOS]].
	690
	691	* Key reference
	692
	693	Every binding in the three presets, generated from the presets themselves. Each command's id, for =keymap.toml=, follows its title.
	694
	695	- Emacs lists the Emacs preset's keys.
	696	- Mac lists the Mac preset's keys, with macOS symbols. =⇥= is Tab and =↩= Return.
	697	- Doom lists the keys the Doom preset adds. Every Emacs-preset key that starts with =C-c= or =C-x=, the =M-= and =S-= arrow keys, =M-RET=, =M-S-RET=, =C-RET= and =M-x= 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.
	698
	699	When a key appears in several rows, it runs the command whose condition holds at the caret: for example =M-<right>= 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.
	700
	701	** Movement and the region
	702
	703	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	704	\|-+-+-+-+-\|
	705	\| Forward Character (=edit.forward-char=) \| =C-f= \| — \| — \| Moves forward one character (=forward-char=). \|
	706	\| Backward Character (=edit.backward-char=) \| =C-b= \| — \| — \| Moves back one character (=backward-char=). \|
	707	\| Next Line (=edit.next-line=) \| =C-n= \| — \| — \| Moves down one line (=next-line=). \|
	708	\| Previous Line (=edit.previous-line=) \| =C-p= \| — \| — \| Moves up one line (=previous-line=). \|
	709	\| Beginning of Line (=edit.beginning-of-line=) \| =C-a= \| — \| — \| Moves to the start of the line (=move-beginning-of-line=). \|
	710	\| End of Line (=edit.end-of-line=) \| =C-e= \| — \| — \| Moves to the end of the line (=move-end-of-line=). \|
	711	\| Forward Word (=edit.forward-word=) \| =M-f= \| — \| — \| Moves forward one word (=forward-word=). \|
	712	\| Backward Word (=edit.backward-word=) \| =M-b= \| — \| — \| Moves back one word (=backward-word=). \|
	713	\| Beginning of Buffer (=edit.beginning-of-buffer=) \| =M-<= \| — \| — \| Moves to the start of the file (=beginning-of-buffer=). \|
	714	\| End of Buffer (=edit.end-of-buffer=) \| =M->= \| — \| — \| Moves to the end of the file (=end-of-buffer=). \|
	715	\| Scroll Up (=edit.scroll-up=) \| =C-v= \| — \| — \| Scrolls down one screen (=scroll-up-command=). \|
	716	\| Scroll Down (=edit.scroll-down=) \| =M-v= \| — \| — \| Scrolls up one screen (=scroll-down-command=). \|
	717	\| Recenter (=edit.recenter=) \| =C-l= \| — \| — \| Scrolls so the caret's line is in the middle of the window (=recenter-top-bottom=, without the cycling). \|
	718	\| Set Mark (=edit.set-mark=) \| =C-SPC= \| — \| — \| Sets the mark at the caret. Until the next command that is not a movement, movement keys extend the selection (=set-mark-command=). \|
	719	\| Quit (=edit.keyboard-quit=) \| =C-g= \| — \| — \| Drops the mark and the selection, and shows =Quit= (=keyboard-quit=). \|
	720	\| Select All (=edit.select-all=) \| =C-x h= \| — \| — \| Selects the whole file (=mark-whole-buffer=). \|
	721
	722	** Editing
	723
	724	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	725	\|-+-+-+-+-\|
	726	\| Delete Character (=edit.delete-char=) \| =C-d= \| — \| — \| Deletes the character after the caret (=delete-char=). \|
	727	\| Kill Word (=edit.kill-word=) \| =M-d= \| — \| — \| Deletes to the end of the word (=kill-word=). \|
	728	\| Kill Word Backward (=edit.backward-kill-word=) \| =M-DEL= \| — \| — \| Deletes to the start of the word (=backward-kill-word=). \|
	729	\| Kill Line (=edit.kill-line=) \| =C-k= \| — \| — \| Deletes to the end of the line, or the newline at its end, into the macOS kill buffer (=kill-line=). \|
	730	\| Kill Region (=edit.kill-region=) \| =C-w= \| — \| — \| Cuts the selection to the clipboard (=kill-region=). \|
	731	\| Copy Region (=edit.copy-region=) \| =M-w= \| — \| — \| Copies the selection to the clipboard (=kill-ring-save=). \|
	732	\| Yank (=edit.yank=) \| =C-y= \| — \| — \| Inserts the text last deleted with Kill Line, from the macOS kill buffer, not the clipboard (=yank=). There is no kill ring. \|
	733	\| Undo (=edit.undo=) \| =C-/=, =C-_=, =C-x u= \| — \| — \| Undoes the last change (=undo=). \|
	734	\| Transpose Characters (=edit.transpose-chars=) \| =C-t= \| — \| — \| Swaps the characters around the caret (=transpose-chars=). \|
	735	\| Find (=edit.find=) \| =C-s=, =C-r= \| — \| =SPC s s= (N) \| Opens the find bar. =C-s= and =C-r= both open it; there is no incremental search (=isearch-forward=). \|
	736	\| Find and Replace (=edit.replace=) \| =M-%= \| — \| — \| Opens the find bar with replace (=query-replace=). \|
	737	\| Find Next (=edit.find-next=) \| — \| — \| — \| Goes to the next match of the find bar's text. \|
	738	\| Find Previous (=edit.find-previous=) \| — \| — \| — \| Goes to the previous match. \|
	739	\| Use Selection for Find (=edit.use-selection-for-find=) \| — \| — \| — \| Puts the selection in the find bar. \|
	740	\| Complete at Point (=editor.complete=) \| =C-M-i= \| — \| =C-SPC= (I), =C-@= (I) \| Completes what is typed at the caret: =#+= keywords and their values, link types, entities, tags, TODO keywords, headings, drawers, properties, src languages and header arguments, and =<s=-style templates (=completion-at-point=). One candidate is inserted; several open a list. \|
	741	\| Fill Paragraph (=org.fill-paragraph=) \| =M-q= \| =⌃⌘P= \| — \| Refills the paragraph or list item to the fill column (=org-fill-paragraph=). \|
	742
	743	** Outline: visibility and narrowing
	744
	745	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	746	\|-+-+-+-+-\|
	747	\| Cycle Visibility (=org.cycle=) \| =TAB= \| =⇥= \| =TAB= (N, V), =z a= (N), =z c= (N), =z o= (N) \| 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 (=org-cycle=). Elsewhere, =TAB= types a tab in the Emacs and Mac presets. \|
	748	\| Cycle Global Visibility (=org.cycle-global=) \| =S-TAB= \| =⇧⇥= \| =S-TAB=, =z A= (N) \| Cycles the whole file through overview, contents and everything (=org-global-cycle=). \|
	749	\| Narrow to Subtree (=org.narrow.subtree=) \| =C-x n s= \| — \| =SPC m s n= (N) \| Shows only the current subtree (=org-narrow-to-subtree=). \|
	750	\| Narrow to Block (=org.narrow.block=) \| =C-x n b= \| — \| — \| Shows only the current block (=org-narrow-to-block=). \|
	751	\| Widen (=org.widen=) \| =C-x n w= \| — \| =SPC m s N= (N) \| Shows the whole file again (=widen=). \|
	752	\| Narrow to Subtree or Widen (=org.narrow.toggle=) \| — \| — \| — \| Narrows to the subtree, or widens when already narrowed (=org-toggle-narrow-to-subtree=). \|
	753	\| Sparse Tree… (=org.sparse-tree=) \| =C-c /= \| — \| =SPC m s s= (N) \| Asks for a match and shows only the matching entries and their context (=org-sparse-tree=). =C-c C-c= clears the highlights. \|
	754	\| Show or Hide Inline Images (=org.toggle-inline-images=) \| =C-c C-x C-v= \| — \| — \| Shows or hides image links as images (=org-toggle-inline-images=). \|
	755
	756	** Outline: headings and subtrees
	757
	758	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	759	\|-+-+-+-+-\|
	760	\| Next Heading (=org.heading.next=) \| =C-c C-n= \| =⌥⌘↓= \| — \| Moves to the next heading (=org-next-visible-heading=). \|
	761	\| Previous Heading (=org.heading.previous=) \| =C-c C-p= \| =⌥⌘↑= \| — \| Moves to the previous heading (=org-previous-visible-heading=). \|
	762	\| Next Heading at Same Level (=org.heading.forward-same-level=) \| =C-c C-f= \| — \| =g j= (N), =] h= (N) \| Moves to the next heading at the same level (=org-forward-heading-same-level=). \|
	763	\| Previous Heading at Same Level (=org.heading.backward-same-level=) \| =C-c C-b= \| — \| =g k= (N), =[ h= (N) \| Moves to the previous heading at the same level (=org-backward-heading-same-level=). \|
	764	\| Up to Parent Heading (=org.heading.up=) \| =C-c C-u= \| — \| =g h= (N) \| Moves to the parent heading (=outline-up-heading=). \|
	765	\| Go to Heading… (=org.goto=) \| =C-c C-j= \| — \| =SPC m .= (N) \| Asks for a heading of this file by its outline path and jumps to it (=org-goto=). \|
	766	\| Insert Heading (=org.heading.insert=) \| =M-RET= \| =⌘↩= \| — \| Inserts a heading at the current level; on a list item, see Insert Item (=org-meta-return=, =org-insert-heading=). \|
	767	\| Insert Heading After Subtree (=org.heading.insert-after-subtree=) \| =C-RET= \| =⌃⌘↩= \| — \| Inserts a heading after the current subtree (=org-insert-heading-respect-content=). \|
	768	\| Insert TODO Heading (=org.heading.insert-todo=) \| =M-S-RET= \| =⇧⌘↩= \| — \| Inserts a heading with the first TODO keyword (=org-insert-todo-heading=). \|
	769	\| Promote Heading (=org.heading.promote=) \| =M-<left>= \| =⌃⌘←= \| =M-h=, =C-d= (I), =S-TAB= (I) \| On a heading, raises it one level (=org-do-promote=). \|
	770	\| Demote Heading (=org.heading.demote=) \| =M-<right>= \| =⌃⌘→= \| =M-l=, =C-t= (I), =TAB= (I) \| On a heading, lowers it one level (=org-do-demote=). \|
	771	\| Promote Subtree (=org.subtree.promote=) \| =M-S-<left>= \| =⌃⌥⌘←= \| =M-H=, =SPC m s h= (N) \| On a heading, raises it and its subtree (=org-promote-subtree=). \|
	772	\| Demote Subtree (=org.subtree.demote=) \| =M-S-<right>= \| =⌃⌥⌘→= \| =M-L=, =SPC m s l= (N) \| On a heading, lowers it and its subtree (=org-demote-subtree=). \|
	773	\| Move Subtree Up (=org.subtree.up=) \| =M-<up>= \| =⌃⌥⌘↑= \| =M-k=, =SPC m s k= (N) \| On a heading, swaps the subtree with the one above (=org-move-subtree-up=). \|
	774	\| Move Subtree Down (=org.subtree.down=) \| =M-<down>= \| =⌃⌥⌘↓= \| =M-j=, =SPC m s j= (N) \| On a heading, swaps the subtree with the one below (=org-move-subtree-down=). \|
	775	\| Mark Subtree (=org.subtree.mark=) \| =C-c @= \| — \| — \| Selects the current subtree (=org-mark-subtree=). \|
	776	\| Cut Subtree (=org.subtree.cut=) \| =C-c C-x C-w= \| — \| =SPC m s d= (N) \| Cuts the subtree to the clipboard (=org-cut-subtree=). \|
	777	\| Copy Subtree (=org.subtree.copy=) \| =C-c C-x M-w= \| — \| — \| Copies the subtree to the clipboard (=org-copy-subtree=). \|
	778	\| Paste Subtree (=org.subtree.paste=) \| =C-c C-x C-y= \| — \| — \| Pastes a subtree from the clipboard, its levels adjusted to fit (=org-paste-subtree=). \|
	779	\| Clone Subtree with Time Shift (=org.subtree.clone=) \| =C-c C-x c= \| — \| =SPC m s c= (N) \| Asks for a count and a time shift, then inserts shifted copies of the subtree (=org-clone-subtree-with-time-shift=). \|
	780	\| Sort Entries (=org.sort=) \| =C-c ^= \| — \| =SPC m s S= (N) \| 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 (=org-sort=). \|
	781	\| Toggle Heading (=org.heading.toggle=) \| =C-c *= \| — \| =SPC m h= (N) \| Outside a table, turns headings into text and lines or items into headings (=org-toggle-heading=). \|
	782	\| Toggle COMMENT (=org.heading.toggle-comment=) \| =C-c ;= \| — \| — \| Adds or removes the =COMMENT= keyword (=org-toggle-comment=). \|
	783	\| Refile… (=app.refile=) \| =C-c C-w= \| =⌃⌘W= \| =SPC m r r= (N), =SPC m s r= (N) \| Asks for a target heading in your folders and moves the subtree there (=org-refile=). \|
	784	\| Archive Subtree (=app.archive=) \| =C-c C-x C-s=, =C-c $= \| =⌃⌘A= \| =SPC m A= (N), =SPC m s A= (N) \| Moves the subtree to the archive file (=org-archive-subtree=). \|
	785	\| Toggle ARCHIVE Tag (=org.archive.toggle-tag=) \| =C-c C-x a= \| — \| =SPC m s a= (N) \| Adds or removes the =ARCHIVE= tag (=org-toggle-archive-tag=). \|
	786	\| Archive to Archive Sibling (=org.archive.to-sibling=) \| =C-c C-x A= \| — \| — \| Moves the subtree under an =Archive= sibling heading (=org-archive-to-archive-sibling=). \|
	787
	788	** Lists and checkboxes
	789
	790	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	791	\|-+-+-+-+-\|
	792	\| Insert Item (=org.item.insert=) \| =M-RET= \| =⌘↩= \| — \| In a list, inserts a new item (=org-insert-item=). \|
	793	\| Insert Checkbox Item (=org.item.insert-checkbox=) \| =M-S-RET= \| =⇧⌘↩= \| — \| In a list, inserts a new item with a checkbox. \|
	794	\| Indent Item (=org.item.indent=) \| =M-<right>= \| =⌃⌘→= \| =M-l=, =C-t= (I) \| In a list, indents the item (=org-indent-item=). \|
	795	\| Outdent Item (=org.item.outdent=) \| =M-<left>= \| =⌃⌘←= \| =M-h=, =C-d= (I) \| In a list, outdents the item (=org-outdent-item=). \|
	796	\| Indent Item and Children (=org.item.indent-tree=) \| =M-S-<right>= \| =⌃⌥⌘→= \| =M-L=, =TAB= (I) \| In a list, indents the item and its children (=org-indent-item-tree=). \|
	797	\| Outdent Item and Children (=org.item.outdent-tree=) \| =M-S-<left>= \| =⌃⌥⌘←= \| =M-H=, =S-TAB= (I) \| In a list, outdents the item and its children (=org-outdent-item-tree=). \|
	798	\| Move Item Up (=org.item.up=) \| =M-<up>= \| =⌃⌥⌘↑= \| =M-k= \| In a list, swaps the item with the one above (=org-move-item-up=). \|
	799	\| Move Item Down (=org.item.down=) \| =M-<down>= \| =⌃⌥⌘↓= \| =M-j= \| In a list, swaps the item with the one below (=org-move-item-down=). \|
	800	\| Toggle Checkbox (=org.checkbox.toggle=) \| =C-c C-x C-b= \| =⌃⌘C= \| =SPC m x= (N) \| Checks or unchecks the item's checkbox (=org-toggle-checkbox=). \|
	801	\| Toggle Item (=org.item.toggle=) \| =C-c -= \| — \| =SPC m i= (N) \| Outside a table: on an item, cycles the list's bullet style; elsewhere turns lines into items and items into text (=org-ctrl-c-minus=). \|
	802
	803	** TODO, priority and tags
	804
	805	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	806	\|-+-+-+-+-\|
	807	\| Cycle TODO State (=org.todo.cycle=) \| =C-c C-t= \| =⌃⌘T= \| =SPC m t= (N) \| Cycles the TODO keyword; with fast-selection keys in =#+TODO=, asks for one (=org-todo=). \|
	808	\| Next TODO Keyword (=org.todo.next=) \| =S-<right>= \| — \| =C-S-l= (N, I) \| On a heading, sets the next keyword across all sequences (=org-shiftright=). \|
	809	\| Previous TODO Keyword (=org.todo.previous=) \| =S-<left>= \| — \| =C-S-h= (N, I) \| On a heading, sets the previous keyword (=org-shiftleft=). \|
	810	\| Raise Priority (=org.priority.up=) \| =S-<up>= \| =⌃⌘↑= \| =C-S-k= (N, I), =SPC m p u= (N) \| On a heading, raises the priority (=org-priority-up=). \|
	811	\| Lower Priority (=org.priority.down=) \| =S-<down>= \| =⌃⌘↓= \| =C-S-j= (N, I), =SPC m p d= (N) \| On a heading, lowers the priority (=org-priority-down=). \|
	812	\| Set Priority… (=org.priority.set=) \| =C-c ,= \| — \| =SPC m p p= (N) \| Asks for a priority; =SPC= removes it (=org-priority=). \|
	813	\| Set Priority A (=org.priority.set-a=) \| — \| — \| — \| Sets priority A. Bound only as a speed key. \|
	814	\| Set Priority B (=org.priority.set-b=) \| — \| — \| — \| Sets priority B. Bound only as a speed key. \|
	815	\| Set Priority C (=org.priority.set-c=) \| — \| — \| — \| Sets priority C. Bound only as a speed key. \|
	816	\| Remove Priority (=org.priority.remove=) \| — \| — \| — \| Removes the priority. Bound only as a speed key. \|
	817	\| Set Tags (=org.tags.set=) \| =C-c C-q= \| =⌃⌘Q= \| =SPC m q= (N) \| Sets the heading's tags, with fast selection when =#+TAGS= has keys (=org-set-tags-command=). \|
	818
	819	** Properties and column view
	820
	821	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	822	\|-+-+-+-+-\|
	823	\| Set Property… (=org.property.read-and-set=) \| =C-c C-x p= \| — \| =SPC m o= (N) \| Asks for a property and a value and sets it (=org-set-property=). \|
	824	\| Next Allowed Value (=org.property.next-value=) \| =S-<right>= \| — \| =C-S-l= (N, I) \| On a property line, sets the next allowed value (=org-property-next-allowed-value=). \|
	825	\| Previous Allowed Value (=org.property.previous-value=) \| =S-<left>= \| — \| =C-S-h= (N, I) \| On a property line, sets the previous allowed value (=org-property-previous-allowed-value=). \|
	826	\| Set Effort (=org.effort.set=) \| =C-c C-x e= \| — \| =SPC m c E= (N) \| Sets the =Effort= property, offering =Effort_ALL= values (=org-set-effort=). \|
	827	\| Column View (=org.columns=) \| =C-c C-x C-c= \| — \| — \| Shows the column view of the entries, read-only (=org-columns=). \|
	828	\| Insert Column View Table (=org.columns.insert-dblock=) \| =C-c C-x i= \| — \| — \| Inserts a =columnview= dynamic block (=org-columns-insert-dblock=). \|
	829	\| Update Dynamic Block (=org.dblock.update=) \| =C-c C-x C-u=, =C-c C-c= \| — \| — \| Updates the dynamic block at point, such as a clock table; =C-c C-c= does it on the block's =#+BEGIN= line (=org-update-dblock=). \|
	830
	831	** Dates and clocking
	832
	833	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	834	\|-+-+-+-+-\|
	835	\| Insert Timestamp (=org.timestamp.active=) \| =C-c .= \| =⌃⌘.= \| =SPC m d t= (N) \| Asks for a date and inserts an active timestamp, or changes the one at point (=org-timestamp=). \|
	836	\| Insert Inactive Timestamp (=org.timestamp.inactive=) \| =C-c != \| =⌃⌥⌘.= \| =SPC m d T= (N) \| Same, inactive (=org-timestamp-inactive=). \|
	837	\| Schedule (=org.schedule=) \| =C-c C-s= \| =⌃⌘S= \| =SPC m d s= (N) \| Asks for a date and sets =SCHEDULED= (=org-schedule=). \|
	838	\| Set Deadline (=org.deadline=) \| =C-c C-d= \| =⌃⌘D= \| =SPC m d d= (N) \| Asks for a date and sets =DEADLINE= (=org-deadline=). \|
	839	\| Increase Timestamp Part (=org.timestamp.up=) \| =S-<up>= \| =⌃⌘↑= \| =C-S-k= (N, I) \| On a timestamp, increases the part under the caret: year, month, day, hour or minute (=org-timestamp-up=). \|
	840	\| Decrease Timestamp Part (=org.timestamp.down=) \| =S-<down>= \| =⌃⌘↓= \| =C-S-j= (N, I) \| On a timestamp, decreases the part under the caret (=org-timestamp-down=). \|
	841	\| Timestamp One Day Later (=org.timestamp.day-later=) \| =S-<right>= \| =⌃⌘→= \| =C-S-l= (N, I) \| On a timestamp, moves it one day later (=org-timestamp-up-day=). \|
	842	\| Timestamp One Day Earlier (=org.timestamp.day-earlier=) \| =S-<left>= \| =⌃⌘←= \| =C-S-h= (N, I) \| On a timestamp, moves it one day earlier (=org-timestamp-down-day=). \|
	843	\| Evaluate Time Range (=org.timestamp.evaluate-range=) \| =C-c C-y= \| — \| — \| Shows how long the time range lasts, or updates a clock line (=org-evaluate-time-range=). \|
	844	\| Clock In (=app.clock.in=) \| =C-c C-x C-i= \| — \| =SPC m c i= (N) \| Starts the clock on the current entry (=org-clock-in=). \|
	845	\| Clock Out (=app.clock.out=) \| =C-c C-x C-o= \| — \| =SPC m c o= (N) \| Stops the clock (=org-clock-out=). \|
	846	\| Cancel Clock (=app.clock.cancel=) \| =C-c C-x C-q= \| — \| =SPC m c c= (N) \| Stops the clock and removes the running clock line (=org-clock-cancel=). \|
	847	\| Go to Clocked Entry (=app.clock.goto=) \| =C-c C-x C-j= \| — \| =SPC m c g= (N) \| Opens the entry the clock is running on (=org-clock-goto=). \|
	848	\| Clock Report (=app.clock.report=) \| — \| — \| =SPC z t= (N), =SPC m c R= (N) \| Opens the Clock Report window. \|
	849	\| Insert or Update Clock Table (=org.clock.report=) \| =C-c C-x C-r= \| — \| — \| Inserts a clock table, or updates the one at point (=org-clock-report=). \|
	850
	851	** Tables
	852
	853	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	854	\|-+-+-+-+-\|
	855	\| Create Table (=org.table.create=) \| =C-c= \vert{} \| =⌃⌘\= \| — \| Asks for a size and inserts an empty table (=org-table-create=). \|
	856	\| Next Table Field (=org.table.next-field=) \| =TAB= \| =⇥= \| =TAB= (I) \| In a table, aligns it and moves to the next field, adding a row at the end (=org-table-next-field=). \|
	857	\| Previous Table Field (=org.table.previous-field=) \| =S-TAB= \| =⇧⇥= \| =S-TAB= (I) \| In a table, moves to the previous field (=org-table-previous-field=). \|
	858	\| Next Table Row (=org.table.next-row=) \| =RET= \| =↩= \| =RET= (I) \| In a table, moves to the same field in the next row, adding a row at the end (=org-table-next-row=). \|
	859	\| Align Table (=org.table.align=) \| =C-c C-c= \| — \| =SPC m b a= (N) \| In a table, aligns it (=org-table-align=). \|
	860	\| Move Table Row Up (=org.table.row-up=) \| =M-<up>= \| =⌃⌘↑= \| =M-k= \| In a table, moves the row up (=org-table-move-row-up=). \|
	861	\| Move Table Row Down (=org.table.row-down=) \| =M-<down>= \| =⌃⌘↓= \| =M-j= \| In a table, moves the row down (=org-table-move-row-down=). \|
	862	\| Move Table Column Left (=org.table.column-left=) \| =M-<left>= \| =⌃⌘←= \| =M-h=, =C-d= (I) \| In a table, moves the column left (=org-table-move-column-left=). \|
	863	\| Move Table Column Right (=org.table.column-right=) \| =M-<right>= \| =⌃⌘→= \| =M-l=, =C-t= (I) \| In a table, moves the column right (=org-table-move-column-right=). \|
	864	\| Insert Table Column (=org.table.insert-column=) \| =M-S-<right>= \| =⌃⌥⌘→= \| =M-L=, =SPC m b i c= (N) \| In a table, inserts a column (=org-table-insert-column=). \|
	865	\| Delete Table Column (=org.table.delete-column=) \| =M-S-<left>= \| =⌃⌥⌘←= \| =M-H=, =SPC m b d c= (N) \| In a table, deletes the column (=org-table-delete-column=). \|
	866	\| Insert Table Row (=org.table.insert-row=) \| =M-S-<down>= \| =⌃⌥⌘↓= \| =M-J=, =SPC m b i r= (N) \| In a table, inserts a row (=org-table-insert-row=). \|
	867	\| Delete Table Row (=org.table.kill-row=) \| =M-S-<up>= \| =⌃⌥⌘↑= \| =M-K=, =SPC m b d r= (N) \| In a table, deletes the row (=org-table-kill-row=). \|
	868	\| Insert Table Rule (=org.table.insert-hline=) \| =C-c -= \| =⌃⌘-= \| =SPC m b -= (N), =SPC m b i h= (N) \| In a table, inserts a horizontal rule (=org-table-insert-hline=). \|
	869	\| Recalculate Table Row (=org.table.recalc=) \| =C-c *= \| — \| — \| In a table, recalculates the current row (=org-table-recalculate=). \|
	870	\| Recalculate Table (=org.table.recalc-all=) \| =C-c C-c= \| — \| =SPC m b r= (N) \| Recalculates the whole table; =C-c C-c= runs it on a =#+TBLFM= line (=org-table-recalculate= with =C-u=). \|
	871	\| Set Column Formula (=org.table.column-formula=) \| ~C-c =~ \| — \| — \| Asks for the column's formula, offering the stored one (=org-table-eval-formula=). \|
	872	\| Edit Table Field (=org.table.edit-field=) \| =C-c `= \| — \| — \| In a table, edits the field in a separate editor (=org-table-edit-field=). \|
	873	\| Shrink or Expand Table Column (=org.table.toggle-column-width=) \| =C-c TAB= \| — \| — \| In a table, shrinks or expands the column (=org-table-toggle-column-width=). \|
	874
	875	** Links and footnotes
	876
	877	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	878	\|-+-+-+-+-\|
	879	\| Open Link (=org.link.open=) \| =C-c C-o= \| — \| — \| Follows the link or timestamp at the caret (=org-open-at-point=). \|
	880	\| Insert Link… (=org.link.insert=) \| =C-c C-l= \| — \| =SPC m l l= (N) \| Asks for a link and description and inserts it, offering stored links (=org-insert-link=). \|
	881	\| Store Link (=org.link.store=) \| =C-c l= \| — \| =SPC m l s= (N), =SPC n l= (N) \| Stores a link to the current entry for a later Insert Link (=org-store-link=). \|
	882	\| Store ID Link (=org.id.store-link=) \| — \| — \| =SPC m l i= (N) \| Gives the entry an =ID= if needed and stores an =id:= link to it (=org-id-store-link=). \|
	883	\| Footnote Action (=org.footnote.action=) \| =C-c C-x f= \| — \| — \| On a reference, goes to its definition; on a definition, back to a reference; elsewhere inserts a footnote (=org-footnote-action=). \|
	884
	885	** Code blocks and C-c C-c
	886
	887	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	888	\|-+-+-+-+-\|
	889	\| Act at Point (C-c C-c) (=org.ctrl-c-ctrl-c=) \| =C-c C-c= \| — \| — \| 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, and refreshes the setup on a =#+= keyword line (=org-ctrl-c-ctrl-c=). After a sparse tree, the first =C-c C-c= only clears the highlights. More specific bindings take =C-c C-c= in tables, src blocks, =#+TBLFM= lines and dynamic blocks. \|
	890	\| Act at Point (=org.dwim=) \| — \| — \| =RET= (N) \| Doom's =+org/dwim-at-point=: follows a link, runs a src block, recalculates or aligns a table, toggles a checkbox, or switches a heading between TODO and done. \|
	891	\| Run Source Block (=org.babel.execute=) \| =C-c C-c= \| — \| — \| In a src block, runs it and inserts the results (=org-babel-execute-src-block=). \|
	892	\| Tangle File (=org.babel.tangle=) \| =C-c C-v t=, =C-c C-v C-t= \| — \| — \| Writes the file's src blocks to their tangle targets (=org-babel-tangle=). \|
	893	\| Insert Structure Template (=org.structure-template=) \| =C-c C-,= \| — \| — \| Asks for a block type and inserts the block, or wraps the selection (=org-insert-structure-template=). \|
	894	\| Edit Block (=org.edit-special=) \| =C-c '= \| — \| =SPC m '= (N) \| Edits the src, example or export block at point in a separate editor (=org-edit-special=). \|
	895
	896	** Agenda and capture
	897
	898	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	899	\|-+-+-+-+-\|
	900	\| Agenda (=app.agenda=) \| =C-c a= \| — \| =SPC o a= (N) \| Opens the Agenda window (=org-agenda=). \|
	901	\| Capture… (=app.capture=) \| =C-c c= \| — \| =SPC X= (N) \| Opens the Capture window (=org-capture=). \|
	902
	903	** Export
	904
	905	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	906	\|-+-+-+-+-\|
	907	\| Export… (=app.export-dialog=) \| =C-c C-e= \| — \| — \| Opens the export sheet (=org-export-dispatch=). \|
	908	\| Export to HTML (=app.export.html=) \| =C-c C-e h h= \| — \| =SPC m e h h= (N) \| Exports to HTML (=org-html-export-to-html=). \|
	909	\| Export to HTML and Open (=app.export.html-open=) \| =C-c C-e h o= \| — \| =SPC m e h o= (N) \| Exports to HTML and opens the result. \|
	910	\| Export to Markdown (=app.export.markdown=) \| =C-c C-e m m= \| — \| =SPC m e m m= (N) \| Exports to Markdown (=org-md-export-to-markdown=). \|
	911	\| Export to PDF with Emacs (=app.export.pdf=) \| =C-c C-e l p= \| — \| =SPC m e l p= (N) \| Exports to PDF through Emacs (=org-latex-export-to-pdf=). \|
	912	\| Export to LaTeX with Emacs (=app.export.latex=) \| =C-c C-e l l= \| — \| — \| Exports to LaTeX through Emacs (=org-latex-export-to-latex=). \|
	913	\| Export to ODT with Emacs (=app.export.odt=) \| =C-c C-e o o= \| — \| — \| Exports to ODT through Emacs (=org-odt-export-to-odt=). \|
	914	\| Export to Plain Text with Emacs (=app.export.text=) \| =C-c C-e t u= \| — \| — \| Exports to plain text through Emacs (=org-ascii-export-to-ascii=). \|
	915
	916	** Files, buffers and the app
	917
	918	\| Command \| Emacs \| Mac \| Doom \| What it does \|
	919	\|-+-+-+-+-\|
	920	\| Save (=app.save=) \| =C-x C-s= \| — \| =SPC f s= (N), =SPC b s= (N) \| Saves the file (=save-buffer=). \|
	921	\| Save All Buffers (=app.save-all=) \| =C-x s= \| — \| =SPC b S= (N) \| Saves every open buffer (=save-some-buffers=). \|
	922	\| Quick Open… (=app.quick-open=) \| =C-x C-f= \| — \| =SPC SPC= (N), =SPC .= (N), =SPC f f= (N) \| Opens a file of your folders by name (=find-file=). \|
	923	\| Switch to Buffer… (=app.buffer.switch=) \| =C-x b=, =C-x C-b= \| — \| =SPC b b= (N), =SPC b B= (N), =SPC ,= (N) \| Asks for an open buffer and shows it (=switch-to-buffer=). \|
	924	\| Next Buffer (=app.buffer.next=) \| =C-x <right>= \| =⌃⇥= \| =SPC b n= (N), =SPC b ]= (N), =] b= (N) \| Shows the next open buffer (=next-buffer=). \|
	925	\| Previous Buffer (=app.buffer.previous=) \| =C-x <left>= \| =⌃⇧⇥= \| =SPC b p= (N), =SPC b [= (N), =[ b= (N) \| Shows the previous open buffer (=previous-buffer=). \|
	926	\| Last Buffer (=app.buffer.last=) \| — \| — \| =SPC `= (N) \| Shows the buffer you were in before this one. \|
	927	\| Close Buffer (=app.buffer.kill=) \| =C-x k= \| — \| =SPC b k= (N), =SPC b d= (N) \| Closes the buffer, asking about unsaved changes in explicit save mode (=kill-buffer=). \|
	928	\| Close Other Buffers (=app.buffer.kill-others=) \| — \| — \| =SPC b O= (N) \| Closes every other buffer. \|
	929	\| Close All Buffers (=app.buffer.kill-all=) \| — \| — \| =SPC b K= (N) \| Closes every buffer. \|
	930	\| Command Palette… (=app.palette=) \| =M-x= \| — \| =SPC := (N) \| Opens the command palette (=execute-extended-command=). \|
	931	\| Search Notes (=app.search=) \| — \| — \| =SPC /= (N), =SPC s p= (N) \| Moves to the search field for searching your notes. \|
	932	\| Reload Keymap (=app.reload-keymap=) \| — \| — \| =SPC h r r= (N) \| Reads =keymap.toml= again. \|
	933	\| Check Spelling While Typing (=editor.toggle-spell-check=) \| — \| — \| =SPC t s= (N) \| Turns spell checking while typing on or off. \|
	934	\| Truncate or Wrap Long Lines (=editor.toggle-truncate-lines=) \| =C-x x t= \| — \| =SPC t w= (N) \| Switches between wrapping and truncating long lines (=toggle-truncate-lines=). \|
	935	\| Quit Orgstar (=app.quit=) \| — \| — \| =SPC q q= (N) \| Quits Orgstar (=save-buffers-kill-terminal=). \|
	936
	937	** Unbound commands
	938
	939	No preset binds these. Run them from the palette or a menu, or bind them in =keymap.toml=.
	940
	941	\| Command \| What it does \|
	942	\|-+-\|
	943	\| Board (=app.board=) \| Opens the Board window. Window ▸ Board, =⇧⌘B=. \|
	944	\| Cancel Running Block (=app.babel.cancel=) \| Stops the src block that is running. Edit ▸ Cancel Running Block, =⌘.=. \|
	945	\| Edit Config File (=app.edit-config=) \| Opens =config.toml= in the editor. =⌥⌘,=. \|
	946	\| Import from Emacs… (=app.import-emacs=) \| Opens Import from Emacs…. \|
	947	\| Revert to File on Disk (=app.revert=) \| Replaces the buffer with the file on disk; unsaved changes go to recovery (=revert-buffer=). \|
	948	\| Recovery Versions… (=app.recovery=) \| Shows the recovery versions of the file. \|
	949	\| Resolve Sync Conflicts… (=app.sync-conflicts=) \| Shows the file's sync conflict copies to resolve them. \|
	950	\| Import Table from File… (=app.table-import=) \| Asks for a CSV, TSV or space-separated file and inserts it as a table (=org-table-import=). \|
	951	\| Export Table to File… (=app.table-export=) \| Writes the table at point to a CSV or TSV file (=org-table-export=). \|
	952	\| Show or Hide Outline (=app.toggle-outline=) \| Shows or hides the outline pane. View ▸ Show or Hide Outline. \|
	953	\| Show or Hide Backlinks (=app.toggle-backlinks=) \| Shows or hides the backlinks pane. View ▸ Show or Hide Backlinks. \|
	954	\| Show or Hide Columns and Clock (=app.toggle-inspector=) \| Shows or hides the columns and clock inspector. \|
	955	\| Show or Hide Markup (=app.toggle-markup=) \| Shows or hides link brackets and emphasis markers. View ▸ Show Markup, =⇧⌘M=. \|
	956	\| Show or Hide Line Numbers (=app.toggle-line-numbers=) \| Shows or hides line numbers. View ▸ Show Line Numbers, =⇧⌘L=. \|
	957	\| Show or Hide Tab Bar (=app.toggle-tab-bar=) \| Shows or hides the tab bar. View ▸ Show Tab Bar. \|
	958	\| Tangle Block (=org.babel.tangle-block=) \| Tangles only the src block at point (=org-babel-tangle= with =C-u=). \|
	959	\| Tangle Block's Target (=org.babel.tangle-target=) \| Tangles every block that writes to the same file as the block at point (=org-babel-tangle= with =C-u C-u=). \|
	960	\| Column View of File (=org.columns.global=) \| Shows the column view of the whole file (=org-columns= with =C-u=). \|
	961	\| Remove Schedule (=org.schedule.remove=) \| Removes =SCHEDULED= (=org-schedule= with =C-u=). \|
	962	\| Remove Deadline (=org.deadline.remove=) \| Removes =DEADLINE= (=org-deadline= with =C-u=). \|
	963	\| Create ID (=org.id.create=) \| Gives the entry an =ID= property unless it has one (=org-id-get-create=). \|
	964	\| Delete Property… (=org.property.delete=) \| Asks for a property of the entry and deletes it (=org-delete-property=). \|
	965	\| Delete Property Everywhere… (=org.property.delete-globally=) \| Asks for a property and deletes it from every entry in the file (=org-delete-property-globally=). \|
	966	\| Property Action… (=org.property.action=) \| Offers set, delete and delete globally for the property at point (=org-property-action=). =C-c C-c= in a property drawer runs it. \|
	967	\| Footnote Menu (=org.footnote.menu=) \| Offers the footnote commands as a menu (=org-footnote-action= with =C-u=). \|
	968	\| Set Field Formula (=org.table.field-formula=) \| Asks for the current field's formula (=org-table-eval-formula= with =C-u=). \|
	969	\| Sort Table Lines (=org.table.sort=) \| Asks for alphabetic, numeric or time order, or their reverse, and sorts the table's lines by the current column (=org-table-sort-lines=). Sort Entries does the same in a table. \|
	970	\| Transpose Table (=org.table.transpose=) \| Swaps the table's rows and columns (=org-table-transpose-table-at-point=). \|
	971	\| Shrink Table Columns with Widths (=org.table.shrink=) \| Shrinks the table's columns that have a width cookie (=org-table-shrink=). \|
	972	\| Expand Table Columns (=org.table.expand=) \| Expands the table's shrunk columns (=org-table-expand=). \|
	973
	974	** Speed keys reference
	975
	976	At the very start of a heading line, with =org-use-speed-commands= on. The same in every preset (Doom: insert state).
	977
	978	\| Key \| Command \|
	979	\|-+-\|
	980	\| =n= \| Next Heading (=org.heading.next=) \|
	981	\| =p= \| Previous Heading (=org.heading.previous=) \|
	982	\| =f= \| Next Heading at Same Level (=org.heading.forward-same-level=) \|
	983	\| =b= \| Previous Heading at Same Level (=org.heading.backward-same-level=) \|
	984	\| =u= \| Up to Parent Heading (=org.heading.up=) \|
	985	\| =j= \| Go to Heading… (=org.goto=) \|
	986	\| =c= \| Cycle Visibility (=org.cycle=) \|
	987	\| =C= \| Cycle Global Visibility (=org.cycle-global=) \|
	988	\| =s= \| Narrow to Subtree or Widen (=org.narrow.toggle=) \|
	989	\| =k= \| Cut Subtree (=org.subtree.cut=) \|
	990	\| =U= \| Move Subtree Up (=org.subtree.up=) \|
	991	\| =D= \| Move Subtree Down (=org.subtree.down=) \|
	992	\| =r= \| Demote Heading (=org.heading.demote=) \|
	993	\| =l= \| Promote Heading (=org.heading.promote=) \|
	994	\| =R= \| Demote Subtree (=org.subtree.demote=) \|
	995	\| =L= \| Promote Subtree (=org.subtree.promote=) \|
	996	\| =i= \| Insert Heading After Subtree (=org.heading.insert-after-subtree=) \|
	997	\| =^= \| Sort Entries (=org.sort=) \|
	998	\| =w= \| Refile… (=app.refile=) \|
	999	\| =a= \| Archive Subtree (=app.archive=) \|
	1000	\| =@= \| Mark Subtree (=org.subtree.mark=) \|
	1001	\| =#= \| Toggle COMMENT (=org.heading.toggle-comment=) \|
	1002	\| =I= \| Clock In (=app.clock.in=) \|
	1003	\| =O= \| Clock Out (=app.clock.out=) \|
	1004	\| =t= \| Cycle TODO State (=org.todo.cycle=) \|
	1005	\| =,= \| Set Priority… (=org.priority.set=) \|
	1006	\| =0= \| Remove Priority (=org.priority.remove=) \|
	1007	\| =1= \| Set Priority A (=org.priority.set-a=) \|
	1008	\| =2= \| Set Priority B (=org.priority.set-b=) \|
	1009	\| =3= \| Set Priority C (=org.priority.set-c=) \|
	1010	\| =:= \| Set Tags (=org.tags.set=) \|
	1011	\| =e= \| Set Effort (=org.effort.set=) \|
	1012	\| =v= \| Agenda (=app.agenda=) \|
	1013	\| =/= \| Sparse Tree… (=org.sparse-tree=) \|
	1014	\| =o= \| Open Link (=org.link.open=) \|

docs/manual/guide/04-outlines.org added +884

		@@ -0,0 +1,884 @@
	1	#+TITLE: Outlines and structure
	2	#+DESCRIPTION: Headings, subtrees, plain lists, checkboxes, blocks, drawers, properties, column view, footnotes, refiling and archiving.
	3	#+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.
	4
	5	Every command in this chapter is in the Org menu and the command palette (=⇧⌘P=),
	6	under the title given in the tables, whatever keymap you use. The Org menu shows the
	7	keys that run each command in your current keymap.
	8
	9	Keys are listed for the three presets. The Emacs and Doom presets use Emacs notation
	10	(=M-RET= is Meta-Return, =C-c C-w= is Control-c then Control-w). The Mac preset uses
	11	macOS symbols. The Doom preset has every Emacs-preset key that starts with =C-c= or
	12	=C-x=, and the =M-=, =S-= arrow and =RET= chords, in normal, insert and visual
	13	state, plus the Doom keys listed. Where the Mac column says "menu", the Mac preset has
	14	no key for the command; run it from the Org menu or the palette, or bind one in
	15	=keymap.toml= (see [[file:03-keys.org][Keys]]).
	16
	17	* Headings
	18
	19	A heading is a line that starts with one or more stars and a space. The number of stars
	20	is its level. A heading and everything under it, down to the next heading at the same
	21	or a higher level, is a subtree.
	22
	23	#+BEGIN_SRC org
	24	,* Project
	25	Notes about the project.
	26	,** TODO Write the plan
	27	,** Meetings
	28	,*** Kickoff
	29	#+END_SRC
	30
	31	** Inserting headings
	32
	33	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	34	\|------------------------------+------------------------------------------+-----------+-------+-----------\|
	35	\| Insert Heading \| =org-insert-heading= \| =M-RET= \| =⌘↩= \| =M-RET= \|
	36	\| Insert Heading After Subtree \| =org-insert-heading-respect-content= \| =C-RET= \| =⌃⌘↩= \| =C-RET= \|
	37	\| Insert TODO Heading \| =org-insert-todo-heading= \| =M-S-RET= \| =⇧⌘↩= \| =M-S-RET= \|
	38
	39	The new heading has the level of the heading the caret is under, or level 1 before the
	40	first heading. In a plain list the same keys insert an item instead (see [[*Plain lists][Plain lists]]).
	41
	42	Insert TODO Heading gives the new heading the keyword of the previous heading at the
	43	same level when that keyword is not a done state, and otherwise the first keyword of
	44	the file's TODO sequence. If the parent has a statistics cookie, it is updated.
	45
	46	Two settings change where Insert Heading puts the heading. Both are in Settings ▸
	47	Editing and in =config.toml= under the Emacs variable names:
	48
	49	\| Setting (=config.toml=) \| Settings ▸ Editing \| Orgstar default \| Org default \|
	50	\|--------------------------------------+-----------------------------------------------+-----------------+-------------\|
	51	\| =org-insert-heading-respect-content= \| M-RET adds the new heading after the subtree \| =true= \| =nil= \|
	52	\| =org-M-RET-may-split-line= \| M-RET splits the line at the caret \| =false= \| =t= \|
	53
	54	With =org-insert-heading-respect-content= on (the Orgstar default), Insert Heading
	55	behaves as Insert Heading After Subtree: the new heading goes after the end of the
	56	current subtree, at the current level. Insert Heading also does this when the caret is
	57	in folded text.
	58
	59	With it off, Insert Heading works where the caret is:
	60
	61	- At the start of a heading line, the new heading is inserted above it.
	62	- Elsewhere on a heading line, the new heading goes below that line. With
	63	=org-M-RET-may-split-line= on and the caret inside the title, the text after the caret
	64	moves to the new heading. Tags stay on the original line and are realigned.
	65	- In body text, a new heading line is started below. With =org-M-RET-may-split-line=
	66	on, the line is split at the caret first.
	67
	68	Orgstar follows Org's =org-blank-before-new-entry= default of =auto= for headings: if
	69	the heading the caret is in is preceded by a blank line, the new heading is too.
	70
	71	Insert Heading After Subtree always inserts after the subtree:
	72
	73	#+BEGIN_SRC org
	74	,* a
	75	body
	76	,** b
	77	,* c
	78	#+END_SRC
	79
	80	With the caret on =* a=, =C-RET= gives:
	81
	82	#+BEGIN_SRC org
	83	,* a
	84	body
	85	,** b
	86	,*
	87	,* c
	88	#+END_SRC
	89
	90	** Promoting and demoting
	91
	92	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	93	\|-----------------+----------------------+---------------+--------+-------------------------------------------\|
	94	\| Promote Heading \| =org-promote= \| =M-<left>= \| =⌃⌘←= \| =M-h=; in insert state =S-TAB= or =C-d= \|
	95	\| Demote Heading \| =org-demote= \| =M-<right>= \| =⌃⌘→= \| =M-l=; in insert state =TAB= or =C-t= \|
	96	\| Promote Subtree \| =org-promote-subtree= \| =M-S-<left>= \| =⌃⌥⌘←= \| =M-H=, =SPC m s h= \|
	97	\| Demote Subtree \| =org-demote-subtree= \| =M-S-<right>= \| =⌃⌥⌘→= \| =M-L=, =SPC m s l= \|
	98
	99	These run with the caret on a heading line. Promote and Demote Heading change only that
	100	line's stars; its children keep their level. The subtree commands change the heading and
	101	every heading under it. Tags are realigned after each change. A level 1 heading can't be
	102	promoted ("Cannot promote to level 0").
	103
	104	On a list item the same keys indent and outdent the item instead.
	105
	106	** Moving subtrees
	107
	108	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	109	\|-------------------+--------------------------+------------+--------+-------------------\|
	110	\| Move Subtree Up \| =org-move-subtree-up= \| =M-<up>= \| =⌃⌥⌘↑= \| =M-k=, =SPC m s k= \|
	111	\| Move Subtree Down \| =org-move-subtree-down= \| =M-<down>= \| =⌃⌥⌘↓= \| =M-j=, =SPC m s j= \|
	112
	113	The subtree at the caret swaps places with the previous or next sibling subtree. It
	114	can't move past its parent or the start or end of the file. The caret keeps its column.
	115
	116	On a list item the same keys move the item; in a table they move the row. On other
	117	lines they do nothing. Orgstar has no =org-drag-element= for paragraphs.
	118
	119	** Moving between headings
	120
	121	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	122	\|--------------------------------+-----------------------------------+-----------+--------+-------------------\|
	123	\| Next Heading \| =org-next-visible-heading= \| =C-c C-n= \| =⌥⌘↓= \| =C-c C-n= \|
	124	\| Previous Heading \| =org-previous-visible-heading= \| =C-c C-p= \| =⌥⌘↑= \| =C-c C-p= \|
	125	\| Next Heading at Same Level \| =org-forward-heading-same-level= \| =C-c C-f= \| menu \| =g j=, =] h= \|
	126	\| Previous Heading at Same Level \| =org-backward-heading-same-level= \| =C-c C-b= \| menu \| =g k=, =[ h= \|
	127	\| Up to Parent Heading \| =outline-up-heading= \| =C-c C-u= \| menu \| =g h= \|
	128	\| Go to Heading… \| =org-goto= \| =C-c C-j= \| menu \| =SPC m .= \|
	129
	130	Next and Previous Heading skip headings that are folded out of sight. The same-level
	131	commands stop at the parent's boundary. Go to Heading asks for a heading by its outline
	132	path (=Project/Meetings/Kickoff=) with completion, as =org-goto= does with
	133	=outline-path-completion=.
	134
	135	** Toggling headings, items and comments
	136
	137	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	138	\|-----------------+--------------------------------------------+---------+------+-------------------\|
	139	\| Toggle Heading \| =org-toggle-heading= \| =C-c *= \| menu \| =SPC m h= \|
	140	\| Toggle Item \| =org-ctrl-c-minus=, =org-toggle-item= \| =C-c -= \| menu \| =SPC m i= \|
	141	\| Toggle COMMENT \| =org-toggle-comment= \| =C-c ;= \| menu \| =C-c ;= \|
	142
	143	These work on the caret's line, or on every line of the selection.
	144
	145	Toggle Heading:
	146
	147	- On headings, removes their stars, so they become text.
	148	- On list items, turns them into headings one level below the entry they are in. A
	149	checkbox becomes a keyword: =[ ]= the first TODO keyword, =[X]= the first done
	150	keyword. Nested items become deeper headings.
	151	- On other lines, makes each non-blank line a heading one level below the current entry.
	152	Comment lines are skipped.
	153
	154	#+BEGIN_SRC org
	155	,* Shopping
	156	- [ ] milk
	157	- [X] bread
	158	#+END_SRC
	159
	160	Selecting both items and pressing =C-c *= gives:
	161
	162	#+BEGIN_SRC org
	163	,* Shopping
	164	,** TODO milk
	165	,** DONE bread
	166	#+END_SRC
	167
	168	Toggle Item:
	169
	170	- On a list item, with no selection, cycles the list's bullets (see [[*Bullets and numbering][Bullets and numbering]]).
	171	- On items in a selection, removes their bullets.
	172	- On headings, turns them into items. The tags, planning line and property drawer are
	173	removed. A TODO keyword becomes a checkbox, =[X]= for a done state and =[ ]= otherwise.
	174	The section's text is indented under the item.
	175	- On other lines, puts a =-= bullet and a space in front of each non-blank line.
	176
	177	In a table, =C-c *= recalculates and =C-c -= inserts a horizontal line instead (see
	178	[[file:10-tables.org][Tables]]).
	179
	180	Toggle COMMENT adds or removes the =COMMENT= keyword after the stars and TODO keyword.
	181	Commented subtrees are left out of export and column view.
	182
	183	** Selecting a subtree
	184
	185	Mark Subtree (=org-mark-subtree=, =C-c @= in the Emacs and Doom presets) selects the
	186	subtree at the caret, from its heading line to the end of its last line.
	187
	188	* Subtrees as text
	189
	190	** Cut, copy and paste
	191
	192	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	193	\|---------------+----------------------+---------------+------+---------------------------\|
	194	\| Cut Subtree \| =org-cut-subtree= \| =C-c C-x C-w= \| menu \| =C-c C-x C-w=, =SPC m s d= \|
	195	\| Copy Subtree \| =org-copy-subtree= \| =C-c C-x M-w= \| menu \| =C-c C-x M-w= \|
	196	\| Paste Subtree \| =org-paste-subtree= \| =C-c C-x C-y= \| menu \| =C-c C-x C-y= \|
	197
	198	The kill ring is the system clipboard. Cut Subtree and Copy Subtree put the subtree at
	199	the caret, with the blank lines after it, on the clipboard and report its length.
	200
	201	Paste Subtree takes the clipboard's text and adjusts its levels to fit where it lands.
	202	The text has to start with a heading and contain no heading above its first one's
	203	level; otherwise the command refuses. The level comes from:
	204
	205	- an empty heading line, such as =***= followed by a space, at the caret: that level, and the empty line is
	206	replaced;
	207	- the caret at the start of a heading: that heading's level, pasted before it;
	208	- otherwise the deeper of the heading above the caret and the heading below it, pasted
	209	before the next heading.
	210
	211	** Cloning with a time shift
	212
	213	Clone Subtree with Time Shift (=org-clone-subtree-with-time-shift=, =C-c C-x c=, Doom
	214	=SPC m s c=) asks for a number of clones, then, if the subtree has timestamps, for a
	215	shift per clone such as =+1d=, =+1w=, =+2m= or =+1y= (units =h=, =d=, =w=, =m=, =y=).
	216	Leave the shift empty to copy the dates unchanged.
	217
	218	The clones are inserted after the subtree. The nth clone has its dates moved by n times
	219	the shift. Clones lose their =CLOCK:= lines, and drawers left empty by that are removed.
	220	An entry with an =:ID:= property gets a new ID in each clone. When the subtree has a
	221	repeating timestamp and a shift is given, the repeater is removed from the clones, and
	222	the original, with its repeater, moves after them with its dates shifted past the last
	223	clone, as Org does.
	224
	225	** Sorting
	226
	227	Sort Entries (=org-sort=, =C-c ^=, Doom =SPC m s S=) sorts what the caret is in:
	228
	229	- In a table, the table's lines (=org-table-sort-lines=, see [[file:10-tables.org][Tables]]).
	230	- On a list item, the items of that list (=org-sort-list=).
	231	- Otherwise headings (=org-sort-entries=): with a selection, the headings in it;
	232	on a heading, its children; before the first heading, the top-level headings.
	233
	234	It then asks for a sort key, one keystroke. A capital letter sorts in reverse.
	235
	236	\| Key \| Headings \| List items \|
	237	\|-----+--------------------------------------------------+--------------------------------------\|
	238	\| =a= \| alphabetically by title \| alphabetically by text \|
	239	\| =n= \| numerically by the title's leading number \| numerically by the text \|
	240	\| =p= \| priority \| \|
	241	\| =r= \| a property's value (asks which property) \| \|
	242	\| =o= \| TODO keyword, in sequence order \| \|
	243	\| =t= \| first active timestamp, else first timestamp \| first timestamp, or a timer \|
	244	\| =s= \| =SCHEDULED= date \| \|
	245	\| =d= \| =DEADLINE= date \| \|
	246	\| =c= \| creation time: the first inactive timestamp at the start of a line \| \|
	247	\| =k= \| clocked time in the subtree \| \|
	248	\| =x= \| \| checkbox state \|
	249
	250	Alphabetical and numeric sorts ignore a leading =COMMENT=, link brackets and emphasis
	251	markers. Sorting is stable, so entries with equal keys keep their order. Entries
	252	without a date sort as if dated now. After sorting a list, its numbering is repaired.
	253	Org's =f= (custom function) key is not available.
	254
	255	* Narrowing
	256
	257	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	258	\|----------------------------+----------------------------------+-----------+------+------------\|
	259	\| Narrow to Subtree \| =org-narrow-to-subtree= \| =C-x n s= \| menu \| =SPC m s n= \|
	260	\| Narrow to Block \| =org-narrow-to-block= \| =C-x n b= \| menu \| =C-x n b= \|
	261	\| Widen \| =widen= \| =C-x n w= \| menu \| =SPC m s N= \|
	262	\| Narrow to Subtree or Widen \| =org-toggle-narrow-to-subtree= \| speed key =s= \| speed key =s= \| speed key =s= \|
	263
	264	Narrowing hides everything outside the current subtree or block, so the editor shows
	265	only that part of the file. Narrow to Block works on src, example, export, comment and
	266	verse blocks (with the blank lines after them) and, for other blocks, on the lines
	267	between the opening and closing lines. Edits inside the narrowed text move its bounds
	268	as you type. Jumping to a position outside it, from a link, search or the outline pane,
	269	widens first.
	270
	271	Narrowing is a view. Commands still see the whole file: for example, a new footnote's
	272	definition still goes into the =Footnotes= section at the end of the file, and a sparse
	273	tree searches the whole file.
	274
	275	* Sparse trees
	276
	277	Sparse Tree… (=org-sparse-tree=, =C-c /=, Doom =SPC m s s=) folds the file to an
	278	overview and then shows only the matches and the headings above them. It asks what to
	279	match, one keystroke:
	280
	281	\| Key \| Shows \| Org function \|
	282	\|------+-----------------------------------------------------------------------+------------------------\|
	283	\| =r= \| text matching a regular expression (asks for it); case-insensitive \| =org-occur= \|
	284	\| =t= \| headings with a TODO keyword that is not a done state \| =org-show-todo-tree= \|
	285	\| =T= \| headings with the keywords you give (several separated by a vertical bar) \| =org-show-todo-tree= \|
	286	\| =m= \| headings matching a tags and properties match \| =org-match-sparse-tree= \|
	287	\| =p= \| headings where a property has a value (asks for both, with completion) \| =org-match-sparse-tree= \|
	288	\| =d= \| deadlines past due or due within 14 days (fixed), in entries not done \| =org-check-deadlines= \|
	289	\| =b= \| entries with a =SCHEDULED= or =DEADLINE= before a date \| =org-check-before-date= \|
	290	\| =a= \| entries with a =SCHEDULED= or =DEADLINE= on or after a date \| =org-check-after-date= \|
	291	\| =D= \| entries with a =SCHEDULED= or =DEADLINE= in a date range \| =org-check-dates-range= \|
	292
	293	The regular expression uses Emacs syntax. The match syntax for =m= is the one the
	294	agenda's tags search uses (see [[file:07-agenda.org][Agenda]]). Dates are read as Org reads them (see
	295	[[file:06-dates-and-clocking.org][Dates and clocking]]).
	296
	297	For a text match, the whole entry around each match is shown; for heading matches,
	298	the heading line. The matched text is highlighted, and the echo area reports the number
	299	of matches. Subtrees tagged =ARCHIVE= stay folded. The highlights go away at the next
	300	edit or with =C-c C-c=. =TAB= and =S-TAB= work as usual afterwards; cycling leaves the
	301	sparse view.
	302
	303	* Plain lists
	304
	305	Orgstar's list commands are ports of =org-list.el=. A list item starts with a bullet:
	306	=-=, =+=, =*= (not at the left margin, where it would be a heading), or a number
	307	followed by =.= or =)=. With alphabetical lists on, =a.=, =A.=, =a)= and =A)= are bullets
	308	too. A description item has =::= after its term:
	309
	310	#+BEGIN_SRC org
	311	- milk
	312	- eggs
	313	1. free range
	314	2. brown
	315	- Orgstar :: an org editor for macOS and iOS
	316	#+END_SRC
	317
	318	\| Setting (=config.toml=) \| Settings ▸ Editing \| Orgstar default \| Org default \|
	319	\|-------------------------------+----------------------------------+-----------------+-------------\|
	320	\| =org-list-allow-alphabetical= \| Lists can use letters (a. b. c.) \| =true= \| =nil= \|
	321
	322	** List commands
	323
	324	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	325	\|---------------------------+--------------------------+---------------+--------+-----------------------------------\|
	326	\| Insert Item \| =org-insert-item= \| =M-RET= \| =⌘↩= \| =M-RET= \|
	327	\| Insert Checkbox Item \| =org-insert-item= with a checkbox \| =M-S-RET= \| =⇧⌘↩= \| =M-S-RET= \|
	328	\| Indent Item \| =org-indent-item= \| =M-<right>= \| =⌃⌘→= \| =M-l=; =C-t= in insert state \|
	329	\| Outdent Item \| =org-outdent-item= \| =M-<left>= \| =⌃⌘←= \| =M-h=; =C-d= in insert state \|
	330	\| Indent Item and Children \| =org-indent-item-tree= \| =M-S-<right>= \| =⌃⌥⌘→= \| =M-L=; =TAB= in insert state \|
	331	\| Outdent Item and Children \| =org-outdent-item-tree= \| =M-S-<left>= \| =⌃⌥⌘←= \| =M-H=; =S-TAB= in insert state \|
	332	\| Move Item Up \| =org-move-item-up= \| =M-<up>= \| =⌃⌥⌘↑= \| =M-k= \|
	333	\| Move Item Down \| =org-move-item-down= \| =M-<down>= \| =⌃⌥⌘↓= \| =M-j= \|
	334	\| Toggle Checkbox \| =org-toggle-checkbox= \| =C-c C-x C-b= \| =⌃⌘C= \| =SPC m x=, =RET= in normal state \|
	335	\| Toggle Item \| =org-ctrl-c-minus= \| =C-c -= \| menu \| =SPC m i= \|
	336
	337	Insert Item works anywhere inside an item. The new item gets the next bullet: the same
	338	symbol, the next number or the next letter. In a description list the new item has an
	339	empty term followed by =::=, with the caret on the term. With =org-M-RET-may-split-line= on, text after the caret moves
	340	to the new item; with it off (the Orgstar default), the new item goes after the current
	341	one. At the start of an item, the new item is inserted before it. If the list's items
	342	are separated by blank lines, so is the new one.
	343
	344	The indent, outdent and move commands need the caret on an item's first line.
	345
	346	- Indent Item and Outdent Item move one item; its children stay where they are, and an
	347	item with children can't be outdented alone ("Cannot outdent an item without its
	348	children").
	349	- The "and Children" variants move the item with its sub-items.
	350	- On the first item of a list, Indent Item refuses; Indent Item and Children and
	351	Outdent Item and Children move the whole list. A list moved to the left margin
	352	changes =*= bullets to =-=.
	353	- Move Item Up and Down swap the item, with its children, with the previous or next
	354	item at the same level.
	355
	356	After every list command the list is repaired as Org repairs it: bullets are renumbered,
	357	indentation is fixed and checkboxes of parent items are updated.
	358
	359	** Bullets and numbering
	360
	361	Toggle Item (=C-c -=) on an item, with no selection, cycles the bullet of the whole
	362	list (=org-cycle-list-bullet=) through:
	363
	364	=-=, =+=, =*=, =1.=, =1)=, then with alphabetical lists =a.=, =A.=, =a)=, =A)=.
	365
	366	=*= is skipped for a list at the left margin. Description lists skip the numbered and
	367	lettered bullets. Lettered bullets are offered only when the list has 26 items or
	368	fewer. Org also cycles bullets with =S-<left>= and =S-<right>= on an item; Orgstar
	369	does not bind those on items.
	370
	371	Numbered and lettered lists are renumbered whenever a list command changes them, and
	372	by =C-c C-c= on any item. To start a list at a given number, put a counter after the
	373	bullet, as in Org:
	374
	375	#+BEGIN_SRC org
	376	5. [@5] fifth
	377	6. sixth
	378	#+END_SRC
	379
	380	* Checkboxes and statistics
	381
	382	** Checkboxes
	383
	384	An item with =[ ]= after its bullet has a checkbox. =[X]= is checked, and =[-]= marks a
	385	parent item whose children are partly checked.
	386
	387	#+BEGIN_SRC org
	388	- [-] packing
	389	- [X] passport
	390	- [ ] charger
	391	#+END_SRC
	392
	393	Toggle Checkbox (=C-c C-x C-b=) checks or unchecks the item on the caret's line, or
	394	every item in the selection. =C-c C-c= on an item toggles its checkbox too, and on an
	395	item without one, repairs the list. A parent item's checkbox follows its children: it
	396	can't be checked while children are unchecked ("Cannot toggle this checkbox: unchecked
	397	subitems").
	398
	399	Toggle Checkbox works only on item lines. Org's behaviour on a heading, toggling the
	400	checkboxes of the region or subtree, is not available.
	401
	402	** Statistics cookies
	403
	404	A cookie =[/]= or =[%]= on a heading or an item shows progress:
	405
	406	- On an item, it counts that item's direct child checkboxes.
	407	- On a heading, it counts the checkboxes of the top-level items in the heading's own
	408	section. If the section has none, it counts the TODO children: direct child headings
	409	with a keyword, and how many of them are in a done state.
	410
	411	#+BEGIN_SRC org
	412	,* Groceries [1/3]
	413	- [X] milk
	414	- [ ] eggs
	415	- [ ] bread
	416
	417	,* Release [50%]
	418	,** DONE Tag the build
	419	,** TODO Write the notes
	420	#+END_SRC
	421
	422	Cookies update when you toggle or insert a checkbox, when a child heading's TODO state
	423	changes, when you archive an entry, and when you press =C-c C-c= with the caret on the
	424	cookie. A cookie with nothing to count shows =[0/0]= or =[100%]=. Tags are realigned when
	425	the cookie's width changes.
	426
	427	The =COOKIE_DATA= property changes what a heading's cookie counts, as in Org:
	428
	429	\| Value \| Effect \|
	430	\|-------------+----------------------------------------------------------------\|
	431	\| =todo= \| count TODO children, not checkboxes \|
	432	\| =checkbox= \| count checkboxes, not TODO children \|
	433	\| =recursive= \| count all descendants, not only direct children \|
	434
	435	For TODO statistics, =COOKIE_DATA= is read with inheritance, from the parent or an
	436	ancestor. Orgstar counts TODO children hierarchically, as Org does with
	437	=org-hierarchical-todo-statistics= at its default.
	438
	439	* Blocks
	440
	441	Blocks are lines between =#+BEGIN_name= and =#+END_name=:
	442
	443	#+BEGIN_SRC org
	444	,#+BEGIN_QUOTE
	445	Text to quote.
	446	,#+END_QUOTE
	447	#+END_SRC
	448
	449	** Structure templates
	450
	451	Insert Structure Template (=org-insert-structure-template=, =C-c C-,= in the Emacs and
	452	Doom presets) asks for a block type, one keystroke:
	453
	454	\| Key \| Block \|
	455	\|-----+-----------------\|
	456	\| =a= \| =export ascii= \|
	457	\| =c= \| =center= \|
	458	\| =C= \| =comment= \|
	459	\| =e= \| =example= \|
	460	\| =E= \| =export= \|
	461	\| =h= \| =export html= \|
	462	\| =l= \| =export latex= \|
	463	\| =q= \| =quote= \|
	464	\| =s= \| =src= \|
	465	\| =v= \| =verse= \|
	466
	467	Press =TAB= to type any other type. These are Org's default
	468	=org-structure-template-alist=; Orgstar does not read a custom one. The block is
	469	inserted at the caret's indentation. With a selection, the block wraps the selected
	470	lines, and for =src=, =example=, =export= and =comment= blocks, lines that would read as
	471	headings or keywords are protected with a leading comma. For =src= and =export=, the
	472	caret ends on the opening line after a space, ready for the language; otherwise it ends
	473	inside the block. The case of =BEGIN= and =END= follows the case of the type you typed.
	474
	475	** org-tempo templates
	476
	477	Typing =<= and a key at the start of a line (after blanks only) and then completing
	478	expands it as =org-tempo= does. =<s= becomes:
	479
	480	#+BEGIN_SRC org
	481	,#+begin_src
	482	,#+end_src
	483	#+END_SRC
	484
	485	with the caret after =begin_src=. The keys are those of the table above, plus =<L=,
	486	=<H=, =<A= and =<i=, which insert =#+latex:=, =#+html:=, =#+ascii:= and =#+index:=
	487	keyword lines.
	488
	489	Completion runs with Complete at Point (=C-M-i= in the Emacs preset, =C-SPC= in Doom's
	490	insert state; in the Mac preset, from the palette). In the Doom preset the completion
	491	list also opens by itself after a short pause once you have typed =<= and a letter, and
	492	=TAB= or =RET= takes the selected candidate. =TAB= alone does not expand =<s= in the
	493	Emacs or Mac preset.
	494
	495	** Folding and editing blocks
	496
	497	=TAB= on a block's first or last line folds or unfolds it. Blocks are open when a file
	498	opens unless =org-cycle-hide-block-startup= is on in =config.toml= or the file has
	499	=#+STARTUP: hideblocks= (=nohideblocks= overrides the setting the other way). See
	500	[[file:02-the-editor.org][The editor]] for folding in general.
	501
	502	Edit Block (=org-edit-special=, =C-c '=) edits a src, example or export block in a
	503	separate editor. See [[file:11-code-blocks.org][Code blocks]].
	504
	505	* Drawers
	506
	507	A drawer is a named group of lines between =:NAME:= and =:END:=. Orgstar writes the
	508	=PROPERTIES= drawer for properties and, depending on =org-log-into-drawer=, a =LOGBOOK=
	509	drawer for state notes and clock lines (see [[file:05-todos-and-tags.org][TODOs and tags]] and
	510	[[file:06-dates-and-clocking.org][Dates and clocking]]). You can write any other drawer by hand:
	511
	512	#+BEGIN_SRC org
	513	,* Meeting
	514	:NOTES:
	515	Private notes, folded away.
	516	:END:
	517	#+END_SRC
	518
	519	=TAB= on a drawer's first or last line folds or unfolds it. Drawers are folded when a
	520	file opens, as with Org's =org-cycle-hide-drawer-startup= (=true= by default in
	521	=config.toml=). =#+STARTUP: nohidedrawers= keeps them open in one file, and
	522	=#+STARTUP: hidedrawers= folds them when the setting is off.
	523
	524	Org's =org-insert-drawer= (=C-c C-x d=) is not available; type the two lines yourself.
	525
	526	* Properties
	527
	528	Properties are key-value pairs in an entry's =PROPERTIES= drawer, right after the
	529	heading and its planning line:
	530
	531	#+BEGIN_SRC org
	532	,* Laptop
	533	:PROPERTIES:
	534	:VENDOR: Apple
	535	:Effort: 1:00
	536	:END:
	537	#+END_SRC
	538
	539	File-wide properties come from =#+PROPERTY:= lines and from a =PROPERTIES= drawer before
	540	the first heading. A key written =KEY+= appends its value to the inherited one with a
	541	space between.
	542
	543	** Setting and deleting
	544
	545	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	546	\|-----------------------------+---------------------------------+-------------+------+------------\|
	547	\| Set Property… \| =org-set-property= \| =C-c C-x p= \| menu \| =SPC m o= \|
	548	\| Delete Property… \| =org-delete-property= \| none \| menu \| none \|
	549	\| Delete Property Everywhere… \| =org-delete-property-globally= \| none \| menu \| none \|
	550	\| Property Action… \| =org-property-action= \| =C-c C-c= in a property drawer \| menu \| =C-c C-c= \|
	551	\| Next Allowed Value \| =org-property-next-allowed-value= \| =S-<right>= on a property line \| menu \| =S-<right>=, =C-S-l= \|
	552	\| Previous Allowed Value \| =org-property-previous-allowed-value= \| =S-<left>= on a property line \| menu \| =S-<left>=, =C-S-h= \|
	553
	554	Set Property asks for the key, offering the keys used in the file, Org's standard keys
	555	and the properties named in =COLUMNS= formats; on a property line, Return takes that
	556	line's key. It then asks for the value. If the key has allowed values, those are
	557	offered and required unless the list includes =:ETC=; otherwise the values the key has
	558	elsewhere in the file are offered. An empty answer keeps the current value. The drawer
	559	is created if the entry has none, and lines are aligned as Org's
	560	=org-property-format= (="%-10s %s"=) aligns them. Setting =TODO= sets the entry's TODO
	561	keyword instead.
	562
	563	Delete Property asks which of the entry's properties to remove, when it has more than
	564	one, and removes the drawer if it becomes empty. Delete Property Everywhere removes a key
	565	from every entry in the file and reports how many it changed. Property Action, run by
	566	=C-c C-c= in a property drawer, asks =s= (set), =d= (delete) or =D= (delete everywhere).
	567
	568	** Allowed values
	569
	570	A property =KEY_ALL= lists the values =KEY= may take, separated by spaces, with quotes
	571	around values that contain spaces. Orgstar looks for it on the entry, then its
	572	ancestors, then the file:
	573
	574	#+BEGIN_SRC org
	575	,#+PROPERTY: Status_ALL open blocked done
	576	#+END_SRC
	577
	578	Next and Previous Allowed Value step through the list on a property line. =TODO= and
	579	=PRIORITY= take their values from the file's keywords and priority range. A property
	580	whose value is =[ ]= or =[X]= toggles between them.
	581
	582	** Inheritance
	583
	584	Orgstar inherits properties as Org does with =org-use-property-inheritance= at its
	585	default of =nil=: a property applies only to the entry that has it, with these
	586	exceptions:
	587
	588	- =CATEGORY=, =ARCHIVE=, =COLUMNS=, =LOGGING= and the =header-args= properties are
	589	always inherited from ancestors and =#+PROPERTY:= lines.
	590	- =ID= and =CUSTOM_ID= are never inherited.
	591	- =KEY_ALL= allowed values and =COOKIE_DATA= for TODO statistics are looked up through
	592	the ancestors.
	593
	594	Orgstar has no setting for =org-use-property-inheritance=.
	595
	596	** Special properties
	597
	598	Org computes some properties instead of reading them from a drawer. Orgstar treats
	599	these as special and doesn't offer them as allowed-value lists: =ALLTAGS=, =BLOCKED=,
	600	=CLOCKSUM=, =CLOCKSUM_T=, =CLOSED=, =DEADLINE=, =FILE=, =ITEM=, =PRIORITY=, =SCHEDULED=,
	601	=TAGS=, =TIMESTAMP=, =TIMESTAMP_IA= and =TODO=. Column view computes =ITEM=, =TODO=,
	602	=PRIORITY=, =TAGS=, =ALLTAGS=, =DEADLINE=, =SCHEDULED=, =CLOSED= and =CLOCKSUM=; the
	603	others show as empty there.
	604
	605	* Column view
	606
	607	Column view shows entries as rows and properties as columns. The columns come from a
	608	=COLUMNS= format, found in this order:
	609
	610	1. a =COLUMNS= property on the entry at the caret or one of its ancestors (the nearest
	611	one wins, and that entry becomes the top of the view);
	612	2. a =#+COLUMNS:= line in the file;
	613	3. Org's default, =%25ITEM %TODO %3PRIORITY %TAGS=.
	614
	615	#+BEGIN_SRC org
	616	,#+COLUMNS: %40ITEM %TODO %Effort(Estimate){:} %CLOCKSUM
	617	#+END_SRC
	618
	619	Each column is =%[width]PROPERTY[(title)][{summary}]=, as in Org. The width limits the
	620	column, the title replaces the property name in the header, and the summary is computed
	621	for parent entries from their children. The summary operators are =+=, =$=, =min=,
	622	=max=, =mean=, =X=, =X/=, =X%=, =:=, =:min=, =:max=, =:mean= and =est+=. Org's age
	623	operators (=@min=, =@max=, =@mean=) are not supported. The numeric operators take a
	624	format after a semicolon, as in ={+;%.1f}=.
	625
	626	Subtrees tagged =ARCHIVE= and commented subtrees are left out.
	627
	628	** The column view sheet
	629
	630	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	631	\|---------------------+---------------------------+---------------+------+---------------\|
	632	\| Column View \| =org-columns= \| =C-c C-x C-c= \| menu \| =C-c C-x C-c= \|
	633	\| Column View of File \| =org-columns= with a prefix \| none \| menu \| none \|
	634
	635	Column View opens a sheet with the entries from the view's top (the entry with the
	636	=COLUMNS= property, or the entry at the caret; the whole file before the first
	637	heading). Column View of File shows every entry in the file. Click a row to go to its
	638	heading. Done (or Escape) closes the sheet.
	639
	640	The sheet is read-only. Org's column view lets you edit values in place and writes
	641	parent summaries back into the file; Orgstar's does neither. Change values with Set
	642	Property, or edit the drawer.
	643
	644	** The Columns inspector
	645
	646	View ▸ Show or Hide Columns and Clock opens an inspector beside the editor. Its Columns
	647	tab shows the same table for the open file, kept current as you type. Choose File for
	648	every entry or Subtree for the entry at the caret. The row of the heading at the caret
	649	is shown in bold, and clicking a row goes to it. The Clock tab is described in
	650	[[file:06-dates-and-clocking.org][Dates and clocking]].
	651
	652	** Column view tables
	653
	654	Insert Column View Table (=org-columns-insert-dblock=, =C-c C-x i=) asks what to
	655	capture: =local= (the default, the entry at the caret), =global= (the whole file) or an
	656	=ID= of an entry. It inserts a =columnview= dynamic block and fills it:
	657
	658	#+BEGIN_SRC org
	659	,#+BEGIN: columnview :hlines 1 :id local
	660	\| ITEM \| TODO \| PRIORITY \| TAGS \|
	661	\|------+------+----------+------\|
	662	\| ... \| \| \| \|
	663	,#+END:
	664	#+END_SRC
	665
	666	=C-c C-c= on the =#+BEGIN:= line, or =C-c C-x C-u= anywhere in the block, updates it.
	667	Updating writes summary values into the parents' properties, as Org does. The block
	668	takes these parameters:
	669
	670	\| Parameter \| Meaning \|
	671	\|--------------------+-------------------------------------------------------------------\|
	672	\| =:id= \| =local=, =global=, or an entry's =ID= \|
	673	\| =:format= \| a column format to use instead of the entry's or file's \|
	674	\| =:hlines= \| =t= for a line between all rows, or N for one before each level N or higher row \|
	675	\| =:maxlevel= \| leave out deeper headings \|
	676	\| =:skip-empty-rows= \| leave out rows whose columns other than =ITEM= are empty \|
	677	\| =:exclude-tags= \| leave out entries with these tags, as a list \|
	678	\| =:indent= \| indent =ITEM= by level \|
	679
	680	Existing =#+TBLFM:= lines after the table are kept. An =:id= of the form =file:path=
	681	(another file) is not supported.
	682
	683	* Footnotes
	684
	685	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	686	\|-----------------+----------------------+-------------+------+-------------\|
	687	\| Footnote Action \| =org-footnote-action= \| =C-c C-x f= \| menu \| =C-c C-x f= \|
	688	\| Footnote Menu \| =org-footnote-action= with a prefix \| none \| menu \| none \|
	689
	690	Footnote Action depends on where the caret is:
	691
	692	- On a reference such as =[fn:1]=, it goes to the definition. If there is none, it asks
	693	whether to create one.
	694	- On a definition's label, it goes back to a reference.
	695	- Elsewhere, where a footnote is allowed, it inserts a new reference with the next free
	696	number and creates its definition.
	697	- Where a footnote can't go, it shows the footnote menu.
	698
	699	=C-c C-c= on a reference or a definition's label does the same jumps.
	700
	701	New definitions go in a level 1 heading named =Footnotes= at the end of the file, which
	702	is created when needed (Org's =org-footnote-section=):
	703
	704	#+BEGIN_SRC org
	705	,* Notes
	706	Orgstar reads org files.[fn:1]
	707
	708	,* Footnotes
	709
	710	[fn:1] And writes them.
	711	#+END_SRC
	712
	713	The footnote menu asks, one keystroke:
	714
	715	\| Key \| Action \| Org function \|
	716	\|-----+----------------------------------------------------------------------------+------------------------------\|
	717	\| =s= \| sort definitions into the order of their first reference \| =org-footnote-sort= \|
	718	\| =r= \| renumber numeric labels =fn:N= in order of appearance \| =org-footnote-renumber-fn:N= \|
	719	\| =S= \| renumber, then sort \| \|
	720	\| =n= \| normalize: number every footnote, labeled, anonymous and inline, and collect all definitions in the footnote section \| =org-footnote-normalize= \|
	721	\| =d= \| delete the footnote at the caret: its references and definition \| =org-footnote-delete= \|
	722
	723	A reference with no definition gets the text =DEFINITION NOT FOUND.= when sorted or
	724	normalized.
	725
	726	* Refiling
	727
	728	Refile… (=org-refile=, =C-c C-w=, Mac =⌃⌘W=, Doom =SPC m r r= or =SPC m s r=) moves the
	729	subtree at the caret under another heading, in this file or another one.
	730
	731	It asks for the target with completion. The targets are every org file in your folders
	732	and every heading down to level 3 in those files, written as the file's path relative
	733	to its folder followed by the outline path:
	734
	735	#+BEGIN_EXAMPLE
	736	projects.org
	737	projects.org/Work
	738	projects.org/Work/Website
	739	notes/inbox.org/Someday
	740	#+END_EXAMPLE
	741
	742	Choosing a heading makes the subtree its last child, at one level below it. Choosing a
	743	file adds the subtree at the end of that file as a level 1 heading. Levels inside the
	744	subtree are shifted to match, and tags are realigned. A subtree can't be refiled into
	745	itself.
	746
	747	For the open file, targets come from the buffer, including unsaved edits. When the
	748	target is another file, Orgstar writes that file first, into its open buffer if it has
	749	one, otherwise through the normal save path, and removes the subtree from the source
	750	only after that succeeds. If the target file changed on disk in the meantime, nothing
	751	is refiled.
	752
	753	This matches Org with =org-refile-targets= set to headings of maximum level 3 in all
	754	files, =org-refile-use-outline-path= set to =file=, =org-reverse-note-order= =nil= (new
	755	entries go last), =org-log-refile= =nil= and =org-refile-keep= =nil=. None of these is
	756	configurable in Orgstar. Refiling from the agenda is covered in [[file:07-agenda.org][Agenda]].
	757
	758	* Archiving
	759
	760	** Archive Subtree
	761
	762	Archive Subtree (=org-archive-subtree=, =C-c C-x C-s= or =C-c $=, Mac =⌃⌘A=, Doom
	763	=SPC m A= or =SPC m s A=) moves the subtree at the caret to an archive.
	764
	765	The archive location is read from, in order: the =ARCHIVE= property of the entry or an
	766	ancestor, a =#+ARCHIVE:= line in the file, and Org's default =%s_archive::=. A location
	767	is =file::heading=, where =%s= stands for the current file's name:
	768
	769	\| Location \| Where the subtree goes \|
	770	\|------------------------+----------------------------------------------------------------------------\|
	771	\| =%s_archive::= \| the end of =notes.org_archive= next to =notes.org=, at level 1 \|
	772	\| =archive.org::* Old= \| under the heading =* Old= in =archive.org=, created if missing \|
	773	\| =::* Archived= \| under =* Archived= in the same file \|
	774	\| =%s_archive::datetree/= \| under year, month and day headings in the archive file, for the entry's =CLOSED= date or today \|
	775
	776	Relative paths are relative to the current file's folder, and =~= is your home folder. A
	777	new archive file starts with a line =Archived entries from file= followed by the
	778	source's path.
	779
	780	The archived entry gets these properties, as with Org's default
	781	=org-archive-save-context-info=: =ARCHIVE_TIME=, =ARCHIVE_FILE=, =ARCHIVE_OLPATH=,
	782	=ARCHIVE_CATEGORY=, =ARCHIVE_TODO= and =ARCHIVE_ITAGS= (empty ones are left out).
	783	Within the same file, tags it inherited are added to its heading. After the subtree
	784	leaves, the parent's statistics cookies are updated. The entry's TODO state is not
	785	changed.
	786
	787	If the archive file is open, the subtree goes into its buffer. Otherwise Orgstar writes
	788	the archive file first and removes the subtree from the source only after that
	789	succeeds. Org's option =org-archive-location= in Emacs is not read; use the =ARCHIVE=
	790	property or =#+ARCHIVE:=. Archiving from the agenda is covered in [[file:07-agenda.org][Agenda]].
	791
	792	** The ARCHIVE tag
	793
	794	Toggle ARCHIVE Tag (=org-toggle-archive-tag=, =C-c C-x a=, Doom =SPC m s a=) adds or
	795	removes the =ARCHIVE= tag on the entry at the caret. Adding it folds the subtree.
	796
	797	Subtrees tagged =ARCHIVE= stay where they are, but are folded when a file opens and in
	798	sparse trees, and are left out of column view. =TAB= opens an archived subtree like
	799	any other; Org's =org-cycle-open-archived-trees= behaviour, which keeps them closed, is
	800	not reproduced. See [[file:05-todos-and-tags.org][TODOs and tags]] for tags in general.
	801
	802	** Archive sibling
	803
	804	Archive to Archive Sibling (=org-archive-to-archive-sibling=, =C-c C-x A=) moves the
	805	subtree at the caret under a sibling heading named =Archive= with the =ARCHIVE= tag,
	806	creating it at the end of the parent's children if needed. The moved entry gets an
	807	=ARCHIVE_TIME= property, and the =Archive= sibling is folded.
	808
	809	* The outline pane
	810
	811	The outline pane, to the left of the editor, lists the headings of the open org file,
	812	indented by level. Click a heading to go to it; folded text around it opens. A heading
	813	with no title is shown as =(untitled)=.
	814
	815	Show or hide it with the toolbar button or View ▸ Show or Hide Outline. Orgstar
	816	remembers the choice for org files; for other files the pane starts hidden and shows
	817	"Only org files have an outline." Drag the divider to resize it. While the search field
	818	has text, the pane shows search results instead. The backlinks pane, when shown, sits
	819	below the outline (see [[file:09-links.org][Links]]).
	820
	821	* C-c C-c
	822
	823	=C-c C-c= (=org-ctrl-c-ctrl-c=) does what fits the caret's position. In the Emacs and
	824	Doom presets it is =C-c C-c=; in the Mac preset, run Act at Point (C-c C-c) from the Org
	825	menu or the palette. In order, it:
	826
	827	\| Caret on \| Effect \|
	828	\|--------------------------------------------+------------------------------------------------------------\|
	829	\| anywhere, while sparse tree highlights show \| removes the highlights, and nothing else (not in a table or src block) \|
	830	\| a src block, a =#+CALL= line or inline code \| runs it (see [[file:11-code-blocks.org][Code blocks]]) \|
	831	\| a table or =#+TBLFM= line \| aligns the table, or recalculates it (see [[file:10-tables.org][Tables]]) \|
	832	\| a footnote reference or definition label \| jumps between them \|
	833	\| a blank line \| nothing \|
	834	\| a =CLOCK:= line \| fixes the weekdays and writes the duration again \|
	835	\| a dynamic block's =#+BEGIN:= line \| updates the block \|
	836	\| a statistics cookie \| updates it \|
	837	\| a timestamp \| fixes its weekday \|
	838	\| a heading \| sets tags (see [[file:05-todos-and-tags.org][TODOs and tags]]) \|
	839	\| a list item \| toggles its checkbox, repairs the list and updates cookies \|
	840	\| a =#+KEYWORD:= line \| rereads the file's settings and =#+SETUPFILE= \|
	841	\| a property drawer \| runs Property Action \|
	842
	843	Elsewhere it reports that it can do nothing useful.
	844
	845	In the Doom preset, =RET= in normal state runs Doom's =+org/dwim-at-point= instead. It
	846	follows a link, recalculates a table with formulas or aligns one without, runs a src
	847	block, toggles an item's checkbox, or on a heading switches between the first TODO and
	848	first done keyword of its sequence.
	849
	850	* Speed keys
	851
	852	With =org-use-speed-commands= set to =true= in =config.toml=, single keys run commands when the
	853	caret is at the very start of a heading line, before the stars. These are Org's
	854	=org-speed-commands=; the structure ones are:
	855
	856	\| Key \| Command \| Key \| Command \|
	857	\|-----+-------------------------------+-----+----------------------------\|
	858	\| =n= \| Next Heading \| =U= \| Move Subtree Up \|
	859	\| =p= \| Previous Heading \| =D= \| Move Subtree Down \|
	860	\| =f= \| Next Heading at Same Level \| =r= \| Demote Heading \|
	861	\| =b= \| Previous Heading at Same Level \| =l= \| Promote Heading \|
	862	\| =u= \| Up to Parent Heading \| =R= \| Demote Subtree \|
	863	\| =j= \| Go to Heading… \| =L= \| Promote Subtree \|
	864	\| =s= \| Narrow to Subtree or Widen \| =i= \| Insert Heading After Subtree \|
	865	\| =k= \| Cut Subtree \| =^= \| Sort Entries \|
	866	\| =@= \| Mark Subtree \| =w= \| Refile… \|
	867	\| =#= \| Toggle COMMENT \| =a= \| Archive Subtree \|
	868	\| =/= \| Sparse Tree… \| =c=, =C= \| cycle visibility, cycle global visibility \|
	869
	870	The full list is in [[file:03-keys.org][Keys]].
	871
	872	* Not supported
	873
	874	These Org structure features are not in Orgstar:
	875
	876	- =org-insert-drawer=, =org-copy= (refile a copy) and =org-refile= with a prefix
	877	(jump to a target).
	878	- Editing values in column view, and writing summaries from it; the
	879	=columnview= dynamic block does write summaries.
	880	- The =ORDERED= property, radio lists and timer list items in the list commands.
	881	- =S-<left>= and =S-<right>= to cycle bullets on an item; use =C-c -=.
	882	- =org-drag-element= (=M-<up>= and =M-<down>= on paragraphs).
	883	- Custom =org-structure-template-alist=, =org-refile-targets=, =org-archive-location=
	884	and =org-use-property-inheritance=.

docs/manual/guide/05-todos-and-tags.org added +317

		@@ -0,0 +1,317 @@
	1	#+TITLE: TODOs and tags
	2	#+DESCRIPTION: TODO keywords, state logging, priorities, tags and progress cookies in Orgstar.
	3	#+LEDE: Mark headings as tasks, record when their state changes, rank them, and label them with tags.
	4
	5	* TODO keywords
	6
	7	A heading becomes a task when its first word after the stars is a TODO keyword:
	8
	9	#+BEGIN_SRC org
	10	,* TODO Write the quarterly report
	11	,* DONE Book the venue
	12	#+END_SRC
	13
	14	Keywords come in sequences. Each sequence has active keywords, a =\|=, and done keywords. A keyword after the =\|= counts as done for logging, statistics cookies, repeating tasks and the agenda.
	15
	16	** The default keywords
	17
	18	Files without a =#+TODO= line use the keywords in Settings ▸ Editing ▸ Default TODO keywords, which is the =org-todo-keywords= key in =config.toml=. The default is:
	19
	20	#+BEGIN_SRC org
	21	TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) \| DONE(d) KILL(k)
	22	#+END_SRC
	23
	24	The value uses =#+TODO= syntax. To define more than one sequence, put one per line (=\n= in =config.toml=). Orgstar reads this setting at launch, so a change takes effect after you restart the app. See [[file:13-configuration.org][Configuration]] for the file itself and for keyword colors under =[theme.todo]=.
	25
	26	** Keywords in the file
	27
	28	A file can set its own keywords, which replace the default ones for that file:
	29
	30	#+BEGIN_SRC org
	31	,#+TODO: TODO NEXT WAIT \| DONE CANCELED
	32	,#+TODO: BUG(b) \| FIXED(f)
	33	,#+SEQ_TODO: DRAFT REVIEW \| PUBLISHED
	34	,#+TYP_TODO: ALICE BOB \| DONE
	35	#+END_SRC
	36
	37	- Each line is one sequence. =#+SEQ_TODO= means the same as =#+TODO=.
	38	- Without a =\|=, the last word is the done keyword.
	39	- =#+TYP_TODO= marks a sequence of types (=org-todo-interpretation= =type=). The only difference Orgstar makes is in repeating tasks: a repeating entry returns to the keyword it had before it was done, instead of to the first keyword of the sequence.
	40	- The order of sequences is the order Org uses: =#+TYP_TODO= lines first, then =#+TODO=, then =#+SEQ_TODO=.
	41	- Lines inside blocks are ignored. Lines from a =#+SETUPFILE= count as if they came first in the file.
	42
	43	Edits to these lines take effect as you type. If the keywords come from a setup file you changed, press =C-c C-c= on any =#+= keyword line to read the setup files again (=org-mode-restart=).
	44
	45	** Keyword options
	46
	47	The parentheses after a keyword hold a fast-selection key and logging flags, as in Org:
	48
	49	\| Form \| Meaning \|
	50	\|----------------+-----------------------------------------------------------\|
	51	\| =WAIT(w)= \| Fast-selection key =w= \|
	52	\| =WAIT(w!)= \| Key =w=, record the time when entering the state \|
	53	\| =WAIT(w@)= \| Key =w=, ask for a note when entering the state \|
	54	\| =WAIT(w@/!)= \| Note when entering, time when leaving to a state that logs nothing \|
	55	\| =WAIT(@/!)= \| No key, same logging \|
	56
	57	Logging is described under "Logging state changes" below.
	58
	59	* Changing the state
	60
	61	\| Command \| Org command \| Emacs, Doom \| Mac \| Doom leader \|
	62	\|------------------------+------------------+----------------+------+-------------\|
	63	\| Cycle TODO State \| =org-todo= \| =C-c C-t= \| ⌃⌘T \| =SPC m t= \|
	64	\| Next TODO Keyword \| =org-shiftright= \| =S-<right>= \| \| \|
	65	\| Previous TODO Keyword \| =org-shiftleft= \| =S-<left>= \| \| \|
	66
	67	=S-<right>= and =S-<left>= 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 =C-S-l= and =C-S-h= do the same. The Mac preset has no key for them; use the Org menu or the command palette.
	68
	69	With speed commands on (=org-use-speed-commands=), =t= at the start of a heading line runs Cycle TODO State.
	70
	71	** Cycling
	72
	73	=C-c C-t= behaves in one of two ways:
	74
	75	- If any keyword in the file has a fast-selection key, it opens fast selection (=org-use-fast-todo-selection= =auto=). The default keywords all have keys, so this is what you get unless you define keywords without keys.
	76	- 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.
	77
	78	=S-<right>= and =S-<left>= never use fast selection. They step through every keyword of every sequence in order, then to no keyword, and wrap around.
	79
	80	** Fast selection
	81
	82	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.
	83
	84	\| Key \| Effect \|
	85	\|------------+---------------------------------------------------\|
	86	\| a keyword's key \| Set that keyword \|
	87	\| =SPC= \| Remove the keyword \|
	88	\| =Esc=, =C-g=, any other key \| Quit without changing anything \|
	89
	90	Keywords without a key in parentheses get one: the first letter of the keyword not already taken (a leading =@= is skipped), and failing that a digit counting up from =0=. When two sequences use the same key, the key picks the keyword from the current keyword's sequence.
	91
	92	** Inserting a TODO heading
	93
	94	Insert TODO Heading (=org-insert-todo-heading=, =M-S-RET= 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 [[file:04-outlines.org][Outlines]].
	95
	96	** Dependencies
	97
	98	Orgstar does not enforce TODO dependencies. =org-enforce-todo-dependencies= and the =ORDERED= and =NOBLOCKING= 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.
	99
	100	* Logging state changes
	101
	102	Orgstar logs state changes as =org-todo= does in Org 9.8.
	103
	104	** CLOSED
	105
	106	When =org-log-done= is =time= and an entry moves from an active keyword to a done one, Orgstar adds a =CLOSED= stamp to its planning line:
	107
	108	#+BEGIN_SRC org
	109	,* DONE Book the venue
	110	CLOSED: [2026-10-07 Wed 14:32]
	111	#+END_SRC
	112
	113	With =note=, it also asks for a closing note. Moving the entry back to an active keyword, or removing the keyword, removes =CLOSED=. This happens only while some logging is on (=org-log-done= or a keyword with =!= or =@=); with no logging at all, an existing =CLOSED= stamp stays.
	114
	115	** State notes
	116
	117	A keyword with =!= or =@= records a note when the entry enters it, and the part after =/= records one when the entry leaves it for a state that logs nothing on entry. =!= records the time; =@= asks for a note in the echo area:
	118
	119	#+BEGIN_SRC org
	120	,#+TODO: TODO(t) WAIT(w@/!) \| DONE(d!) CANCELED(c@)
	121
	122	,* WAIT Call the supplier
	123	- State "WAIT" from "TODO" [2026-10-07 Wed 09:15] \\
	124	Left a message, waiting for a reply.
	125	#+END_SRC
	126
	127	Notes go first in the entry, after the planning line and property drawer, newest first (=org-log-states-order-reversed= =t=). The note text is indented under the item; lines starting with =#= and a space are dropped. If the keyword's own flag and =org-log-done= both apply, the keyword's flag wins.
	128
	129	The headings are Org's default =org-log-note-headings=:
	130
	131	\| Event \| Note heading \|
	132	\|-----------------------+------------------------------------------------------\|
	133	\| State change \| =State "DONE" from "TODO" [timestamp]= \|
	134	\| Closing note \| =CLOSING NOTE [timestamp]= \|
	135	\| Rescheduled \| =Rescheduled from "[old date]" on [timestamp]= \|
	136	\| Schedule removed \| =Not scheduled, was "[old date]" on [timestamp]= \|
	137	\| New deadline \| =New deadline from "[old date]" on [timestamp]= \|
	138	\| Deadline removed \| =Removed deadline, was "[old date]" on [timestamp]= \|
	139
	140	Rescheduling and deadline notes are covered in [[file:06-dates-and-clocking.org][Dates, scheduling and clocking]]. Orgstar has no command to add a free note to an entry (=org-add-note=).
	141
	142	** The LOGBOOK drawer
	143
	144	With =org-log-into-drawer= set to a drawer name, notes go at the top of that drawer, which Orgstar creates when it is missing:
	145
	146	#+BEGIN_SRC org
	147	,* DONE Book the venue
	148	CLOSED: [2026-10-07 Wed 14:32]
	149	:LOGBOOK:
	150	- State "DONE" from "TODO" [2026-10-07 Wed 14:32]
	151	:END:
	152	#+END_SRC
	153
	154	In =config.toml=, ="LOGBOOK"= is the equivalent of Emacs's =t=, and =""= (the default) means no drawer. Clock lines always go into a =LOGBOOK= drawer, whatever this setting says.
	155
	156	** Where the settings come from
	157
	158	Later sources override earlier ones:
	159
	160	1. =config.toml=: =org-log-done=, =org-log-reschedule=, =org-log-redeadline= (each =nil=, =time= or =note=, default =nil=) and =org-log-into-drawer= (default =""=). These have no control in the Settings window. =org-log-repeat= is always =time= unless the file changes it.
	161	2. Keyword flags such as =DONE(d!)=.
	162	3. =#+STARTUP= words in the file or its setup files.
	163	4. The =LOGGING= property, inherited from ancestors.
	164	5. The =LOG_INTO_DRAWER= property, inherited from ancestors: =t= for =LOGBOOK=, =nil= for none, or a drawer name.
	165
	166	\| =#+STARTUP= word \| Effect \|
	167	\|--------------------------------------------------------+------------------------------------------\|
	168	\| =logdone=, =lognotedone=, =nologdone= \| =org-log-done= =time=, =note=, =nil= \|
	169	\| =logrepeat=, =lognoterepeat=, =nologrepeat= \| =org-log-repeat= =time=, =note=, =nil= \|
	170	\| =logreschedule=, =lognotereschedule=, =nologreschedule= \| =org-log-reschedule= \|
	171	\| =logredeadline=, =lognoteredeadline=, =nologredeadline= \| =org-log-redeadline= \|
	172	\| =logdrawer=, =nologdrawer= \| =org-log-into-drawer= =LOGBOOK= or none \|
	173
	174	A =LOGGING= property (=org-local-logging=) replaces the done, repeat and per-keyword settings for its subtree. It takes the =logdone= and =logrepeat= words above and keyword specifications such as =WAIT(@)=; =nil= turns them all off:
	175
	176	#+BEGIN_SRC org
	177	,* Errands
	178	:PROPERTIES:
	179	:LOGGING: DONE(!) WAIT(@) logrepeat
	180	:LOG_INTO_DRAWER: NOTES
	181	:END:
	182	#+END_SRC
	183
	184	* Priorities
	185
	186	A priority cookie goes after the keyword:
	187
	188	#+BEGIN_SRC org
	189	,* TODO [#A] Renew the passport
	190	#+END_SRC
	191
	192	The range is =A= (highest) to =C= (lowest), with =B= as the default. A file can change it with =#+PRIORITIES: highest lowest default=, using letters or numbers:
	193
	194	#+BEGIN_SRC org
	195	,#+PRIORITIES: A E C
	196	,#+PRIORITIES: 1 10 5
	197	#+END_SRC
	198
	199	\| Command \| Org command \| Emacs, Doom \| Mac \| Doom leader \|
	200	\|-------------------------------+-----------------+-----------------+-------+-------------\|
	201	\| Set Priority… \| =org-priority= \| =C-c ,= \| \| =SPC m p p= \|
	202	\| Raise Priority \| =org-priority-up= \| =S-<up>= \| ⌃⌘↑ \| =SPC m p u= \|
	203	\| Lower Priority \| =org-priority-down= \| =S-<down>= \| ⌃⌘↓ \| =SPC m p d= \|
	204
	205	=S-<up>= and =S-<down>= act on the priority when the caret is on a heading line and not on a timestamp; Doom also binds =C-S-k= and =C-S-j=.
	206
	207	- Set Priority shows the priorities with their keys (lowercase letters, or the digits of a numeric range) and =SPC= to remove the cookie. When the lowest numeric priority is 10 or more, it asks you to type the number instead.
	208	- Raise and Lower start at the default priority when the heading has none (=org-priority-start-cycle-with-default=). Going past the highest or lowest priority removes the cookie.
	209	- With speed commands on, =,= runs Set Priority, =1=, =2= and =3= set =A=, =B= and =C=, and =0= removes the priority.
	210
	211	The agenda sorts by priority; see [[file:07-agenda.org][The agenda]].
	212
	213	* Tags
	214
	215	Tags go at the end of a heading, between colons:
	216
	217	#+BEGIN_SRC org
	218	,* TODO Order parts :work:urgent:
	219	#+END_SRC
	220
	221	A tag consists of letters, digits, =_=, =@=, =#= and =%=.
	222
	223	** Setting tags
	224
	225	\| Command \| Org command \| Emacs, Doom \| Mac \| Doom leader \|
	226	\|-----------+---------------------------+---------------+-------+-------------\|
	227	\| Set Tags \| =org-set-tags-command= \| =C-c C-q= \| ⌃⌘Q \| =SPC m q= \|
	228
	229	=C-c C-c= on a heading line also runs Set Tags, and so does =:= as a speed command.
	230
	231	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 =#+TAGS= lines, or, without those, every tag used in the file and its =#+FILETAGS=, 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.
	232
	233	Setting tags on the text before the first heading (file tags) is not supported; edit the =#+FILETAGS= line directly.
	234
	235	Typing =:= at the end of a heading line also completes tags: from the =#+TAGS= 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 [[file:02-the-editor.org][The editor]] for how completion works.
	236
	237	** Fast tag selection
	238
	239	When a =#+TAGS= line gives at least one tag a key, Set Tags opens fast selection (=org-fast-tag-selection=):
	240
	241	#+BEGIN_SRC org
	242	,#+TAGS: { @office(o) @home(h) @errand(e) } laptop(l) phone(p)
	243	,#+TAGS: [ Project : alpha beta ]
	244	#+END_SRC
	245
	246	\| Key \| Effect \|
	247	\|----------------+-----------------------------------------------------------\|
	248	\| a tag's key \| Toggle that tag \|
	249	\| =SPC= \| Remove all tags \|
	250	\| =TAB= \| Type a tag by name, then =RET= \|
	251	\| =!= \| Turn the exclusion of ={ }= groups off or back on \|
	252	\| =RET= \| Apply the selection \|
	253	\| =q= \| Quit, unless a tag uses =q= as its key \|
	254	\| =Esc=, =C-g= \| Quit \|
	255
	256	The view shows the inherited tags, the current selection, and each tag with its key, in the rows and groups of the =#+TAGS= lines.
	257
	258	- Tags between ={= and =}= exclude each other: selecting one removes the others in the group.
	259	- Tags between =[= and =]=, with =:= 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 [[file:07-agenda.org][The agenda]].
	260	- Tags without a key get one: their first letter if it is free, otherwise the next free character from =a–z=, =A–Z= and ={\|}~=.
	261	- The selected tags are written in the order of the =#+TAGS= lines, followed by any others.
	262
	263	=#+TAGS= lines come only from the file and its setup files. Orgstar has no global tag list (=org-tag-alist=); the workspace's tags are used for completion only.
	264
	265	** Inheritance
	266
	267	An entry inherits the tags of its ancestors and the file's =#+FILETAGS= (=org-use-tag-inheritance= =t=). Fast selection lists inherited tags separately. Agenda matches and clock tables with =:tags t= use the inherited tags too. Orgstar has no setting to limit inheritance (=org-tags-exclude-from-inheritance=).
	268
	269	#+BEGIN_SRC org
	270	,#+FILETAGS: :home:
	271
	272	,* Garden :outdoor:
	273	,** TODO Prune the roses
	274	#+END_SRC
	275
	276	Here "Prune the roses" has the tags =home= and =outdoor= through inheritance.
	277
	278	** Alignment
	279
	280	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 =org-tags-column=, under Settings ▸ Editing ▸ Tags:
	281
	282	\| Value \| Placement \|
	283	\|------------+----------------------------------------------------\|
	284	\| =-77= \| Tags end at column 77 (the default) \|
	285	\| =0= \| One space after the title \|
	286	\| negative N \| Tags end at column N \|
	287	\| positive N \| Tags start at column N \|
	288
	289	The Settings window offers =-77= and =0=; other values go in =config.toml=. Columns are counted as Emacs displays the line, so links count as their description and, when =org-hide-emphasis-markers= is on, emphasis markers do not count. A heading always keeps at least one space before its tags.
	290
	291	* Progress on child tasks
	292
	293	A =[/]= or =[%]= cookie in a heading shows how many of its children are done:
	294
	295	#+BEGIN_SRC org
	296	,* Move house [1/3]
	297	,** DONE Hire a van
	298	,** TODO Pack the kitchen
	299	,** TODO Forward the mail
	300	#+END_SRC
	301
	302	Orgstar updates the cookie whenever a child's TODO keyword changes (=org-update-parent-todo-statistics=, with =org-hierarchical-todo-statistics= =t=). Only direct children with a TODO keyword count; children without one are ignored. =C-c C-c= on a cookie updates it by hand.
	303
	304	The =COOKIE_DATA= property changes what the parent's cookie counts:
	305
	306	- =recursive= 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.
	307	- =checkbox= makes the cookie count checkboxes in the entry's lists instead of child tasks. Checkbox cookies are described in [[file:04-outlines.org][Outlines]].
	308
	309	* Related settings
	310
	311	\| Setting \| Where \| Default \|
	312	\|-------------------------+-------------------------------------------+----------------------------\|
	313	\| =org-todo-keywords= \| Settings ▸ Editing, =config.toml= \| See "The default keywords" above \|
	314	\| =org-log-done= \| =config.toml= \| =nil= \|
	315	\| =org-log-into-drawer= \| =config.toml= \| =""= (no drawer) \|
	316	\| =org-tags-column= \| Settings ▸ Editing, =config.toml= \| =-77= \|
	317	\| =org-use-speed-commands= \| =config.toml= \| =false= \|

docs/manual/guide/06-dates-and-clocking.org added +390

		@@ -0,0 +1,390 @@
	1	#+TITLE: Dates, scheduling and clocking
	2	#+DESCRIPTION: Timestamps, the date prompt, SCHEDULED and DEADLINE, repeating tasks, effort, clocking, clock tables, habits and reminders in Orgstar.
	3	#+LEDE: Put dates on entries, plan work with scheduled dates and deadlines, and record the time you spend.
	4
	5	* Timestamps
	6
	7	A timestamp is a date, optionally with a time, in angle brackets (active) or square brackets (inactive):
	8
	9	#+BEGIN_SRC org
	10	<2026-10-07 Wed>
	11	<2026-10-07 Wed 14:30>
	12	<2026-10-07 Wed 10:00-11:30>
	13	<2026-10-07 Wed>--<2026-10-09 Fri>
	14	[2026-10-07 Wed 09:12]
	15	#+END_SRC
	16
	17	- Active timestamps put the entry on the agenda for that day. Inactive ones are records only.
	18	- =10:00-11:30= is a time range within one day. =<…>--<…>= is a range of days; both ends must be of the same kind.
	19	- Orgstar writes day names in English. When reading, it accepts a day name in any language, as Org does.
	20
	21	** Repeaters and warning periods
	22
	23	After the date and time, a timestamp can carry a repeater and a warning or delay:
	24
	25	#+BEGIN_SRC org
	26	<2026-10-07 Wed +1w>
	27	<2026-10-07 Wed 08:00 ++1d>
	28	<2026-10-07 Wed .+2w>
	29	<2026-10-31 Sat -3d>
	30	<2026-10-31 Sat +1m -5d>
	31	<2026-10-07 Wed .+2d/4d>
	32	#+END_SRC
	33
	34	\| Element \| Meaning \|
	35	\|----------+-------------------------------------------------------------------------\|
	36	\| =+1w= \| Repeat every week, counted from the date in the timestamp \|
	37	\| =++1w= \| Repeat every week, moving the date past today when the task is done \|
	38	\| =.+1w= \| Repeat one week after the day the task is done \|
	39	\| =-3d= \| On a deadline, start warning 3 days before; on a scheduled date, hide it from the agenda until 3 days after \|
	40	\| =--3d= \| As =-3d=, for the first occurrence only; it is dropped when the task repeats \|
	41	\| =/4d= \| After a repeater, the longest interval a habit allows (see "Habits") \|
	42
	43	Units are =h= (hours), =d=, =w=, =m= and =y=. What happens when a repeating task is done is described under "Repeating tasks".
	44
	45	** Diary sexps
	46
	47	The agenda also reads =<%%(…)>= timestamps and =%%(…)= lines with Emacs diary expressions such as =diary-float=, =diary-anniversary=, =diary-block= and =diary-cyclic=, and their =org-= counterparts. See [[file:07-agenda.org][The agenda]] for the functions that are supported. Orgstar does not insert or edit these.
	48
	49	* Inserting timestamps
	50
	51	\| Command \| Org command \| Emacs, Doom \| Mac \| Doom leader \|
	52	\|-----------------------------+----------------------+-------------+-------+-------------\|
	53	\| Insert Timestamp \| =org-timestamp= \| =C-c .= \| ⌃⌘. \| =SPC m d t= \|
	54	\| Insert Inactive Timestamp \| =org-timestamp-inactive= \| =C-c != \| ⌃⌥⌘. \| =SPC m d T= \|
	55
	56	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. Run the command again right after inserting a timestamp to add a second one and make a range, =<…>--<…>=.
	57
	58	Org's prefix arguments are not available: to include the current time, type it, or use a relative time such as =+0h= (see below).
	59
	60	* The date prompt
	61
	62	Every command that asks for a date shows the same prompt (=org-read-date=): a text field, the date the text reads as, and a month calendar.
	63
	64	- Type a date in any of the forms below. The line above the field shows the result, such as =<2026-10-09 Fri 15:00>=, as you type.
	65	- Click a day in the calendar to answer with that day. A time you typed is kept.
	66	- =S-<left>= and =S-<right>= in the field move the answer one day; =S-<up>= and =S-<down>= move it one week.
	67	- =RET= accepts. An empty answer takes the default: the date of the timestamp being changed, or today.
	68	- =Esc= cancels.
	69
	70	Orgstar reads the answer as Org 9.8 does, with =org-read-date-prefer-future= =t=: a date given without a year, or without a month, is taken to be the next such date from today.
	71
	72	\| You type \| Result \|
	73	\|--------------------+-----------------------------------------------------------\|
	74	\| =.= \| Today \|
	75	\| =+0= \| Today \|
	76	\| =+1=, =+2d= \| Tomorrow, two days from today \|
	77	\| =-3d= \| Three days ago \|
	78	\| =+1w=, =+2m=, =-1y= \| One week, two months from today; one year ago \|
	79	\| =++3= \| Three days after the default date, not after today \|
	80	\| =+3h= \| Three hours after the default time; sets a time \|
	81	\| =fri=, =mon= \| The next Friday or Monday, the default date included \|
	82	\| =+fri= \| The next Friday after today \|
	83	\| =-fri= \| The last Friday before today \|
	84	\| =+2fri= \| The second Friday from today \|
	85	\| =2026-10-07=, =2026-10-7= \| That date \|
	86	\| =10-7= \| 7 October, the next one \|
	87	\| =7.10.=, =7.10.2027= \| 7 October (day first) \|
	88	\| =10/7=, =10/7/27= \| 7 October (month first) \|
	89	\| =15= \| The 15th, this month or next \|
	90	\| =sep 15=, =15 sep= \| 15 September, the next one \|
	91	\| =dec 25 2027= \| 25 December 2027 \|
	92	\| =w42=, =2027-w01=, =w3-5= \| Monday of ISO week 42; Monday of week 1 of 2027; Friday of week 3 \|
	93	\| =10:00=, =9:30= \| The default date at that time \|
	94	\| =10am=, =3pm=, =12:30pm= \| 12-hour times \|
	95	\| =10h=, =10h30=, =h45= \| 10:00, 10:30, 00:45 \|
	96	\| =10:00-11:30= \| A time range \|
	97	\| =10:00+1:30= \| 10:00-11:30 \|
	98	\| =fri 10:00=, =+2d 9:00= \| A date and a time together \|
	99
	100	Forms without a sign, such as =fri=, =15= or =10:00=, 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; =++= counts from the default date. Two-digit years are read relative to the current year. Words the prompt does not recognize are ignored, so =tomorrow= gives the default date.
	101
	102	* Changing dates
	103
	104	\| Command \| Org command \| Emacs, Doom \| Mac \|
	105	\|------------------------------+--------------------------+---------------+------\|
	106	\| Increase Timestamp Part \| =org-timestamp-up= \| =S-<up>= \| ⌃⌘↑ \|
	107	\| Decrease Timestamp Part \| =org-timestamp-down= \| =S-<down>= \| ⌃⌘↓ \|
	108	\| Timestamp One Day Later \| =org-timestamp-up-day= \| =S-<right>= \| ⌃⌘→ \|
	109	\| Timestamp One Day Earlier \| =org-timestamp-down-day= \| =S-<left>= \| ⌃⌘← \|
	110	\| Evaluate Time Range \| =org-evaluate-time-range= \| =C-c C-y= \| \|
	111
	112	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 ([[file:05-todos-and-tags.org][TODOs and tags]]). In the Doom preset they work in normal and insert state, and =C-S-h=, =C-S-j=, =C-S-k= and =C-S-l= do the same as =S-<left>=, =S-<down>=, =S-<up>= and =S-<right>=.
	113
	114	=S-<up>= and =S-<down>= change the part of the timestamp under the caret:
	115
	116	- the year, month or day (on the day name, the day);
	117	- the hour, or the minute in steps of 5 (=org-time-stamp-rounding-minutes=), first rounding to a multiple of 5;
	118	- in a time range, the end time; changing the start time moves the end time with it;
	119	- the number or unit of a repeater or warning (the unit cycles =d=, =w=, =m=, =y=);
	120	- on the opening or closing bracket, the timestamp switches between active and inactive.
	121
	122	=S-<left>= and =S-<right>= 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.
	123
	124	=C-c C-c= on a timestamp rewrites its day name to match its date. =C-c C-y= shows the length of the range at the caret, or of the first range on the line, such as =2 days 3 hours=; on a clock line it recomputes the clock's duration.
	125
	126	* SCHEDULED and DEADLINE
	127
	128	A planning line goes directly under the heading:
	129
	130	#+BEGIN_SRC org
	131	,* TODO Submit the tax return
	132	DEADLINE: <2026-10-31 Sat -7d> SCHEDULED: <2026-10-20 Tue>
	133	#+END_SRC
	134
	135	- =SCHEDULED= is the day you plan to start. The agenda shows the entry from that day until it is done.
	136	- =DEADLINE= is the day it is due. The agenda warns about it 14 days ahead (=org-deadline-warning-days=), or as the timestamp's own =-Nd= says.
	137
	138	\| Command \| Org command \| Emacs, Doom \| Mac \| Doom leader \|
	139	\|------------------+------------------+-------------+------+-------------\|
	140	\| Schedule \| =org-schedule= \| =C-c C-s= \| ⌃⌘S \| =SPC m d s= \|
	141	\| Set Deadline \| =org-deadline= \| =C-c C-d= \| ⌃⌘D \| =SPC m d d= \|
	142	\| Remove Schedule \| =C-u C-c C-s= \| \| \| \|
	143	\| Remove Deadline \| =C-u C-c C-d= \| \| \| \|
	144
	145	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 =CLOSED= stamp from the entry. Remove Schedule and Remove Deadline have no default keys; run them from the Org menu or the command palette ([[file:03-keys.org][Keys]]).
	146
	147	With =org-log-reschedule= or =org-log-redeadline= set to =time= or =note= in =config.toml=, or the matching =#+STARTUP= words, Orgstar logs each change of an existing date and each removal:
	148
	149	#+BEGIN_SRC org
	150	,* TODO Submit the tax return
	151	SCHEDULED: <2026-10-22 Thu>
	152	- Rescheduled from "[2026-10-20 Tue]" on [2026-10-19 Mon 08:40]
	153	#+END_SRC
	154
	155	Where these notes go, and the =#+STARTUP= words, are covered in [[file:05-todos-and-tags.org][TODOs and tags]].
	156
	157	* Repeating tasks
	158
	159	When an entry with a repeater in an active timestamp changes from an active TODO keyword to a done one (=org-auto-repeat-maybe=), Orgstar does not leave it done:
	160
	161	1. The keyword returns to the first keyword of its sequence. In a =#+TYP_TODO= sequence it returns to the keyword it had. A =REPEAT_TO_STATE= property, inherited from ancestors, names another keyword to use.
	162	2. =CLOSED= is removed.
	163	3. With =org-log-repeat= on (the default, =time=), the =LAST_REPEAT= property is set to the current time and a state note is logged, such as =- State "DONE" from "TODO" [2026-10-07 Wed 18:02]=.
	164	4. A =SCHEDULED= date without a repeater is removed.
	165	5. Every active timestamp with a repeater in the entry moves forward:
	166	- =+N= moves it by N once, which may leave it in the past.
	167	- =++N= moves it by N until it is after today (for hours, after now).
	168	- =.+N= sets it to today and then moves it by N.
	169	6. =--= delays in those timestamps are removed.
	170
	171	#+BEGIN_SRC org
	172	,* TODO Water the plants
	173	SCHEDULED: <2026-10-07 Wed .+3d>
	174	#+END_SRC
	175
	176	Marking this done on 7 October gives:
	177
	178	#+BEGIN_SRC org
	179	,* TODO Water the plants
	180	SCHEDULED: <2026-10-10 Sat .+3d>
	181	:PROPERTIES:
	182	:LAST_REPEAT: [2026-10-07 Wed 18:02]
	183	:END:
	184	- State "DONE" from "TODO" [2026-10-07 Wed 18:02]
	185	#+END_SRC
	186
	187	A repeater of =0= (=+0d=) 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.
	188
	189	To turn the repeat note off for a file, use =#+STARTUP: nologrepeat=; =lognoterepeat= asks for a note instead.
	190
	191	* Effort
	192
	193	Effort estimates live in the =Effort= property.
	194
	195	\| Command \| Org command \| Emacs, Doom \| Doom leader \| Speed key \|
	196	\|-------------+------------------+---------------+---------------+-----------\|
	197	\| Set Effort \| =org-set-effort= \| =C-c C-x e= \| =SPC m c E= \| =e= \|
	198
	199	Set Effort asks for a value, such as =0:30= or =2:00=, starting with the current one. If the entry, an ancestor, or a =#+PROPERTY: Effort_ALL= line defines =Effort_ALL=, its values are offered as choices; you can also type another value.
	200
	201	#+BEGIN_SRC org
	202	,#+PROPERTY: Effort_ALL 0:15 0:30 1:00 2:00 4:00
	203	#+END_SRC
	204
	205	Effort appears in column view and in clock tables with =:properties ("Effort")=. Orgstar does not compare the running clock with the effort estimate.
	206
	207	* Clocking
	208
	209	Clocking records the time you work on an entry as =CLOCK:= lines in its =LOGBOOK= drawer.
	210
	211	\| Command \| Org command \| Emacs, Doom \| Doom leader \| Speed key \|
	212	\|----------------------+--------------------+-----------------+-------------+-----------\|
	213	\| Clock In \| =org-clock-in= \| =C-c C-x C-i= \| =SPC m c i= \| =I= \|
	214	\| Clock Out \| =org-clock-out= \| =C-c C-x C-o= \| =SPC m c o= \| =O= \|
	215	\| Cancel Clock \| =org-clock-cancel= \| =C-c C-x C-q= \| =SPC m c c= \| \|
	216	\| Go to Clocked Entry \| =org-clock-goto= \| =C-c C-x C-j= \| =SPC m c g= \| \|
	217
	218	The Mac preset has no keys for these; run them from the command palette, or the clock menus described below. In the agenda, =I=, =O= and =X= clock in, out and cancel for the entry at the line ([[file:07-agenda.org][The agenda]]). Capture templates can clock in too ([[file:08-capture.org][Capture]]).
	219
	220	** Clocking in and out
	221
	222	Clock In starts a clock on the heading at the caret and inserts a line at the top of its =LOGBOOK= drawer, creating the drawer after the planning line and property drawer if needed:
	223
	224	#+BEGIN_SRC org
	225	,* TODO Write the report
	226	:LOGBOOK:
	227	CLOCK: [2026-10-07 Wed 09:00]
	228	CLOCK: [2026-10-06 Tue 14:00]--[2026-10-06 Tue 15:30] => 1:30
	229	:END:
	230	#+END_SRC
	231
	232	- Only one clock runs at a time. Clocking in while another clock runs clocks that one out first.
	233	- =CLOCK:= lines outside a drawer move into the new drawer the first time you clock in on that entry.
	234	- Clock Out completes the line with the end time and the duration in hours and minutes. Clocks of zero minutes are kept.
	235	- Cancel Clock removes the running clock's line, and the drawer if it is left empty.
	236	- Go to Clocked Entry opens the file and moves the caret to the running clock's line.
	237
	238	Orgstar remembers the running clock across restarts, in =clock.json= in =~/Library/Application Support/Orgstar=. If the open =CLOCK:= line is deleted from the file, Clock Out reports "Clock start time is gone" and forgets the clock.
	239
	240	These parts of Org's clocking are not implemented:
	241
	242	- clock history and the =C-u C-c C-x C-i= selection of recent tasks;
	243	- idle detection and resolving dangling clocks (=org-clock-idle-time=, =org-resolve-clocks=);
	244	- sharing the running clock with Emacs: Orgstar does not read or write Emacs's =org-clock-persist= file, so a clock started in one is not known to the other, although both see the open =CLOCK:= line;
	245	- rounding, changing the TODO state on clock-in (=org-clock-in-switch-to-state=), and clocking out when the entry is marked done (=org-clock-out-when-done=): the clock keeps running;
	246	- a =CLOCK_INTO_DRAWER= property or another drawer name: clocks always go into =LOGBOOK=.
	247
	248	** The running clock
	249
	250	While a clock runs, Orgstar shows it in three places, refreshed every 30 seconds:
	251
	252	- the mode line under the editor: =⏱ 0:42 Write the report=;
	253	- the window's toolbar;
	254	- the macOS menu bar, with the elapsed time.
	255
	256	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 menu bar item also has Clock Report.
	257
	258	** Editing clock lines
	259
	260	You can edit clock lines by hand. =S-<up>= and =S-<down>= change their timestamps as anywhere else, but do not update the duration after ~=>~. Press =C-c C-c= (or =C-c C-y=) on the line afterwards: Orgstar fixes both day names and writes the duration again (=org-clock-update-time-maybe=).
	261
	262	A line of the form ~CLOCK: => 1:15~, with only a duration, counts towards clock tables.
	263
	264	* Clock summaries
	265
	266	** The inspector
	267
	268	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.
	269
	270	** The clock report window
	271
	272	Clock Report (=SPC m c R= and =SPC z t= 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:
	273
	274	#+BEGIN_SRC org
	275	,#+title: Time Report
	276
	277	\| Date \| Code \| Hours \|
	278	\|--------------+-----------------------------------------------+-------\|
	279	\| 2026-10-05 \| Write the report \| 2:15 \|
	280	\| 2026-10-06 \| Write the report \| 1:30 \|
	281	\|--------------+-----------------------------------------------+-------\|
	282	\| 2026-W41 \| WEEK TOTAL \| 3:45 \|
	283	#+END_SRC
	284
	285	Copy puts it on the clipboard; Save writes it to a file.
	286
	287	* Clock tables
	288
	289	A clock table is a dynamic block that Orgstar fills with a summary of clocked time (=org-clocktable-write-default=).
	290
	291	\| Command \| Org command \| Emacs, Doom \|
	292	\|---------------------------------+----------------------+-----------------\|
	293	\| Insert or Update Clock Table \| =org-clock-report= \| =C-c C-x C-r= \|
	294	\| Update Dynamic Block \| =org-update-dblock= \| =C-c C-x C-u= \|
	295
	296	=C-c C-c= on the =#+BEGIN:= line also updates the block. In the Mac preset, use the Org menu or the command palette.
	297
	298	Insert or Update Clock Table updates the clock table at the caret. Elsewhere it inserts a new one, with =:scope subtree= inside an entry or =:scope file= before the first heading, and fills it:
	299
	300	#+BEGIN_SRC org
	301	,#+BEGIN: clocktable :scope file :maxlevel 2 :block thisweek
	302	,#+CAPTION: Clock summary at [2026-10-07 Wed 17:00], for week 2026-W41.
	303	\| Headline \| Time \| \|
	304	\|------------------+--------+------\|
	305	\| Total time \| 5:15 \| \|
	306	\|------------------+--------+------\|
	307	\| Project Alpha \| 5:15 \| \|
	308	\| \_ Design \| \| 3:00 \|
	309	\| \_ Write code \| \| 2:15 \|
	310	,#+END:
	311	#+END_SRC
	312
	313	Times are written as =H:MM=, with a day count such as =2d= before them for a day or more. A heading's time includes its subtree's. Only finished clock lines and ~CLOCK: => H:MM~ lines count; a running clock does not. A =COMMENT= prefix is left out of headlines.
	314
	315	** Parameters
	316
	317	\| Parameter \| Values \| Default \|
	318	\|-------------------+------------------------------------------------+-----------\|
	319	\| =:scope= \| =file= (or =nil=), =subtree=, =tree=, =treeN= \| =file= \|
	320	\| =:maxlevel= \| Deepest heading level listed \| =2= \|
	321	\| =:block= \| A time block (see below) \| none \|
	322	\| =:tstart=, =:tend= \| Start and end, such as ="<2026-09-01>"=, ="<today>"=, ="<-1w>"= \| none \|
	323	\| =:wstart= \| First day of the week for =:block= weeks, =1= is Monday \| =1= \|
	324	\| =:mstart= \| First day of the month for =:block= months \| =1= \|
	325	\| =:link= \| =t=: headlines link to their headings \| =nil= \|
	326	\| =:narrow= \| =N= adds a =<N>= width cookie; =N!= cuts headlines to N characters \| =40!= \|
	327	\| =:indent= \| =t=: indent sublevels with =\_= \| =t= \|
	328	\| =:compact= \| =t=: one time column, indented, cut to 40 characters \| =nil= \|
	329	\| =:emphasize= \| =t=: level 1 bold, level 2 italic \| =nil= \|
	330	\| =:level= \| =t=: a column with the level \| =nil= \|
	331	\| =:tags= \| =t=: a column with the tags, inherited ones first \| =nil= \|
	332	\| =:properties= \| A list of property names, such as =("Effort")=, one column each \| none \|
	333	\| =:tcolumns= \| Number of time columns \| up to =:maxlevel= \|
	334	\| =:formula= \| =%= adds a percentage column; a string becomes the table's =#+TBLFM= \| none \|
	335	\| =:fileskip0= \| Accepted; has no effect within one file \| =nil= \|
	336
	337	=:scope tree= covers the top-level tree around the block; =tree2= the tree from its level-2 ancestor, and so on. =:block= takes precedence over =:tstart= and =:tend=. Clocks that cross the start or end of the range count only the part inside it.
	338
	339	=:block= values:
	340
	341	\| Value \| Range \|
	342	\|-------------------------------------------+-----------------------------------------\|
	343	\| =today=, =yesterday=, =today-N= \| One day \|
	344	\| =thisweek=, =lastweek=, =thisweek-N= \| One week, from =:wstart= \|
	345	\| =thismonth=, =lastmonth=, =thismonth-N= \| One month, from =:mstart= \|
	346	\| =thisyear=, =lastyear=, =thisyear-N= \| One year \|
	347	\| =2026=, =2026-10=, =2026-W41=, =2026-10-07= \| That year, month, ISO week or day \|
	348
	349	=week=, =month= and =year= are the same as =thisweek=, =thismonth= and =thisyear=, and a =+N= suffix moves forward.
	350
	351	A =#+TBLFM= line already under the table is kept when the table is updated, unless =:formula= gives one.
	352
	353	Not supported: scopes over other files (=agenda=, file lists, =file-with-archives=), =:match= and =:step=, which stop the update with a message, and =:formatter=, which is ignored along with other unknown parameters. Labels are in English only.
	354
	355	* Habits
	356
	357	A habit is a repeating task whose history the agenda shows as a consistency graph (=org-habit=). Define one with the =STYLE= property and a =SCHEDULED= date with a repeater:
	358
	359	#+BEGIN_SRC org
	360	,* TODO Go for a run
	361	SCHEDULED: <2026-10-07 Wed .+2d/4d>
	362	:PROPERTIES:
	363	:STYLE: habit
	364	:END:
	365	:LOGBOOK:
	366	- State "DONE" from "TODO" [2026-10-05 Mon 07:30]
	367	- State "DONE" from "TODO" [2026-10-03 Sat 07:10]
	368	:END:
	369	#+END_SRC
	370
	371	- The repeater sets the interval you aim for. Use =.+= for most habits, so the next date counts from when you last did it.
	372	- The optional =/4d= sets the longest acceptable interval. It must be longer than the repeater.
	373	- The repeater's unit must be =d=, =w=, =m= or =y=. A month counts as 30.4 days and a year as 365.25.
	374	- The history comes from the entry's state notes for done keywords and its =CLOSING NOTE= lines, up to 28 of them. Those are written when the task repeats, as long as =org-log-repeat= is on (the default), or when =org-log-done= is =note=.
	375
	376	How habits appear in the agenda, with the graph covering 21 days back and 7 ahead, is described in [[file:07-agenda.org][The agenda]].
	377
	378	* Reminders
	379
	380	Orgstar can post a macOS notification before entries that have a time of day, as Emacs's =appt= does with =org-agenda-to-appt=.
	381
	382	- 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.
	383	- Each reminder comes the lead time before the entry's time: 12 minutes by default (=appt-message-warning-time=). An =APPT_WARNTIME= property on the entry, in minutes, overrides it.
	384	- If the warning time has already passed when Orgstar sets a reminder but the entry has not started, the notification comes at once.
	385	- At most 64 reminders are pending at a time, the earliest first.
	386	- 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.
	387
	388	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.
	389
	390	Turn reminders on or off, and set the lead time from 0 to 120 minutes, in Settings ▸ Agenda; in =config.toml= the keys are =reminders= under =[orgstar]= (default =true=) and =appt-message-warning-time=. 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 [[file:14-ios.org][iOS]].

docs/manual/guide/07-agenda.org added +445

		@@ -0,0 +1,445 @@
	1	#+TITLE: The agenda
	2	#+DESCRIPTION: The agenda window, the TODO list, tag and property matches, saved views, filters, reminders and the board.
	3	#+LEDE: The agenda collects dated entries and TODO items from your agenda files into one list you can act on.
	4
	5	* Opening the agenda
	6
	7	On the Mac the agenda is its own window. Open it with Window ▸ Agenda, or with the key for your preset:
	8
	9	\| Preset \| Key \|
	10	\|--------+--------------------------------------\|
	11	\| Mac \| =⇧⌘A= \|
	12	\| Emacs \| =C-c a= or =⇧⌘A= \|
	13	\| Doom \| =SPC o a= (normal state), =C-c a= or =⇧⌘A= \|
	14
	15	With =org-use-speed-commands= on, =v= at the start of a heading line opens it too (see [[file:03-keys.org][Keys]]).
	16
	17	The key opens the window directly. There is no =org-agenda= dispatcher; you choose what the window shows from the view menu at the left of its toolbar (see [[*Views][Views]]).
	18
	19	Opening a timestamp with =org-open-at-point= (=C-c C-o= in the Emacs preset) opens the agenda on that timestamp's day, or on every day of a date range.
	20
	21	On iOS the agenda is the first tab. See [[*The agenda on iOS][The agenda on iOS]].
	22
	23	* Agenda files
	24
	25	Orgstar has no =org-agenda-files= list. The agenda reads every =.org= file at the top level of each folder you have added (see [[file:01-files-and-folders.org][Files and folders]]). Files whose names start with a dot are left out, as =org-agenda-file-regexp= leaves them out.
	26
	27	To include files in subfolders as well, turn on Settings ▸ Agenda ▸ Include files in subfolders, or set this in =config.toml=:
	28
	29	#+BEGIN_SRC toml
	30	[orgstar]
	31	agenda-include-subfolders = true
	32	#+END_SRC
	33
	34	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 =#+SETUPFILE= is read again on every refresh, because its setup file may have changed.
	35
	36	Within a file, the agenda skips:
	37
	38	- trees tagged =ARCHIVE=, and every entry in a file whose =#+FILETAGS= include =ARCHIVE=;
	39	- commented trees (a heading whose title starts with =COMMENT=);
	40	- everything below a skipped heading.
	41
	42	An entry's category is the nearest =CATEGORY= property on it or an ancestor, else the file's =#+CATEGORY=, else the file name without =.org=.
	43
	44	If no agenda file exists, the window says so.
	45
	46	* The day and week view
	47
	48	The default view is =org-agenda-list=: a run of days, each with a header such as =Monday 5 October 2026 W41= (the ISO week number appears on Mondays).
	49
	50	\| Setting \| Default \| =config.toml= \| Range in Settings \|
	51	\|------------------------------+---------+-----------------------------------+-------------------\|
	52	\| Days shown \| 10 \| =org-agenda-span = 10= \| 1 to 31 \|
	53	\| First day, relative to today \| 3 days before \| =org-agenda-start-day = "-3d"= \| 0 to 14 days before \|
	54
	55	Both mirror the Emacs variables of the same name. The defaults are Doom's values, not plain Emacs's (a week starting today). =org-agenda-start-day= takes only day offsets such as ="-3d"= or ="+0d"=. There are no day, week or month view keys (=d=, =w=, =m= in Emacs) and no =org-agenda-start-on-weekday=: the span is a number of days and always begins at the configured offset.
	56
	57	** Moving through days
	58
	59	\| Key \| Toolbar \| Does \| Org command \|
	60	\|-----+-----------+-----------------------------------+--------------------------\|
	61	\| =f= \| Later (›) \| Moves forward by a whole span \| =org-agenda-later= \|
	62	\| =b= \| Earlier (‹) \| Moves back by a whole span \| =org-agenda-earlier= \|
	63	\| =.= \| Today \| Returns to the span around today \| =org-agenda-goto-today= \|
	64	\| =g=, =r= \| \| Refreshes, and reloads =views.toml= \| =org-agenda-redo= \|
	65
	66	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.
	67
	68	** What appears on each day
	69
	70	The entries follow =org-agenda-get-day-entries= with Org's default entry types, in the formats Org prints.
	71
	72	\| Entry \| Where it appears \| Leader \|
	73	\|-----------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------\|
	74	\| =DEADLINE= on that day \| On its day \| =Deadline:= \|
	75	\| =DEADLINE= in the future \| On today, from the warning period before it \| =In 3 d.:= \|
	76	\| =DEADLINE= in the past, not done \| On today \| =2 d. ago:= \|
	77	\| =SCHEDULED= on that day \| On its day \| =Scheduled:= \|
	78	\| =SCHEDULED= in the past, not done \| On today \| =Sched. 3x:= \|
	79	\| Active timestamp =<2026-10-05 Mon>= \| On its day; also in property drawers \| none \|
	80	\| Repeating timestamp =<… +1w>= \| On each occurrence within the span \| none \|
	81	\| Date range =<…>--<…>= \| On every day of the range \| =(2/5):= (day 2 of 5) \|
	82	\| Diary sexp =%%(…)= line or =<%%(…)>= \| On each day the sexp applies; see [[*Diary sexps][Diary sexps]] \| none \|
	83	\| Habit (=STYLE: habit=) \| On today only, while not done; see [[*Habits][Habits]] \| none, with a consistency graph \|
	84
	85	Details:
	86
	87	- Deadline warnings use =org-deadline-warning-days=, fixed at 14 days. A =-Nd= cookie in the timestamp (=<2026-10-20 Tue -3d>=) changes the warning for that deadline; =w=, =m= and =y= units work too.
	88	- A =-Nd= cookie on a =SCHEDULED= timestamp delays it: the entry first shows N days after the scheduled date.
	89	- Repeaters on =SCHEDULED= and =DEADLINE= timestamps (=+1w=, =++1w=, =.+1d=) make the entry show on the next occurrence on future days, as in Org.
	90	- A done entry shows only on the day of its deadline or scheduled date, not as overdue.
	91	- Inactive timestamps (=[…]=) never appear, except in log mode.
	92	- Ranges in comment lines and inside source blocks are ignored, as in Org.
	93
	94	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.
	95
	96	A time can come from the timestamp (=<2026-10-05 Mon 14:00-15:30>=) or from the heading text (=Call Ada 9:30am=), as =org-agenda-search-headline-for-time= allows. Times past 24:00, such as =25:30=, show as =+1:30=.
	97
	98	** Sorting
	99
	100	Days are sorted as =org-agenda-sorting-strategy= sorts them by default for the agenda: =(habit-down time-up urgency-down category-keep)=. 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.
	101
	102	** Log mode
	103
	104	Press =l= to turn log mode (=org-agenda-log-mode=) on or off. Each day then also shows:
	105
	106	- =Closed:= entries whose =CLOSED:= timestamp is on that day;
	107	- =Clocked: (1:30)= for each =CLOCK:= line that starts on that day, with the clock's range and duration.
	108
	109	A note under a clock line (a list item directly below it) is added to the line after a =-=. These are the default =org-agenda-log-mode-items=, =(closed clock)=; state changes are not shown and there is no setting for that.
	110
	111	* Diary sexps
	112
	113	The agenda evaluates diary sexps as =org-diary-sexp-entry= does. They can appear as a line starting with =%%(= under a heading, as an active timestamp =<%%(…)>=, or as a =SCHEDULED= or =DEADLINE= value.
	114
	115	#+BEGIN_SRC org
	116	,* Birthdays
	117	%%(diary-anniversary 10 7 1990) Ada is %d years old
	118	%%(org-anniversary 1985 3 14) Bob turns %d
	119
	120	,* Teaching
	121	,** Algebra lecture
	122	<%%(org-class 2026 9 7 2026 12 18 1 41)>
	123	#+END_SRC
	124
	125	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.
	126
	127	\| Function \| Applies \| Date order \|
	128	\|--------------------------------------------+--------------------------------------------------------------------+-------------------\|
	129	\| =diary-date= /month day year/ \| On matching dates; =t= or a list matches any or several \| month day year \|
	130	\| =diary-block= /m1 d1 y1 m2 d2 y2/ \| Every day from the first date to the second \| month day year \|
	131	\| =diary-float= /month dayname n/ [/day/] \| The nth /dayname/ (0 is Sunday) of the month; negative n counts from the end \| month \|
	132	\| =diary-anniversary= /month day/ [/year/] \| Each year on the date; =%d= is the count, =%s= its ordinal suffix \| month day year \|
	133	\| =diary-cyclic= /n month day year/ \| Every n days from the date \| month day year \|
	134	\| =diary-remind= /sexp days/ \| On the days before another sexp applies: =Reminder: Only 3 days until …= \| n/a \|
	135	\| =org-anniversary= /year month day/ \| As =diary-anniversary= \| year month day \|
	136	\| =org-cyclic= /n year month day/ \| As =diary-cyclic= \| year month day \|
	137	\| =org-block= /y1 m1 d1 y2 m2 d2/ \| As =diary-block= \| year month day \|
	138	\| =org-date= /year month day/ \| As =diary-date= \| year month day \|
	139	\| =org-class= /y1 m1 d1 y2 m2 d2 dayname/ [/skip-weeks…/] \| On /dayname/ between the dates, except the ISO weeks listed \| year month day \|
	140
	141	The =diary-= functions read dates in =calendar-date-style= =american= (month, day, year); the =org-= functions use ISO order. =org-class= skip lists take ISO week numbers only; holiday names and =holidays= need the Emacs calendar's holiday lists and make the sexp fail.
	142
	143	For your own expressions, the variables =date= (as =(month day year)=) and =entry= are bound, and these calendar functions are available: =calendar-extract-month=, =calendar-extract-day=, =calendar-extract-year=, =calendar-absolute-from-gregorian=, =calendar-gregorian-from-absolute=, =calendar-day-of-week=, =calendar-leap-year-p=, =calendar-last-day-of-month=, =calendar-date-equal=, =calendar-day-number=, =calendar-nth-named-absday=, =calendar-nth-named-day=, =calendar-iso-from-absolute=, =diary-ordinal-suffix= and =diary-make-date=. The evaluator also has the common special forms (=if=, =when=, =cond=, =and=, =or=, =let=, =progn= and others) and arithmetic. It is a small subset of Emacs Lisp, not Emacs.
	144
	145	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.
	146
	147	* Habits
	148
	149	An entry with the property =STYLE: habit= and a =SCHEDULED= timestamp with a repeater is a habit, as in =org-habit=:
	150
	151	#+BEGIN_SRC org
	152	,* TODO Run
	153	SCHEDULED: <2026-10-05 Mon .+2d/4d>
	154	:PROPERTIES:
	155	:STYLE: habit
	156	:END:
	157	- State "DONE" from "TODO" [2026-10-03 Sat 07:10]
	158	- State "DONE" from "TODO" [2026-10-01 Thu 07:05]
	159	#+END_SRC
	160
	161	The repeater can be =+=, =++= or =.+=, with an optional =/Nd= maximum interval. Days the habit was done are read from =- State "DONE" … [date]= lines (for any done keyword) and =CLOSING NOTE [date]= lines in the entry.
	162
	163	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 (=org-habit-preceding-days= and =org-habit-following-days=), with =*= on days it was done and =!= on today. Cell colors follow org-habit's faces:
	164
	165	\| Color \| Meaning \| Theme key \|
	166	\|--------+--------------------------------------------+-----------------\|
	167	\| Blue \| Not yet due \| =habit-clear= \|
	168	\| Green \| Due, within the allowed interval \| =habit-ready= \|
	169	\| Yellow \| Last day of the interval \| =habit-alert= \|
	170	\| Red \| Overdue \| =habit-overdue= \|
	171
	172	Future days use lighter shades. Hover a cell to see its date. Habits sort after other entries.
	173
	174	* The TODO list
	175
	176	The built-in view TODO List is =org-todo-list=: every heading with a TODO keyword that is not a done keyword, sorted by urgency (priority first). The time-based skipping options (=org-agenda-todo-ignore-scheduled= and its relatives) are not supported; every open TODO appears, as with Org's defaults.
	177
	178	A saved view can list specific keywords instead, done ones included, with =keywords = "WAIT\|HOLD"= (see [[*Views][Views]]). This mirrors =C-u M-x org-todo-list= with a keyword argument.
	179
	180	* Tag and property matches
	181
	182	Choose Match… from the view menu to list entries matching a match string, as =org-tags-view= (=m=) does, or TODO Match… to list only entries with an open TODO keyword (=M=). Type the match in the toolbar field and press Return.
	183
	184	The syntax is =org-make-tags-matcher='s:
	185
	186	#+BEGIN_SRC text
	187	+work-boss\|LEVEL>2+TODO="WAIT"/!NEXT
	188	#+END_SRC
	189
	190	** Tags
	191
	192	\| Form \| Matches \|
	193	\|----------------+-----------------------------------------------------------\|
	194	\| =work=, =+work= \| Entries with the tag \|
	195	\| =-boss= \| Entries without the tag \|
	196	\| =+work-boss= \| Both conditions (and) \|
	197	\| =a&b= \| =&= between terms is the same as =+= \|
	198	\| ={^proj}= \| Any tag matching the regular expression \|
	199
	200	=work\|home= matches either side: the vertical bar separates alternatives, and within an alternative, terms are joined by =+=, =-= or =&=. Tags include inherited tags and =#+FILETAGS=. Tag names compare exactly; regular expressions in braces are Emacs regexps, matched without case.
	201
	202	** Properties
	203
	204	A term can compare a property: =NAME op value=.
	205
	206	\| Operator \| Meaning \|
	207	\|-----------------------+-----------------------\|
	208	\| ===, ==== \| Equal \|
	209	\| =<>=, =!==, =/== \| Not equal \|
	210	\| =<=, =<== \| Less, less or equal \|
	211	\| =>=, =>== \| Greater, greater or equal \|
	212
	213	The value decides how the comparison works:
	214
	215	\| Value \| Compared as \|
	216	\|--------------------+-----------------------------------------------------------------------------\|
	217	\| =3=, =-1.5= \| Numbers; a missing or non-numeric property is 0 \|
	218	\| ="WAIT"= \| Strings \|
	219	\| ={regexp}= \| Regular expression match; with =<>=, =!== or =/== it must not match \|
	220	\| ="<2026-10-01>"= \| Dates. Also ="<now>"=, ="<today>"=, ="<tomorrow>"=, ="<yesterday>"=, and offsets such as ="<-1w>"= or ="<+3d>"= (units =h= =d= =w= =m= =y=). Brackets may be =[…]=. \|
	221
	222	Follow the operator with == (=Effort>1=) to require that the property exists; without it, a missing property compares as an empty string or 0.
	223
	224	Names are case-insensitive. Prefix a character in a name with =\= to use it literally (=MY\-PROP="x"=). Besides the entry's own property drawer, these special properties work:
	225
	226	\| Name \| Value \|
	227	\|----------------+----------------------------------------------------------\|
	228	\| =LEVEL= \| The heading's level \|
	229	\| =TODO= \| The TODO keyword \|
	230	\| =ITEM= \| The heading title \|
	231	\| =PRIORITY= \| The priority letter, or the default priority \|
	232	\| =CATEGORY= \| The entry's category \|
	233	\| =FILE= \| The file's path \|
	234	\| =TAGS= \| The heading's own tags, as =:a:b:= \|
	235	\| =ALLTAGS= \| All tags including inherited ones \|
	236	\| =SCHEDULED=, =DEADLINE=, =CLOSED= \| The planning timestamp \|
	237	\| =TIMESTAMP=, =TIMESTAMP_IA= \| The entry's first active or inactive timestamp \|
	238
	239	Properties are not inherited in matches (=org-use-property-inheritance= is nil). With a date value, =<>= and its synonyms match dates that are equal, as Orgstar's comparison mirrors =org-time<>= in Org 9.8.7; use =<= and =>= for date ranges.
	240
	241	** TODO keywords
	242
	243	After the last =/= (one not followed by a quote), the match restricts TODO keywords:
	244
	245	\| Form \| Matches \|
	246	\|--------------------+----------------------------------------------------------\|
	247	\| =/NEXT= \| Entries whose keyword is =NEXT= \|
	248	\| =/-WAIT= \| Any keyword but =WAIT=, and entries with none \|
	249	\| =/{^W}= \| Keywords matching the regexp \|
	250	\| =/!= \| Only entries with an open (not done) TODO keyword \|
	251	\| =/!-WAIT-HOLD= \| Open TODO entries except those two \|
	252
	253	=/TODO\|NEXT= matches either keyword, and =/!NEXT\|WAIT= either one while open. =/!= has the same effect as choosing TODO Match….
	254
	255	* Text search
	256
	257	The agenda has no =org-search-view= (=s=). To search the text of your files, use Search Notes (=⇧⌘F=).
	258
	259	* Views
	260
	261	The view menu lists the built-in views, Agenda and TODO List, then the views in =views.toml=, then Match… and TODO Match…. Saved views mirror =org-agenda-custom-commands=, with fewer options.
	262
	263	=views.toml= lives in the configuration folder beside =config.toml= (=~/.config/orgstar/= by default; see [[file:13-configuration.org][Configuration]]). Each view is a =[[view]]= table:
	264
	265	#+BEGIN_SRC toml
	266	[[view]]
	267	name = "Fortnight"
	268	type = "agenda"
	269	span = 14
	270	start = 0
	271
	272	[[view]]
	273	name = "Waiting"
	274	type = "todo"
	275	keywords = "WAIT\|HOLD"
	276
	277	[[view]]
	278	name = "Work"
	279	type = "match"
	280	match = "+work-boss"
	281
	282	[[view]]
	283	name = "Next at work"
	284	type = "todo-match"
	285	match = "+work/NEXT"
	286	#+END_SRC
	287
	288	\| Key \| Applies to \| Meaning \|
	289	\|------------+--------------------+----------------------------------------------------------------------------\|
	290	\| =name= \| all, required \| The name in the view menu \|
	291	\| =type= \| all \| =agenda= (the default), =todo=, =match= or =todo-match= \|
	292	\| =span= \| =agenda= \| Days shown; the setting when omitted \|
	293	\| =start= \| =agenda= \| First day as an integer number of days from today (=-3=, =0=); the setting when omitted \|
	294	\| =keywords= \| =todo= \| Keywords separated by the vertical bar; all open TODOs when omitted \|
	295	\| =match= \| =match=, =todo-match=, required \| A match string as in [[*Tag and property matches][Tag and property matches]]; =todo-match= keeps only open TODO entries \|
	296
	297	Note that =start= is a plain integer here, while =org-agenda-start-day= in =config.toml= is a string such as ="-3d"=.
	298
	299	Not supported: block agendas (several views in one), per-view settings such as =org-agenda-skip-function= or a different prefix format, =stuck= projects, and search views. The views load when the window opens and again on =g= or =r=. A problem in the file, such as a missing =name= or an unknown =type=, shows in the status line at the bottom of the window, and the remaining views still load.
	300
	301	* Filters
	302
	303	Filters hide lines without changing the view, as =org-agenda-filter= does. Time grid lines always stay. The active filter shows in the status line at the bottom of the window as =Filter: …=.
	304
	305	\| Key \| Does \| Org command \|
	306	\|------+---------------------------------------------------------------+-----------------------------------\|
	307	\| =/= \| Asks for a combined filter, starting from the current one \| =org-agenda-filter= \|
	308	\| =\= \| Asks for a tag filter \| =org-agenda-filter-by-tag= \|
	309	\| =<= \| Keeps only the selected line's category; again removes it \| =org-agenda-filter-by-category= \|
	310	\| === \| Asks for a regexp filter \| =org-agenda-filter-by-regexp= \|
	311	\| =_= \| Asks for an effort filter \| =org-agenda-filter-by-effort= \|
	312
	313	The vertical bar key, =\|=, removes every filter (=org-agenda-filter-remove-all=).
	314
	315	The combined filter =/= reads terms such as:
	316
	317	#+BEGIN_SRC text
	318	+work-phone<2:00/report/
	319	#+END_SRC
	320
	321	- =+word= keeps and =-word= drops lines. A word without a sign keeps.
	322	- 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 =-=: ="my-cat"=.
	323	- =<0:30=, =>1:00= and ==1:00= compare the entry's =Effort= property. Entries without an effort count as longer than any effort, as with =org-agenda-sort-noeffort-is-high= t. Durations can be =H:MM=, minutes, or units such as =1h 30min= or =2d=.
	324	- =/regexp/= keeps lines whose text matches; =-/regexp/= drops them. Matching ignores case.
	325	- Starting the input with =+= followed by another sign (=++urgent=) adds to the current filter instead of replacing it.
	326
	327	With two or more =+= categories, a line may have any of them. Tag terms all have to hold.
	328
	329	The =\= prompt reads every word as a tag, whether or not a line has it; there, ={regexp}= matches any tag that matches the regexp. The === prompt takes one regexp, with a leading =-= to drop matches. The =_= prompt takes one comparison such as =<0:30=.
	330
	331	* The prefix and line layout
	332
	333	Each line shows the category, the time, the leader (=Deadline:=, =In 3 d.:=, =(2/5):=), the heading with its TODO keyword colored, the habit graph if any, and the tags.
	334
	335	To change what comes before the heading, set =org-agenda-prefix-format= in =config.toml=:
	336
	337	#+BEGIN_SRC toml
	338	[org-agenda-prefix-format]
	339	agenda = " %i %-12:c%?-12t% s"
	340	todo = " %i %-12:c"
	341	tags = " %i %-12:c"
	342	#+END_SRC
	343
	344	These are the defaults. =agenda= applies to the day view, =todo= to the TODO list, and =tags= 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.
	345
	346	\| Field \| Shows \|
	347	\|-------+-----------------------------------------------------------------------\|
	348	\| =%c= \| The category \|
	349	\| =%t= \| The time of day, or the time range \|
	350	\| =%s= \| The leader: =Scheduled:=, =Deadline:=, =In 3 d.:= and so on \|
	351	\| =%e= \| The =Effort= property \|
	352	\| =%l= \| One space per heading level \|
	353	\| =%b= \| The outline path above the heading, each title followed by =->= \|
	354	\| =%i= \| The category icon; always empty in Orgstar \|
	355
	356	Each field takes Org's modifiers: =%-12c= pads to 12 columns on the right (=%12c= on the left); =%-12.6c= limits a category to 5 characters; =%?t= leaves the field out entirely when empty; a punctuation character after the width (=%-12:c=) is added after a non-empty value. When the format contains =%t=, times move out of the heading text into the prefix, as =org-agenda-remove-times-when-in-prefix= does. =%(…)= Lisp forms are accepted but always empty.
	357
	358	Colors come from the theme keys =agenda-background=, =agenda-date=, =agenda-today=, =agenda-time=, =agenda-category=, =agenda-deadline=, =agenda-upcoming=, =agenda-scheduled= and =agenda-scheduled-past= (see [[file:13-configuration.org][Configuration]]).
	359
	360	* Acting on entries
	361
	362	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 =keymap.toml=.
	363
	364	\| Key \| Does \| Org command \|
	365	\|-------------------------+--------------------------------------------------------------+------------------------------\|
	366	\| =RET= or double click \| Shows the entry in the main window \| =org-agenda-switch-to= \|
	367	\| =t= or =C-c C-t= \| Changes the TODO state, as in the editor \| =org-agenda-todo= \|
	368	\| =+=, =-= \| Raises or lowers the priority \| =org-agenda-priority-up=/=-down= \|
	369	\| =:= or =C-c C-q= \| Sets tags \| =org-agenda-set-tags= \|
	370	\| =C-c C-s= \| Schedules \| =org-agenda-schedule= \|
	371	\| =C-c C-d= \| Sets a deadline \| =org-agenda-deadline= \|
	372	\| =S-<right>=, =S-<left>= (=⇧→=, =⇧←=) \| Moves the date the line is listed for by a day \| =org-agenda-date-later=/=-earlier= \|
	373	\| =I= \| Clocks in \| =org-agenda-clock-in= \|
	374	\| =O= \| Clocks out \| =org-agenda-clock-out= \|
	375	\| =X= \| Cancels the clock \| =org-agenda-clock-cancel= \|
	376	\| =C-c C-w= \| Refiles \| =org-agenda-refile= \|
	377	\| =$=, =C-c $=, =C-c C-x C-s= \| Archives \| =org-agenda-archive= \|
	378
	379	=t= follows =org-todo=: with fast-selection keys in your TODO keywords it asks for the state, otherwise it cycles (see [[file:05-todos-and-tags.org][TODOs and tags]]). Questions an action needs, such as a date for =C-c C-s= or a note on a state change, appear in the agenda window. Dates take the same input as in the editor (see [[file:06-dates-and-clocking.org][Dates, scheduling and clocking]]). =S-<right>= and =S-<left>= work only on deadline, scheduled and timestamp lines; they change the timestamp the line comes from.
	380
	381	=C-c C-w= brings the main window forward and asks for the target there, where the target list is searchable.
	382
	383	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.
	384
	385	** Bulk actions
	386
	387	\| Key \| Does \| Org command \|
	388	\|-----+------------------------------------------+--------------------------------\|
	389	\| =m= \| Marks the selected entry (shown with =›=) \| =org-agenda-bulk-mark= \|
	390	\| =u= \| Unmarks it \| =org-agenda-bulk-unmark= \|
	391	\| =U= \| Unmarks everything \| =org-agenda-bulk-unmark-all= \|
	392	\| =B= \| Asks for an action on every marked entry \| =org-agenda-bulk-action= \|
	393
	394	=B= offers =$= archive, =r= refile, =t= set a TODO state (typed; empty for none), =+= add a tag, =-= remove a tag, =s= schedule and =d= 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.
	395
	396	* Reminders
	397
	398	Orgstar can post a notification before each timed entry, as =org-agenda-to-appt= hands entries to =appt=. 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.
	399
	400	\| Setting \| Default \| =config.toml= \|
	401	\|-------------------------------+---------+------------------------------------\|
	402	\| Notify before timed entries \| on \| =reminders = true= under =[orgstar]= \|
	403	\| Minutes of warning \| 12 \| =appt-message-warning-time = 12= \|
	404
	405	Both are in Settings ▸ Agenda. An entry's =APPT_WARNTIME= 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.
	406
	407	The notification's title is the heading; its body is the time, the leader if any, and the category, such as =14:00 · Scheduled: · work=. Clicking it shows the entry in the main window.
	408
	409	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.
	410
	411	* The board
	412
	413	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 (=⇧⌘B=). It reads the same files as the agenda, including the subfolder setting.
	414
	415	The toolbar has:
	416
	417	- a Table / Kanban switch;
	418	- a match field, with the syntax of [[*Tag and property matches][Tag and property matches]]. When empty, the board shows every entry with a TODO keyword;
	419	- in table mode, a field of property names to show as extra columns, separated by commas (default =EFFORT=).
	420
	421	These three choices are remembered by the app; they are not in =config.toml=.
	422
	423	** Table
	424
	425	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 =NAME value=) and Open. Double-click a row to open the entry.
	426
	427	** Kanban
	428
	429	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.
	430
	431	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.
	432
	433	The board is not available on iOS.
	434
	435	* The agenda on iOS
	436
	437	The Agenda tab shows the same views from the same files, using the settings in the synced =config.toml= and the views in =views.toml= (see [[file:14-ios.org][iOS]]). Differences from the Mac:
	438
	439	- 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 =/!= in the match or a =todo-match= view. Today, Earlier and Later are in the same menu.
	440	- Pull down to refresh.
	441	- The Filter button opens a sheet: type a filter as for =/=, or tap a tag or category to cycle between Keep, Leave out and no filter.
	442	- Tap an entry to open it. Swipe left on an open TODO to mark it done with the first done keyword of its sequence.
	443	- Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile… and Archive….
	444	- There are no keyboard commands, time grid lines, habit graphs, log mode, bulk marks or custom prefix formats.
	445	- 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.

docs/manual/guide/08-capture.org added +332

		@@ -0,0 +1,332 @@
	1	#+TITLE: Capture
	2	#+DESCRIPTION: Capture templates, the capture window, date trees, org-protocol, Shortcuts and the iOS share sheet.
	3	#+LEDE: Capture files a note, task or link into the right place in your org files without leaving what you are doing.
	4
	5	* Starting a capture
	6
	7	Capture mirrors =org-capture=. Start it from anywhere in the app:
	8
	9	\| Preset \| Key \|
	10	\|--------+----------------------------------------\|
	11	\| Mac \| =⇧⌘N= (File ▸ Capture…) \|
	12	\| Emacs \| =C-c c= or =⇧⌘N= \|
	13	\| Doom \| =SPC X= (normal state), =C-c c= or =⇧⌘N= \|
	14
	15	=⌃⌥Space= opens the capture window from any app, with Orgstar in the background. Turn it off in Settings ▸ Capture, or in =config.toml=:
	16
	17	#+BEGIN_SRC toml
	18	[orgstar]
	19	global-capture-hotkey = false
	20	#+END_SRC
	21
	22	The shortcut is registered as a system hot key and needs no accessibility permission.
	23
	24	Captures can also arrive from a browser through org-protocol, from Shortcuts, and on iOS from the share sheet; see the sections below.
	25
	26	* The capture window
	27
	28	A capture goes through up to three steps.
	29
	30	1. Choose a template. The window lists your templates with their keys and targets. Press a template's key, or click it.
	31	2. Answer its questions. If the template has prompts (=%^{…}=, =%^g=, =%^t= and the others below), they appear as a form. Leave a field empty for its default. Press Return (Continue) to go on.
	32	3. Edit and file. The filled template appears in an editor, headed with the template's name and target, with the cursor where =%?= was. Press =⌘Return= (File It) to file it.
	33
	34	Press Esc (Cancel) at any step to close the window without filing anything, as =org-capture-kill= does.
	35
	36	Filing, the equivalent of =org-capture-finalize=, 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.
	37
	38	If filing fails, for example because a heading on an =olp= path is missing, the window stays open with your text, so you can try again after fixing the file or cancel.
	39
	40	Limits compared with Emacs:
	41
	42	- The editor is a plain text editor. Org editing commands and keys such as =C-c C-c= and =C-c C-k= don't work in it; use =⌘Return= and Esc.
	43	- There is no refile from the capture window (=C-c C-w= in an Emacs capture buffer). Capture to an inbox heading and refile from the agenda or the editor.
	44	- The target is not shown while you edit (the capture buffer in Emacs is narrowed to the new entry in the target file).
	45
	46	* Capture templates
	47
	48	Templates live in =capture.toml= in the configuration folder (=~/.config/orgstar/capture.toml= by default; see [[file:13-configuration.org][Configuration]]). Settings ▸ Capture shows its path. Each template is a =[[template]]= table:
	49
	50	#+BEGIN_SRC toml
	51	[[template]]
	52	key = "t"
	53	name = "Personal todo"
	54	type = "entry"
	55	file = "todo.org"
	56	headline = "Inbox"
	57	template = "* TODO %?\n%i\n%a"
	58	prepend = false
	59	#+END_SRC
	60
	61	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:
	62
	63	\| Key \| Name \| Target \| Template \|
	64	\|-----+----------------+-----------------------------+-----------------------\|
	65	\| =t= \| Personal todo \| =todo.org=, heading =Inbox= \| =* TODO %?\n%i\n%a= \|
	66	\| =n= \| Personal notes \| =notes.org=, heading =Inbox= \| =* %u %?\n%i\n%a= \|
	67
	68	A problem in the file, such as a table without a key, shows in red under the template list; the other templates still load.
	69
	70	Templates are a flat list. A key is matched against a single key press, so a key longer than one character can only be chosen by clicking. Emacs's template groups (an entry with only a key and a description) have no equivalent.
	71
	72	** Keys
	73
	74	\| Key \| Value \| Meaning \| Org property \|
	75	\|----------------------+-------------------+-----------------------------------------------------------------------------------------------+-------------------------\|
	76	\| =key= \| string, required \| What you press to choose the template \| key \|
	77	\| =name= \| string \| The name in the list; the key when omitted \| description \|
	78	\| =type= \| string \| =entry= (the default), =item=, =checkitem=, =plain= or =table-line= \| type \|
	79	\| =template= \| string, required \| The text to fill; see [[*Template escapes][Template escapes]] \| template \|
	80	\| =file= \| string \| The target file; required except with =id= or =clock= \| target \|
	81	\| =headline= \| string \| A heading in =file= \| =file+headline= \|
	82	\| =olp= \| string \| An outline path in =file=, titles separated by =/= \| =file+olp= \|
	83	\| =datetree= \| boolean \| Today's entry in a date tree in =file=, under =olp= if given \| =file+olp+datetree= \|
	84	\| =tree-type= \| string \| =day= (the default), =week= or =month=, for =datetree= \| =:tree-type= \|
	85	\| =id= \| string \| The heading with this =ID= property, in any file \| =id= \|
	86	\| =clock= \| boolean \| The entry the clock is running in \| =clock= \|
	87	\| =prepend= \| boolean \| Put the text first rather than last \| =:prepend= \|
	88	\| =immediate-finish= \| boolean \| File without showing the editor \| =:immediate-finish= \|
	89	\| =empty-lines= \| integer \| Blank lines before and after the captured text \| =:empty-lines= \|
	90	\| =empty-lines-before= \| integer \| Blank lines before; overrides =empty-lines= \| =:empty-lines-before= \|
	91	\| =empty-lines-after= \| integer \| Blank lines after; overrides =empty-lines= \| =:empty-lines-after= \|
	92	\| =jump-to-captured= \| boolean \| Show the new entry in the editor after filing \| =:jump-to-captured= \|
	93	\| =clock-in= \| boolean \| Clock in to the captured entry \| =:clock-in= \|
	94	\| =clock-keep= \| boolean \| With =clock-in=, keep the clock running after filing \| =:clock-keep= \|
	95	\| =clock-resume= \| boolean \| With =clock-in=, restart the clock that was running before \| =:clock-resume= \|
	96	\| =table-line-pos= \| string \| Where a =table-line= goes, such as ="II-3"= \| =:table-line-pos= \|
	97
	98	=capture.toml= uses a subset of TOML: basic strings in double quotes, literal strings in single quotes, booleans and integers. Multi-line strings (="""…"""=) are not supported, so write a newline in a template as =\n= inside a double-quoted string. A double-quoted string accepts only the escapes =\"=, =\\=, =\n=, =\t=, =\uXXXX= and =\UXXXXXXXX=; any other backslash is an error. A template backslash, as in =%\1= or =\%=, is therefore written =%\\1= or =\\%= in double quotes, or as it is in a single-quoted string, which has no escapes and no =\n=.
	99
	100	#+BEGIN_SRC toml
	101	[[template]]
	102	key = "m"
	103	name = "Meeting"
	104	file = "work.org"
	105	olp = "Meetings"
	106	template = "* %^{Topic} :meeting:\n%U\n- Attendees: %^{Attendees}\n- Topic again: %\\1\n%?"
	107	#+END_SRC
	108
	109	** Targets
	110
	111	The target keys are checked in this order: =id=, =clock=, =datetree=, =headline=, =olp=; with none of them the target is =file= itself.
	112
	113	\| Target \| Where the text goes \|
	114	\|---------------------------+-----------------------------------------------------------------------------------------------------------------\|
	115	\| =file= alone \| The file's top level: an =entry= becomes a top-level heading at the end (or start, with =prepend=) \|
	116	\| =headline = "Inbox"= \| Under the first heading with that exact title, at any level. If there is none, =* Inbox= is added at the end of the file \|
	117	\| =olp = "Projects/Work"= \| Under =Work=, a child of =Projects=. Every heading on the path must exist; otherwise filing fails with =Heading not found on outline path= \|
	118	\| =datetree = true= \| Under today's heading in a date tree; see [[*Date trees][Date trees]] \|
	119	\| =id = "…"= \| Under the heading with that =ID=, found through the workspace index. Fails with =Cannot find target ID= if no heading has it \|
	120	\| =clock = true= \| Under the heading the running clock is in. Fails with =No running clock= when no clock runs \|
	121
	122	=file= may be absolute (=/Users/me/org/todo.org=), start with =~/=, 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 =olp= uses =/= as its separator, a heading whose title contains =/= can't be on an outline path; use =headline= or =id= for it.
	123
	124	Emacs's =file+regexp=, =file+function= and =function= targets, and templates read from a file (=(file "…")=), are not supported.
	125
	126	** Template types
	127
	128	\| Type \| What is inserted \|
	129	\|--------------+----------------------------------------------------------------------------------------------------------------------------------------------------------\|
	130	\| =entry= \| An Org entry. If the text has no heading, =* = 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=). Text whose first heading isn't its highest is refused: =Template is not a valid Org entry or tree= \|
	131	\| =item= \| 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 \|
	132	\| =checkitem= \| As =item=, with a =[ ]= checkbox added if there is none \|
	133	\| =plain= \| The text as it is, at the end of the entry's body (with =prepend=, right after the heading line) \|
	134	\| =table-line= \| A table row, in the first table in the target entry (or the file); a new table is made if there is none \|
	135
	136	For =table-line=, a text that doesn't start with a vertical bar gets one. The row goes at the end of the table. With =prepend= it goes before the first data row after the first rule. With =table-line-pos=, =II-3= means three lines above the second horizontal rule and =I+1= the first line below the first rule; an impossible position fails with =Invalid table line specification=. 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 [[file:10-tables.org][Tables]]).
	137
	138	Placement follows =org-capture-place-entry= and its siblings, including how blank lines are kept: without =empty-lines= options, a new heading gets a blank line before it when its neighbors have one (=org-blank-before-new-entry= =(heading . auto)=). Within an existing list, at most one blank line goes between items.
	139
	140	** Clocking while capturing
	141
	142	With =clock-in = true=, 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 =clock-keep = true= as well, the clock keeps running in the new entry. With =clock-resume = true=, the clock that was running before the capture starts again after filing. See [[file:06-dates-and-clocking.org][Dates, scheduling and clocking]].
	143
	144	* Template escapes
	145
	146	These follow =org-capture-fill-template=. Escapes that need no answer are filled first; prompts are then asked in order.
	147
	148	** Inserted values
	149
	150	\| Escape \| Inserts \|
	151	\|------------+-----------------------------------------------------------------------------------------------------------------\|
	152	\| =%?= \| Nothing; the cursor goes here \|
	153	\| =%i= \| 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 =%i= is on \|
	154	\| =%a= \| A link to where capture started, =[[target][description]]= \|
	155	\| =%A= \| The same link, asking for its description \|
	156	\| =%l= \| The link as =[[target]]=, without description \|
	157	\| =%L= \| The link target alone \|
	158	\| =%c=, =%x= \| The clipboard's text \|
	159	\| =%f= \| The name of the file capture started from \|
	160	\| =%F= \| The full path of that file \|
	161	\| =%n= \| Your full name from macOS \|
	162	\| =%k= \| The title of the entry the clock is running in \|
	163	\| =%K= \| A link to that entry \|
	164	\| =%t= \| Today's date as an active timestamp, =<2026-10-07 Wed>= \|
	165	\| =%T= \| Active timestamp with the current time \|
	166	\| =%u= \| Inactive timestamp, =[2026-10-07 Wed]= \|
	167	\| =%U= \| Inactive timestamp with the current time \|
	168	\| =%<…>= \| The current time formatted with a =format-time-string= pattern, such as =%<%Y-%m-%d %H:%M>= \|
	169	\| =%:name= \| A link property; see below \|
	170
	171	From the Mac capture window, =%a= links to the heading at the cursor in the open file, as =[[file:~/org/work.org::*Heading][Heading]]=, or to the file itself before the first heading. It is empty with no file open.
	172
	173	=%<…>= understands =%Y=, =%m=, =%d=, =%e=, =%H=, =%M=, =%S=, =%a=, =%A=, =%b=, =%B=, =%F=, =%R= and =%%=, with English day and month names. Other =format-time-string= codes are left in the text as they are.
	174
	175	=%:name= inserts a property of the link being captured. From org-protocol these are =%:link=, =%:description= (the page title), =%:type= (the link's scheme, such as =https=), =%:annotation= (the same as =%a=) and =%:initial= (the same as =%i=). Without org-protocol, =%:annotation= and =%:initial= still work and other names insert nothing.
	176
	177	** Prompts
	178
	179	\| Escape \| Asks for \|
	180	\|--------------------------------+--------------------------------------------------------------------------------------------\|
	181	\| =%^{Prompt}= \| A line of text \|
	182	\| =%^g= \| Tags, offering the tags used in the target file \|
	183	\| =%^G= \| Tags, offering every tag in your folders \|
	184	\| =%^t=, =%^T= \| A date, inserted as an active timestamp; =%^T= always includes a time \|
	185	\| =%^u=, =%^U= \| The same as an inactive timestamp \|
	186	\| =%^C= \| Text, offering the initial text and the clipboard \|
	187	\| =%^L= \| As =%^C=, inserted as a link \|
	188	\| =%^{NAME}p= \| A value for the property =NAME=, set in the entry's property drawer \|
	189
	190	=%^{Prompt\|default\|a\|b}= asks for text with a default and suggested choices, separated by vertical bars.
	191
	192	A name in braces before any of the keyed forms becomes its prompt: =%^{Start}T=, =%^{Context}g=. Leave a text answer empty for the default. Tags are typed separated by colons (=work:urgent=); on a heading line they are aligned to =org-tags-column=. A date takes the same input as the editor's date prompt, such as =+2d=, =fri= or =fri 14:00= (see [[file:06-dates-and-clocking.org][Dates, scheduling and clocking]]); an empty answer is today, or now for =%^T= and =%^U=. A time in the answer makes =%^t= include it.
	193
	194	After the prompts are answered, =%\1=, =%\2= and so on insert the answer to the first, second, … text prompt (=%^{…}= only), and =%\1=, =%\2= the answer to the first, second, … prompt of any kind.
	195
	196	** Escaping and unsupported escapes
	197
	198	Put a backslash before =%= to keep it literally: =\%t= inserts =%t= (in a double-quoted TOML string, write =\\%t=). Two backslashes insert one backslash followed by the escape's value.
	199
	200	=%(…)= runs Emacs Lisp in Org and is not supported; a template that contains it fails with a message saying so. =%[file]= (insert a file's contents) is not supported either. Any other =%= sequence is left as it is.
	201
	202	* Date trees
	203
	204	With =datetree = true=, the entry goes under today's date in a tree of headings, as =org-datetree-find-create-entry= builds it. Missing levels are created in date order among their siblings.
	205
	206	\| =tree-type= \| Levels \|
	207	\|-------------+-----------------------------------------------------------\|
	208	\| =day= \| =* 2026=, = 2026-10 October=, =* 2026-10-07 Wednesday= \|
	209	\| =week= \| =* 2026=, = 2026-W41=, =* 2026-10-07 Wednesday= (ISO week and its year) \|
	210	\| =month= \| =* 2026=, =** 2026-10 October= \|
	211
	212	#+BEGIN_SRC toml
	213	[[template]]
	214	key = "j"
	215	name = "Journal"
	216	file = "journal.org"
	217	datetree = true
	218	template = "* %<%H:%M> %?\n%i"
	219	#+END_SRC
	220
	221	With =olp=, 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 =:time-prompt= to choose another day.
	222
	223	* org-protocol
	224
	225	Orgstar registers the =org-protocol:= URL scheme and handles the two handlers browser bookmarklets use, as =org-protocol.el= does in Org 9.8.7. Both the =?key=value= form and the older =:/a/b/c= form work.
	226
	227	** capture
	228
	229	#+BEGIN_SRC text
	230	org-protocol://capture?template=w&url=https%3A%2F%2Fexample.com&title=Example&body=Selected%20text
	231	#+END_SRC
	232
	233	This opens the capture window with:
	234
	235	- =template= chosen. Without =template=, the template list shows. A key with no template reports =No capture template "w"=.
	236	- =%a= and =%:annotation= set to =[[url][title]]= (the URL as its own description when the title is blank; the title alone when there is no URL).
	237	- =%i= and =%:initial= set to =body=.
	238	- =%:link= set to the URL, =%:description= to the title, and =%:type= to the URL's scheme.
	239
	240	In the query form, =+= stands for a space, as in Org; encode a literal =+= as =%2B=.
	241
	242	** store-link
	243
	244	#+BEGIN_SRC text
	245	org-protocol://store-link?url=https%3A%2F%2Fexample.com&title=Example
	246	#+END_SRC
	247
	248	This stores the link, so =C-c C-l= in the editor offers it (see [[file:09-links.org][Links]]), and puts the URL on the clipboard.
	249
	250	Other handlers, such as =open-source=, report that Orgstar handles only capture and store-link. On iOS only =capture= links are handled.
	251
	252	** Bookmarklets
	253
	254	Bookmarklets written for Emacs's org-protocol work unchanged. Add a bookmark with one of these as its address:
	255
	256	#+BEGIN_SRC js
	257	javascript:location.href='org-protocol://capture?template=w&url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)+'&body='+encodeURIComponent(window.getSelection())
	258	#+END_SRC
	259
	260	#+BEGIN_SRC js
	261	javascript:location.href='org-protocol://store-link?url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)
	262	#+END_SRC
	263
	264	A matching web capture template:
	265
	266	#+BEGIN_SRC toml
	267	[[template]]
	268	key = "w"
	269	name = "Web page"
	270	file = "inbox.org"
	271	headline = "Web"
	272	template = "* %:description\n:PROPERTIES:\n:URL: %:link\n:END:\n%U\n%i\n%?"
	273	#+END_SRC
	274
	275	* Shortcuts
	276
	277	The Shortcuts action Capture to Orgstar files text with a template, without the capture window. It has two parameters:
	278
	279	\| Parameter \| Meaning \|
	280	\|--------------+-------------------------------------------------------------------------\|
	281	\| Text \| The text, inserted as =%i= \|
	282	\| Template Key \| A template's =key= in =capture.toml=; the first template when empty \|
	283
	284	Every prompt in the template takes its default (an empty answer: today for dates, no tags), and =%?= is ignored. =%a= is empty. On the Mac, =%c= is the clipboard and =%n= your name; on iOS both are empty, because reading the pasteboard would ask for permission on every run. The action returns a message, =Captured to …= with the target on the Mac and =Captured with …= 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.
	285
	286	On the Mac, the action opens Orgstar if it isn't running and waits up to five seconds for it to be ready.
	287
	288	* Capture on iOS
	289
	290	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 =capture.toml= in your synced configuration folder (see [[file:14-ios.org][iOS]]).
	291
	292	The sheet works as on the Mac, in a form:
	293
	294	- The Template picker chooses the template; it starts on the first one.
	295	- Prompts appear as fields. Date prompts have a date picker; choices and tags appear as buttons, and tapping a tag adds it.
	296	- Continue fills the template and shows the text to edit; File files it; Cancel discards it.
	297
	298	Differences from the Mac: there is no selection, clipboard, current file, user name or clock link to insert, so =%i= and =%a= are empty unless the capture came from a link or the share sheet, and =%c=, =%x=, =%f=, =%F=, =%n=, =%k= and =%K= are empty. An org-protocol link naming a template key that doesn't exist opens the sheet on the first template instead of reporting an error.
	299
	300	** The share sheet
	301
	302	In another app, share a web page or text and choose Orgstar. The share form has:
	303
	304	- a Template picker, with the templates the app read the last time it ran;
	305	- for a link, its title (editable) and address;
	306	- a Text field, filled with shared text.
	307
	308	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 =%a= and =%:link=, the title =%:description=, and the text =%i=. 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.
	309
	310	The share form lists no templates until Orgstar has run once with your configuration folder; the capture sheet then starts on the first template.
	311
	312	* Importing templates from Emacs
	313
	314	Import from Emacs (see [[file:13-configuration.org][Configuration]] and [[file:15-alongside-emacs.org][Alongside Emacs]]) reads =org-capture-templates= and appends a =[[template]]= table to =capture.toml= for each template whose key isn't there already.
	315
	316	\| Emacs \| Imported as \|
	317	\|----------------------------------------------+------------------------------------------\|
	318	\| types =entry=, =item=, =checkitem=, =plain=, =table-line= \| =type= \|
	319	\| =(file "f")= \| =file= \|
	320	\| =(file+headline "f" "H")= \| =file=, =headline= \|
	321	\| =(file+olp "f" "A" "B")= \| =file=, =olp = "A/B"= \|
	322	\| =(file+olp+datetree "f" …)= \| =file=, =datetree=, =olp= if a path is given \|
	323	\| =(file+datetree "f")= \| =file=, =datetree= \|
	324	\| =(file+weektree "f")= \| =file=, =datetree=, =tree-type = "week"= \|
	325	\| =(id "…")= \| =id= \|
	326	\| =(clock)= \| =clock= \|
	327	\| =:prepend=, =:immediate-finish=, =:jump-to-captured=, =:clock-in=, =:clock-keep=, =:clock-resume= \| the boolean of the same name \|
	328	\| =:empty-lines=, =:empty-lines-before=, =:empty-lines-after=, =:table-line-pos=, =:tree-type= \| the key of the same name \|
	329
	330	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 =:tree-type= values, and other properties such as =:time-prompt=, =:kill-buffer= or =:unnarrowed=. Template groups are skipped.
	331
	332	Emacs resolves relative target files against =org-directory=; Orgstar resolves them against the first folder in the sidebar. If =org-directory= isn't your first folder, edit the imported =file= values or make them absolute.

docs/manual/guide/09-links.org added +324

		@@ -0,0 +1,324 @@
	1	#+TITLE: Links
	2	#+DESCRIPTION: Link syntax, the link types Orgstar follows, storing and inserting links, IDs, backlinks and inline images.
	3	#+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.
	4
	5	* Link syntax
	6
	7	Orgstar reads links the way =org-element-link-parser= does. There are three forms.
	8
	9	\| Form \| Example \| Notes \|
	10	\|---------------+-------------------------------------------+-------------------------------------------------------------\|
	11	\| Bracket link \| =[[https://orgmode.org][Org website]]= \| Any link type. The description after =][= is optional. \|
	12	\| Angle link \| =<https://orgmode.org>= \| For =http=, =https=, =mailto=, =file=, =id=, =doi=, =ftp=, =news=, =shell=, =elisp=, =info=, =help= and =attachment=. \|
	13	\| Plain link \| =https://orgmode.org= \| Only =https://=, =http://=, =mailto:= and =file:= are recognized in running text. \|
	14
	15	Inside a bracket link, a target that starts with =/=, =~=, =./= or =../= is a file
	16	link. A target in parentheses, =(name)=, is a coderef. One that starts with =#= is a
	17	custom ID. Anything without a known =type:= prefix is a search for text in the
	18	current file (a "fuzzy" link). A link may run over a line break; the break and
	19	surrounding blanks read as one space.
	20
	21	Backslashes before brackets are escaped as in =org-link-escape=: when Orgstar writes
	22	a link it doubles backslashes that come before a bracket or the end, and it reads them
	23	back the same way.
	24
	25	* How links display
	26
	27	With View ▸ Show Markup off (the default, =⇧⌘M= toggles it), a link with a
	28	description shows only its description, and its brackets and target are hidden. This
	29	is =org-link-descriptive=. The full text appears on the line that holds the caret, so
	30	you can edit it. With Show Markup on, every link shows as written. The setting is
	31	=show-markup= under =[orgstar]= in the config file (see
	32	[[file:13-configuration.org][Configuration]]).
	33
	34	Links without a description show their target, with the brackets hidden in the same
	35	way. Radio targets (=<<<words>>>=) turn every other occurrence of those words in the
	36	file into a link, matched case-insensitively, as in Org.
	37
	38	* Following links
	39
	40	=org-open-at-point= follows the link at the caret, or opens the agenda for a timestamp.
	41
	42	\| Preset \| Key \|
	43	\|--------+---------------------------------------------------------------------------------------\|
	44	\| Emacs \| =C-c C-o= \|
	45	\| Mac \| Org ▸ Open Link (no key by default) \|
	46	\| Doom \| =C-c C-o= in any state; =RET= in normal state follows a link before doing anything else \|
	47	\| All \| =⌘=-click on the link; =o= at the start of a heading line when speed commands are on \|
	48
	49	A message in the echo area explains a link that can't be followed.
	50
	51	** What each link type does
	52
	53	\| Link \| Example \| Result \|
	54	\|----------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------------------\|
	55	\| =http=, =https=, =ftp=, =news=, =mailto= \| =[[mailto:me@example.com]]= \| Opened by macOS in your default browser or mail app. \|
	56	\| =doi= \| =[[doi:10.1000/182]]= \| Opens =https://doi.org/= followed by the DOI. \|
	57	\| =file= (also =file+sys:=, =file+emacs:=) \| =[[file:notes.org::*Ideas]]= \| See /File links/ below. \|
	58	\| =id= \| =[[id:6A3C…]]= \| Opens the file with the heading whose =ID= property matches, and moves to the heading. \|
	59	\| Custom ID \| =[[#setup]]= \| Moves to the heading in this file whose =CUSTOM_ID= property is =setup=. \|
	60	\| Heading \| =[[*Weekly review]]= \| Moves to the heading in this file with that title. \|
	61	\| Text \| =[[budget table]]= \| Searches this file: a =<<budget table>>= target, then =#+NAME: budget table=, then a heading. \|
	62	\| Coderef \| =[[(ref)]]= \| Not supported. The echo area says so. \|
	63	\| =shell=, =elisp= \| =[[shell:ls]]= \| Not run. Orgstar never executes these links. \|
	64	\| =attachment=, =info=, =help=, others \| \| Not followed. The echo area says Orgstar can't open the type. \|
	65
	66	The text search follows =org-link-search=. A dedicated =<<target>>= matches its words
	67	case-insensitively, with any run of blanks between them. A heading matches when its
	68	title, with statistics cookies such as =[2/5]= and a leading =COMMENT= removed, has the
	69	same words as the link, ignoring case. A search that starts with =*= looks at headings
	70	only. Regular-expression searches (=/re/=) are not supported.
	71
	72	Following a radio link looks for a dedicated target, a name or a heading with the same
	73	text. It does not jump to the =<<<radio target>>>= itself.
	74
	75	** File links
	76
	77	A relative path is resolved against the folder of the file that holds the link, as
	78	Org does; =~= is your home folder; an absolute path is used as written. Links between
	79	files in different sidebar folders work the same way, for example
	80	=[[file:../work/projects.org]]= or =[[file:~/Documents/org/inbox.org]]=.
	81
	82	What happens depends on the file:
	83
	84	- An =.org= or =.org_archive= file opens as a buffer in Orgstar.
	85	- Another text file opens in Orgstar as a plain buffer.
	86	- Anything else (images, PDFs, archives, media) is handed to macOS, which opens it in
	87	the default app for that type.
	88
	89	If the file doesn't exist, the echo area shows =No file= and the path.
	90
	91	After =::=, a file link can carry a search option:
	92
	93	\| Option \| Example \| Moves to \|
	94	\|-----------------+----------------------------------+---------------------------------------------\|
	95	\| A number \| =[[file:log.txt::120]]= \| Line 120. \|
	96	\| =Title= \| =[[file:notes.org::Ideas]]= \| The heading with that title. \|
	97	\| =#custom-id= \| =[[file:notes.org::#setup]]= \| The heading with that =CUSTOM_ID=. \|
	98	\| Other text \| =[[file:notes.org::budget]]= \| A target, a =#+NAME= or a heading, as above. \|
	99
	100	** id links
	101
	102	=id:= links are resolved through the index, so the target heading must be in a file
	103	under one of your sidebar folders. A link to an ID that isn't indexed shows =No heading
	104	has the ID= followed by the ID.
	105
	106	** Timestamps
	107
	108	=C-c C-o= or =⌘=-click on a timestamp opens the agenda on that day, as
	109	=org-follow-timestamp-link= does. On a date range such as
	110	=<2026-10-05 Mon>--<2026-10-09 Fri>=, the agenda shows the whole span. See
	111	[[file:07-agenda.org][Agenda]].
	112
	113	* Inserting and editing links
	114
	115	=org-insert-link= asks for a link and a description in the echo area.
	116
	117	\| Preset \| Key \|
	118	\|--------+------------------------------\|
	119	\| Emacs \| =C-c C-l= \|
	120	\| Mac \| Org ▸ Insert Link… \|
	121	\| Doom \| =SPC m l l=, or =C-c C-l= \|
	122
	123	The first prompt reads =Insert link:=, or =Insert link (default …):= when you have
	124	stored links. It completes from:
	125
	126	- your stored links, most recent first, and their descriptions;
	127	- the link abbreviations defined in the file (see /Link abbreviations/);
	128	- the link types =id=, =eww=, =rmail=, =mhe=, =irc=, =info=, =gnus=, =docview=,
	129	=bibtex=, =bbdb=, =w3m=, =doi=, =file+sys=, =file+emacs=, =shell=, =news=, =mailto=,
	130	=https=, =http=, =ftp=, =shortdoc=, =help=, =file= and =elisp=, each followed by =:=.
	131
	132	Pressing Return on an empty answer inserts the most recent stored link. Choosing a
	133	description inserts the link it belongs to. If you choose a bare type such as =https:=,
	134	a second prompt, =Link (no completion support):=, asks for the rest.
	135
	136	The next prompt, =Description:=, offers the stored link's description, or the
	137	selected text if you selected some before running the command. An empty description
	138	inserts a link without one. With text selected, the link replaces the selection.
	139
	140	When the caret is on an existing link, the same command edits it: the =Link:= prompt
	141	starts with the current target and =Description:= with the current description.
	142
	143	A stored link that you insert is removed from the stored list, as with
	144	=org-link-keep-stored-after-insertion= set to nil.
	145
	146	** File paths in inserted links
	147
	148	When the inserted link is a =file:= link, Orgstar rewrites it as
	149	=org-link-make-string-for-buffer= does:
	150
	151	- A link to a heading or target in the file you are editing loses its =file:= part
	152	and keeps only the search, for example =[[*Ideas]]=.
	153	- A path under the current file's folder becomes relative to it.
	154	- Any other path is written with =~= for your home folder.
	155
	156	** Completion while typing
	157
	158	You can also type a link by hand. With the caret right after =[[=, completion at point
	159	offers =attachment:=, =doi:=, =file:=, =http:=, =https:=, =id:= and =mailto:=, plus
	160	the file's link abbreviations. After =[[*=, it offers the headings of the current file.
	161	Completion at point is =C-M-i= in the Emacs preset and =C-SPC= in Doom's insert state;
	162	see [[file:02-the-editor.org][The editor]].
	163
	164	* Storing links
	165
	166	=org-store-link= remembers a link to where the caret is, for a later Insert Link.
	167
	168	\| Preset \| Key \|
	169	\|--------+---------------------------------------\|
	170	\| Emacs \| =C-c l= \|
	171	\| Mac \| Org ▸ Store Link \|
	172	\| Doom \| =SPC m l s= or =SPC n l= \|
	173
	174	The stored link is a =file:= link to the current file, written with =~= for your home
	175	folder, followed by a search option chosen as Org does with
	176	=org-link-context-for-files= on:
	177
	178	1. If the caret touches a =<<target>>= on its line, the link points at the target.
	179	2. Otherwise, if text is selected, the link searches for that text.
	180	3. Otherwise, if the caret is in an element with a =#+NAME=, the link uses the name.
	181	4. Otherwise, inside a heading's entry, the link uses =#custom-id= if the heading has a
	182	=CUSTOM_ID= property, and =*Title= if not. The title becomes the description.
	183	5. Before the first heading, the link searches for the text of the current line.
	184
	185	The echo area shows =Stored:= and the description or link. Storing the same link again
	186	moves it to the front of the list. Stored links last until you quit Orgstar; they
	187	aren't saved between sessions, as in Emacs.
	188
	189	* IDs
	190
	191	Org identifies headings across files with an =ID= property. Two commands manage it.
	192
	193	\| Command \| Org function \| Keys \|
	194	\|-----------------------+---------------------------------------+-----------------------------------\|
	195	\| Org ▸ Create ID \| =org-id-get-create= \| No default key \|
	196	\| Org ▸ Store ID Link \| =org-id-get-create= + =org-id-store-link= \| Doom =SPC m l i=; no key in Emacs or Mac \|
	197
	198	Create ID gives the heading at the caret an =ID= property if it doesn't have one. The
	199	ID is a new UUID in upper case, for example =6A3C2F9E-…=. Before the first heading,
	200	the property goes into the file-level property drawer.
	201
	202	Store ID Link does the same, then stores an =id:= link to the heading with its title
	203	as the description. Before the first heading, the description is the =#+TITLE=, or
	204	the file name. If the caret is on a target or named element inside the entry, the
	205	link carries that search, as =id:…::search=, which mirrors =org-id-link-use-context=.
	206
	207	=CUSTOM_ID= is a property you set yourself, with the property commands in
	208	[[file:04-outlines.org][Outlines]]. Link to it with =[[#name]]= in the same file or
	209	=[[file:other.org::#name]]= from another. Store Link uses it when the heading has one.
	210
	211	* Targets and radio targets
	212
	213	=<<target>>= marks a place in the text that a link with the same words reaches:
	214	=[[target]]=. Store Link with the caret on a target stores a link to it.
	215
	216	=<<<radio target>>>= makes every other occurrence of its words in the file a link,
	217	matched case-insensitively and between non-word characters. Radio links are
	218	highlighted as links and exported as links to the target (see
	219	[[file:12-export.org][Export]]). Following one in the editor does not reach the
	220	radio target; see /What each link type does/.
	221
	222	* Link abbreviations
	223
	224	A =#+LINK:= line defines an abbreviation, as =org-link-abbrev-alist-local= does:
	225
	226	#+BEGIN_SRC org
	227	,#+LINK: gh https://github.com/%s
	228	,#+LINK: search https://duckduckgo.com/?q=%h
	229	,#+LINK: wiki https://en.wikipedia.org/wiki/
	230
	231	[[gh:orgmode/org-mode]] → https://github.com/orgmode/org-mode
	232	[[search:org tables]] → https://duckduckgo.com/?q=org%20tables
	233	[[wiki:Org-mode]] → https://en.wikipedia.org/wiki/Org-mode
	234	#+END_SRC
	235
	236	In the template, =%s= is replaced by the text after the colon, =%h= by the same text
	237	percent-encoded, and a template with neither has the text appended. Function
	238	templates (=%(…)=) are not supported. Abbreviations from a =#+SETUPFILE= count too.
	239	When a key is defined twice, the first definition wins.
	240
	241	* The backlinks pane
	242
	243	View ▸ Show or Hide Backlinks shows a pane beside the editor of an org file. It has
	244	two sections:
	245
	246	- Links to the heading at the caret, named after that heading.
	247	- Links to this file.
	248
	249	Each row shows the linking heading and its file name. Click a row to open it. The
	250	pane is shown by default and updates as you move the caret and edit.
	251
	252	The pane looks at every org file in your sidebar folders, including unsaved changes
	253	in open buffers. A link counts when following it would lead to the heading or the
	254	file:
	255
	256	- =id:= links to the heading's =ID=;
	257	- =file:= links and plain paths (=./=, =../=, =/=, =~/=) to the file, with no search
	258	option for the file section, or with =::*Title=, =::#custom-id= or =::Title= for a
	259	heading;
	260	- within the same file, =[[*Title]]=, =[[#custom-id]]= and =[[Title]]=.
	261
	262	Links to targets, names and line numbers are not counted. Only links inside a heading's
	263	entry are indexed, so links in the text before a file's first heading don't appear.
	264	A heading's links to itself are left out.
	265
	266	* Inline images
	267
	268	=org-toggle-inline-images= shows image links as images.
	269
	270	\| Preset \| Key \|
	271	\|--------+----------------------------------------------\|
	272	\| Emacs \| =C-c C-x C-v= \|
	273	\| Mac \| Org ▸ Show or Hide Inline Images \|
	274	\| Doom \| =C-c C-x C-v= \|
	275
	276	The echo area reports how many images are shown, or that inline display is off.
	277
	278	A line shows an image when it holds nothing but a bracket link, without a description,
	279	to a file ending in =.png=, =.jpg=, =.jpeg=, =.gif=, =.svg=, =.webp=, =.tif=, =.tiff=,
	280	=.bmp=, =.heic= or =.avif= (in any case):
	281
	282	#+BEGIN_SRC org
	283	[[file:images/diagram.png]]
	284	[[./photo.jpg]]
	285	#+END_SRC
	286
	287	Relative paths are resolved against the file's folder. Web addresses and
	288	=attachment:= links are not shown as images. The link text is hidden while the image
	289	is shown, except on the line that holds the caret.
	290
	291	** Sizing
	292
	293	An image is drawn at its own width, up to the width of the text area. To set a width,
	294	put =#+ATTR_ORG: :width= with a number of points among the keywords above the link:
	295
	296	#+BEGIN_SRC org
	297	,#+CAPTION: Network layout
	298	,#+ATTR_ORG: :width 300
	299	[[file:images/network.png]]
	300	#+END_SRC
	301
	302	The height follows the image's proportions. =#+ATTR_HTML= and other exporters'
	303	attributes don't affect the editor.
	304
	305	** Showing images when a file opens
	306
	307	The config key =org-startup-with-inline-images= (default =false=) shows images in
	308	every file when it opens. In a file, =#+STARTUP: inlineimages= or
	309	=#+STARTUP: noinlineimages= overrides it.
	310
	311	* org-protocol store-link
	312
	313	Orgstar handles =org-protocol://store-link= URLs, in the new form
	314	~org-protocol://store-link?url=…&title=…~ and the old form
	315	=org-protocol://store-link:/URL/TITLE=. The URL is added to your stored links with
	316	the title as its description, and is also copied to the clipboard. Insert it with
	317	Insert Link. Setting up a browser bookmarklet, and =org-protocol://capture=, are in
	318	[[file:08-capture.org][Capture]].
	319
	320	* On iOS
	321
	322	The iOS app follows links: tap a link in the reader. Org files open in the app, and
	323	web, mail and other files go to the system. Storing and inserting links, the backlinks
	324	pane and inline images are Mac features. See [[file:14-ios.org][iOS]].

docs/manual/guide/10-tables.org added +553

		@@ -0,0 +1,553 @@
	1	#+TITLE: Tables
	2	#+DESCRIPTION: Creating and editing Org tables, column widths, import and export, and spreadsheet formulas.
	3	#+LEDE: Org tables are plain text that Orgstar keeps aligned, edits by row and column, and recalculates with the same formulas Emacs uses.
	4
	5	* Tables in Org
	6
	7	A table is a run of lines that start with =\|=. Fields are separated by =\|=, and a line
	8	that starts with =\|-= is a horizontal rule:
	9
	10	#+BEGIN_SRC org
	11	\| Name \| Qty \| Price \|
	12	\|-------+-----+-------\|
	13	\| Apple \| 3 \| 0.50 \|
	14	\| Pear \| 12 \| 0.75 \|
	15	#+END_SRC
	16
	17	Orgstar follows =org-table.el= from Org 9.8.7, with =org-table-automatic-realign= on,
	18	=org-table-tab-jumps-over-hlines= on, and formulas adjusted without asking when rows
	19	and columns move (=org-table-fix-formulas-confirm= nil). Tables inside dynamic blocks
	20	count as tables; tables inside other blocks don't.
	21
	22	* Creating a table
	23
	24	Type =\|=, a few field names separated by =\|=, and press =TAB=: Orgstar aligns the line
	25	as a table and moves to the next field, adding a row after the last one. Type =\|-= on
	26	the line below a row and press =TAB= to turn it into a full-width rule.
	27
	28	=org-table-create-or-convert-from-region= builds one for you: ~C-c \|~ in the Emacs
	29	and Doom presets, =⌃⌘\= in the Mac preset.
	30
	31	With no selection it asks =Table size Columns x Rows [e.g. 5x2]:=. An empty answer
	32	makes a 5 × 2 table. When there is more than one row, a rule follows the first row.
	33
	34	With text selected, the command converts the selected lines to a table instead
	35	(=org-table-convert-region=). The separator is guessed:
	36
	37	- tabs, when every line has a tab;
	38	- otherwise commas, when every line has a comma, read as CSV: a field in double quotes
	39	can hold commas, and a line break in it becomes a space;
	40	- otherwise runs of spaces.
	41
	42	* Moving around and alignment
	43
	44	\| Key \| Org command \| Action \|
	45	\|---------+----------------------------+----------------------------------------------------------------------------\|
	46	\| =TAB= \| =org-table-next-field= \| Aligns the table and moves to the next field, skipping rules. In the last field it adds a row. \|
	47	\| =S-TAB= \| =org-table-previous-field= \| Aligns the table and moves to the previous field. \|
	48	\| =RET= \| =org-table-next-row= \| 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. \|
	49
	50	These keys work the same in the Emacs and Mac presets. In Doom they apply in insert
	51	state; in normal state =RET= is Doom's "act at point" (see /Recalculating/).
	52
	53	Alignment (=org-table-align=) pads every field to its column's width and redraws
	54	rules to match. A column is right-aligned when at least half of its non-empty fields
	55	are numbers, and left-aligned otherwise. A field that holds only a cookie =<l>=, =<c>=
	56	or =<r>= (optionally with a width, such as =<r10>=) fixes the column's alignment.
	57	Widths count display columns, so wide characters and hidden link markup are measured
	58	as they appear.
	59
	60	Alignment happens when you press =TAB=, =S-TAB= or =RET= in a table and after every
	61	table command, not while you type. To align without moving, use Org ▸ Align Table:
	62
	63	\| Preset \| Key \|
	64	\|--------+------------------------------\|
	65	\| Emacs \| =C-c C-c= in a table \|
	66	\| Mac \| Org ▸ Align Table \|
	67	\| Doom \| =C-c C-c=, or =SPC m b a= \|
	68
	69	To align every table when a file opens, set =org-startup-align-all-tables= to =true=
	70	in the config file (default =false=), or put =#+STARTUP: align= in the file;
	71	=#+STARTUP: noalign= turns it off for that file. See
	72	[[file:13-configuration.org][Configuration]].
	73
	74	* Editing rows and columns
	75
	76	\| Action \| Org command \| Emacs \| Mac \| Doom \|
	77	\|-----------------------------------+----------------------------+----------------+-------------+-------------------------------\|
	78	\| Move row up \| =org-table-move-row-up= \| =M-<up>= \| =⌃⌘↑= \| =M-<up>=, =M-k= \|
	79	\| Move row down \| =org-table-move-row-down= \| =M-<down>= \| =⌃⌘↓= \| =M-<down>=, =M-j= \|
	80	\| Move column left \| =org-table-move-column-left= \| =M-<left>= \| =⌃⌘←= \| =M-<left>=, =M-h= \|
	81	\| Move column right \| =org-table-move-column-right= \| =M-<right>= \| =⌃⌘→= \| =M-<right>=, =M-l= \|
	82	\| Insert column \| =org-table-insert-column= \| =M-S-<right>= \| =⌃⌥⌘→= \| =M-S-<right>=, =SPC m b i c= \|
	83	\| Delete column \| =org-table-delete-column= \| =M-S-<left>= \| =⌃⌥⌘←= \| =M-S-<left>=, =SPC m b d c= \|
	84	\| Insert row above \| =org-table-insert-row= \| =M-S-<down>= \| =⌃⌥⌘↓= \| =M-S-<down>=, =SPC m b i r= \|
	85	\| Delete row \| =org-table-kill-row= \| =M-S-<up>= \| =⌃⌥⌘↑= \| =M-S-<up>=, =SPC m b d r= \|
	86	\| Insert rule below \| =org-table-insert-hline= \| =C-c -= \| =⌃⌘-= \| =C-c -=, =SPC m b -=, =SPC m b i h= \|
	87	\| Sort rows \| =org-table-sort-lines= \| =C-c ^= \| Org ▸ Sort Table Lines \| =C-c ^= \|
	88	\| Transpose \| =org-table-transpose-table-at-point= \| Org ▸ Transpose Table \| Org ▸ Transpose Table \| Org ▸ Transpose Table \|
	89	\| Edit field in its own editor \| =org-table-edit-field= \| =C-c `= \| Org ▸ Edit Table Field \| =C-c `= \|
	90
	91	The new column goes to the left of the caret's column, empty. Deleting a row deletes
	92	the line; it doesn't go to the clipboard. When rows and columns move, are inserted or
	93	are deleted, the =#+TBLFM= line is updated to match: references are renumbered, and
	94	formulas for a deleted row or column are removed.
	95
	96	The Mac preset uses the same keys for headings and list items; in a table they act on
	97	the table.
	98
	99	** Sorting
	100
	101	=C-c ^= in a table asks =Sort Table: [a]lphabetic, [n]umeric, [t]ime. A/N/T means
	102	reversed:= and sorts the rows between the rules around the caret by the caret's
	103	column. If the caret isn't in a field, it asks for the column first. Sorting is stable.
	104
	105	- a compares text without case.
	106	- n compares the number at the start of each field.
	107	- t compares a timestamp in the field, else a duration such as =1:30= or =2h 15min=,
	108	else a clock time =H:MM=. Fields with none of these sort as 0.
	109
	110	** Transposing
	111
	112	Org ▸ Transpose Table swaps rows and columns. Rules are dropped.
	113
	114	** The field editor
	115
	116	=C-c `= opens the field at the caret in an editor of its own, which is easier for long
	117	text. =C-c '= or =⌘Return= puts it back; =Escape= or =C-c C-k= leaves it unchanged.
	118	Line breaks become single spaces and lines that start with =#= are dropped, as
	119	=org-table-finish-edit-field= does.
	120
	121	* Narrow columns
	122
	123	A field that holds a width cookie =<N>=, optionally with an alignment letter
	124	(=<l10>=, =<c8>=, =<r12>=), marks the column for narrowing. Narrowed fields show their
	125	first /N/ display columns followed by =…=. The text itself is unchanged.
	126
	127	\| Command \| Org command \| Keys \|
	128	\|------------------------------------------+-----------------------------------+------------------------------------------\|
	129	\| Org ▸ Shrink or Expand Table Column \| =org-table-toggle-column-width= \| Emacs and Doom =C-c TAB= \|
	130	\| Org ▸ Shrink Table Columns with Widths \| =org-table-shrink= \| No default key \|
	131	\| Org ▸ Expand Table Columns \| =org-table-expand= \| No default key \|
	132
	133	=C-c TAB= in a field toggles that column. Outside a column, for example on the leading
	134	=\|=, it asks for =Column ranges (e.g. 2-4 6-):=, where =6-= means column 6 to the end.
	135	A column without a width cookie shrinks to a bare =…= when toggled. Typing in a narrowed
	136	field widens its column again, as editing Org's overlays does. =#+STARTUP: shrink=
	137	narrows every column with a width cookie when the file opens.
	138
	139	* Importing and exporting
	140
	141	\| Command \| Org command \|
	142	\|----------------------------------------+--------------------\|
	143	\| Import Table from File… (command palette) \| =org-table-import= \|
	144	\| Export Table to File… (command palette) \| =org-table-export= \|
	145
	146	Open the command palette with =⇧⌘P= (=M-x= in the Emacs preset, =SPC := in Doom).
	147
	148	Import asks for a CSV, TSV or plain text file, inserts its contents at the caret on a
	149	line of its own, and converts them to a table with the separator guessed as for a
	150	region (see /Creating a table/).
	151
	152	Export writes the table at the caret. A file name ending in =.csv= gets CSV: fields
	153	separated by commas, with fields that contain a comma or a double quote quoted and
	154	inner quotes doubled. Any other name gets TSV. Rules are left out.
	155
	156	Import and export are Mac only.
	157
	158	* Formulas
	159
	160	Orgstar evaluates Org's spreadsheet formulas, =org-table-recalculate= and
	161	=org-table-eval-formula=, natively: Calc expressions in a reimplementation of the part
	162	of Emacs Calc that tables use, and Lisp formulas in a small Emacs Lisp evaluator. What
	163	falls outside them is handed to Emacs on the Mac (see /When Emacs is needed/).
	164
	165	Formulas live in a =#+TBLFM:= line right after the table, separated by =::=:
	166
	167	#+BEGIN_SRC org
	168	\| Item \| Qty \| Price \| Total \|
	169	\|-------+-----+-------+-------\|
	170	\| Apple \| 3 \| 0.50 \| 1.50 \|
	171	\| Pear \| 12 \| 0.75 \| 9.00 \|
	172	\|-------+-----+-------+-------\|
	173	\| Sum \| \| \| 10.50 \|
	174	,#+TBLFM: $4=$2*$3;%.2f::@>$4=vsum(@I..@II);%.2f
	175	#+END_SRC
	176
	177	Blank lines between the table and =#+TBLFM:= are allowed. If there are several
	178	=#+TBLFM:= lines, recalculating the table uses the first; =C-c C-c= on another applies
	179	that line instead (=org-table-calc-current-TBLFM=).
	180
	181	** Kinds of formula
	182
	183	\| Left side \| Kind \| Applies to \|
	184	\|-------------------------+----------------------+------------------------------------------------------------------\|
	185	\| =$3= \| Column formula \| Every data row of column 3, except rows marked =!=, =^=, =_=, =$= or =/= in the first column. \|
	186	\| =$<=, =$>= \| Column formula \| The first or last column. \|
	187	\| =@2$3=, =@>$3= \| Field formula \| One field. Field formulas override column formulas. \|
	188	\| =@2$2..@4$3= \| Range formula \| Every field in the rectangle. \|
	189	\| =@4= \| Row formula \| Every field of data row 4. \|
	190	\| =$name= \| Named field formula \| The field named by a =^= or =_= row (see /Names, parameters and constants/). \|
	191
	192	A left side relative to the current row, such as =@-1$2=, is an error
	193	(=Unknown field=), and so is one relative to a rule, such as =@I$2=, as in Org. Two
	194	formulas for the same field are an error.
	195
	196	** References
	197
	198	Rows count data lines from 1; rules don't count. Columns count from 1.
	199
	200	\| Reference \| Meaning \|
	201	\|----------------------+----------------------------------------------------------------------\|
	202	\| =$2= \| Column 2 in the current row. \|
	203	\| =$-1=, =$+1= \| The column before or after the current one. \|
	204	\| =$<=, =$>=, =$>>= \| The first column, the last, the one before last. \|
	205	\| =@3= \| Row 3 in the current column. \|
	206	\| =@-1=, =@+1= \| The row above or below. \|
	207	\| =@<=, =@>= \| The first or last data row. \|
	208	\| =@I=, =@II=, =@III= \| The first, second, third rule; as a row, the line after it. \|
	209	\| =@-I= \| The rule above the current row. \|
	210	\| =@I+2= \| Two data rows after the first rule. \|
	211	\| =@2$3= \| Row 2, column 3. \|
	212	\| =$0= \| The current column. \|
	213	\| =@#=, =$#= \| The current row's or column's number, as a value. \|
	214	\| =@2$1..@4$3= \| A range: the fields of the rectangle, as a vector. \|
	215	\| =$1..$3= \| Columns 1 to 3 of the current row. \|
	216	\| =@I..@II= \| The current column from the first rule to the second. \|
	217
	218	In a Calc formula a single field becomes a number in parentheses, and a range becomes
	219	a vector such as =[1,2,3]=. Without the =E= flag, empty fields count as 0 on their own
	220	and are left out of ranges.
	221
	222	Fields in a Calc formula must hold numbers, timestamps or =nan=, unless the =N= flag
	223	reads every field as a number. A reference to a field with other text needs Emacs,
	224	because Calc would treat the text as a symbol.
	225
	226	** Names, parameters and constants
	227
	228	The first column can mark special rows, as in Org's spreadsheet:
	229
	230	\| Mark \| Row \|
	231	\|-------+---------------------------------------------------------------------------------------\|
	232	\| =!= \| Column names: =$qty= in a formula means the column whose =!= row field is =qty=. \|
	233	\| =^= \| Names for the fields in the row above, usable as =$name=. \|
	234	\| =_= \| Names for the fields in the row below. \|
	235	\| =$= \| Parameters: fields like ~rate=0.2~, usable as =$rate=. \|
	236	\| =#= \| Marked for recalculation. \|
	237	\| =*= \| Marked for recalculation. \|
	238	\| =/= \| Not recalculated. \|
	239
	240	When any row's first field is one of =!=, =^=, =_=, =$=, =#= or =*=, column formulas
	241	in a whole-table recalculation apply only to the rows marked =#= or =*=, as
	242	=org-table-calculate-mark-regexp= decides in Org. So a table with a =!= names row and
	243	no =#= rows gets no column formulas applied; mark the rows to calculate. Field
	244	formulas apply either way. Rows marked =!=, =^=, =_=, =$= or =/= are never changed by
	245	column formulas.
	246
	247	#+BEGIN_SRC org
	248	\| ! \| qty \| price \| total \|
	249	\|---+-----+-------+-------\|
	250	\| # \| 2 \| 3 \| 6 \|
	251	\| # \| 4 \| 0.5 \| 2 \|
	252	,#+TBLFM: $4=$qty*$price
	253	#+END_SRC
	254
	255	A =$name= that isn't a column name, parameter or named field is looked up as
	256	=org-table-get-constant= does:
	257
	258	- in =#+CONSTANTS:= lines of the file or its setup file, written ~name=value~ and
	259	separated by spaces (~#+CONSTANTS: c=299792458 g=9.81~);
	260	- =$PROP_xyz= reads the =xyz= property of the entry holding the table, with
	261	inheritance.
	262
	263	A name that isn't found becomes =#UNDEFINED_NAME=. A parameter named =%= in a =$= row,
	264	for example ~%=%.2f~, is put in front of the flags of every formula that has a =;=,
	265	so ~$3=$2/3;~ is formatted with =%.2f=.
	266
	267	** Remote references
	268
	269	=remote(NAME, REF)= reads a field or range from another table:
	270
	271	#+BEGIN_SRC org
	272	,#+NAME: rates
	273	\| item \| rate \|
	274	\|------+------\|
	275	\| a \| 2 \|
	276	\| b \| 3 \|
	277
	278	\| x \| y \| z \|
	279	\|---+---+---\|
	280	\| 4 \| 8 \| 5 \|
	281	,#+TBLFM: $2=$1*remote(rates,@2$2)::$3=vsum(remote(rates,@2$2..@>$2))
	282	#+END_SRC
	283
	284	=NAME= is found in this order:
	285
	286	1. a table after =#+NAME: NAME= or =#+TBLNAME: NAME= in the same file;
	287	2. the first table in the entry whose =ID= property is =NAME=, in the same file;
	288	3. the first table in the entry with that =ID= in any indexed file in your sidebar
	289	folders, read from the file on disk.
	290
	291	=REF= may use spreadsheet-style references such as =B3= (column B, row 3), which
	292	become =@3$2=.
	293
	294	** Calc expressions
	295
	296	Calc formulas use Calc's number rules: integers are exact, and decimal numbers are
	297	rounded to 12 significant digits after every operation. Results are shown with up to
	298	8 significant digits unless a format flag says otherwise (=org-calc-default-modes=).
	299
	300	Operators, from lowest to highest precedence (the lowest, ~\|\|~, is logical or, giving
	301	1 or 0):
	302
	303	\| Operator \| Meaning \|
	304	\|------------------------------------+-----------------------------------------------------------\|
	305	\| =&&= \| Logical and. \|
	306	\| =!= \| Logical not. \|
	307	\| ~==~, ~!=~, =<=, =>=, ~<=~, ~>=~ \| Comparisons, giving 1 or 0. They can't be chained. \|
	308	\| =+=, =-= \| Addition and subtraction. \|
	309	\| =/=, =%=, =\= \| Division, modulo (sign of the divisor), integer division rounding down. \|
	310	\| =*= \| Multiplication. \|
	311	\| unary =-= \| Negation. \|
	312	\| =^= \| Power. \|
	313
	314	Parentheses group, =[a, b, c]= writes a vector, =<2026-10-05 Mon>= writes a date, and
	315	=nan= is "not a number".
	316
	317	Functions:
	318
	319	\| Function \| Result \|
	320	\|--------------------------------------------+---------------------------------------------------------------\|
	321	\| =vsum=, =vprod= \| Sum or product of a vector. \|
	322	\| =vcount= \| Number of elements. \|
	323	\| =vmean=, =vmedian= \| Mean, median. \|
	324	\| =vmax=, =vmin= \| Largest, smallest element. \|
	325	\| =vvar=, =vsdev= \| Sample variance, sample standard deviation. \|
	326	\| =vpvar=, =vpsdev= \| Population variance, population standard deviation. \|
	327	\| =max(a, b, …)=, =min(a, b, …)= \| Largest, smallest argument. \|
	328	\| =if(c, a, b)= \| =a= if =c= is nonzero, else =b=. \|
	329	\| =abs= \| Absolute value. \|
	330	\| =floor=, =ceil=, =trunc= \| Round down, up, toward zero, to an integer. \|
	331	\| =round(x)=, =round(x, n)= \| Round to an integer, or to /n/ decimal places. \|
	332	\| =mod(a, b)=, =idiv(a, b)= \| As =%= and =\=. \|
	333	\| =fact= \| Factorial of a non-negative integer. \|
	334	\| =sqrt=, =exp=, =ln=, =log10= \| Square root, exponential, natural and base-10 logarithm. \|
	335	\| =sin=, =cos=, =tan= \| Trigonometry, in degrees unless the =R= flag is set. \|
	336	\| =arcsin=, =arccos=, =arctan= \| Inverse trigonometry, in degrees unless =R=. \|
	337
	338	Other Calc functions, variables such as =pi= or =e=, symbolic results, complex results
	339	and division by zero need Emacs.
	340
	341	** Mode flags and formats
	342
	343	After the formula, a =;= starts its flags, as in ~$3=$1/$2;%.2f~ or ~$4=$1*2;f2~:
	344
	345	\| Flag \| Meaning \|
	346	\|-----------+-------------------------------------------------------------------------------------------\|
	347	\| =nN= \| Float format with /N/ significant digits. \|
	348	\| =fN= \| Fixed format with /N/ decimal places. \|
	349	\| =sN= \| Scientific format with /N/ digits. \|
	350	\| =eN= \| Engineering format with /N/ digits. \|
	351	\| =pN= \| Calc precision. Only =p12=, the default, is evaluated natively; others need Emacs. \|
	352	\| =D=, =R= \| Angles in degrees (the default) or radians. \|
	353	\| =F= \| Prefer fractions: =1/3= stays =1:3=. \|
	354	\| =N= \| Treat every field as a number; text counts as 0. \|
	355	\| =E= \| Keep empty fields: in ranges they stay in, and count as =nan= in Calc. \|
	356	\| =L= \| Literal: in Lisp formulas, insert fields as they are written. \|
	357	\| =T= \| Durations: read =H:MM= and =H:MM:SS= fields as times, show the result as =HH:MM:SS=. \|
	358	\| =U= \| As =T=, showing =HH:MM=. \|
	359	\| =t= \| As =T=, showing decimal hours with two places, such as =1.50=. \|
	360
	361	The flags =S= (symbolic) and =u= need Emacs. Any other text after the flags is a
	362	=format= string applied to the result, such as =%.2f= or =%d=; =format= supports
	363	=%s=, =%S=, =%d=, =%o=, =%x=, =%X=, =%c=, =%e=, =%f= and =%g=.
	364
	365	** Durations
	366
	367	With =T=, =U= or =t=, fields like =1:30= or =10:00:30= are read as hours, minutes and
	368	seconds:
	369
	370	#+BEGIN_SRC org
	371	\| start \| end \| sum \| diff \| hours \|
	372	\|----------+---------+----------+-------+-------\|
	373	\| 1:30 \| 0:45 \| 02:15:00 \| 00:45 \| 3.00 \|
	374	\| 10:00:30 \| 2:15:10 \| 12:15:40 \| 07:45 \| 20.02 \|
	375	,#+TBLFM: $3=$1+$2;T::$4=$1-$2;U::$5=$1*2;t
	376	#+END_SRC
	377
	378	** Dates
	379
	380	Timestamps in fields, active or inactive, take part in Calc arithmetic as dates. The
	381	difference of two dates is a number of days, with a fraction when the timestamps have
	382	times. A date plus a number is a date, written back as an inactive timestamp:
	383
	384	#+BEGIN_SRC org
	385	\| start \| end \| days \| later \|
	386	\|------------------+------------------+------+------------------\|
	387	\| <2026-10-05 Mon> \| <2026-10-12 Mon> \| 7 \| [2026-10-12 Mon] \|
	388	,#+TBLFM: $3=$2-$1::$4=$1+7
	389	#+END_SRC
	390
	391	** Lisp formulas
	392
	393	A formula that starts with ='(= is Emacs Lisp. Each reference becomes a Lisp string,
	394	or a number with =N=, or the field's text inserted as is with =L=. A range becomes the
	395	values separated by spaces, so wrap it in a quoted list:
	396
	397	#+BEGIN_SRC org
	398	\| name \| greeting \|
	399	\|-------+----------\|
	400	\| Ada \| Ada! \|
	401	\| Grace \| Grace! \|
	402	,#+TBLFM: $2='(concat $1 "!")
	403
	404	\| n \|
	405	\|---\|
	406	\| 1 \|
	407	\| 2 \|
	408	\|---\|
	409	\| 3 \|
	410	,#+TBLFM: @>$1='(apply '+ '(@I..@II));N
	411	#+END_SRC
	412
	413	The evaluator supports:
	414
	415	- special forms: =quote=, =function=, =lambda=, =progn=, =prog1=, =if=, =when=,
	416	=unless=, =cond=, =and=, =or=, =let=, =let*=, =setq=, =push=, =pop=, =while=,
	417	=dolist=, =dotimes=, =with-output-to-string=, =ignore-errors=, =condition-case=;
	418	- arithmetic: =+=, =-=, =*=, =/=, =%=, =mod=, =1+=, =1-=, =abs=, =max=, =min=, =float=,
	419	=floor=, =ceiling=, =round=, =truncate=, ~=~, =<=, =>=, ~<=~, ~>=~, ~/=~, =zerop=;
	420	- predicates: =not=, =null=, =eq=, =eql=, =equal=, =numberp=, =integerp=, =floatp=,
	421	=stringp=, =listp=, =consp=, =symbolp=;
	422	- lists: =car=, =cdr=, =cadr=, =cddr=, =cons=, =list=, =nth=, =nthcdr=, =elt=, =aref=,
	423	=append=, =length=, =reverse=, =number-sequence=, =memq=, =member=, =memql=, =assoc=,
	424	=assq=, =delq=, =delete=, =mapcar=, =mapc=, =mapconcat=, =funcall=, =apply=,
	425	=identity=, =ignore=;
	426	- strings: =concat=, =format=, =format-message=, ~string=~, =string-equal=, =string<=,
	427	=string-lessp=, =upcase=, =downcase=, =capitalize=, =substring=, =string-to-number=,
	428	=number-to-string=, =int-to-string=, =string-prefix-p=, =string-suffix-p=,
	429	=string-empty-p=, =string-trim=, =split-string=, =prin1-to-string=;
	430	- output and errors: =princ=, =prin1=, =print=, =terpri=, =message=, =error=,
	431	=user-error=;
	432	- Org's lookup functions =org-lookup-first=, =org-lookup-last= and =org-lookup-all=.
	433
	434	Any other function needs Emacs. An error inside a Lisp formula writes =#ERROR= in the
	435	field, as does a Calc error.
	436
	437	* Entering formulas
	438
	439	There are three ways to set a formula.
	440
	441	In the field. Type ~=expr~ in a field and press =TAB= or =RET=: Orgstar stores
	442	~$N=expr~ as the column's formula and evaluates it, as
	443	=org-table-maybe-eval-formula= does. Type ~:=expr~ instead to store a field formula
	444	~@R$C=expr~.
	445
	446	With a prompt. =org-table-eval-formula= asks for the formula (~Column formula $N=~
	447	or ~Field formula @R$C=~) with the stored one filled in, stores it and evaluates it in
	448	the current field. An empty answer keeps the stored formula and evaluates it again,
	449	unlike Emacs, where an empty answer removes it. To remove a formula, delete it in the
	450	formula editor below or from the =#+TBLFM:= line.
	451
	452	\| Command \| Emacs \| Mac \| Doom \|
	453	\|-------------------------------+----------+-----------------------------+----------\|
	454	\| Org ▸ Set Column Formula \| ~C-c =~ \| Org ▸ Set Column Formula \| ~C-c =~ \|
	455	\| Org ▸ Set Field Formula \| none \| Org ▸ Set Field Formula \| none \|
	456
	457	Org's ~C-u C-c =~ for field formulas has no equivalent key, because Orgstar has no
	458	prefix argument; use the menu item or type ~:=~ in the field.
	459
	460	In the formula editor. =C-c '= in a table or on its =#+TBLFM:= line
	461	(=org-table-edit-formulas=) opens the formulas in an editor of their own, one per line,
	462	grouped under =# Column Formulas=, =# Field and Range Formulas= and
	463	=# Named Field Formulas=. A formula can continue on indented lines. =C-c '= or
	464	=⌘Return= installs the formulas; =Escape= or =C-c C-k= leaves them unchanged.
	465	Installing doesn't recalculate; do that next with =C-c C-c= on the =#+TBLFM:= line, or
	466	Org ▸ Recalculate Table in the Mac preset.
	467
	468	The formulas are stored sorted the way =org-table-formula-less-p= sorts them.
	469
	470	* Recalculating
	471
	472	\| Command \| Org command \| Emacs \| Mac \| Doom \|
	473	\|----------------------------------+-----------------------------------+-------------------------------+-----------------------------+-------------------------------------\|
	474	\| Recalculate Table \| =org-table-recalculate= with =C-u= \| =C-c C-c= on =#+TBLFM:= \| Org ▸ Recalculate Table \| =SPC m b r=, =C-c C-c= on =#+TBLFM:= \|
	475	\| Recalculate Table Row \| =org-table-recalculate= \| =C-c = \| Org ▸ Recalculate Table Row \| =C-c = \|
	476
	477	In Doom's normal state, =RET= in a table recalculates it when it has a =#+TBLFM:=
	478	line and aligns it otherwise; on a =#+TBLFM:= line it recalculates.
	479
	480	When the table has a rule below its first data row, recalculating the whole table
	481	leaves the rows above that rule, the header, alone. With marked rows, the marks decide
	482	instead (see /Names, parameters and constants/). Each
	483	command evaluates the column formulas row by row, then the field formulas, then aligns
	484	the table. Formulas are evaluated once; Org's iterate-until-stable recalculation
	485	(=C-u C-u C-c *=) isn't available.
	486
	487	Tables are not recalculated automatically. Rows marked =#= are not recalculated when
	488	you press =TAB= or =RET= in them, as =org-table-maybe-recalculate-line= would do in
	489	Emacs; recalculate with one of the commands above.
	490
	491	* When Emacs is needed
	492
	493	When a formula uses something the native evaluator doesn't have, the command reports
	494	what it was and the Mac recalculates the table in Emacs instead. This happens for:
	495
	496	- references to fields holding text in a Calc formula, and symbolic results;
	497	- Calc functions and variables not listed above, precision other than =p12=, and the
	498	=S= and =u= flags;
	499	- division by zero, complex results, vector results, and numbers too large for
	500	64-bit integers;
	501	- Lisp functions not listed above.
	502
	503	The echo area shows =Recalculating in Emacs (reason)…=, then =Recalculated in Emacs=.
	504	Orgstar runs =emacs -Q --batch= on a copy of the file, so your Emacs init file,
	505	packages and customizations are not loaded, then replaces the table with Emacs's
	506	result. It looks for Emacs at the path in the =ORGSTAR_EMACS= environment variable,
	507	then =/opt/homebrew/bin/emacs=, =/usr/local/bin/emacs=,
	508	=/Applications/Emacs.app/Contents/MacOS/Emacs=, =/run/current-system/sw/bin/emacs= and
	509	=/usr/bin/emacs=. If none is found, the echo area says Emacs isn't installed and the
	510	table is unchanged. The run stops after 60 seconds. If you edit the table while Emacs
	511	is working, its result is discarded.
	512
	513	If the table's formulas contain Lisp, Orgstar asks first:
	514	=This table's formulas run Lisp. Run them? (yes, no, always)=. =always= trusts this
	515	table's text in this file, so the question isn't asked again until the text changes.
	516
	517	Entering a formula that needs Emacs with ~C-c =~, Set Field Formula or ~=~ in a field
	518	is not handed to Emacs. The echo area shows =The formula was stored; recalculating it
	519	needs Emacs= and the reason, but the table and its =#+TBLFM:= line stay unchanged.
	520	Add such a formula in the formula editor or by editing the =#+TBLFM:= line, then
	521	recalculate the table, which runs it in Emacs.
	522
	523	For how Orgstar and Emacs share files, see
	524	[[file:15-alongside-emacs.org][Using Orgstar alongside Emacs]].
	525
	526	* table.el tables
	527
	528	Tables drawn with =+= corners and =-= and =\|= borders, as the =table.el= package makes
	529	them, are recognized and kept as written:
	530
	531	#+BEGIN_SRC org
	532	+-------+-------+
	533	\| Name \| Value \|
	534	+-------+-------+
	535	\| a \| 1 \|
	536	+-------+-------+
	537	#+END_SRC
	538
	539	Orgstar doesn't edit them as tables: =TAB=, alignment and formulas don't apply. HTML
	540	export renders them as tables, with cells that span rows and columns, and Markdown
	541	export writes them as a code block. See [[file:12-export.org][Export]].
	542
	543	* Plotting
	544
	545	=#+PLOT:= lines are recognized and completed as keywords, but Orgstar doesn't draw
	546	plots (=org-plot/gnuplot= is not available).
	547
	548	* On iOS
	549
	550	The iOS app evaluates formulas natively with the same engine. Tables that need Emacs
	551	are not recalculated there; the app reports =This table needs Emacs, which runs on the
	552	Mac= with the reason. Table import and export are Mac only. See
	553	[[file:14-ios.org][iOS]].

docs/manual/guide/11-code-blocks.org added +648

		@@ -0,0 +1,648 @@
	1	#+TITLE: Code blocks
	2	#+DESCRIPTION: Source blocks in Orgstar: highlighting, editing, running with Babel, results, header arguments, noweb and tangling.
	3	#+LEDE: Orgstar runs and tangles source blocks the way Org Babel does, and refuses anything it would run differently.
	4
	5	* Source blocks
	6
	7	A source block holds code in a named language:
	8
	9	#+BEGIN_SRC org
	10	,#+begin_src python
	11	return 6 * 7
	12	,#+end_src
	13	#+END_SRC
	14
	15	Orgstar reads the same syntax Org does: the language after =#+begin_src=, then any switches such as =-i= or =-r=, then header arguments. A =#+NAME:= line above a block names it, so other blocks, =#+CALL:= lines and =:var= references can refer to it.
	16
	17	Lines inside a block that start with =*= or =#+= are protected with a leading comma, as Org does (=org-escape-code-in-region=). The comma is removed when the block runs, tangles or exports, and when you edit the block apart.
	18
	19	** Syntax highlighting
	20
	21	On the Mac, the code in a block is highlighted in the editor and in the block editor. Highlighting uses tree-sitter grammars for these language names:
	22
	23	\| Language names \| Grammar \|
	24	\|---------------------------------+------------\|
	25	\| =sh=, =bash=, =shell=, =zsh= \| Bash \|
	26	\| =python=, =python3=, =py= \| Python \|
	27	\| =emacs-lisp=, =elisp= \| Emacs Lisp \|
	28	\| =c= \| C \|
	29	\| =c++=, =cpp= \| C++ \|
	30	\| =r= \| R \|
	31	\| =js=, =javascript=, =node= \| JavaScript \|
	32	\| =java= \| Java \|
	33	\| =scheme= \| Scheme \|
	34	\| =clojure=, =clj= \| Clojure \|
	35	\| =haskell= \| Haskell \|
	36	\| =rust= \| Rust \|
	37	\| =go= \| Go \|
	38	\| =ruby= \| Ruby \|
	39	\| =json= \| JSON \|
	40	\| =yaml=, =yml= \| YAML \|
	41	\| =toml=, =conf-toml= \| TOML \|
	42	\| =lua= \| Lua \|
	43
	44	Names are matched without regard to case. Blocks in any other language show as plain monospaced text. The iOS app does not highlight code.
	45
	46	* Editing a block apart
	47
	48	=org-edit-special= edits a block's contents in a separate editor. Put the caret in a =src=, =example= or =export= block (or on a =#+TBLFM:= line; see [[file:10-tables.org][Tables]]) and run Edit Block.
	49
	50	\| Preset \| Key \|
	51	\|--------+---------------------------\|
	52	\| Emacs \| =C-c '= \|
	53	\| Doom \| =C-c '=, or =SPC m '= in normal state \|
	54	\| Mac \| Org ▸ Edit Block, or the command palette \|
	55
	56	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.
	57
	58	\| Action \| Keys \|
	59	\|--------+--------------------------------------\|
	60	\| Save \| =C-c '= or ⌘Return, or Save Block \|
	61	\| Leave \| =C-c C-k= or Escape, or Cancel \|
	62
	63	If the block changed in the main editor while you edited it, the edit is not saved and the message area says so.
	64
	65	On iOS the block opens in a plain text sheet with Cancel and Save buttons.
	66
	67	* Running a block
	68
	69	=C-c C-c= in a source block runs it (=org-babel-execute-src-block=) and writes its result under it. The same command runs a =#+CALL:= line or an inline =src_= block when the caret is on one.
	70
	71	\| Preset \| Key \|
	72	\|--------+------------------------------------------------------\|
	73	\| Emacs \| =C-c C-c= \|
	74	\| Doom \| =C-c C-c= in normal, insert and visual state \|
	75	\| Mac \| Org ▸ Run Source Block, or the command palette \|
	76
	77	The program runs in the folder of the file, or in =:dir=. It reads the code on standard input. While it runs, the message area shows "Running /language/ block…"; when it ends, it shows "Code block evaluation complete." or the problem.
	78
	79	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.
	80
	81	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.
	82
	83	** Languages that run
	84
	85	On the Mac, Orgstar starts each interpreter through =/usr/bin/env=. Because an app opened from the Dock does not see your shell's =PATH=, Orgstar adds =/opt/homebrew/bin=, =/usr/local/bin=, =/usr/bin= and =/bin= to the end of it.
	86
	87	\| Language \| Program run \|
	88	\|------------------------------------------------------------------+-----------------------------------------------------\|
	89	\| =sh=, =bash=, =zsh=, =fish=, =ksh=, =dash=, =ash=, =csh=, =mksh=, =posh= \| The shell of that name \|
	90	\| =shell= \| The shell in =SHELL=, or =/bin/sh= \|
	91	\| =python= \| =python3=, or the program in =:python= \|
	92	\| =emacs-lisp=, =elisp= \| =emacs -Q --batch=; see Emacs Lisp blocks below \|
	93	\| =ruby= \| =ruby= \|
	94	\| =js=, =javascript= \| =node= \|
	95	\| =R= \| =Rscript -= \|
	96	\| =awk= \| =awk -f /dev/stdin= \|
	97	\| =dot=, =plantuml=, =mermaid= \| =dot=, =plantuml=, =mmdc=; see Graphics below \|
	98
	99	For =ruby=, =js=, =javascript=, =R= and =awk=, =:cmd= names a different program. These languages always return their standard output, and =:var= is refused for them.
	100
	101	Any other language is refused with "No way to run /language/ blocks yet."
	102
	103	A run that takes longer than five minutes is stopped. Runs in a =:session= have no time limit.
	104
	105	** The trust prompt
	106
	107	Before a block runs, Orgstar asks "Run this /language/ block? (yes, no, always)", as =org-confirm-babel-evaluate= does.
	108
	109	- =yes= runs it this once.
	110	- =no= does not run it.
	111	- =always= runs it and remembers the block, so it runs without asking next time.
	112
	113	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 =trusted.json= in Orgstar's Application Support folder (=~/Library/Application Support/Orgstar= 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.
	114
	115	When a block's =:var= or =:stdin= 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."
	116
	117	** =:eval=
	118
	119	\| Value \| Effect \|
	120	\|------------------------------------------+------------------------------------------------------------\|
	121	\| =never=, =no=, =never-export=, =no-export= \| The block does not run: "Evaluation of this /language/ code block is disabled." \|
	122	\| =query= \| Asks every time, with only =yes= and =no=. A block reached through =:var= with =:eval query= makes the whole chain ask every time. \|
	123	\| anything else, or absent \| Runs after the trust prompt. \|
	124
	125	Orgstar does not export by running blocks, so =never-export= and =no-export= also stop the block from running interactively. In Org these two values only stop evaluation during export.
	126
	127	** Cancelling a run
	128
	129	On the Mac, Edit ▸ Cancel Running Block (⌘.) stops the running block. Its result is not inserted, and the message area shows "Code block canceled." The command is also in the command palette.
	130
	131	Only one block runs at a time. Starting another block cancels the one that is running.
	132
	133	Cancelling a block that runs in a =:session= stops the session's interpreter, so the session's state is lost. The next block in that session starts a new one.
	134
	135	The iOS app has no cancel command.
	136
	137	* Results
	138
	139	The result is written after a =#+RESULTS:= line below the block (=org-babel-insert-result=). Running again replaces it. A named block's result goes under =#+RESULTS: name=, wherever that line is in the file. An unnamed block's result is the =#+RESULTS:= 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.
	140
	141	#+BEGIN_SRC org
	142	,#+begin_src sh
	143	echo hello
	144	,#+end_src
	145
	146	,#+RESULTS:
	147	: hello
	148	#+END_SRC
	149
	150	By default a result is shaped like this:
	151
	152	- Text of fewer than ten lines gets a =: = prefix on each line.
	153	- Text of ten lines or more goes in an =#+begin_example= block.
	154	- A table becomes an aligned Org table.
	155
	156	** Value or output
	157
	158	\| Word \| Result \|
	159	\|----------+---------------------------------------------------------------------------------------------------------\|
	160	\| =value= \| The value of the block. This is the default. \|
	161	\| =output= \| Everything the program printed on standard output. \|
	162
	163	What "value" means depends on the language:
	164
	165	\| Language \| Value \|
	166	\|-------------------------+-----------------------------------------------------------------------------------------------\|
	167	\| Shells, by default \| Standard output, read as a table: tab-separated columns, then comma-separated, then space-separated; a single field is a plain value. \|
	168	\| Shells, =:results value= written out \| The exit status of the last command. \|
	169	\| Python \| What the block returns. The body runs as a function, so it needs =return=. =:return expr= adds a final =return expr=. \|
	170	\| Python in a =:session= \| The value of the last expression. \|
	171	\| Emacs Lisp \| The value of the last form. \|
	172	\| =ruby=, =js=, =R=, =awk= \| Standard output, always. \|
	173
	174	Python lists of lists become tables, with =None= rows as rules. A flat list becomes a one-row table. Emacs Lisp lists become tables the same way, with =hline= for rules. Numbers are written the way Emacs prints them.
	175
	176	** Result types
	177
	178	\| Word \| Effect \|
	179	\|----------------------+----------------------------------------------------------------------------\|
	180	\| =table=, =vector= \| Read the result as a table. This is the default for values. \|
	181	\| =list= \| Write a plain list, one =- = item per line or per element. \|
	182	\| =scalar=, =verbatim= \| Write the result as text without reading it as a table. \|
	183	\| =file= \| Write a link to a file (see Results in files below). \|
	184
	185	=:results verbatim= on an Emacs Lisp value writes it as =prin1= would, with quotes around strings.
	186
	187	** Result formats
	188
	189	\| Word \| Written as \|
	190	\|----------+----------------------------------------------------------------\|
	191	\| =raw= \| The text as it is, so Org markup in it takes effect. \|
	192	\| =drawer= \| Between =:results:= and =:end:=. \|
	193	\| =code= \| In a =#+begin_src= block of the block's language. \|
	194	\| =org= \| In a =#+begin_src org= block. \|
	195	\| =html= \| In a =#+begin_export html= block. \|
	196	\| =latex= \| In a =#+begin_export latex= block. \|
	197	\| =pp= \| Python: formatted with =pprint=; written as text. \|
	198
	199	Lines that start with =*= or =#+= inside =code=, =org=, =html= and =latex= results are comma-protected.
	200
	201	** Inserting
	202
	203	\| Word \| Effect \|
	204	\|-----------+----------------------------------------------------------------\|
	205	\| =replace= \| Replace the previous result. This is the default. \|
	206	\| =append= \| Add after the previous result. \|
	207	\| =prepend= \| Add before the previous result. \|
	208	\| =silent= \| Show the output in the message area and write nothing. \|
	209	\| =none=, =discard= \| Write nothing. \|
	210
	211	Words from different groups combine: =:results output list append=. A later word replaces an earlier one from the same group.
	212
	213	** =:wrap=
	214
	215	=:wrap= puts the result in a block, ahead of any format word.
	216
	217	\| Value \| Wrapped in \|
	218	\|---------------------+----------------------------------------------------\|
	219	\| =:wrap= alone \| =#+begin_results= … =#+end_results= \|
	220	\| =:wrap example= \| =#+begin_example= … =#+end_example= \|
	221	\| =:wrap src python= \| =#+begin_src python= … =#+end_src= \|
	222	\| =:wrap export html= \| =#+begin_export html= … =#+end_export= \|
	223	\| =:wrap no=, =:wrap nil= \| No wrapping \|
	224
	225	Inside =example=, =src= and =export= wrappers, lines starting with =*= or =#+= are comma-protected.
	226
	227	** Results in files
	228
	229	With =:results file=, the result is a link instead of text.
	230
	231	\| Header \| Effect \|
	232	\|---------------+--------------------------------------------------------------------------------------------\|
	233	\| =:file name= \| Write the result into =name= and link to it. Without =:results file=, =:file= has no effect, except in graphics blocks. \|
	234	\| =:output-dir dir= \| Put =:file= under =dir=. The folder must exist. \|
	235	\| =:file-desc text= \| Give the link a description: =[[file:name][text]]=. An empty =:file-desc= uses the file name. \|
	236
	237	A relative =:file= is written in the folder the block ran in: the file's folder, or =:dir=. Without =:file=, =:results file= takes the result itself as the path to link to.
	238
	239	#+BEGIN_SRC org
	240	,#+begin_src sh :results file :file out.txt :file-desc Output
	241	echo hello
	242	,#+end_src
	243
	244	,#+RESULTS:
	245	[[file:out.txt][Output]]
	246	#+END_SRC
	247
	248	* Header arguments
	249
	250	** Where they come from
	251
	252	Orgstar merges header arguments in this order, each layer overriding the ones before it (=org-babel-get-src-block-info=):
	253
	254	1. =#+PROPERTY: header-args …= in the file, then =header-args= properties of the block's headings, from the outermost heading inwards.
	255	2. =header-args:LANG= the same way, for blocks in language =LANG=.
	256	3. The arguments on the =#+begin_src= line.
	257	4. =#+HEADER:= lines above the block.
	258	5. For a call, the call's arguments (see Calls below).
	259
	260	A property written with a =+=, such as =header-args+=, adds to the value inherited from above instead of replacing it.
	261
	262	#+BEGIN_SRC org
	263	,#+PROPERTY: header-args :results output
	264
	265	,* Scripts
	266	:PROPERTIES:
	267	:header-args:sh: :dir /tmp
	268	:END:
	269
	270	,#+HEADER: :results verbatim
	271	,#+begin_src sh :var name="world"
	272	echo "hello $name"
	273	,#+end_src
	274	#+END_SRC
	275
	276	Without any of these, a block has =:results replace=, =:exports code=, =:session none=, =:cache no=, =:noweb no=, =:hlines no= and =:tangle no=. An inline =src_= block defaults to =:exports results= and =:hlines yes=.
	277
	278	** Lisp in header values
	279
	280	A header value that starts with =(=, ='=, =`= or =[= and is not in quotes is Lisp, as in =org-babel-read=. Orgstar evaluates it with its own Emacs Lisp interpreter, which also knows =buffer-file-name=, =default-directory=, =system-type= and the functions =expand-file-name=, =file-name-directory=, =file-name-nondirectory=, =file-name-sans-extension= and =file-name-as-directory=.
	281
	282	#+BEGIN_SRC org
	283	,#+begin_src sh :dir (concat "/" "usr") :results output
	284	pwd
	285	,#+end_src
	286	#+END_SRC
	287
	288	A string or number takes the place of the form. Lisp that the interpreter cannot evaluate is refused where it matters: for =:var= ("is Lisp that only Emacs can evaluate"), =:colnames= and =:rownames=, and any header of a =:cache yes= block.
	289
	290	** Header argument reference
	291
	292	\| Argument \| Values \| Effect \|
	293	\|-------------------+------------------------------------------------+--------------------------------------------------------------------------------------------\|
	294	\| =:results= \| see Results above \| How the result is collected, shaped and inserted. \|
	295	\| =:wrap= \| block type and parameters \| Wraps the result in a block. \|
	296	\| =:file= \| file name \| Where a file result goes; required for graphics. \|
	297	\| =:output-dir= \| folder \| Folder for =:file=. \|
	298	\| =:file-desc= \| text \| Description of a file result's link. \|
	299	\| =:var= \| =name=value= \| Passes a value in (see Variables below). \|
	300	\| =:colnames= \| =yes=, =no=, Lisp list \| Header row of table variables (see Tables in variables below). \|
	301	\| =:rownames= \| =yes=, =no=, Lisp list \| First column of table variables. \|
	302	\| =:hlines= \| =yes=, =no= \| Keep rules in table variables. \|
	303	\| =:separator= \| text \| Column separator for tables in shell variables; a tab by default. \|
	304	\| =:hline-string= \| text \| What a rule becomes in a shell variable with =:hlines yes=; =hline= by default. \|
	305	\| =:dir= \| folder \| Folder to run in, relative to the file's folder. It must exist. \|
	306	\| =:session= \| name, =none= \| Runs in a long-lived interpreter (see Sessions below). Shells and Python only. \|
	307	\| =:stdin= \| name of a table, list or block \| Feeds the value to standard input. Shells only. \|
	308	\| =:cmdline= \| arguments \| Command-line arguments. Shells, =dot=, =plantuml= and =mermaid= only. \|
	309	\| =:shebang= \| =#!…= line \| Runs the block as a script with this first line. Shells only; also used by tangling. \|
	310	\| =:padline= \| =no= \| No blank line after the shebang of a script, or between tangled blocks. \|
	311	\| =:python= \| program \| Python interpreter to use. \|
	312	\| =:cmd= \| program \| Interpreter for =ruby=, =js=, =javascript=, =R= and =awk=. \|
	313	\| =:return= \| expression \| Python: the value to return. \|
	314	\| =:cache= \| =yes=, =no= \| Skip the run when the result is current (see Caching below). \|
	315	\| =:eval= \| =never=, =no=, =query=, … \| Whether and how to ask before running (see =:eval= above). \|
	316	\| =:noweb= \| see Noweb below \| Expands =<<name>>= references. \|
	317	\| =:noweb-ref= \| name \| Makes the block part of =<<name>>=. \|
	318	\| =:noweb-sep= \| text \| Separator between blocks joined under one =:noweb-ref=; a newline by default. \|
	319	\| =:noweb-prefix= \| =no= \| Do not repeat the text before =<<name>>= on each expanded line. \|
	320	\| =:exports= \| =code=, =results=, =both=, =none= \| What export shows (see [[file:12-export.org][Export]]). \|
	321	\| =:tangle= \| see Tangling below \| Where tangling writes the block. \|
	322
	323	** Arguments that are refused
	324
	325	Orgstar does not run a block whose arguments it would handle differently from Emacs. Instead it says why and runs nothing.
	326
	327	\| Argument \| Refused for \| Message \|
	328	\|-----------------------------+-------------------------------------------------+----------------------------------------------------------\|
	329	\| =:prologue=, =:epilogue=, =:post= \| every language when running (tangling uses =:prologue= and =:epilogue=) \| "=:prologue= isn't supported yet; nothing was run." \|
	330	\| =:stdin=, =:shebang= \| languages other than shells \| "=:stdin= isn't supported yet; nothing was run." \|
	331	\| =:cmdline= \| languages other than shells and graphics \| "=:cmdline= isn't supported for /language/ yet; nothing was run." \|
	332	\| =:session= \| languages other than shells and Python \| "=:session= isn't supported for /language/ yet; nothing was run." \|
	333	\| =:var= \| =ruby=, =js=, =javascript=, =R=, =awk= \| "=:var= isn't supported for /language/ yet." \|
	334
	335	* Variables
	336
	337	=:var name=value= passes a value into the block (=org-babel-ref-resolve=). One =:var= can hold several assignments separated by spaces, and you can repeat =:var=. A later assignment to the same name replaces an earlier one.
	338
	339	\| Value \| Meaning \|
	340	\|--------------------------------+---------------------------------------------------------------------------------\|
	341	\| =5=, =2.5= \| A number. \|
	342	\| ="two words"= \| A string. =\n= and =\t= in it are a newline and a tab. \|
	343	\| ='(1 2)=, =(+ 1 2)=, ='((1 2) hline (3 4))= \| Lisp: evaluated to a string, number, list or table. \|
	344	\| =tbl= \| The table or plain list under =#+NAME: tbl= in the same file. \|
	345	\| =gen= \| The result of the source block named =gen=, which runs first. \|
	346	\| =double(n=4)= \| The result of the block named =double=, run with =n= set to 4. \|
	347
	348	#+BEGIN_SRC org
	349	,#+NAME: nums
	350	\| 1 \| 2 \|
	351	\| 3 \| 4 \|
	352
	353	,#+begin_src python :var t=nums :var scale=10
	354	return [[c * scale for c in row] for row in t]
	355	,#+end_src
	356	#+END_SRC
	357
	358	A referenced block runs before the block that refers to it, after the one trust prompt that covers them all. A block with =:cache yes= and a current result gives that result without running. A chain that leads back to itself is refused with "/name/ refers to itself through :var".
	359
	360	These are not supported and are refused:
	361
	362	- Indexing into a table, such as =tbl[1,2]=: "References like … aren't supported yet."
	363	- A name that matches nothing in the file: "Can't find … for :var."
	364	- References to other files.
	365
	366	How a value reaches the code depends on the language:
	367
	368	\| Language \| Scalars \| Lists \| Tables \|
	369	\|------------+-------------------------+--------------------------------+--------------------------------------------------------------\|
	370	\| bash \| quoted string \| indexed array (=declare -a=) \| two or more columns: associative array keyed by the first column (=declare -A=); one column: indexed array \|
	371	\| other shells \| quoted string \| one item per line \| rows on lines, cells separated by a tab or =:separator= \|
	372	\| fish \| =set name 'value'= \| as other shells \| as other shells \|
	373	\| Python \| literal \| list \| list of lists, =None= for rules \|
	374	\| Emacs Lisp \| =let=-bound value \| list \| list of lists, =hline= for rules \|
	375
	376	For =shell= blocks, the bash forms are used when =SHELL= is bash.
	377
	378	#+BEGIN_SRC org
	379	,#+NAME: kv
	380	\| a \| 1 \|
	381	\| b \| 2 \|
	382
	383	,#+begin_src bash :var t=kv :results output
	384	echo ${t[a]} ${t[b]}
	385	,#+end_src
	386	#+END_SRC
	387
	388	** Tables in variables
	389
	390	A table passed as a variable loses some of its structure first (=org-babel-disassemble-tables=):
	391
	392	- Rules are removed, unless =:hlines yes=.
	393	- The first row is taken off as column names when =:colnames yes=, or when the table's only rule is under the first row. =:colnames no= keeps it as data.
	394	- The first column is taken off as row names when =:rownames yes=.
	395
	396	If the result is a table of the same width (for columns) or height (for rows), the names are put back on it (=org-babel-reassemble-table=). =:colnames= and =:rownames= can also be Lisp lists of names to put on the result, such as =:colnames '("x" "y")=.
	397
	398	#+BEGIN_SRC org
	399	,#+NAME: tbl
	400	\| a \| b \|
	401	\|---+---\|
	402	\| 1 \| x \|
	403	\| 2 \| y \|
	404
	405	,#+begin_src python :var t=tbl
	406	return [r + ["!"] for r in t]
	407	,#+end_src
	408	#+END_SRC
	409
	410	** Standard input and arguments
	411
	412	For shell blocks, =:stdin name= sends a table, list or block result to standard input, a table as tab-separated lines. =:cmdline= gives the script arguments, and =:shebang= its first line. With any of the three, the block is written to an executable script and run by the shell (=org-babel-sh-evaluate=); without =:shebang=, the first line is =#!/usr/bin/env= and the shell's name.
	413
	414	#+BEGIN_SRC org
	415	,#+begin_src sh :cmdline one "two words" :results output
	416	for a in "$@"; do echo "[$a]"; done
	417	,#+end_src
	418	#+END_SRC
	419
	420	* Sessions
	421
	422	=:session name= 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.
	423
	424	- =:session= with no name uses =language=, such as =sh=. =:session none= runs without one.
	425	- A session belongs to one folder, one interpreter and one name. Blocks in different folders, or with different names, do not share state.
	426	- A session starts in the block's =:dir=, or the file's folder, the first time it is used.
	427	- A shell session's output is what the block prints. =:results value= gives the exit status of the last command.
	428	- A Python session runs the block at top level. Its value is the value of the last expression, so =return= is not used.
	429	- Sessions stop when you quit Orgstar, or when you cancel a block running in one.
	430
	431	#+BEGIN_SRC org
	432	,#+begin_src python :session py :results output
	433	a = 2
	434	print("set")
	435	,#+end_src
	436
	437	,#+begin_src python :session py
	438	a * 3
	439	,#+end_src
	440	#+END_SRC
	441
	442	* Caching
	443
	444	With =:cache yes=, Orgstar computes a SHA-1 hash of the block's header arguments and expanded body, as =org-babel-sha1-hash= does, and writes it on the results line: =#+RESULTS[hash]:=. When you run the block again and the hash matches, nothing runs and the message area shows the cached value ("Cached: …").
	445
	446	Change the block or its arguments and it runs again. Results inserted with =append= or =prepend= carry no hash. Inline blocks are not cached. A cached block that has Lisp in its header arguments the interpreter cannot evaluate is refused.
	447
	448	* Noweb
	449
	450	A noweb reference =<<name>>= in a block's body stands for other code. Whether references expand depends on =:noweb= and on what is happening:
	451
	452	\| =:noweb= \| Running \| Tangling \| Exporting \|
	453	\|-----------------+----------+------------------+-----------\|
	454	\| =no= (default) \| no \| no \| no \|
	455	\| =yes= \| expands \| expands \| no \|
	456	\| =tangle= \| no \| expands \| no \|
	457	\| =eval= \| expands \| no \| no \|
	458	\| =no-export= \| expands \| expands \| no \|
	459	\| =strip-export= \| expands \| expands \| no \|
	460	\| =strip-tangle= \| expands \| removes the references \| no \|
	461
	462	Exported code always shows the references as written; see [[file:12-export.org][Export]].
	463
	464	=<<name>>= expands to the first of these that exists:
	465
	466	1. The contents of the heading whose =ID= property is =name=, or whose =CUSTOM_ID= is =name= without its leading =#=.
	467	2. The body of the source block named =name=.
	468	3. The bodies of all blocks with =:noweb-ref name=, joined by each block's =:noweb-sep= (a newline by default).
	469
	470	Blocks under a =COMMENT= heading are skipped. A referenced block expands its own references according to its own =:noweb=, up to 32 levels deep.
	471
	472	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. =:noweb-prefix no= turns this off.
	473
	474	#+BEGIN_SRC org
	475	,#+NAME: greeting
	476	,#+begin_src sh
	477	echo hello
	478	,#+end_src
	479
	480	,#+begin_src sh :noweb yes
	481	<<greeting>>
	482	echo world
	483	,#+end_src
	484	#+END_SRC
	485
	486	A reference that runs a block, =<<name()>>=, is refused: "Noweb references that run a block (…) aren't supported yet; nothing was run."
	487
	488	* Calls
	489
	490	** =#+CALL:= lines
	491
	492	=#+CALL:= runs a named block with other arguments, as Org's library of Babel calls do (=org-babel-lob-get-info=). Run it with =C-c C-c= on the line.
	493
	494	#+BEGIN_SRC org
	495	,#+NAME: double
	496	,#+begin_src sh :var n=2
	497	echo $((n*2))
	498	,#+end_src
	499
	500	,#+CALL: double(n=5)
	501
	502	,#+RESULTS:
	503	: 10
	504	#+END_SRC
	505
	506	The full form is =#+CALL: name[inside](arguments) end=:
	507
	508	- =name= is the block to run. It must be in the same file.
	509	- =[inside]= holds header arguments applied to the block, such as =[:results raw]=.
	510	- =(arguments)= are =:var= assignments, separated by commas.
	511	- =end= holds header arguments for the call's result, such as =:results verbatim=.
	512
	513	The result goes under the call. A =#+NAME:= line above the =#+CALL:= names the result.
	514
	515	** Inline calls and blocks
	516
	517	An inline source block, =src_sh{echo hi}=, runs with =C-c C-c= on it. Header arguments go in brackets: =src_sh[:var x=3]{echo $x}=. The result is written right after the block as a =results= macro:
	518
	519	#+BEGIN_SRC org
	520	Text src_sh{echo hi} {{{results(=hi=)}}} end.
	521	#+END_SRC
	522
	523	Running again replaces the macro. With =:results raw= 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.
	524
	525	An inline call, =call_double(n=6)=, has the same parts as a =#+CALL:= line: =call_name[inside](arguments)[end]=. Orgstar reads inline calls and writes their results the same way as inline blocks, but =C-c C-c= on an inline call does not run it. Use a =#+CALL:= line instead.
	526
	527	* Emacs Lisp blocks
	528
	529	On the Mac, an =emacs-lisp= or =elisp= block runs in a new =emacs -Q --batch= for each run, with lexical binding on. =-Q= means your init file and packages are not loaded, and nothing carries over between runs. Orgstar looks for Emacs at =ORGSTAR_EMACS=, then =/opt/homebrew/bin/emacs=, =/usr/local/bin/emacs=, =/Applications/Emacs.app/Contents/MacOS/Emacs=, =/run/current-system/sw/bin/emacs= and =/usr/bin/emacs=. Without Emacs, the block fails with "Emacs isn't installed, so Emacs Lisp blocks can't run."
	530
	531	On iOS, Emacs Lisp blocks run in Orgstar's own Emacs Lisp interpreter. It covers ordinary list, string, number and control forms, =princ= and =message=. 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.
	532
	533	Variables are bound with =let= around the body. =:results output= collects what the block prints with =princ=, =prin1=, =print= and =terpri=.
	534
	535	* Graphics
	536
	537	=dot= (Graphviz), =plantuml= and =mermaid= blocks draw a picture into =:file=, and the result is a link to it. =:file= is required: "/language/ code blocks need a :file header argument". The file's extension picks the output format; with none, =png= is used.
	538
	539	\| Language \| Command \|
	540	\|------------+-------------------------------------------\|
	541	\| =dot= \| =dot -T/ext/ -o file= \|
	542	\| =plantuml= \| =plantuml -p -t/ext/=, output to the file \|
	543	\| =mermaid= \| =mmdc -i input -o file= \|
	544
	545	A =plantuml= body without an =@start…= line is wrapped in =@startuml= and =@enduml=. =:cmdline= adds options to the command. The program must be installed and on the =PATH= described under Languages that run.
	546
	547	#+BEGIN_SRC org
	548	,#+begin_src dot :file graph.svg
	549	digraph { a -> b }
	550	,#+end_src
	551
	552	,#+RESULTS:
	553	[[file:graph.svg]]
	554	#+END_SRC
	555
	556	* Tangling
	557
	558	Tangling writes source blocks to the files their =:tangle= argument names (=org-babel-tangle=).
	559
	560	\| Command \| Emacs and Doom \| What it tangles \|
	561	\|-------------------------+-----------------------------+---------------------------------------------------\|
	562	\| Tangle File \| =C-c C-v t=, =C-c C-v C-t= \| Every block in the file \|
	563	\| Tangle Block \| none \| The block at the caret (Emacs: =C-u C-c C-v t=) \|
	564	\| Tangle Block's Target \| none \| Every block going to the same file as the one at the caret (Emacs: =C-u C-u C-c C-v t=) \|
	565
	566	All three are in the Org menu and the command palette. The Mac preset has no keys for them. Tangling uses the text in the editor, saved or not, and the message area reports "Tangled /N/ code blocks from /file/".
	567
	568	** =:tangle= and file names
	569
	570	\| =:tangle= \| Target \|
	571	\|-------------------+-------------------------------------------------------------------------------------------------\|
	572	\| =no= (default) \| Not tangled. \|
	573	\| =yes= \| The Org file's name with the language as extension: =el= for =emacs-lisp= and =elisp=, =bib= for =bibtex=, otherwise the language name itself (=notes.sh= for =sh=, =notes.python= for =python=). \|
	574	\| a path \| That file, relative to the Org file's folder. =~= is expanded. \|
	575	\| Lisp \| Evaluated as described under Lisp in header values, with =buffer-file-name= set to the Org file. \|
	576
	577	Blocks under a =COMMENT= heading, or a heading tagged =ARCHIVE=, are skipped. Blocks going to the same file are written in the order they appear.
	578
	579	#+BEGIN_SRC org
	580	,#+PROPERTY: header-args:python :tangle script.py
	581
	582	,* Tool
	583	:PROPERTIES:
	584	:header-args: :tangle bin/tool.sh :mkdirp yes :shebang "#!/bin/sh"
	585	:END:
	586
	587	,#+begin_src sh
	588	echo tool
	589	,#+end_src
	590	#+END_SRC
	591
	592	** Tangling arguments
	593
	594	\| Argument \| Values \| Effect \|
	595	\|-----------------+---------------------------------------------------+----------------------------------------------------------------------------------------------\|
	596	\| =:mkdirp= \| =yes= \| Create the target's folder if it is missing. \|
	597	\| =:tangle-mode= \| =(identity #o755)=, =#o755=, =o755=, =rwxr-xr-x=, =u+x,g-r= \| Set the file's mode. A symbolic mode starts from =644=. When several blocks give a mode, the first one counts. \|
	598	\| =:shebang= \| =#!…= line \| First line of the file, written once. Makes the file mode =755= unless =:tangle-mode= says otherwise. \|
	599	\| =:padline= \| =no= \| No blank line between this block and the one before it. \|
	600	\| =:comments= \| =no=, =link=, =yes=, =org=, =both=, =noweb= \| Comments around each block (below). \|
	601	\| =:noweb= \| see Noweb above \| Expand or strip =<<name>>= references. \|
	602	\| =:prologue=, =:epilogue= \| text \| A line before and after the block's code. \|
	603	\| =:var= \| as for running \| Shell scalars become assignments, Python values become assignments, Emacs Lisp values are =let=-bound. \|
	604	\| =:no-expand= \| any \| Write the body without =:var=, =:prologue= or =:epilogue=. \|
	605
	606	Block switches also apply. =-r= removes coderef labels such as =(ref:name)=, using the format from =-l= if given. =-i= keeps the block's indentation. Otherwise common indentation and surrounding blank lines are removed.
	607
	608	** Comments
	609
	610	\| =:comments= \| Written \|
	611	\|-------------+----------------------------------------------------------------------------------------------------------\|
	612	\| =no= \| The code only. \|
	613	\| =link=, =yes= \| A comment with a link back to the block before the code, and "/name/ ends here" after it. \|
	614	\| =org= \| The Org text between the heading (or the previous block) and this block, as a comment. \|
	615	\| =both= \| The Org text and the link comments. \|
	616	\| =noweb= \| Link comments, plus link comments around each expanded noweb reference. \|
	617
	618	The link is relative to the tangled file's folder. /name/ is the block's =#+NAME=, or the heading's title and the block's number under that heading, such as =Setup:2=.
	619
	620	Comments need the language's comment syntax. Orgstar knows it for: =emacs-lisp=, =elisp=, =lisp=, =scheme=, =asm= (=;;=); =python=, =ruby=, =perl=, =conf=, =toml=, =makefile=, =awk=, =tcl=, =m4=, =icon=, =desktop= and the shells except =fish= (=#=); =js=, =javascript=, =java=, =cpp=, =C++=, =objc=, =csharp=, =idl=, =pike=, =antlr=, =verilog= (=//=); =c=, =C=, =css= (=/* */=); =lua=, =sql=, =sqlite=, =vhdl= (=--=); =latex=, =tex=, =prolog= (=%%=); =ps=, =metapost= (=%=); =f90=, =dcl= (=!=); =html=, =xml=, =nxml=, =mhtml=, =sgml= (=<!-- -->=); =octave= (=##=); =pascal= (={ }=); =texinfo= (=@c=); =bibtex= (=@Comment=); =nroff= (=\"=); =bat= (=rem=). For any other language, =:comments= other than =no= stops tangling with a message.
	621
	622	** Writing the files
	623
	624	- A file whose contents would not change is left alone, so its modification time stays the same.
	625	- A read-only file is replaced.
	626	- Tangling into the Org file itself is refused: "Not allowed to tangle into the same file as self".
	627
	628	** What tangling refuses
	629
	630	Tangling stops, writes nothing and says why when:
	631
	632	- =:var= refers to a source block, which would have to run: "would run a block while tangling".
	633	- A shell block's =:var= is a table or list.
	634	- =:var= is used in a language other than shells, Python and Emacs Lisp.
	635	- A Lisp header value cannot be evaluated: "is Lisp tangling can't evaluate yet; nothing was tangled."
	636	- =:tangle-mode= is in a form it does not read.
	637	- =:comments= needs a comment syntax it does not know.
	638
	639	* On iOS
	640
	641	- Only Emacs Lisp blocks run, in Orgstar's own interpreter. Any other language fails with "/language/ blocks need the Mac to run.", and so does an Emacs Lisp block whose =:var= refers to a block in another language.
	642	- There are no sessions and no graphics.
	643	- The trust prompt works the same way, with its own =trusted.json= on the device.
	644	- There is no cancel command.
	645	- Tangling works, for files in folders Orgstar can write to.
	646	- Edit Block opens a plain text sheet without highlighting.
	647
	648	See [[file:14-ios.org][iOS]] for the rest of the iOS app.

docs/manual/guide/12-export.org added +305

		@@ -0,0 +1,305 @@
	1	#+TITLE: Export
	2	#+DESCRIPTION: Exporting Org files from Orgstar to HTML and Markdown, and to PDF, LaTeX, ODT and plain text through Emacs.
	3	#+LEDE: Orgstar exports HTML and Markdown itself, and hands PDF, LaTeX, ODT and plain text to Emacs on the Mac.
	4
	5	* Exporting a file
	6
	7	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 [[file:11-code-blocks.org][Code blocks]].
	8
	9	** On the Mac
	10
	11	\| Format \| Command \| Emacs preset \| Doom \| Needs Emacs \|
	12	\|--------------------+----------------------------------+---------------+-------------------------------+-------------\|
	13	\| HTML \| Export to HTML \| =C-c C-e h h= \| =SPC m e h h=, =C-c C-e h h= \| no \|
	14	\| HTML, then open it \| Export to HTML and Open \| =C-c C-e h o= \| =SPC m e h o=, =C-c C-e h o= \| no \|
	15	\| Markdown \| Export to Markdown \| =C-c C-e m m= \| =SPC m e m m=, =C-c C-e m m= \| no \|
	16	\| PDF \| Export to PDF with Emacs \| =C-c C-e l p= \| =SPC m e l p=, =C-c C-e l p= \| yes \|
	17	\| LaTeX \| Export to LaTeX with Emacs \| =C-c C-e l l= \| =C-c C-e l l= \| yes \|
	18	\| ODT \| Export to ODT with Emacs \| =C-c C-e o o= \| =C-c C-e o o= \| yes \|
	19	\| Plain text \| Export to Plain Text with Emacs \| =C-c C-e t u= \| =C-c C-e t u= \| yes \|
	20
	21	The keys follow Emacs's export dispatcher (=org-export-dispatch=). The =SPC m e= keys work in normal state; the =C-c C-e= keys work in every Doom state. The Mac preset has no export keys.
	22
	23	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: =.html=, =.md=, =.pdf=, =.tex=, =.odt= or =.txt=. A file already there is replaced. The message area shows "Exported to /name/".
	24
	25	** The export dialog
	26
	27	The command palette's Export… opens a dialog with:
	28
	29	- Format: HTML, Markdown, PDF (Emacs), ODT (Emacs), LaTeX (Emacs) or Plain text (Emacs).
	30	- Destination: beside the Org file by default. Choose… picks another place and name. Changing the format changes the extension.
	31	- Open after export: opens the file in its default app when the export finishes.
	32
	33	The dialog remembers the format and the Open after export setting.
	34
	35	** On iOS
	36
	37	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.
	38
	39	* HTML export
	40
	41	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, =ox-html=.
	42
	43	** Title, author and date
	44
	45	\| Keyword \| Effect \|
	46	\|------------+--------------------------------------------------------------------------\|
	47	\| =#+TITLE:= \| The page title and a top heading. Without one, the file's name is used. \|
	48	\| =#+AUTHOR:=\| Shown under the title. \|
	49	\| =#+DATE:= \| Shown under the title, after the author, as written. \|
	50
	51	Keywords in files named by =#+SETUPFILE:= count, as they do in Org.
	52
	53	** =#+OPTIONS=
	54
	55	\| Option \| Values \| Default \| Effect \|
	56	\|---------+---------------------------------------+---------+------------------------------------------------------------------------\|
	57	\| =toc= \| =t=, =nil=, a number \| =t= \| Table of contents, to the given depth. =t= goes to =H=. \|
	58	\| =num= \| =t=, =nil=, a number \| =t= \| Section numbers, to the given depth. =t= goes to =H=. \|
	59	\| =H= \| a number \| =3= \| The deepest heading level the table of contents and numbering count. \|
	60	\| =tags= \| =t=, =nil=, =not-in-toc= \| =t= \| Heading tags; =not-in-toc= leaves them out of the table of contents. \|
	61	\| =todo= \| =t=, =nil= \| =t= \| TODO keywords in headings. \|
	62	\| =pri= \| =t=, =nil= \| =nil= \| Priority cookies in headings. \|
	63	\| =^= \| =t=, =nil=, ={}= \| =t= \| =_= and =^= as subscripts and superscripts; ={}= only when braced, as in =x_{1}=. \|
	64	\| =tex= \| =t=, =nil= \| =t= \| LaTeX fragments and environments; =nil= drops them. \|
	65	\| =title= \| =t=, =nil= \| =t= \| The title heading. \|
	66	\| =author=\| =t=, =nil= \| =t= \| The author. \|
	67	\| =date= \| =t=, =nil= \| =t= \| The date. \|
	68
	69	A depth for =toc= or =num= larger than =H= is cut to =H=. Any value other than =nil= turns an option on. Other =#+OPTIONS= keys are ignored.
	70
	71	#+BEGIN_SRC org
	72	,#+TITLE: Field notes
	73	,#+AUTHOR: Sam
	74	,#+OPTIONS: toc:2 num:nil pri:t ^:{}
	75	#+END_SRC
	76
	77	** Which headings are exported
	78
	79	- A heading tagged with one of =#+EXCLUDE_TAGS= (=noexport= by default) is left out, with everything under it.
	80	- A heading whose title starts with =COMMENT= is left out.
	81	- A heading tagged =ARCHIVE= is exported as the heading alone, without its contents.
	82	- If any heading has one of =#+SELECT_TAGS= (=export= by default), only those headings, their ancestors and everything under them are exported.
	83
	84	Each heading gets an =id= for links: its =CUSTOM_ID= property, or a slug made from its title. Headings are one level down from Org's: a top-level heading is an =<h2>=, since the title is the =<h1>=.
	85
	86	** The page head
	87
	88	Each =#+HTML_HEAD:= and =#+HTML_HEAD_EXTRA:= line goes into the page's =<head>= as written, in order. Use them for stylesheets and scripts:
	89
	90	#+BEGIN_SRC org
	91	,#+HTML_HEAD: <link rel="stylesheet" href="notes.css">
	92	#+END_SRC
	93
	94	The built-in stylesheet is always included first. Other =#+HTML_…= keywords are not used.
	95
	96	** Math
	97
	98	LaTeX fragments (=$…$=, =\[…\]=, =$…$=, =$$…$$=) and LaTeX environments are left in the page for MathJax. When the page has any, Orgstar adds MathJax 3 from =cdn.jsdelivr.net=, so the page needs a network connection to show math. Entities such as =\alpha= become their characters.
	99
	100	** Includes
	101
	102	=#+INCLUDE:= inserts another file before export, as =org-export-expand-include-keyword= does. Paths are relative to the Org file.
	103
	104	\| Form \| Effect \|
	105	\|-----------------------------------------------+-----------------------------------------------------------\|
	106	\| =#+INCLUDE: "part.org"= \| The file's contents, read as Org; its includes are expanded too, up to eight levels. \|
	107	\| =#+INCLUDE: "part.org::*Heading"= \| Only the subtree with that heading. \|
	108	\| =#+INCLUDE: "part.org::#custom-id"= \| Only the subtree with that =CUSTOM_ID=. \|
	109	\| =#+INCLUDE: "code.sh" src sh= \| The file in a source block. \|
	110	\| =#+INCLUDE: "log.txt" example= \| The file in an example block. \|
	111	\| =#+INCLUDE: "page.html" export html= \| The file in an export block. \|
	112	\| =quote=, =verse=, =center=, =comment= \| The file in a block of that kind. \|
	113	\| =:lines "5-10"= \| Only those lines; either end may be left out. \|
	114	\| =:minlevel 2= \| Shift the included headings so the shallowest is at that level. \|
	115
	116	A file that cannot be read is replaced by an empty line.
	117
	118	** Macros
	119
	120	={{{name(arguments)}}}= is replaced before export (=org-macro-replace-all=).
	121
	122	\| Macro \| Replaced by \|
	123	\|------------------------------+----------------------------------------------------------------------\|
	124	\| =#+MACRO: name text= \| =text=, with =$1=, =$2=… replaced by the arguments. \|
	125	\| ={{{title}}}=, ={{{author}}}=, ={{{date}}}=, ={{{email}}}= \| That keyword's value. \|
	126	\| ={{{keyword(NAME)}}}= \| The value of =#+NAME:=. \|
	127	\| ={{{input-file}}}= \| The Org file's name. \|
	128	\| ={{{n}}}=, ={{{n(name)}}}= \| A counter, increased at each use. =n(name,-)= repeats the current value; =n(name,5)= sets it to 5. \|
	129	\| ={{{time(format)}}}= \| The current time, formatted as =format-time-string= does. \|
	130
	131	Arguments are separated by commas; write =\,= for a literal comma. Macros defined with =(eval …)=, and macros Orgstar does not know, become empty. =#+MACRO:= definitions in setup files count.
	132
	133	** Footnotes
	134
	135	Footnote references, named or inline (=[fn:: text]=), 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.
	136
	137	** Tables
	138
	139	An Org table becomes an HTML =<table>=. If it has rules, the rows before the first rule are the header (=<thead>=) and the rest the body. =#+CAPTION:= gives the table a caption. =#+TBLFM:= lines are not exported.
	140
	141	A table.el table (one drawn with =+=, =-= and =\|=) becomes a table with each cell's =colspan= and =rowspan=, 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.
	142
	143	** Images and links
	144
	145	A link to an image file without a description becomes an =<img>=. The image types are =png=, =jpg=, =jpeg=, =gif=, =svg=, =webp=, =bmp=, =tif=, =tiff= and =avif=. =#+ATTR_HTML:= before the paragraph adds attributes (=:width 300 :alt "Map"=); without an =:alt=, the file name is used.
	146
	147	An image paragraph with =#+CAPTION:= or =#+ATTR_HTML:= becomes a =<figure>=; a caption is numbered "Figure 1:", "Figure 2:" and so on.
	148
	149	Links to =.org= files point to the =.html= file of the same name. Links to headings (=[[*Heading]]=), to =CUSTOM_ID= targets and to radio targets point to the heading's or target's =id= on the page. =id:= links point to =#= and the ID. Other links are written as they are.
	150
	151	** Source blocks and their results
	152
	153	A source block is exported as =<pre><code class="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 =#+HTML_HEAD= highlight it. Noweb references are shown as written. Line-number switches are ignored.
	154
	155	The block's =:exports= argument decides what appears. Orgstar reads it from the =#+begin_src= line only.
	156
	157	\| =:exports= \| Exported \|
	158	\|------------------+-------------------------------------------\|
	159	\| =code= (default) \| The code. \|
	160	\| =results= \| The block's existing =#+RESULTS:=. \|
	161	\| =both= \| The code, then the results. \|
	162	\| =none= \| Nothing. \|
	163
	164	An inline =src_= block is exported as its code in =<code>=. Results of =#+CALL:= lines and inline blocks are not exported.
	165
	166	** Other blocks and elements
	167
	168	\| Org \| HTML \|
	169	\|----------------------------------+-------------------------------------------------\|
	170	\| =#+begin_example= \| =<pre>= \|
	171	\| =: = lines \| =<pre class="example">= \|
	172	\| =#+begin_quote= \| =<blockquote>= \|
	173	\| =#+begin_center= \| =<div class="center">= \|
	174	\| =#+begin_verse= \| =<p class="verse">=, lines and indentation kept \|
	175	\| =#+begin_export html= \| Its contents, as they are \|
	176	\| =#+begin_export= other formats \| Nothing \|
	177	\| =#+begin_comment= \| Nothing \|
	178	\| =#+begin_NAME=, any other name \| =<div class="NAME">= (a special block) \|
	179	\| =@@html:…@@= \| Its contents, as they are; other back-ends' snippets are dropped \|
	180	\| Plain, numbered and description lists \| =<ul>=, =<ol>=, =<dl>=; checkboxes as =[X]=, =[-]=, =[ ]= \|
	181	\| Timestamps \| =<time datetime="…">= \|
	182	\| Inline tasks \| =<div class="inlinetask">= with the title in bold \|
	183	\| Dynamic blocks \| Their contents \|
	184	\| =-----= \| =<hr>= \|
	185
	186	Comments, drawers, property drawers, planning lines, clock lines and keywords are not exported.
	187
	188	** Citations
	189
	190	HTML and Markdown export handle citations the same way; see Citations below.
	191
	192	* Markdown export
	193
	194	Markdown export writes GitHub-flavored Markdown:
	195
	196	- =#+TITLE:= becomes a top =#= heading. Org headings are one level down: =*= is =##=. TODO keywords and priorities stay in the heading text, and tags are shown as inline code.
	197	- Source blocks become fenced code blocks with the language; example blocks, =: = lines and table.el tables become fenced blocks without one.
	198	- Tables become pipe tables. A rule after the first row makes it the header; otherwise the header row is empty.
	199	- Checkboxes become task-list items (=- [x]=, =- [ ]=).
	200	- Footnotes become =[^1]= references with the notes at the end.
	201	- Quotes become =>= blocks. Verse lines end with two spaces.
	202	- Images become =![](path)=. Links to =.org= files written without =file:= point to the =.md= file of the same name.
	203	- =#+begin_export= blocks for =markdown=, =md= or =html=, and =@@html:…@@= snippets, are copied as they are.
	204	- Underline, subscripts and superscripts are written as HTML tags.
	205	- =:exports= is handled as in HTML export.
	206	- Citations are handled as in HTML export.
	207
	208	Markdown export is simpler than HTML export. It does not read =#+OPTIONS=, =#+EXCLUDE_TAGS= or =#+SELECT_TAGS=, does not leave out =noexport= or =COMMENT= headings, does not expand =#+INCLUDE:=, and drops macros. It writes no author or date.
	209
	210	* Exporting through Emacs
	211
	212	On the Mac, PDF, LaTeX, ODT and plain text exports are done by Emacs, with the =ox= functions Emacs's dispatcher uses:
	213
	214	\| Format \| Function \|
	215	\|------------+-----------------------------\|
	216	\| PDF \| =org-latex-export-to-pdf= \|
	217	\| LaTeX \| =org-latex-export-to-latex= \|
	218	\| ODT \| =org-odt-export-to-odt= \|
	219	\| Plain text \| =org-ascii-export-to-ascii= \|
	220
	221	Orgstar runs =emacs -Q --batch= 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 /name/".
	222
	223	What you need:
	224
	225	- Emacs, at =ORGSTAR_EMACS= or one of =/opt/homebrew/bin/emacs=, =/usr/local/bin/emacs=, =/Applications/Emacs.app/Contents/MacOS/Emacs=, =/run/current-system/sw/bin/emacs= or =/usr/bin/emacs=. Without it the export fails with "Emacs isn't installed, so this format can't be exported."
	226	- For PDF, a TeX installation that Emacs's LaTeX export can run.
	227
	228	Things to know:
	229
	230	- =-Q= 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.
	231	- File-local variables are applied only when Emacs considers them safe.
	232	- =org-export-use-babel= is off, so no source blocks run.
	233	- An export that takes more than two minutes is stopped with "Emacs took too long to export."
	234	- If Emacs fails, the message area shows the last line of its error output.
	235
	236	To use your own Emacs configuration, or formats Orgstar does not list, export from Emacs itself; see [[file:15-alongside-emacs.org][Alongside Emacs]].
	237
	238	* Citations
	239
	240	HTML and Markdown export process citations as Org's =basic= citation processor does (=oc-basic=).
	241
	242	#+BEGIN_SRC org
	243	,#+bibliography: refs.bib
	244	,#+cite_export: basic author-year
	245
	246	As shown in [cite:@smith2020], and again [cite/t:@smith2020; see @lee2019 p. 4].
	247
	248	,#+print_bibliography:
	249	#+END_SRC
	250
	251	** Bibliography files
	252
	253	Each =#+bibliography:= line names one file, relative to the Org file, optionally in quotes. A file ending in =.json= is read as CSL-JSON; anything else is read as BibTeX, with =@string= abbreviations expanded and =@comment= and =@preamble= skipped. You can have several =#+bibliography:= lines; for a key in more than one file, the first file wins.
	254
	255	** =#+cite_export:=
	256
	257	=#+cite_export: PROCESSOR [BIBLIOGRAPHY-STYLE [CITATION-STYLE]]=.
	258
	259	- With no =#+cite_export:=, or with =basic=, citations are processed.
	260	- With any other processor, such as =csl= or =biblatex=, Orgstar leaves citations as they are written.
	261	- The citation style, which may include a variant (=text/bare=), is the default for citations that do not name one.
	262
	263	** Citation styles
	264
	265	A citation is =[cite:…]= or =[cite/style:…]= or =[cite/style/variant:…]=, holding one or more =@key= references separated by =;=. Each reference may have its own prefix and suffix, and the whole citation a common prefix and suffix.
	266
	267	\| Style \| Output \|
	268	\|-------------------------------+-------------------------------------------------------------------------\|
	269	\| default (none given) \| =(Author, Year)= \|
	270	\| =author=, =a= \| =Author= \|
	271	\| =noauthor=, =na= \| =(Year)= \|
	272	\| =text=, =t= \| =Author (Year)= \|
	273	\| =note=, =ft= \| A footnote holding the =text= form \|
	274	\| =numeric=, =nb= \| =(1)=, numbered by the cited works sorted by author; three or more in a row as =1-3= \|
	275	\| =nocite=, =n= \| Nothing; the work is still listed in the bibliography \|
	276
	277	\| Variant \| Effect \|
	278	\|----------------------+--------------------------------------------\|
	279	\| =bare=, =b= \| No parentheses \|
	280	\| =caps=, =c= \| Capitalized author \|
	281	\| =bare-caps=, =bc= \| Both \|
	282
	283	Works by the same author in the same year get =a=, =b=, … after the year. A key not found in any bibliography file shows as =??= and =????=. Citations in the title are dropped.
	284
	285	For =note= citations, the blank before the citation is removed and punctuation right after it moves in front of the footnote mark, as =org-cite-adjust-note= does.
	286
	287	** The bibliography
	288
	289	=#+print_bibliography:= is replaced by an entry for every cited work, sorted by author. The bibliography style from =#+cite_export:= sets the form:
	290
	291	\| Bibliography style \| Entry \|
	292	\|------------------------+----------------------------------------------------------\|
	293	\| default \| =Author (Year). /Title/, Publisher.= \|
	294	\| =plain= \| =Surnames. Title, Publisher, Year.= \|
	295	\| =numeric= \| =[1] Author, /Title/, Publisher, Year.= \|
	296
	297	The publisher part comes from the =publisher=, =journal=, =institution= or =school= field. Without =#+print_bibliography:= no bibliography is written.
	298
	299	* What export does not do
	300
	301	- There is no subtree export, body-only export, or asynchronous export; each command exports the whole file.
	302	- =#+EXPORT_FILE_NAME:= is not used by HTML and Markdown export.
	303	- Source blocks are not run, and noweb references are not expanded.
	304	- HTML export does not color source code.
	305	- Export settings in the dialog are not per file.

docs/manual/guide/13-configuration.org added +551

		@@ -0,0 +1,551 @@
	1	#+TITLE: Configuration
	2	#+DESCRIPTION: The Settings window, the files in ~/.config/orgstar, in-file settings, importing from Emacs, themes and fonts.
	3	#+LEDE: Every setting lives in a text file you can edit, and most of them also appear in the Settings window.
	4
	5	* Where settings live
	6
	7	Orgstar keeps its settings in a configuration folder:
	8
	9	- =$XDG_CONFIG_HOME/orgstar= when =XDG_CONFIG_HOME= is set and not empty,
	10	- otherwise =~/.config/orgstar=.
	11
	12	The environment variable =ORGSTAR_CONFIG_DIR= overrides both. If a file is missing from the configuration folder but exists in =~/Library/Application Support/Orgstar= (where earlier versions kept it), Orgstar reads it from there.
	13
	14	The folder holds these files:
	15
	16	\| File \| What it holds \| Written by Orgstar \|
	17	\|----------------------+------------------------------------------------------------------+---------------------------------------\|
	18	\| =config.toml= \| Every setting of the Settings window, and the theme \| Yes, when you change a setting \|
	19	\| =keymap.toml= \| Your key bindings, on top of the preset \| Only by Import from Emacs \|
	20	\| =capture.toml= \| Capture templates \| Only by Import from Emacs \|
	21	\| =views.toml= \| Saved agenda views \| No \|
	22	\| =default-theme.toml= \| The default theme's colors, for reference \| Yes, at every launch \|
	23
	24	=config.toml= 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.
	25
	26	When you add the folder to a dotfiles repository, keep =default-theme.toml= out of it or ignore its changes: Orgstar rewrites it whenever its contents differ from the built-in theme.
	27
	28	** Opening config.toml
	29
	30	- Orgstar ▸ Edit Config File (=⌥⌘,=) opens =config.toml= as a buffer in the main window. The command palette has the same command as Edit Config File.
	31	- Settings ▸ General has three buttons for the file: Edit in Orgstar, Open with Default App, and Show in Finder.
	32
	33	Saving the buffer applies the file, the same as saving it from another editor.
	34
	35	** Problems in the files
	36
	37	If =config.toml= 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:
	38
	39	- =config.toml: unknown setting editor.foo=
	40	- =config.toml: org-log-done must be one of nil, time, note=
	41	- =config.toml: org-agenda-start-day must look like "-3d" or "+0d"=
	42	- =config.toml: theme.light.background must be a color such as "#1f2328"=
	43
	44	A file that isn't valid TOML is reported with its parse error, and none of it applies. =keymap.toml=, =capture.toml= and =views.toml= report their problems the same way when they are read.
	45
	46	* The Settings window
	47
	48	Open it with Orgstar ▸ Settings (=⌘,=). It has five panes. Each control writes the =config.toml= key named in the tables below; the config.toml reference below gives the type and the Emacs variable.
	49
	50	** General
	51
	52	\| Control \| Choices \| Default \| Key \|
	53	\|--------------------------------------------+------------------------------------------------------------------------------+---------------------------------+------------------\|
	54	\| config.toml: Edit in Orgstar \| Opens the file in the main window \| \| \|
	55	\| config.toml: Open with Default App \| Opens the file in the app macOS uses for =.toml= \| \| \|
	56	\| config.toml: Show in Finder \| Selects the file in Finder \| \| \|
	57	\| Emacs: Import from Emacs… \| Opens the import sheet; see Import from Emacs below\| \| \|
	58	\| Save files \| Automatically, when typing stops; Only with File ▸ Save (=⌘S=) \| Automatically \| =save= \|
	59	\| Keys \| Emacs; Mac; Doom (Vim keys) \| Emacs \| =keymap= \|
	60	\| Show hidden files and folders \| On or off \| On \| =show-hidden-files= \|
	61	\| Option as Meta \| Left Option; Right Option; Both; Neither \| Left Option \| =option-as-meta= \|
	62
	63	Automatic saving writes a file one second after you stop typing. The keymap presets and =keymap.toml= are covered in [[file:03-keys.org][Keys and commands]].
	64
	65	** Editing
	66
	67	\| Control \| Choices or range \| Default \| Key \|
	68	\|------------------------------------------------------------+--------------------------------------------------------+---------------------+--------------------------------------\|
	69	\| Tags \| Aligned to end at column 77; One space after the title \| Aligned (=-77=) \| =org-tags-column= \|
	70	\| M-RET adds the new heading after the subtree \| On or off \| On \| =org-insert-heading-respect-content= \|
	71	\| M-RET splits the line at the caret \| On or off \| Off \| =org-M-RET-may-split-line= \|
	72	\| Lists can use letters (a. b. c.) \| On or off \| On \| =org-list-allow-alphabetical= \|
	73	\| M-q fills to column N \| 40 to 200 \| 80 \| =fill-column= \|
	74	\| Emacs hides emphasis markers (org-hide-emphasis-markers) \| On or off \| On \| =org-hide-emphasis-markers= \|
	75	\| Emacs shows entities as characters (org-pretty-entities) \| On or off \| On \| =org-pretty-entities= \|
	76	\| Default TODO keywords \| Text in =#+TODO= syntax, one sequence per line \| See below \| =org-todo-keywords= \|
	77
	78	The two "Emacs hides" and "Emacs shows" switches describe your Emacs, not Orgstar's display. Tag alignment, table alignment and =M-q= 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.
	79
	80	The Tags picker offers two values. =config.toml= accepts any integer; with a value other than =-77= or =0= the picker shows no selection.
	81
	82	Default TODO keywords apply to files without a =#+TODO= line. Orgstar reads them at launch, so a change takes effect after you quit and reopen Orgstar.
	83
	84	** Appearance
	85
	86	\| Control \| Range \| Default \| Key \|
	87	\|---------------------------------+-----------------------------------------------+--------------------+---------------------\|
	88	\| Font \| System monospaced, or any installed monospaced family \| System monospaced \| =font= \|
	89	\| Size \| 8 to 36 pt \| 13 pt \| =font-size= \|
	90	\| Line spacing \| 0 to 16 pt \| 2 pt \| =line-spacing= \|
	91	\| Headings grow by N pt a level \| 0 to 8 pt \| 1 pt \| =heading-size-step= \|
	92	\| Colors: Edit in config.toml \| Opens =config.toml= \| \| \|
	93	\| Colors: Show Default Theme \| Opens =default-theme.toml= \| \| \|
	94
	95	See Themes and Fonts below.
	96
	97	** Agenda
	98
	99	\| Control \| Range \| Default \| Key \|
	100	\|-------------------------------------+------------------------+--------------+-----------------------------\|
	101	\| Agenda shows N days \| 1 to 31 \| 10 \| =org-agenda-span= \|
	102	\| Agenda starts N days before today \| 0 to 14 days before \| 3 days \| =org-agenda-start-day= \|
	103	\| Include files in subfolders \| On or off \| Off \| =agenda-include-subfolders= \|
	104	\| Notify before timed agenda entries \| On or off \| On \| =reminders= \|
	105	\| N minutes before \| 0 to 120 \| 12 \| =appt-message-warning-time= \|
	106
	107	An entry's =APPT_WARNTIME= property overrides the lead time. The agenda is covered in [[file:07-agenda.org][The agenda]].
	108
	109	** Capture
	110
	111	\| Control \| Default \| Key \|
	112	\|----------------------------------------+---------+-------------------------\|
	113	\| ⌃⌥Space opens Capture from any app \| On \| =global-capture-hotkey= \|
	114
	115	The footer shows the path of =capture.toml=. Templates are covered in [[file:08-capture.org][Capture]].
	116
	117	** Settings only in config.toml
	118
	119	These settings have no control in the Settings window. Some are in the View menu.
	120
	121	\| Key \| Also in \|
	122	\|----------------------------------+----------------------------\|
	123	\| =org-log-done= \| \|
	124	\| =org-log-reschedule= \| \|
	125	\| =org-log-redeadline= \| \|
	126	\| =org-log-into-drawer= \| \|
	127	\| =org-startup-indented= \| \|
	128	\| =org-hide-leading-stars= \| \|
	129	\| =org-startup-align-all-tables= \| \|
	130	\| =org-startup-truncated= \| \|
	131	\| =org-startup-with-inline-images= \| \|
	132	\| =org-cycle-hide-drawer-startup= \| \|
	133	\| =org-cycle-hide-block-startup= \| \|
	134	\| =org-use-speed-commands= \| \|
	135	\| =spell-check= \| \|
	136	\| =electric-pair-mode= \| \|
	137	\| =display-line-numbers-type= \| View ▸ Show Line Numbers (=⇧⌘L=) \|
	138	\| =tab-bar= \| View ▸ Show Tab Bar \|
	139	\| =show-markup= \| View ▸ Show Markup (=⇧⌘M=) \|
	140	\| =ignored-folders= \| \|
	141	\| =[org-agenda-prefix-format]= \| \|
	142	\| =theme-file= \| \|
	143
	144	* config.toml reference
	145
	146	Settings that mirror an Emacs variable sit at the top of the file under that variable's name. The agenda prefix formats are in =[org-agenda-prefix-format]=, type and theme in =[theme]=, and the settings Emacs has no variable for in =[orgstar]=.
	147
	148	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.
	149
	150	** Top level
	151
	152	\| Key \| Type \| Default \| Effect \|
	153	\|--------------------------------------+---------+---------+----------------------------------------------------------------------------------------------------------------\|
	154	\| =fill-column= \| integer \| =80= \| The column =M-q= fills to. Mirrors =fill-column=. \|
	155	\| =org-tags-column= \| integer \| =-77= \| Negative: tags end at that column. =0=: one space between title and tags. Mirrors =org-tags-column=. \|
	156	\| =org-insert-heading-respect-content= \| boolean \| =true= \| =M-RET= adds the new heading after the current subtree. Mirrors =org-insert-heading-respect-content=. \|
	157	\| =org-M-RET-may-split-line= \| boolean \| =false= \| =M-RET= in the middle of a line splits it at the caret. Mirrors the =default= entry of =org-M-RET-may-split-line=. \|
	158	\| =org-list-allow-alphabetical= \| boolean \| =true= \| =a.=, =b)=, =A.= are list bullets. Mirrors =org-list-allow-alphabetical=. \|
	159	\| =org-hide-emphasis-markers= \| boolean \| =true= \| Your Emacs hides =bold= and ~=code=~ markers; Orgstar hides them when markup is hidden and measures text without them. Mirrors =org-hide-emphasis-markers=. \|
	160	\| =org-pretty-entities= \| boolean \| =true= \| Your Emacs shows =\alpha= as α and lowers =x_{1}=; Orgstar does the same when markup is hidden. Mirrors =org-pretty-entities=. \|
	161	\| =org-todo-keywords= \| string \| see below \| Keywords for files without =#+TODO=, in =#+TODO= syntax; separate sequences with =\n=. Letters in parentheses turn on fast selection. Read at launch. Mirrors =org-todo-keywords=. \|
	162	\| =org-log-done= \| string \| ="nil"= \| =nil=, =time= (a =CLOSED= timestamp) or =note= (=CLOSED= and a note). Mirrors =org-log-done=. \|
	163	\| =org-log-reschedule= \| string \| ="nil"= \| =nil=, =time= or =note=: log changing or removing a =SCHEDULED= date. Mirrors =org-log-reschedule=. \|
	164	\| =org-log-redeadline= \| string \| ="nil"= \| =nil=, =time= or =note=: log changing or removing a =DEADLINE=. Mirrors =org-log-redeadline=. \|
	165	\| =org-log-into-drawer= \| string \| =""= \| The drawer state notes go in. ="LOGBOOK"= is Emacs's =t=; =""= puts them under the heading. Mirrors =org-log-into-drawer=. \|
	166	\| =org-startup-indented= \| boolean \| =true= \| Indent bodies under their headings, as =org-indent-mode=. =#+STARTUP: indent= / =noindent= override it. Mirrors =org-startup-indented=. \|
	167	\| =org-hide-leading-stars= \| boolean \| =false= \| Show only a heading's last star, without indentation. =#+STARTUP: hidestars= / =showstars= override it. Mirrors =org-hide-leading-stars=. \|
	168	\| =org-startup-align-all-tables= \| boolean \| =false= \| Align every table when a file opens. =#+STARTUP: align= / =noalign= override it. Mirrors =org-startup-align-all-tables=. \|
	169	\| =org-startup-truncated= \| boolean \| =false= \| Long lines run off the right edge instead of wrapping. Mirrors =org-startup-truncated=. \|
	170	\| =spell-check= \| boolean \| =false= \| Check spelling while typing, outside code, links, dates, tags and keywords. \|
	171	\| =electric-pair-mode= \| boolean \| =true= \| Type brackets, =<>= and quotes in pairs. Mirrors =electric-pair-mode=. \|
	172	\| =org-startup-with-inline-images= \| boolean \| =false= \| Show image links as images when a file opens. =#+STARTUP: inlineimages= / =noinlineimages= override it. Mirrors =org-startup-with-inline-images=. \|
	173	\| =org-use-speed-commands= \| boolean \| =false= \| Single keys at the start of a heading line run commands (=n=, =p=, =t=, =c=, …). Mirrors =org-use-speed-commands=. \|
	174	\| =org-cycle-hide-drawer-startup= \| boolean \| =true= \| Fold drawers when a file opens. =#+STARTUP: hidedrawers= / =nohidedrawers= override it. Mirrors =org-cycle-hide-drawer-startup=. \|
	175	\| =org-cycle-hide-block-startup= \| boolean \| =false= \| Fold blocks when a file opens. =#+STARTUP: hideblocks= / =nohideblocks= override it. Mirrors =org-cycle-hide-block-startup=. \|
	176	\| =display-line-numbers-type= \| boolean \| =true= \| Line numbers in the editor's gutter. Orgstar numbers lines absolutely; there is no relative or visual mode. \|
	177	\| =org-agenda-span= \| integer \| =10= \| Days the agenda shows. Mirrors =org-agenda-span=. \|
	178	\| =org-agenda-start-day= \| string \| ="-3d"= \| The agenda's first day relative to today, as ="-3d"= or ="+0d"=. Only day offsets are accepted. Mirrors =org-agenda-start-day=. \|
	179	\| =appt-message-warning-time= \| integer \| =12= \| Minutes of warning before timed entries. An entry's =APPT_WARNTIME= property overrides it. Mirrors =appt-message-warning-time=. \|
	180
	181	The default =org-todo-keywords= is the first sequence of Doom Emacs's default:
	182
	183	#+BEGIN_SRC toml
	184	org-todo-keywords = "TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) \| DONE(d) KILL(k)"
	185	#+END_SRC
	186
	187	The startup settings (=org-startup-=, =org-hide-leading-stars=, =org-cycle-hide--startup=) apply when a file opens. Files already open keep their state until you open them again.
	188
	189	** [org-agenda-prefix-format]
	190
	191	\| Key \| Type \| Default \| Effect \|
	192	\|----------+--------+--------------------------+-------------------------------------\|
	193	\| =agenda= \| string \| =" %i %-12:c%?-12t% s"= \| Prefix of lines in the day view \|
	194	\| =todo= \| string \| =" %i %-12:c"= \| Prefix of lines in the TODO list \|
	195	\| =tags= \| string \| =" %i %-12:c"= \| Prefix of tag and property matches \|
	196
	197	These mirror the entries of =org-agenda-prefix-format=. In the format, =%c= is the category, =%t= the time, =%s= the scheduled or deadline note, =%e= the effort, =%l= the level, =%b= the outline path, and a number such as =%-12= pads. See [[file:07-agenda.org][The agenda]].
	198
	199	** [theme]
	200
	201	\| Key \| Type \| Default \| Effect \|
	202	\|---------------------+---------+---------+----------------------------------------------------------------------------------------------\|
	203	\| =font= \| string \| =""= \| A font family. =""= uses the system's monospaced font. \|
	204	\| =font-size= \| integer \| =13= \| Points. \|
	205	\| =line-spacing= \| integer \| =2= \| Points between lines. \|
	206	\| =heading-size-step= \| integer \| =1= \| Points a heading is larger than the level below. Level 4 and deeper are body size. \|
	207	\| =theme-file= \| string \| =""= \| A theme in its own file in the configuration folder, applied under the colors in =config.toml=. \|
	208
	209	Any other key in =[theme]= is a color; see Themes below.
	210
	211	** [orgstar]
	212
	213	\| Key \| Type \| Default \| Effect \|
	214	\|-----------------------------+---------+---------------+-----------------------------------------------------------------------------------------\|
	215	\| =save= \| string \| ="automatic"= \| =automatic= (one second after typing stops) or =explicit= (only with =⌘S=). \|
	216	\| =keymap= \| string \| ="emacs"= \| =emacs=, =mac= or =doom=. Your own bindings go in =keymap.toml=. \|
	217	\| =option-as-meta= \| string \| ="left"= \| Which Option key is Meta: =left=, =right=, =both= or =none=. \|
	218	\| =tab-bar= \| boolean \| =false= \| A tab for each open buffer above the editor. \|
	219	\| =show-markup= \| boolean \| =false= \| Show link brackets and emphasis markers. \|
	220	\| =show-hidden-files= \| boolean \| =true= \| List dotfiles and dot folders in your folders. \|
	221	\| =ignored-folders= \| string \| see below \| Folder names never listed or searched, separated by spaces. \|
	222	\| =agenda-include-subfolders= \| boolean \| =false= \| The agenda reads org files in subfolders too. \|
	223	\| =reminders= \| boolean \| =true= \| Notify before timed entries. \|
	224	\| =global-capture-hotkey= \| boolean \| =true= \| =⌃⌥Space= opens Capture from any app. \|
	225
	226	The default =ignored-folders= is:
	227
	228	#+BEGIN_SRC toml
	229	ignored-folders = ".Spotlight-V100 .Trash .build .bzr .cache .fseventsd .git .gradle .hg .jj .mypy_cache .next .pytest_cache .stfolder .stversions .svn .terraform .tox .venv node_modules"
	230	#+END_SRC
	231
	232	** An example
	233
	234	#+BEGIN_SRC toml
	235	fill-column = 72
	236	org-tags-column = 0
	237	org-todo-keywords = "TODO(t) NEXT(n) WAIT(w@/!) \| DONE(d!) CANCELED(c@)"
	238	org-log-done = "time"
	239	org-log-into-drawer = "LOGBOOK"
	240	org-startup-truncated = true
	241	org-agenda-span = 7
	242	org-agenda-start-day = "+0d"
	243
	244	[theme]
	245	font = "JetBrains Mono"
	246	font-size = 14
	247	link = "#0a7ea4"
	248
	249	[theme.todo]
	250	WAIT = "#bf8700"
	251
	252	[orgstar]
	253	keymap = "doom"
	254	save = "explicit"
	255	#+END_SRC
	256
	257	** Names from earlier versions
	258
	259	Earlier versions used keys such as =editor.fill-column= and =agenda.span=. Orgstar still reads them. At launch, a file that uses any of them is rewritten with the current names and every setting at its current value; comments you added are not kept. A file that lacks a whole section (such as =[theme]=) gets that section added at the end.
	260
	261	* keymap.toml and capture.toml
	262
	263	=keymap.toml= holds =[[bind]]= tables with =keys=, =command=, and optionally =mode= and =when=. They layer over the preset chosen in Keys. Orgstar reloads the file when it changes. See [[file:03-keys.org][Keys and commands]].
	264
	265	#+BEGIN_SRC toml
	266	[[bind]]
	267	keys = "C-c a"
	268	command = "app.agenda"
	269	#+END_SRC
	270
	271	=capture.toml= holds =[[template]]= tables. Without the file, Orgstar uses two templates: =t= (Personal todo, under =Inbox= in =todo.org=) and =n= (Personal notes, under =Inbox= in =notes.org=). See [[file:08-capture.org][Capture]].
	272
	273	=views.toml= holds =[[view]]= tables for the agenda; see [[file:07-agenda.org][The agenda]].
	274
	275	* In-file settings
	276
	277	Keyword lines in a file set options for that file, as in Emacs. Orgstar reads them outside blocks; for =#+STARTUP= only lines at the element level count, so a =#+STARTUP= line inside a paragraph or a block doesn't change folding.
	278
	279	** Keywords Orgstar reads
	280
	281	\| Keyword \| Effect \|
	282	\|-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------\|
	283	\| =#+TODO=, =#+SEQ_TODO= \| A TODO sequence: active keywords, a bar, then done keywords. Without the bar, the last word is the done state. =NAME(k)= gives a fast-selection key, =NAME(k!/@)= logging on entering and leaving. Any TODO line replaces the default keywords. \|
	284	\| =#+TYP_TODO= \| A type sequence. As in Org, type sequences come first, then =#+TODO=, then =#+SEQ_TODO=. \|
	285	\| =#+PRIORITIES= \| Three values: highest, lowest, default, as =A C B= or =1 5 3=. The default is =A C B=. \|
	286	\| =#+STARTUP= \| Startup options; see below. \|
	287	\| =#+TAGS= \| Tags for fast tag selection with =C-c C-q=, with keys as =work(w)=, groups in ={ }= and tag groups in =[ ]=. Without =#+TAGS=, =C-c C-q= offers the tags used in the file. \|
	288	\| =#+FILETAGS= \| Tags every heading in the file inherits, as =:work:project:=. \|
	289	\| =#+PROPERTY= \| A file-wide property, as =#+PROPERTY: header-args :results output=. =NAME+= appends to the value. \|
	290	\| =#+CATEGORY= \| The file's category in the agenda. Without it the category is the file name. \|
	291	\| =#+ARCHIVE= \| Where =C-c C-x C-a= archives to. The default is =%s_archive::=. \|
	292	\| =#+COLUMNS= \| The default column view format. \|
	293	\| =#+LINK= \| A link abbreviation, as =#+LINK: gh https://github.com/%s=. \|
	294	\| =#+CONSTANTS= \| Constants for table formulas, as =#+CONSTANTS: c=299792458 pi=3.14=. \|
	295	\| =#+SETUPFILE= \| A file whose keyword lines count as this file's; see below. \|
	296	\| =#+TITLE=, =#+AUTHOR=, =#+DESCRIPTION= \| Used by export, Quick Look and Spotlight. \|
	297	\| =#+OPTIONS=, =#+MACRO=, =#+INCLUDE=, =#+EXCLUDE_TAGS=, =#+SELECT_TAGS= \| Export settings; see [[file:12-export.org][Export]]. \|
	298
	299	#+BEGIN_SRC org
	300	,#+TODO: TODO(t) NEXT(n) WAIT(w@/!) \| DONE(d!) CANCELED(c@)
	301	,#+PRIORITIES: A E C
	302	,#+STARTUP: content logdrawer
	303	,#+FILETAGS: :work:
	304	,#+CATEGORY: acme
	305	#+END_SRC
	306
	307	After you change a keyword line, press =C-c C-c= on it to read the file's settings again, as =org-mode-restart= does in Emacs. Changes to =#+TODO=, =#+SEQ_TODO=, =#+TYP_TODO= and =#+PRIORITIES= apply as you type.
	308
	309	** #+STARTUP options
	310
	311	\| Option \| Effect \|
	312	\|-----------------------------------------------+--------------------------------------------------------------------------\|
	313	\| =overview=, =fold= \| Only top-level headings show when the file opens. \|
	314	\| =content= \| All headings show, no bodies. \|
	315	\| =showall=, =nofold= \| Everything shows. \|
	316	\| =show2levels= … =show5levels= (any =showNlevels=) \| Headings down to level N show. \|
	317	\| =showeverything= \| Everything shows, including drawers and blocks; =VISIBILITY= properties are ignored. \|
	318	\| =hidedrawers=, =nohidedrawers= \| Fold or don't fold drawers at startup. \|
	319	\| =hideblocks=, =nohideblocks= \| Fold or don't fold blocks at startup. \|
	320	\| =indent=, =noindent= \| Virtual indentation on or off. \|
	321	\| =hidestars=, =showstars= \| Hide leading stars or show them. \|
	322	\| =align=, =noalign= \| Align every table when the file opens, or don't. \|
	323	\| =inlineimages=, =noinlineimages= \| Show image links as images, or don't. \|
	324	\| =shrink= \| Shrink table columns that have a width cookie. \|
	325	\| =logdone=, =lognotedone=, =nologdone= \| Record a time, a note, or nothing when an entry becomes done. \|
	326	\| =logrepeat=, =lognoterepeat=, =nologrepeat= \| The same, when a repeating entry is completed. \|
	327	\| =logreschedule=, =lognotereschedule=, =nologreschedule= \| The same, when a scheduled date changes. \|
	328	\| =logredeadline=, =lognoteredeadline=, =nologredeadline= \| The same, when a deadline changes. \|
	329	\| =logdrawer=, =nologdrawer= \| Notes go in =LOGBOOK=, or under the heading. \|
	330
	331	After the startup visibility, Orgstar applies each heading's =VISIBILITY= property and folds subtrees tagged =ARCHIVE=, unless =showeverything= is set.
	332
	333	Completion offers every option of =org-startup-options=. Options not in the table above, such as =odd=, =entitiespretty=, =latexpreview=, =constSI= and the footnote options, are accepted and ignored.
	334
	335	** Setup files
	336
	337	=#+SETUPFILE: path= reads the keyword lines of another file and treats them as if they were in this file, before its own lines. This follows =org--collect-keywords-1= in Org:
	338
	339	- A relative path is relative to the folder of the file that names it. =~= expands to your home folder. Quotes around the path are removed.
	340	- A setup file can name further setup files; each is read once, and a file never reads itself.
	341	- URLs (anything starting with =scheme://=) aren't fetched.
	342	- A setup file that can't be read, or isn't UTF-8, is skipped without a message.
	343
	344	Keywords from setup files count for TODO keywords, priorities, =#+STARTUP=, =#+TAGS=, =#+FILETAGS=, =#+PROPERTY=, =#+CATEGORY=, =#+ARCHIVE=, =#+COLUMNS=, =#+LINK=, =#+CONSTANTS= and export. Orgstar reads setup files when a file opens, when you press =C-c C-c= on a keyword line, and when the file changes on disk. If you edit only the setup file, press =C-c C-c= on a keyword line of each open file that uses it.
	345
	346	* Import from Emacs
	347
	348	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.
	349
	350	** Running it
	351
	352	1. Open Settings ▸ General and click Import from Emacs…, or run Import from Emacs… from the command palette (=⇧⌘P=).
	353	2. Orgstar looks for a configuration in these places, in order, and reads the first it finds: =$DOOMDIR=, =~/.config/doom=, =~/.doom.d=, =~/.config/emacs=, =~/.emacs.d=, =~/.emacs=. A folder counts when it holds =init.el=, =config.el= or =custom.el=. Doom's own installation folder (one with =lisp/doom.el=) is skipped.
	354	3. To read another configuration, click Choose… and pick a file or a folder. For a folder, Orgstar reads =init.el=, =config.el= and =custom.el= in it.
	355	4. The sheet lists what it found under Settings, Folders, Capture templates and Key bindings, each with the line it came from (=config.el:27=, or =Doom default=). Everything is selected; clear what you don't want.
	356	5. Click Import. The sheet then summarizes what was imported and any problems.
	357
	358	What Import does with each kind of item:
	359
	360	- Settings are written to =config.toml=.
	361	- Folders are added to the sidebar if they exist and aren't there already.
	362	- Capture templates are appended to =capture.toml=, except those whose key is already in the file.
	363	- Key bindings are appended to =keymap.toml=. Running the import again appends them again.
	364
	365	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.
	366
	367	A literate configuration (=config.org=) isn't read. Point Choose… at the =config.el= it tangles to.
	368
	369	** Doom Emacs
	370
	371	A configuration counts as Doom when it contains =(doom!=, =(map! = or =(after! =. Orgstar then also reads Doom's own org defaults, from the Doom installation in =$EMACSDIR=, =~/.config/emacs= or =~/.emacs.d=: =modules/lang/org/config.el= and =lisp/doom-emacs.el=. Your configuration overrides them. Doom defaults Orgstar has no use for are counted in the footer rather than listed.
	372
	373	A Doom configuration, or any configuration that enables =evil=, adds =keymap = "doom"=.
	374
	375	** What it reads
	376
	377	Orgstar reads the configuration as Lisp data; it never runs it. It looks at these forms:
	378
	379	\| Form \| What Orgstar takes \|
	380	\|----------------------------------------------------------------------+---------------------------------------------------------------------------------\|
	381	\| =setq=, =setq-default=, =setq!=, =setopt=, =csetq= \| Each variable and value \|
	382	\| =defvar=, =defcustom= \| The value, below every other assignment \|
	383	\| =custom-set-variables= \| Each quoted =(variable value)= \|
	384	\| =after!=, =with-eval-after-load=, =eval-after-load= \| The forms inside, ranked above plain assignments \|
	385	\| =use-package=, =use-package!= \| Forms in =:config= and =:init=, and pairs in =:custom= \|
	386	\| =progn=, =when=, =unless=, =if=, =let=, =let*=, =with-no-warnings= \| The forms inside. Conditions aren't evaluated, so every branch is read. \|
	387	\| =map!= (Doom) \| Bindings, with =:leader= (=SPC=), =:localleader= (=SPC m=), =:prefix=, and state keywords such as =:n=, =:i=, =:v=, =:nv= \|
	388	\| =define-key=, =keymap-set=, =global-set-key=, =keymap-global-set= \| Bindings \|
	389	\| =evil-define-key=, =evil-define-key*= \| Bindings in the =normal=, =insert= or =visual= state \|
	390
	391	When a variable is set more than once, the last assignment wins, with assignments inside =after!= and similar forms winning over plain ones, and those over Doom's defaults.
	392
	393	Orgstar works out a value when it is a literal, a quoted or backquoted form (with =,= and =,@=), a variable set earlier in the configuration, or a call to =list=, =concat=, =expand-file-name=, =file-name-concat= or =file-name-as-directory= 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.
	394
	395	Only variables whose names start with =org-=, =appt-=, =display-line-numbers=, =fill-column=, =evil-=, =doom-font=, =doom-variable-pitch-font=, =doom-theme= or =calendar-week-start-day= are considered.
	396
	397	** How variables map
	398
	399	\| Emacs variable \| Becomes \|
	400	\|--------------------------------------------------------------------+-----------------------------------------------------------------------------------------------\|
	401	\| =fill-column=, =org-tags-column=, =appt-message-warning-time= \| The same key, when the value is a number \|
	402	\| =org-insert-heading-respect-content=, =org-list-allow-alphabetical=, =org-hide-emphasis-markers=, =org-pretty-entities=, =org-cycle-hide-drawer-startup=, =org-cycle-hide-block-startup=, =org-use-speed-commands=, =org-startup-with-inline-images=, =org-startup-indented=, =org-hide-leading-stars=, =org-startup-align-all-tables=, =org-startup-truncated= \| The same key: =nil= or an empty list is =false=, anything else =true= \|
	403	\| =org-hide-drawer-startup=, =org-hide-block-startup= \| =org-cycle-hide-drawer-startup=, =org-cycle-hide-block-startup= \|
	404	\| =org-M-RET-may-split-line= \| =org-M-RET-may-split-line=, from the =default= entry of an alist; other per-context entries aren't supported \|
	405	\| =org-agenda-prefix-format= \| =[org-agenda-prefix-format]=: a string sets all three views; an alist sets =agenda=, =todo= and =tags= \|
	406	\| =org-log-done=, =org-log-reschedule=, =org-log-redeadline= \| The same key: =nil=, =time= (also =t=) or =note= \|
	407	\| =org-log-into-drawer= \| A string as given; =t= becomes ="LOGBOOK"=; =nil= becomes =""= \|
	408	\| =display-line-numbers-type= \| =true= unless =nil=; =relative= and =visual= become absolute numbers \|
	409	\| =org-agenda-span= \| A number, or =day= (1), =week= (7), =fortnight= (14), =month= (30), =year= (365) \|
	410	\| =org-agenda-start-day= \| A day offset such as ="-3d"=; =nil= becomes ="+0d"=. Other forms aren't supported. \|
	411	\| =org-todo-keywords= \| =org-todo-keywords=, one line per sequence. Keywords with spaces are left out; =type= sequences are read as sequences. \|
	412	\| =org-directory= \| A folder to add \|
	413	\| =org-agenda-files= \| A folder for each entry; for a =.org= file, its folder \|
	414	\| =org-capture-templates= \| Templates for =capture.toml=; see below \|
	415	\| =doom-font= \| =font= and =font-size=, from =(font-spec :family … :size …)= or ="Family-14"= \|
	416	\| =doom-variable-pitch-font= \| Not imported: Orgstar uses one font \|
	417	\| =doom-theme= \| Not imported: set colors under =[theme]= \|
	418	\| =evil-mode= in use, or Doom \| =keymap = "doom"= \|
	419
	420	Any other =org-= or =appt-= variable is listed as having no equivalent.
	421
	422	Capture templates are imported when their type is =entry=, =item=, =checkitem=, =plain= or =table-line=, their template is a string, and their target is =file=, =file+headline=, =file+olp=, =file+olp+datetree=, =file+datetree=, =file+weektree=, =id= or =clock=. The properties =:prepend=, =:immediate-finish=, =:jump-to-captured=, =:clock-in=, =:clock-keep=, =:clock-resume=, =:empty-lines=, =:empty-lines-before=, =:empty-lines-after=, =:tree-type= (=day=, =week=, =month=) and =:table-line-pos= carry over; others are listed as left out. Template groups (a key and a name only) are skipped.
	423
	424	Key bindings are imported when the command is one Orgstar has a counterpart for, such as =org-todo=, =org-schedule=, =org-refile=, =org-capture= or =save-buffer=. Keys must be a string or =(kbd "…")=. In a Doom configuration, bindings without a state go to the =normal= state.
	425
	426	** Limits of the Lisp reader
	427
	428	- Comments (=;=) are skipped. Strings understand =\n=, =\t=, =\"= and line continuations; other escapes give the character itself.
	429	- =#'= reads as =function=. Other =#= syntax is read as a symbol, so forms using it aren't understood.
	430	- 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.
	431	- Macros other than those in the table above are not expanded, and functions are not called. Settings made by code you wrote (a =defun= that calls =setq=, a hook) aren't found.
	432
	433	* Themes
	434
	435	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 =config.toml=, or by keeping a theme in its own file.
	436
	437	Colors are strings in the form ="#rrggbb"= or ="#rrggbbaa"=. They go in these tables:
	438
	439	\| Table \| Effect \|
	440	\|----------------+------------------------------------------------------------------------\|
	441	\| =[theme]= \| Sets a color for both light and dark appearance \|
	442	\| =[theme.light]= \| Sets a color for light appearance only \|
	443	\| =[theme.dark]= \| Sets a color for dark appearance only \|
	444	\| =[theme.todo]= \| Colors TODO keywords by name, in both appearances, as =org-todo-keyword-faces= \|
	445
	446	#+BEGIN_SRC toml
	447	[theme]
	448	heading-1 = "#005cc5"
	449
	450	[theme.dark]
	451	background = "#1e1e1e"
	452	foreground = "#d4d4d4"
	453
	454	[theme.todo]
	455	WAIT = "#bf8700"
	456	PROJ = "#8250df"
	457	#+END_SRC
	458
	459	A keyword without its own color uses =todo= or =done=.
	460
	461	=default-theme.toml= 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 =config.toml=; edits to =default-theme.toml= itself are overwritten at the next launch.
	462
	463	** Theme files
	464
	465	To keep a theme in its own file, put it in the configuration folder with the same tables (=[theme]=, =[theme.light]=, =[theme.dark]=, =[theme.todo]=) and name it in =config.toml=:
	466
	467	#+BEGIN_SRC toml
	468	[theme]
	469	theme-file = "solarized.toml"
	470	#+END_SRC
	471
	472	The colors stack in this order, each over the one before: the default theme, the theme file, then the colors in =config.toml=. Orgstar reloads the theme file when it changes. Only colors are read from a theme file; =font= and the other type keys in its =[theme]= table are ignored.
	473
	474	** Color keys
	475
	476	\| Key \| Colors \|
	477	\|-------------------------+--------------------------------------------------------------\|
	478	\| =background= \| the editor's background \|
	479	\| =foreground= \| body text \|
	480	\| =cursor= \| the caret \|
	481	\| =selection= \| selected text's background \|
	482	\| =heading-1= … =heading-7= \| headings of that level \|
	483	\| =heading-8= \| level 8 and deeper headings \|
	484	\| =todo= \| TODO keywords not yet done \|
	485	\| =done= \| DONE keywords \|
	486	\| =priority= \| =[#A]= cookies \|
	487	\| =tags= \| =:tags:= \|
	488	\| =link= \| links \|
	489	\| =timestamp= \| timestamps \|
	490	\| =code= \| =~code~= and inline source \|
	491	\| =verbatim= \| ~=verbatim=~ \|
	492	\| =inline-background= \| behind =~code~= and ~=verbatim=~ \|
	493	\| =markup= \| link brackets and emphasis markers \|
	494	\| =comment= \| comments \|
	495	\| =keyword= \| =#+KEYWORD= lines \|
	496	\| =metadata= \| planning lines, drawers, properties and clocks \|
	497	\| =special= \| footnotes, statistics cookies, targets, macros and LaTeX \|
	498	\| =block-background= \| the band behind blocks \|
	499	\| =block-delimiter= \| =#+begin_= and =#+end_= lines \|
	500	\| =table= \| tables \|
	501	\| =line-number= \| line numbers \|
	502	\| =line-number-current= \| the caret's line number \|
	503	\| =syntax-keyword= \| code: keywords \|
	504	\| =syntax-string= \| code: strings \|
	505	\| =syntax-comment= \| code: comments \|
	506	\| =syntax-function= \| code: functions \|
	507	\| =syntax-type= \| code: types and modules \|
	508	\| =syntax-number= \| code: numbers, constants and escapes \|
	509	\| =syntax-property= \| code: properties, attributes and tags \|
	510	\| =syntax-label= \| code: labels \|
	511	\| =sidebar-background= \| the folder sidebar and the outline \|
	512	\| =sidebar-foreground= \| file and heading names there \|
	513	\| =sidebar-header= \| folder names there \|
	514	\| =modeline-background= \| the modeline and message line \|
	515	\| =modeline-foreground= \| modeline text \|
	516	\| =modeline-highlight= \| the outline path and the clock in the modeline \|
	517	\| =state-normal= \| the NORMAL tag (Doom keys) \|
	518	\| =state-insert= \| the INSERT tag \|
	519	\| =state-visual= \| the VISUAL and V-LINE tags \|
	520	\| =agenda-background= \| the agenda and board \|
	521	\| =agenda-date= \| agenda day headers \|
	522	\| =agenda-today= \| today's header and the current time \|
	523	\| =agenda-time= \| times and the time grid \|
	524	\| =agenda-category= \| categories \|
	525	\| =agenda-deadline= \| deadlines due \|
	526	\| =agenda-upcoming= \| deadlines coming up \|
	527	\| =agenda-scheduled= \| scheduled items \|
	528	\| =agenda-scheduled-past= \| items scheduled on an earlier day \|
	529	\| =habit-clear= \| habit graph: not due yet \|
	530	\| =habit-ready= \| habit graph: due \|
	531	\| =habit-alert= \| habit graph: due today, last chance \|
	532	\| =habit-overdue= \| habit graph: overdue \|
	533
	534	The default theme leaves =sidebar-background=, =sidebar-foreground=, =sidebar-header=, =modeline-background=, =modeline-foreground= and =agenda-background= 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.
	535
	536	An unknown color key, a value that isn't a color, or an unknown table such as =[theme.solarized]= is reported as a problem and skipped.
	537
	538	* Appearance
	539
	540	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 =[theme]= rather than =[theme.light]= or =[theme.dark]=.
	541
	542	* Fonts
	543
	544	The editor uses one font for everything: body text, headings, code and tables. Choose it in Settings ▸ Appearance or with =font= under =[theme]=.
	545
	546	- The Font menu lists installed monospaced families. =config.toml= 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.
	547	- =font-size= is the body size, at least 6 points.
	548	- Headings are bold. Level 1 is =font-size= plus three times =heading-size-step=, level 2 plus two times, level 3 plus one time; level 4 and deeper are body size. Set =heading-size-step = 0= for one size throughout.
	549	- =line-spacing= adds space between lines, in points.
	550
	551	On iPhone and iPad, the theme and font settings don't apply; see [[file:14-ios.org][iPhone and iPad]].

docs/manual/guide/14-ios.org added +263

		@@ -0,0 +1,263 @@
	1	#+TITLE: iPhone and iPad
	2	#+DESCRIPTION: The iOS app: folders, reading and editing, search, the agenda, capture, clocking, reminders, export and settings.
	3	#+LEDE: Orgstar for iPhone and iPad reads and edits the same org files as the Mac, with the agenda, capture and search.
	4
	5	* Overview
	6
	7	The app has four tabs:
	8
	9	- Agenda :: the agenda over your folders, with capture.
	10	- Folders :: the folders of org files you added, and their files.
	11	- Settings :: where the app's settings come from.
	12	- Search :: file names and the words of headings.
	13
	14	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.
	15
	16	* Folders and file access
	17
	18	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).
	19
	20	1. Open the Folders tab and tap Add Folder (the folder icon with a plus).
	21	2. Choose a folder in the picker.
	22
	23	Orgstar keeps access to the folder across launches. Each folder appears as a section listing its =.org= 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.
	24
	25	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.
	26
	27	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 [[file:15-alongside-emacs.org][Working alongside Emacs and other tools]].
	28
	29	There is no way to open a single file from the Files app. Add the folder that contains it.
	30
	31	* The reader
	32
	33	Tap a file in Folders, Search or the agenda to read it.
	34
	35	- Tap a heading to fold or unfold it, as =TAB= cycles it on the Mac. A chevron marks headings with content.
	36	- The file opens with the visibility its =#+STARTUP= line and =VISIBILITY= properties ask for; drawers are folded.
	37	- Text is styled as in the editor: TODO keywords, priorities, tags, emphasis, code, timestamps and links. Text can be selected and copied.
	38	- Tap a link to follow it. Links to headings and files in your folders open in the reader; web links open in the browser.
	39	- The toolbar has Outline (a list of headings to jump to), Export, and Edit.
	40
	41	* The editor
	42
	43	Tap Edit in the reader. The title shows the buffer name, with =•= while there are unsaved changes. The tab bar is hidden while you edit.
	44
	45	The editor folds headings, drawers and blocks, styles text with the default theme, and runs the same Org commands as the Mac. Autocorrection, smart quotes and smart dashes are off; spell checking is on.
	46
	47	The toolbar has:
	48
	49	- Conflict :: shown while the file and your edits conflict; opens the conflict sheet.
	50	- Undo
	51	- More :: Commands, Clock In, Export, Sync Conflict Copies, and Recovered Versions.
	52
	53	Messages from commands show at the top of the editor for a few seconds; tap one to dismiss it.
	54
	55	** Saving
	56
	57	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 =save= setting doesn't apply on iOS.
	58
	59	Files that aren't valid UTF-8 open read-only; commands that would change them say so.
	60
	61	** The key bar
	62
	63	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.
	64
	65	\| Button \| Key \|
	66	\|----------------------+-------------\|
	67	\| Commands \| the command list \|
	68	\| Fold \| =TAB= \|
	69	\| Overview \| =S-TAB= \|
	70	\| Promote \| =M-<left>= \|
	71	\| Demote \| =M-<right>= \|
	72	\| Move up \| =M-<up>= \|
	73	\| Move down \| =M-<down>= \|
	74	\| New heading or item \| =M-RET= \|
	75	\| TODO \| =C-c C-t= \|
	76	\| Act at point \| =C-c C-c= \|
	77	\| Schedule \| =C-c C-s= \|
	78	\| Deadline \| =C-c C-d= \|
	79	\| Tags \| =C-c C-q= \|
	80	\| Open link \| =C-c C-o= \|
	81	\| Hide keyboard \| \|
	82
	83	** Commands
	84
	85	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.
	86
	87	When a command asks a question, a sheet opens:
	88
	89	- 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.
	90	- Date questions have a calendar as well as the field; Org's date syntax (=+2d=, =fri=, =14:00=) works in the field.
	91	- 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.
	92
	93	Cancel answers nothing, as =C-g= does.
	94
	95	=C-c '= on a block, and =C-c `= on a table field, open the text in a sheet of its own; Save puts it back.
	96
	97	** Hardware keyboard
	98
	99	With a hardware keyboard, the editor uses the Emacs keymap, whatever =keymap= is set to on the Mac. =keymap.toml= isn't read on iOS.
	100
	101	- Option works as Meta when it begins a binding (=M-RET=, =M-<left>=). Otherwise Option types characters as usual.
	102	- Command shortcuts are the system's.
	103	- Keys the keymap leaves to the text system stay with iOS. These include the editing keys =C-a=, =C-e=, =C-k= and similar, which iOS handles itself.
	104	- After a prefix such as =C-c=, the message line shows =C-c-= while it waits for the next key. An unbound sequence shows =… is undefined=.
	105
	106	See [[file:03-keys.org][Keys and commands]] for the Emacs bindings.
	107
	108	* Search
	109
	110	The Search tab finds:
	111
	112	- Files :: up to eight org files whose path matches what you type, ranked as Quick Open ranks them on the Mac.
	113	- Headings :: headings whose title or text contains your words, including unsaved edits in the open file.
	114
	115	Tap a result to open it in the reader. A heading result opens at that heading.
	116
	117	* The agenda
	118
	119	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.
	120
	121	- Views (the calendar icon) :: the built-in views and those in =views.toml=, Tags and Properties… (a match such as =+work-home= or =TODO="WAIT"=), and in the day view, Today, Earlier and Later.
	122	- Filter :: keep or leave out tags and categories of the entries shown, or type a filter as Org's =/= takes it: =+keep= and =-drop= tags or categories, =<0:30= for effort, =/regexp/=. The status line shows the filter in use.
	123	- Tap an entry to read it, at its heading.
	124	- Swipe a TODO entry to the left to mark it done with the first done keyword of its sequence.
	125	- Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile…, and Archive….
	126
	127	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.
	128
	129	See [[file:07-agenda.org][The agenda]] for the views and matches.
	130
	131	* Capture
	132
	133	Tap Capture (the pencil icon) in the Agenda or Folders tab.
	134
	135	1. Choose a template. The first template is selected.
	136	2. Answer the template's questions (=%^{…}=, =%^g=, =%^t= and the like), then tap Continue. A template without questions skips this step.
	137	3. Edit the text. The caret is where =%?= was.
	138	4. Tap File.
	139
	140	Templates come from =capture.toml= in the configuration folder (see Settings below). Without one, the two default templates apply. A template with =immediate-finish= files as soon as its questions are answered, and one with =jump-to-captured= opens the captured entry. =%^g= offers the target file's tags as choices.
	141
	142	=org-protocol://capture= links opened on the device open the capture sheet with the link's template, URL, title and text.
	143
	144	** From the share sheet
	145
	146	Orgstar appears in the share sheet of other apps for a web link or text.
	147
	148	1. Share a page or text and choose Orgstar.
	149	2. Choose a template, edit the link's title, and add text.
	150	3. Tap Capture.
	151
	152	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.
	153
	154	** From Shortcuts
	155
	156	Shortcuts has a Capture to Orgstar action, and Siri responds to "Capture to Orgstar". The action takes:
	157
	158	- Text :: the text to capture, available to the template as =%i=.
	159	- Template Key :: a key from =capture.toml=; empty uses the first template.
	160
	161	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 =%c= (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.
	162
	163	See [[file:08-capture.org][Capture]] for the template format.
	164
	165	* Clocking
	166
	167	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 =H:MM=, updated every 30 seconds. Tap the bar for:
	168
	169	- Clock Out
	170	- Cancel Clock
	171	- Go to Clocked Entry
	172	- Clock Report
	173
	174	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.
	175
	176	See [[file:06-dates-and-clocking.org][Dates and clocking]].
	177
	178	* Reminders
	179
	180	With =reminders= on, Orgstar schedules a notification before each timed agenda entry in the next week, =appt-message-warning-time= minutes ahead (or the entry's =APPT_WARNTIME=). Tap a notification to open its entry. Notifications show while the app is open too.
	181
	182	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.
	183
	184	* Export
	185
	186	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.
	187
	188	PDF, ODT, LaTeX and plain-text export need Emacs and aren't available on iOS. See [[file:12-export.org][Export]].
	189
	190	* Code blocks and tables
	191
	192	=C-c C-c= on a source block asks whether to run it (yes, no, or always for this block), as on the Mac.
	193
	194	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:
	195
	196	- A block in another language: "/language/ blocks need the Mac to run."
	197	- Emacs Lisp the interpreter doesn't have: "This block uses Emacs Lisp that runs only in Emacs, on the Mac."
	198
	199	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.
	200
	201	Tangling (=C-c C-v t=, in Commands) works on iOS and writes the tangled files next to the org file, or where =:tangle= says.
	202
	203	See [[file:11-code-blocks.org][Code blocks]] and [[file:10-tables.org][Tables]].
	204
	205	* Conflicts and versions
	206
	207	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:
	208
	209	- Keep Mine :: write your version over the disk version.
	210	- Use Disk Version :: replace your edits with the disk version.
	211	- Merge with Markers :: put both versions in the editor, with conflicting lines between =<<<<<<<= and =>>>>>>>= markers, to fix and save.
	212	- Later :: decide later. The Conflict button in the toolbar opens the sheet again. Nothing is saved until you decide.
	213
	214	The version you don't keep goes to the recovery folder.
	215
	216	More ▸ Sync Conflict Copies lists Syncthing's conflict copies of the file (=name.sync-conflict-…=), 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.
	217
	218	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.
	219
	220	See [[file:15-alongside-emacs.org][Working alongside Emacs and other tools]] for how merging and recovery work.
	221
	222	* Settings
	223
	224	The iOS app has no settings of its own. It reads them from a configuration folder: a folder holding =config.toml= and =capture.toml=, such as a copy of the Mac's =~/.config/orgstar= synced through iCloud Drive or another app.
	225
	226	1. Open the Settings tab.
	227	2. Tap Choose Folder… and choose the folder.
	228
	229	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 /folder/; the defaults apply" means the folder has no =config.toml=.
	230
	231	Stop Using This Folder returns every setting to its default.
	232
	233	The In use section shows the TODO keywords, the agenda span and start, the reminder lead time, and the capture template keys in effect.
	234
	235	These settings from =config.toml= apply on iOS:
	236
	237	- =org-todo-keywords=, =org-list-allow-alphabetical=
	238	- =org-tags-column=, =org-insert-heading-respect-content=, =fill-column=
	239	- =org-log-done=, =org-log-reschedule=, =org-log-redeadline=, =org-log-into-drawer=
	240	- =electric-pair-mode=
	241	- =org-agenda-span=, =org-agenda-start-day=, =agenda-include-subfolders=
	242	- =reminders=, =appt-message-warning-time=
	243
	244	=capture.toml= and =views.toml= in the folder apply too. Other settings, including =keymap=, =save=, the theme and font, and the startup settings, don't apply on iOS. See [[file:13-configuration.org][Configuration]].
	245
	246	* Spotlight and Quick Look
	247
	248	Orgstar adds the org files in your folders to Spotlight with their title (=#+TITLE=, 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.
	249
	250	Quick Look in the Files app shows org files as the HTML export renders them.
	251
	252	* What the Mac has that iOS doesn't
	253
	254	- Running code blocks in languages other than Emacs Lisp, Emacs Lisp beyond Orgstar's interpreter, and tables that need Emacs.
	255	- PDF, ODT, LaTeX and plain-text export.
	256	- The Mac and Doom keymaps, Vim keys, and =keymap.toml=.
	257	- Themes, fonts and font sizes. The iOS editor uses the default theme and the system's monospaced font at the Dynamic Type size.
	258	- Import from Emacs.
	259	- The board, column view, the backlinks pane, and the buffer list and tab bar.
	260	- The global capture hotkey and the Settings window.
	261	- Explicit saving.
	262
	263	Commands the iOS app can't carry out show a message instead, such as "Not available on iOS yet". 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.

docs/manual/guide/15-alongside-emacs.org added +237

		@@ -0,0 +1,237 @@
	1	#+TITLE: Working alongside Emacs and other tools
	2	#+DESCRIPTION: 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.
	3	#+LEDE: Orgstar works on plain org files in ordinary folders, so Emacs, other apps and sync tools can work on the same files.
	4
	5	* How Orgstar treats files
	6
	7	** Bytes on disk
	8
	9	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:
	10
	11	- A file with no changes is never rewritten.
	12	- Untouched lines keep their bytes, including trailing whitespace, tabs, and the presence or absence of a final newline.
	13	- Line endings are kept as they are. A file with CRLF line endings keeps them, and on the Mac the modeline shows =CRLF= for such a file. Orgstar doesn't convert line endings; new lines that Orgstar's commands insert end with LF.
	14
	15	** Encodings
	16
	17	Orgstar edits UTF-8 files, with or without a byte order mark. A file that starts with a BOM keeps it.
	18
	19	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.
	20
	21	** How a save works
	22
	23	Saving replaces the file through a temporary file in the same folder (named =.name.org.orgstar-…=), under the system's file coordination, so iCloud and other coordinating apps see a complete file. The steps are:
	24
	25	1. 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).
	26	2. Read the file again. If it changed in the meantime, start over, up to three times.
	27	3. 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.
	28	4. 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.
	29
	30	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.
	31
	32	If the file keeps changing through all three attempts, the save fails with an error and your edits stay unsaved.
	33
	34	** Automatic and explicit saving
	35
	36	With =save = "automatic"= (the default), Orgstar saves a file one second after you stop typing. With ="explicit"=, only =⌘S= (Save) and =⌥⌘S= (Save All) save. See [[file:13-configuration.org][Configuration]]. The iOS app always saves automatically.
	37
	38	* Changes made outside Orgstar
	39
	40	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:
	41
	42	- If you have no unsaved edits in it, Orgstar reloads it. Undo history for the file is cleared.
	43	- If you have unsaved edits, Orgstar merges the disk version into them and saves the result.
	44	- If the changes conflict, nothing is saved and the conflict sheet opens.
	45
	46	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.
	47
	48	After a reload or merge, Orgstar also reads the file's setup files again.
	49
	50	** The conflict sheet
	51
	52	The sheet shows what differs, with lines marked - on disk and + in your version, and offers:
	53
	54	\| Button \| Effect \|
	55	\|--------------------+--------------------------------------------------------------------------------------------------\|
	56	\| Keep Mine \| Writes your version over the disk version. The disk version goes to the recovery folder. \|
	57	\| Use Disk Version \| Loads the disk version. Your version goes to the recovery folder. \|
	58	\| Merge with Markers \| Puts both sets of changes in the buffer, with conflicting lines between =<<<<<<< yours= and =>>>>>>> disk= markers, as =git merge= leaves them. Edit and save. Your version as it was goes to the recovery folder. \|
	59	\| Decide Later \| Closes the sheet. Automatic saving stops for the file until you decide; the Conflict button in the toolbar opens the sheet again. \|
	60
	61	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.
	62
	63	* Sync tools
	64
	65	** iCloud Drive
	66
	67	Orgstar reads and writes files under file coordination, which is how iCloud expects apps to work. Files iCloud hasn't downloaded yet (=.name.org.icloud= 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.
	68
	69	** Syncthing
	70
	71	Syncthing writes files without file coordination. Orgstar sees its changes through file watching and merges them as described above.
	72
	73	- Syncthing's temporary files (=.syncthing.*=) are ignored.
	74	- Its folders =.stfolder= and =.stversions= are in the default =ignored-folders=.
	75	- Conflict copies (=name.sync-conflict-YYYYMMDD-HHMMSS-ID.org=) are listed in the sidebar but never indexed, so they don't appear in the agenda, search or ID links.
	76
	77	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:
	78
	79	\| Button \| Effect \|
	80	\|--------------------+--------------------------------------------------------------------------------------------\|
	81	\| Keep File \| Leaves the file as it is. \|
	82	\| Use Copy \| Replaces the buffer's text with the copy's, as an edit you can undo. \|
	83	\| Merge with Markers \| 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. \|
	84
	85	Each choice then moves the copy to the recovery folder and deletes it from the folder.
	86
	87	** Dropbox and other tools
	88
	89	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.
	90
	91	** Files Orgstar ignores
	92
	93	When scanning folders, Orgstar skips Emacs lock files (=.#name=), backups (=name~=) and auto-save files (=#name#=), its own temporary and backup files (names containing =.orgstar-=), =.DS_Store=, =.localized=, and the folders in =ignored-folders=. With =show-hidden-files = false=, every dotfile and dot folder is skipped. Orgstar doesn't create or honour Emacs lock files.
	94
	95	* Recovery versions
	96
	97	Every version a save, a merge or a conflict resolution displaces is kept in the recovery folder:
	98
	99	- on the Mac, =~/Library/Application Support/Orgstar/Recovery= (or =$ORGSTAR_DATA_DIR/Recovery=),
	100	- on iOS, the app's own Application Support folder.
	101
	102	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:
	103
	104	\| Label \| Kept when \|
	105	\|-----------------+-------------------------------------------------------------------------------\|
	106	\| =external= \| A version written by another program was replaced or merged \|
	107	\| =local= \| Orgstar's version was replaced, or set aside by Use Disk Version, Merge with Markers or Restore \|
	108	\| =sync-conflict= \| A Syncthing conflict copy was resolved \|
	109
	110	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.
	111
	112	* Features that use Emacs on the Mac
	113
	114	Some features run Emacs in batch mode on the Mac. Everything else works without Emacs installed.
	115
	116	\| Feature \| What runs \|
	117	\|----------------------------------------------------------------+-----------------------------------------------------------------------------------------------\|
	118	\| Emacs Lisp source blocks (=emacs-lisp=, =elisp=) \| The block, in =emacs -Q --batch= \|
	119	\| Table formulas outside what Orgstar computes itself \| =org-table-recalculate= on a copy of the file; the table's new text replaces the old one if the table didn't change meanwhile \|
	120	\| Lisp table formulas that Orgstar's Emacs Lisp interpreter can't evaluate \| The same; Orgstar first asks whether to run Lisp (yes, no, always) \|
	121	\| Export to PDF, ODT, LaTeX and plain text \| =org-latex-export-to-pdf=, =org-odt-export-to-odt=, =org-latex-export-to-latex= or =org-ascii-export-to-ascii= \|
	122
	123	HTML and Markdown export don't use Emacs. See [[file:11-code-blocks.org][Code blocks]], [[file:10-tables.org][Tables]] and [[file:12-export.org][Export]].
	124
	125	** How Emacs is found
	126
	127	Orgstar uses the first of these that is an executable file:
	128
	129	1. the path in the environment variable =ORGSTAR_EMACS=,
	130	2. =/opt/homebrew/bin/emacs=,
	131	3. =/usr/local/bin/emacs=,
	132	4. =/Applications/Emacs.app/Contents/MacOS/Emacs=,
	133	5. =/run/current-system/sw/bin/emacs=,
	134	6. =/usr/bin/emacs=.
	135
	136	An app started from the Dock doesn't see your shell's =PATH=, which is why Orgstar looks in fixed places. Without Emacs, these features report "Emacs isn't installed, so …" and change nothing.
	137
	138	** What Emacs sees
	139
	140	- Emacs runs with =-Q=: your =init.el=, packages and customizations aren't loaded. Org and the exporters are the versions bundled with that Emacs.
	141	- 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.
	142	- File-local variables marked safe apply (=enable-local-variables= is =:safe=).
	143	- Export doesn't run source blocks (=org-export-use-babel= is =nil=). The exported file is written next to the org file, as Emacs writes it, or moved to the place you chose.
	144	- PDF export needs a LaTeX installation that Org's LaTeX exporter can run.
	145	- 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, and =⌘.= (Cancel Running Block) stops one.
	146
	147	* Quick Look
	148
	149	Orgstar includes a Quick Look extension for org files (=.org= and =.org_archive=). 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 =#+SETUPFILE= keywords applied. The preview reads only UTF-8 files.
	150
	151	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.
	152
	153	* Spotlight
	154
	155	On the Mac, Orgstar includes a Spotlight importer for org files. Spotlight indexes each file's text, its title (=#+TITLE=, else the file name), =#+AUTHOR=, =#+DESCRIPTION=, and its tags (=#+FILETAGS= and heading tags) and headings as keywords. The importer reads only UTF-8 files.
	156
	157	On iOS, the app adds the files in your folders to Spotlight itself; see [[file:14-ios.org][iPhone and iPad]].
	158
	159	* Finder
	160
	161	Orgstar declares the =org.orgmode.org= file type for the extensions =.org= and =.org_archive=, 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 =open -a Orgstar file.org= 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.
	162
	163	* org-protocol and Shortcuts
	164
	165	Orgstar registers the =org-protocol:= URL scheme on the Mac and iOS, and handles two sub-protocols, in both the =?key=value= form and the older =:/a/b/c= form:
	166
	167	- =org-protocol://capture= opens Capture with the link's template, URL, title and body.
	168	- =org-protocol://store-link= stores the link for =C-c C-l= and copies it to the clipboard. This is Mac only; the iOS app handles only =capture=.
	169
	170	Other sub-protocols, such as =open-source=, show "Orgstar handles org-protocol capture and store-link".
	171
	172	The Shortcuts action Capture to Orgstar, on the Mac and iOS, files text with a capture template without opening the capture window. See [[file:08-capture.org][Capture]].
	173
	174	* Compatibility notes
	175
	176	** Defaults that differ from Emacs
	177
	178	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 =config.toml= to match your Emacs, or use Import from Emacs; see [[file:13-configuration.org][Configuration]].
	179
	180	\| Setting \| Orgstar default \| Plain Emacs default \|
	181	\|--------------------------------------+-------------------------------------+---------------------------------\|
	182	\| =fill-column= \| 80 \| 70 \|
	183	\| =org-todo-keywords= \| =TODO PROJ LOOP STRT WAIT HOLD IDEA=, done =DONE KILL= \| =TODO=, done =DONE= \|
	184	\| =org-insert-heading-respect-content= \| =true= \| =nil= \|
	185	\| =org-M-RET-may-split-line= \| =false= \| =t= \|
	186	\| =org-list-allow-alphabetical= \| =true= \| =nil= \|
	187	\| =org-hide-emphasis-markers= \| =true= \| =nil= \|
	188	\| =org-pretty-entities= \| =true= \| =nil= \|
	189	\| =org-startup-indented= \| =true= \| =nil= \|
	190	\| =org-startup-truncated= \| =false= \| =t= \|
	191	\| =electric-pair-mode= \| =true= \| off \|
	192	\| =org-agenda-span= \| 10 days \| a week \|
	193	\| =org-agenda-start-day= \| ="-3d"= \| today \|
	194
	195	=org-hide-emphasis-markers= and =org-pretty-entities= 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.
	196
	197	These behave as Emacs's defaults and can't be changed: =org-log-repeat= is =time=, fast TODO selection is on when keywords have keys, priorities are =A= to =C= with =B= as default unless =#+PRIORITIES= says otherwise, and =org-use-sub-superscripts= is ={}= for display (only =x_{1}= and =x^{2}= are lowered and raised).
	198
	199	** Known differences from Emacs Org
	200
	201	Orgstar refuses some things with a message rather than doing something different from Emacs. These are the ones found in the current version.
	202
	203	Code blocks (see [[file:11-code-blocks.org][Code blocks]]):
	204
	205	- =:cmdline= is supported only for shells, =dot=, =plantuml= and =mermaid=.
	206	- =:prologue=, =:epilogue= and =:post= aren't supported; =:stdin= and =:shebang= only for shells.
	207	- =:session= is supported only for shells and Python.
	208	- =:var= isn't supported for some languages; references with arguments, as =block(x=1)=, and using another source block's result in =:var= aren't supported.
	209	- Header arguments, =:var= values and =:cache= 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."
	210	- Noweb references that run a block aren't supported.
	211	- Tangling refuses =:var= that would run a block, and tables and lists in =:var= for some languages.
	212	- On iOS, only Emacs Lisp blocks run.
	213
	214	Links (see [[file:09-links.org][Links]]):
	215
	216	- Coderef links (=[[(ref)]]=) and regexp search links (=[[/regexp/]]=) aren't supported.
	217	- =shell:= and =elisp:= links aren't run.
	218
	219	Capture templates (see [[file:08-capture.org][Capture]]):
	220
	221	- =%(= escapes, which run Emacs Lisp, aren't supported.
	222	- =%[file]= escapes aren't supported.
	223
	224	Tables and dynamic blocks (see [[file:10-tables.org][Tables]] and [[file:06-dates-and-clocking.org][Dates and clocking]]):
	225
	226	- Formulas outside Orgstar's own calculator go to Emacs on the Mac and are refused on iOS.
	227	- Clock tables support the scopes =nil=, =file=, =subtree= and =treeN=; other scopes, =:match= and =:step= aren't supported.
	228	- Dynamic blocks other than =clocktable= and =columnview= aren't supported. Column views of other files aren't supported.
	229
	230	Other:
	231
	232	- =C-c C-q= before the first heading (setting file tags) isn't supported.
	233	- Priority ranges that aren't letters or numbers are refused.
	234	- =#+SETUPFILE= URLs aren't fetched.
	235	- Most =#+STARTUP= options for footnotes, entities, LaTeX previews, numbering and odd levels are accepted and ignored; see [[file:13-configuration.org][Configuration]].
	236	- =display-line-numbers-type= has no relative or visual mode.
	237	- In the Doom preset, =ZQ= isn't available; use the window's close button.

docs/manual/index.org added +48

		@@ -0,0 +1,48 @@
	1	#+TITLE: Orgstar
	2	#+DESCRIPTION: A native macOS and iOS editor for org-mode files.
	3	#+LEDE: Orgstar edits org files in place, alongside Emacs and the sync tools you already use.
	4	#+OPTIONS: toc:nil
	5
	6	Orgstar is an editor for [[https://orgmode.org][Org mode]] files on the Mac, with an app for
	7	iPhone and iPad. It reads and writes the same plain-text files Emacs does, behaves the
	8	way Org does where the two overlap, and leaves every byte you didn't change as it was.
	9
	10	On the Mac you get the editor with Emacs, Mac or Doom (Vim) keys, the agenda and a
	11	board view, capture templates, clocking, tables with formulas, code blocks and
	12	tangling, and export to HTML and Markdown (and to other formats through Emacs, if
	13	it is installed). The iOS app has the editor, agenda, capture, search, clocking,
	14	reminders, export and tangling.
	15
	16	* Start here
	17
	18	- [[file:install.org][Install]]: build the app from source.
	19	- [[file:quickstart.org][Quick start]]: add a folder, open a file, and the first keys to learn.
	20	- The manual, below: every feature, chapter by chapter.
	21
	22	* The manual
	23
	24	1. [[file:guide/01-files-and-folders.org][Files, folders and buffers]]
	25	2. [[file:guide/02-the-editor.org][The editor]]
	26	3. [[file:guide/03-keys.org][Keys and commands]]
	27	4. [[file:guide/04-outlines.org][Outlines and structure]]
	28	5. [[file:guide/05-todos-and-tags.org][TODOs and tags]]
	29	6. [[file:guide/06-dates-and-clocking.org][Dates, scheduling and clocking]]
	30	7. [[file:guide/07-agenda.org][The agenda]]
	31	8. [[file:guide/08-capture.org][Capture]]
	32	9. [[file:guide/09-links.org][Links]]
	33	10. [[file:guide/10-tables.org][Tables]]
	34	11. [[file:guide/11-code-blocks.org][Code blocks]]
	35	12. [[file:guide/12-export.org][Export]]
	36	13. [[file:guide/13-configuration.org][Configuration]]
	37	14. [[file:guide/14-ios.org][iPhone and iPad]]
	38	15. [[file:guide/15-alongside-emacs.org][Working alongside Emacs and other tools]]
	39
	40	* Principles
	41
	42	- The files are the source of truth. There is no database of your notes. Orgstar
	43	keeps an index for search and the agenda, rebuilt from the files whenever they change.
	44	- Only your edits are written. Saving rewrites the bytes you changed and nothing
	45	else: indentation, line endings, encoding marks and unusual spacing elsewhere stay.
	46	- Org's behaviour, not a lookalike. Commands follow what Org 9.8 does, and are
	47	checked against Emacs in the test suite. Where Orgstar can't do something the way
	48	Org would, it says so and leaves the file alone rather than guessing.

docs/manual/install.org added +57

		@@ -0,0 +1,57 @@
	1	#+TITLE: Install
	2	#+DESCRIPTION: Building Orgstar for the Mac and the iOS Simulator from source.
	3	#+LEDE: Orgstar is built from source; there are no prebuilt downloads yet.
	4
	5	* Requirements
	6
	7	- macOS 26 or later.
	8	- Xcode 27 (the Swift 6.2 toolchain).
	9	- Optional: GNU Emacs, for the features that hand work to it on the Mac
	10	(Emacs Lisp code blocks that need full Emacs, Lisp table formulas the built-in
	11	interpreter can't run, and export to PDF, LaTeX, ODT and other formats). See
	12	[[file:guide/15-alongside-emacs.org][Working alongside Emacs and other tools]].
	13
	14	* The Mac app
	15
	16	#+BEGIN_SRC sh
	17	git clone https://gitbay.org/krz/orgstar.git
	18	cd orgstar
	19	scripts/build-app.sh
	20	open .build/app/Orgstar.app
	21	#+END_SRC
	22
	23	=scripts/build-app.sh= builds a release binary and assembles
	24	=.build/app/Orgstar.app= with its Quick Look and Spotlight extensions, signed ad hoc
	25	for use on your own Mac. Move it to =/Applications= to keep it. Pass a version number
	26	as the first argument to stamp the bundle (=scripts/build-app.sh 1.0.0=); the default
	27	is =0.1.0=.
	28
	29	Once the app has been launched, Finder opens =.org= files with it, Quick Look shows
	30	them formatted, and Spotlight indexes their headings and text.
	31
	32	* The iOS app
	33
	34	The iOS app (iOS 26 or later) currently builds for the Simulator:
	35
	36	#+BEGIN_SRC sh
	37	scripts/build-ios-app.sh
	38	xcrun simctl install booted .build/ios-app/Orgstar.app
	39	#+END_SRC
	40
	41	See [[file:guide/14-ios.org][iPhone and iPad]] for what it does.
	42
	43	* Updating
	44
	45	Pull and build again:
	46
	47	#+BEGIN_SRC sh
	48	git pull
	49	scripts/build-app.sh
	50	#+END_SRC
	51
	52	Your settings live in =~/.config/orgstar/= and survive rebuilds.
	53
	54	* Uninstalling
	55
	56	Delete =Orgstar.app=. To remove your settings as well, delete =~/.config/orgstar/=.
	57	Your org files are never stored inside the app.

docs/manual/orgo.toml added +33

		@@ -0,0 +1,33 @@
	1	# The Orgstar user manual, built with orgo and published to the pages branch by
	2	# scripts/publish-docs.sh.
	3
	4	[site]
	5	title = "Orgstar"
	6	description = "A native macOS and iOS editor for org-mode files."
	7	language = "en"
	8	base_url = ""
	9	theme = "docs"
	10
	11	[nav]
	12	mode = "explicit"
	13	pages = ["install.org", "quickstart.org"]
	14
	15	[templates]
	16	dir = "templates"
	17
	18	[highlight]
	19	theme = "base16-ocean.dark"
	20
	21	[html]
	22	heading_offset = 1
	23	toc = true
	24	section_numbers = false
	25
	26	[[collections]]
	27	source = "guide"
	28	output = "guide/index.html"
	29	template = "list.html"
	30	title = "Manual"
	31	sort = "path"
	32	order = "asc"
	33	nav = true

docs/manual/quickstart.org added +84

		@@ -0,0 +1,84 @@
	1	#+TITLE: Quick start
	2	#+DESCRIPTION: From a fresh install to editing, scheduling and seeing your agenda.
	3	#+LEDE: Add a folder of org files, open one, and learn the handful of keys you need first.
	4
	5	* Add a folder
	6
	7	Choose File ▸ Add Folder… (=⇧⌘O=) and pick the folder that holds your org files.
	8	It appears in the sidebar, and Orgstar indexes every org file under it for search,
	9	the agenda and links. You can add several folders. Nothing is copied or moved.
	10
	11	If you don't have org files yet, add an empty folder and create =notes.org= in it from
	12	Finder or the sidebar.
	13
	14	* Choose your keys
	15
	16	Open Orgstar ▸ Settings… (=⌘,=) and pick Keys under General:
	17
	18	- Emacs: Org's own bindings, =C-c C-t= and friends. The default.
	19	- Mac: standard Mac editing keys, with Org commands on =⌃⌘= combinations.
	20	- Doom (Vim keys): modal editing as in Doom Emacs, with =SPC= as the leader.
	21
	22	[[file:guide/03-keys.org][Keys and commands]] lists every binding in each preset. If you
	23	already use Emacs, Settings ▸ General ▸ Import from Emacs… reads your configuration:
	24	TODO keywords, agenda files, capture templates and more (see
	25	[[file:guide/13-configuration.org][Configuration]]).
	26
	27	* Open a file
	28
	29	=⌘P= (Quick Open) finds a file by name; the sidebar works too. Open files become
	30	buffers: the tab bar and Switch to Buffer move between them.
	31
	32	* Write an outline
	33
	34	Type a heading and some text:
	35
	36	#+BEGIN_SRC org
	37	,* Projects
	38	,** TODO Write the report
	39	SCHEDULED: <2026-10-09 Fri>
	40	Draft the summary first.
	41	,** Reading list
	42	- [ ] The Org manual
	43	- [ ] This manual
	44	#+END_SRC
	45
	46	With the Emacs keys:
	47
	48	\| Key \| What it does \|
	49	\|-----+--------------\|
	50	\| =TAB= on a heading \| Fold or unfold it (cycles through folded, children, everything). \|
	51	\| =S-TAB= \| Cycle the whole file the same way. \|
	52	\| =M-RET= \| New heading (or list item) at the same level. \|
	53	\| =M-<left>= / =M-<right>= \| Promote or demote the heading. \|
	54	\| =C-c C-t= \| Cycle the TODO state. \|
	55	\| =C-c C-s= / =C-c C-d= \| Schedule, or set a deadline, with the date picker. \|
	56	\| =C-c C-c= \| Context action: toggle a checkbox, align a table, run a code block. \|
	57
	58	With the Mac preset, the Org commands are on =⌃⌘= keys (=⌃⌘T= cycles TODO, =⌃⌘S=
	59	schedules); with Doom, they're under =SPC m= (=SPC m t=, =SPC m d s=).
	60
	61	The [[file:guide/02-the-editor.org][editor chapter]] covers how Org markup is shown and
	62	hidden, and [[file:guide/04-outlines.org][Outlines and structure]] covers headings and lists.
	63
	64	* See your agenda
	65
	66	Window ▸ Agenda (=⇧⌘A=) shows what is scheduled or due across every indexed file,
	67	day by day, and the TODO list. Select an item to jump to it. See
	68	[[file:guide/07-agenda.org][The agenda]].
	69
	70	* Capture a thought
	71
	72	=⇧⌘N= opens capture from anywhere in the app. Until you define your own templates
	73	(in =~/.config/orgstar/capture.toml=, or imported from Emacs), there are two: =t= files a
	74	TODO and =n= a note, each under an =Inbox= heading in =todo.org= or =notes.org= in your
	75	first folder. See [[file:guide/08-capture.org][Capture]].
	76
	77	* Search
	78
	79	=⇧⌘F= searches the text of every indexed file. Results open at the matching line.
	80
	81	* Next
	82
	83	- The command palette (=⇧⌘P=) lists every command with its key.
	84	- The [[file:index.org][chapter list]] goes through every feature.

docs/manual/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	}

docs/manual/templates/base.html added +55

		@@ -0,0 +1,55 @@
	1	<!DOCTYPE html>
	2	<html lang="{{ site.language }}">
	3	<head>
	4	<meta charset="utf-8">
	5	<meta name="viewport" content="width=device-width, initial-scale=1">
	6	<title>{{ page.title }} · {{ site.title }}</title>
	7	{%- if site.base_url %}
	8	<link rel="canonical" href="{{ page.url \| absolute }}">
	9	{%- endif %}
	10	<meta name="description" content="{{ page.excerpt \| truncate(150) }}">
	11	<link rel="icon" href="{{ root }}favicon.svg" type="image/svg+xml">
	12	{%- if theme %}
	13	<link rel="stylesheet" href="{{ theme }}">
	14	{%- endif %}
	15	{%- if stylesheet %}
	16	<link rel="stylesheet" href="{{ stylesheet }}">
	17	{%- endif %}
	18	<link rel="stylesheet" href="{{ root }}style.css">
	19	</head>
	20	<body>
	21	<header class="site">
	22	<a class="site-title" href="{{ root }}index.html">{{ site.title }}</a>
	23	{%- if nav %}
	24	<nav>
	25	{%- for item in nav %}
	26	<a href="{{ item.url }}">{{ item.title }}</a>
	27	{%- endfor %}
	28	</nav>
	29	{%- endif %}
	30	</header>
	31	<main>
	32	<h1>{{ page.title }}</h1>
	33	{%- if page.keywords.lede %}
	34	<p class="lede">{{ page.keywords.lede }}</p>
	35	{%- endif %}
	36	{%- if page.toc \| length > 1 %}
	37	{%- macro toc_list(entries) %}
	38	<ul>
	39	{%- for entry in entries %}
	40	<li><a href="#{{ entry.anchor }}">{{ entry.title }}</a>
	41	{%- if entry.children %}{{ toc_list(entry.children) }}{% endif %}</li>
	42	{%- endfor %}
	43	</ul>
	44	{%- endmacro %}
	45	<nav class="toc" aria-label="On this page">
	46	<h2>On this page</h2>
	47	{{- toc_list(page.toc) }}
	48	</nav>
	49	{%- endif %}
	50	{% block content %}{{ body \| safe }}{% endblock %}</main>
	51	<footer class="site">
	52	Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>.
	53	</footer>
	54	</body>
	55	</html>

docs/manual/templates/list.html added +14

		@@ -0,0 +1,14 @@
	1	{% extends "base.html" %}
	2	{% block content %}
	3	<ul class="post-list">
	4	{%- for entry in pages %}
	5	<li>
	6	<a href="{{ root }}{{ entry.url }}">{{ entry.title }}</a>
	7	{%- if entry.excerpt %}
	8	<p class="excerpt">{{ entry.excerpt \| truncate(180) }}</p>
	9	{%- endif %}
	10	<span class="reading-time">{{ entry.reading_time }} min read</span>
	11	</li>
	12	{%- endfor %}
	13	</ul>
	14	{% endblock %}

scripts/publish-docs.sh added +27

		@@ -0,0 +1,27 @@
	1	#!/bin/sh
	2	# Builds the user manual in docs/manual with orgo and force-pushes it to the `pages`
	3	# branch, which gitbay serves at https://krz.gitbay.page/orgstar/.
	4	# Usage: scripts/publish-docs.sh [--dry-run]
	5	set -eu
	6
	7	cd "$(dirname "$0")/.."
	8	tmp=$(mktemp -d)
	9	trap 'rm -rf "$tmp"' EXIT
	10	site="$tmp/site"
	11
	12	orgo build docs/manual -o "$site" --strict --no-cache
	13	rm -f "$site/.orgo-cache.json"
	14
	15	if [ "${1:-}" = "--dry-run" ]; then
	16	echo "built $(find "$site" -name '*.html' \| wc -l \| tr -d ' ') pages; not published"
	17	exit 0
	18	fi
	19
	20	# The pages branch holds only the built site, replaced on each publish.
	21	sha=$(git rev-parse --short HEAD)
	22	git init -q "$tmp/work"
	23	cp -R "$site/." "$tmp/work/"
	24	git -C "$tmp/work" add -A
	25	git -C "$tmp/work" commit -q -m "Publish the manual from $sha"
	26	git -C "$tmp/work" push -q --force "$(git remote get-url origin)" HEAD:refs/heads/pages
	27	echo "published the manual from $sha"