krz/orgstar

Update the manual for iOS themes and clock history !173

merged merged by cmc on 2026-10-08 08:04 UTC · krz/orgstar:manual-ios-clock into main

6 files changed, +178 −29

Layout: unified · split

docs/manual/guide/02-the-editor.org +2
@@ -292,6 +292,8 @@ Line numbers show in a margin left of the text, as =display-line-numbers-mode= s
292292
293293The 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]].
294294
295The iOS editor uses the same theme and display settings, read from the synced =config.toml=; see [[file:14-ios.org][iPhone and iPad]].
296
295297* Undo
296298
297299Each buffer has its own undo history, kept while other buffers show.
docs/manual/guide/03-keys.org +12 −3
@@ -96,7 +96,7 @@ Type part of a title; matching is fuzzy and the best matches come first. =Return
9696
9797The 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.
9898
99The 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.
99The 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. Its Clock submenu lists the clock commands the same way, followed by the recently clocked entries.
100100
101101* Menu shortcuts
102102
@@ -578,11 +578,15 @@ Besides the leader, the preset binds these evil-org and Doom keys in normal stat
578578| =SPC m b i r= | Insert Table Row (=org.table.insert-row=) |
579579| =SPC m b r= | Recalculate Table (=org.table.recalc-all=) |
580580| =SPC m c E= | Set Effort (=org.effort.set=) |
581| =SPC m c G= | Go to Recent Clocked Entry… (=app.clock.goto-recent=) |
582| =SPC m c I= | Clock In to Last Entry (=app.clock.in-last=) |
581583| =SPC m c R= | Clock Report (=app.clock.report=) |
582584| =SPC m c c= | Cancel Clock (=app.clock.cancel=) |
585| =SPC m c d= | Mark as Default Clock Task (=app.clock.default=) |
583586| =SPC m c g= | Go to Clocked Entry (=app.clock.goto=) |
584587| =SPC m c i= | Clock In (=app.clock.in=) |
585588| =SPC m c o= | Clock Out (=app.clock.out=) |
589| =SPC m c r= | Resolve Open Clocks… (=app.clock.resolve=) |
586590| =SPC m d T= | Insert Inactive Timestamp (=org.timestamp.inactive=) |
587591| =SPC m d d= | Set Deadline (=org.deadline=) |
588592| =SPC m d s= | Schedule (=org.schedule=) |
@@ -686,7 +690,7 @@ With a hardware keyboard, the iOS app runs the Emacs preset's bindings, whatever
686690- Option acts as Meta when the key starts a binding (=M-RET=, =M-<left>=); otherwise Option types characters as usual.
687691- Keys with =⌘= are left to iOS.
688692- 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.
689- 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, show =Not available on iOS yet=.
693- Of the =app.= commands only the clock commands run from keys: =C-c C-x C-i=, =C-c C-x C-o=, =C-c C-x C-q=, =C-c C-x C-j=, =C-c C-x C-x= and =C-c C-x C-z=. Other =app.= keys, and editor commands such as narrowing, show =Not available on iOS yet=.
690694- A sequence of two or more keys whose command cannot run at the caret runs it anyway and shows its message, as on the Mac (for example =Not on a heading=).
691695- A pending prefix shows as a message, without key hints.
692696
@@ -849,9 +853,14 @@ When a key appears in several rows, it runs the command whose condition holds at
849853| 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=). |
850854| 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=). |
851855| Clock In (=app.clock.in=) | =C-c C-x C-i= | =⌃⌘I= | =SPC m c i= (N) | Starts the clock on the current entry (=org-clock-in=). |
856| Clock In to Recent Entry… (=app.clock.in-recent=) | — | =⌃⌥⌘I= | — | Asks for an entry from the clock history and clocks in to it (=org-clock-in= with =C-u=). |
857| Clock In to Last Entry (=app.clock.in-last=) | =C-c C-x C-x= | — | =SPC m c I= (N) | Clocks in to the most recently clocked entry (=org-clock-in-last=). |
852858| Clock Out (=app.clock.out=) | =C-c C-x C-o= | =⌃⇧⌘I= | =SPC m c o= (N) | Stops the clock (=org-clock-out=). |
853859| 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=). |
854| Go to Clocked Entry (=app.clock.goto=) | =C-c C-x C-j= | =⌃⌘J= | =SPC m c g= (N) | Opens the entry the clock is running on (=org-clock-goto=). |
860| Go to Clocked Entry (=app.clock.goto=) | =C-c C-x C-j= | =⌃⌘J= | =SPC m c g= (N) | Opens the entry the clock is running on, or the most recently clocked one (=org-clock-goto=). |
861| Go to Recent Clocked Entry… (=app.clock.goto-recent=) | — | =⌃⌥⌘J= | =SPC m c G= (N) | Asks for an entry from the clock history and opens it (=org-clock-goto= with =C-u=). |
862| Mark as Default Clock Task (=app.clock.default=) | — | — | =SPC m c d= (N) | Makes the current entry the default task, =d= in the clock selection (=org-clock-mark-default-task=). |
863| Resolve Open Clocks… (=app.clock.resolve=) | =C-c C-x C-z= | — | =SPC m c r= (N) | Asks what to do with each open =CLOCK:= line in your folders (=org-resolve-clocks=). |
855864| Clock Report (=app.clock.report=) | — | — | =SPC z t= (N), =SPC m c R= (N) | Opens the Clock Report window. |
856865| 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=). |
857866
docs/manual/guide/06-dates-and-clocking.org +100 −14
@@ -208,14 +208,21 @@ Effort appears in column view and in clock tables with =:properties ("Effort")=.
208208
209209Clocking records the time you work on an entry as =CLOCK:= lines in its =LOGBOOK= drawer.
210210
211| Command | Org command | Emacs, Doom | Mac | Doom leader | Speed key |
212|----------------------+--------------------+-----------------+--------+-------------+-----------|
213| Clock In | =org-clock-in= | =C-c C-x C-i= | =⌃⌘I= | =SPC m c i= | =I= |
214| Clock Out | =org-clock-out= | =C-c C-x C-o= | =⌃⇧⌘I= | =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= | =⌃⌘J= | =SPC m c g= | |
217
218The Mac preset has no key for Cancel Clock; run it 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]]).
211| Command | Org command | Emacs, Doom | Mac | Doom leader | Speed key |
212|-----------------------------+-------------------------------+-----------------+---------+-------------+-----------|
213| Clock In | =org-clock-in= | =C-c C-x C-i= | =⌃⌘I= | =SPC m c i= | =I= |
214| Clock In to Recent Entry… | =org-clock-in= with =C-u= | | =⌃⌥⌘I= | | |
215| Clock In to Last Entry | =org-clock-in-last= | =C-c C-x C-x= | | =SPC m c I= | |
216| Clock Out | =org-clock-out= | =C-c C-x C-o= | =⌃⇧⌘I= | =SPC m c o= | =O= |
217| Cancel Clock | =org-clock-cancel= | =C-c C-x C-q= | | =SPC m c c= | |
218| Go to Clocked Entry | =org-clock-goto= | =C-c C-x C-j= | =⌃⌘J= | =SPC m c g= | |
219| Go to Recent Clocked Entry… | =org-clock-goto= with =C-u= | | =⌃⌥⌘J= | =SPC m c G= | |
220| Mark as Default Clock Task | =org-clock-mark-default-task= | | | =SPC m c d= | |
221| Resolve Open Clocks… | =org-resolve-clocks= | =C-c C-x C-z= | | =SPC m c r= | |
222
223The Emacs keys are Org's own, and work in the Doom preset too, as every =C-c= key does. Commands without a key in your preset are in the command palette and in Org ▸ Clock, which lists every clock command with its keys, followed by the recent entries. In the agenda, =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]]).
224
225Orgstar has no =C-u= forms of these commands. Clock In to Recent Entry… and Go to Recent Clocked Entry… stand for =C-u C-c C-x C-i= and =C-u C-c C-x C-j=.
219226
220227** Clocking in and out
221228
@@ -229,18 +236,19 @@ CLOCK: [2026-10-06 Tue 14:00]--[2026-10-06 Tue 15:30] => 1:30
229236:END:
230237#+END_SRC
231238
232- Only one clock runs at a time. Clocking in while another clock runs clocks that one out first.
239- Only one clock runs at a time. Clocking in while another clock runs clocks that one out first, and remembers it as the interrupted task (=i= in the selection below).
240- Clocking in on the entry whose clock is running changes nothing and says =Clock continues in "Write the report"=.
233241- =CLOCK:= lines outside a drawer move into the new drawer the first time you clock in on that entry.
234242- Clock Out completes the line with the end time and the duration in hours and minutes. Clocks of zero minutes are kept.
235243- 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.
244- Go to Clocked Entry opens the file and moves the caret to the running clock's line. With no clock running, it goes to the most recently clocked entry and says "No running clock, this is the most recently clocked task".
245
246With no clock running, Clock In first asks about open clocks; see Open clocks below.
237247
238Orgstar 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.
248Orgstar remembers the running clock and the clock history 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.
239249
240250These parts of Org's clocking are not implemented:
241251
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=);
244252- 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;
245253- 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;
246254- a =CLOCK_INTO_DRAWER= property or another drawer name: clocks always go into =LOGBOOK=.
@@ -253,7 +261,85 @@ While a clock runs, Orgstar shows it in three places, refreshed every 30 seconds
253261- the window's toolbar;
254262- the macOS menu bar, with the elapsed time.
255263
256The 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.
264The time shown is the time since you clocked in, not the entry's total. Each of them opens a menu with Clock Out, Cancel Clock and Go to Clocked Entry. The toolbar's menu also has Clock In to Recent Entry…, Go to Recent Clocked Entry… and the recent entries. The menu bar item also has Clock In to Recent Entry…, Clock Report and a Recent Entries section. Choosing a recent entry clocks in to it.
265
266** Recent entries
267
268Orgstar keeps a clock history, as =org-clock-history=. Every clock-in, including one from the agenda or a capture template, puts the entry first in the history and removes its other entries there. The history holds =org-clock-history-length= entries (5 by default); the oldest go first.
269
270Entries are found again after edits by their =ID= property, else by the heading's position among the file's headings together with its title, else by the title alone. An entry that can't be found is dropped from the history the next time an entry is added, and left out of the selection.
271
272Clock In to Recent Entry… and Go to Recent Clocked Entry… ask for an entry in the echo area, as =org-clock-select-task= does. Each line shows its key, the entry's category padded to 12 characters, and the heading with its TODO keyword and priority, under these sections:
273
274| Key | Section |
275|----------------------+-------------------------------------------------|
276| =d= | Default Task: the entry marked with Mark as Default Clock Task |
277| =i= | The task interrupted by starting the last one |
278| =c= | Current Clocking Task |
279| =1= … =9=, =A=, =B=, … | Recent Tasks, most recent first |
280
281Type a key to choose. =q=, =x= or =Esc= leave the question. With an empty history the commands say "No recent clock"; a key that isn't listed says "Invalid task choice X".
282
283Clock In to Last Entry clocks in to the first entry of the history, the same as =1=. With no clock running it says "Clocking back: Write the report (in work.org)"; with an empty history, "No last clock".
284
285Mark as Default Clock Task makes the heading at the caret the =d= entry and says "Default clock task: Write the report"; Org sets it without a message. As in Org, the default task lasts until you quit Orgstar.
286
287** Open clocks
288
289An open clock is a =CLOCK:= line with a start and no end. Org calls one that isn't the running clock dangling, for example after Orgstar or Emacs quit while it ran, or a line synced from another machine.
290
291When you clock in with no clock running, Orgstar first looks for open clocks in the org files of your folders and in the open buffers (=org-clock-auto-clock-resolution= set to =when-no-clock-is-running=), and asks about each one:
292
293#+BEGIN_EXAMPLE
294Dangling clock started 95 mins ago [jkKtTgGSscCiq]?
295#+END_EXAMPLE
296
297Resolve Open Clocks… asks the same about every open clock, the running one included, and says "No open clocks" when there are none. Clocking in from the agenda or a capture template doesn't look for open clocks first.
298
299Unlike Org, Orgstar doesn't show the clock's line while it asks; =j= opens it afterwards, except while clocking in.
300
301The answer is a key, as in =org-clock-resolve=. The idle time is the time since the clock started, for an open clock, or since you stopped using the Mac, for an idle one (see Idle time below).
302
303| Key | What happens to the =CLOCK:= line |
304|----------------+-----------------------------------------------------------------------------------------------------|
305| =j= | Nothing; after Resolve Open Clocks… or the idle question, the line opens in the editor to adjust by hand. |
306| =k= | Asks how many minutes of the idle time to keep, all of them by default. With all, the clock keeps running. With fewer, the line ends that many minutes after the idle time began, and a new clock starts now. |
307| =K= | Asks the same, then ends the line after the minutes kept and leaves you clocked out. |
308| =t= | Like =k=, but asks for the date and time you got distracted; the line ends then. |
309| =T= | Like =t=, then leaves you clocked out. |
310| =g= | Asks how many minutes ago you got back, all of the idle time by default. The line ends when the idle time began, and a new clock starts that many minutes ago. |
311| =G= | Like =g=, but leaves you clocked out: the line ends when the idle time began. |
312| =s= | Subtracts the idle time: the line ends when the idle time began, and a new clock starts now. |
313| =S= | Subtracts the idle time and leaves you clocked out. |
314| =C= | Removes the line, as though you never clocked in. |
315| =c=, =i=, =q=, =Esc= | Leaves the line as it is, keeping all the idle time. |
316
317- =k=, =K=, =g= and =G= ask for minutes with the default in the question, as =Keep how many minutes (default 95):=; Return with an empty field takes the default.
318- =t= and =T= ask =Date+time:= with Org's date syntax, as =14:00= or =-1h=.
319- If the clock ran less than 45 seconds before the idle time began, =s= removes the line and starts a new clock now, and =S= removes it. For an open clock all its time is idle time, so =s= and =S= remove its line.
320- Any other key asks again.
321
322While clocking in, an answer never restarts the clock it resolves: where a key would start a new clock or keep one running, the line ends instead, and the clock you asked for starts. Resolving an open clock that isn't running with =k= and all the minutes, outside a clock-in, makes it the running clock.
323
324When =K=, =T= or =S= ends a clock outside a clock-in, the next clock-in asks:
325
326#+BEGIN_EXAMPLE
327You stopped another clock 12 mins ago; start this one from then? (y or n)
328#+END_EXAMPLE
329
330=y= starts the new clock when the old one ended.
331
332** Idle time
333
334On the Mac, set =org-clock-idle-time= to a number of minutes, or turn on Settings ▸ Agenda ▸ "Ask what to do with idle time while clocked in", to be asked about time away from the Mac. The default, =0=, never asks, as =nil= does in Emacs.
335
336While a clock runs, Orgstar checks every minute how long the Mac has had no keyboard or mouse input, in any app. Past the limit, it requests your attention, which bounces its Dock icon while another app is active, and asks in the echo area:
337
338#+BEGIN_EXAMPLE
339Clocked in & idle for 17.3 mins [jkKtTgGSscCiq]?
340#+END_EXAMPLE
341
342The keys are those in the table above, with the idle time starting when input stopped. The iOS app has no idle detection.
257343
258344** Editing clock lines
259345
docs/manual/guide/09-links.org +3 −2
@@ -337,5 +337,6 @@ Insert Link. Setting up a browser bookmarklet, and =org-protocol://capture=, are
337337* On iOS
338338
339339The iOS app follows links: tap a link in the reader. Org files open in the app, and
340web, mail and other files go to the system. Storing and inserting links, the backlinks
341pane and inline images are Mac features. See [[file:14-ios.org][iOS]].
340web, mail and other files go to the system. The iOS editor shows inline images as the
341Mac does; the reader doesn't. Storing and inserting links and the backlinks pane are Mac
342features. See [[file:14-ios.org][iOS]].
docs/manual/guide/13-configuration.org +9 −2
@@ -106,9 +106,14 @@ See Themes and Fonts below.
106106| Include files in subfolders | On or off | Off | =agenda-include-subfolders= |
107107| Notify before timed agenda entries | On or off | On | =reminders= |
108108| N minutes before | 0 to 120 | 12 | =appt-message-warning-time= |
109| Ask what to do with idle time while clocked in | On or off | Off | =org-clock-idle-time= |
110| After N minutes without keyboard or mouse input | 1 to 240 | 15 when turned on | =org-clock-idle-time= |
111| Remember N recently clocked entries | 1 to 35 | 5 | =org-clock-history-length= |
109112
110113An entry's =APPT_WARNTIME= property overrides the lead time. The agenda is covered in [[file:07-agenda.org][The agenda]].
111114
115Turning on the idle question sets =org-clock-idle-time= to 15 minutes; turning it off sets it to =0=. The minutes stepper is disabled while the question is off. Idle time and the clock history are covered in [[file:06-dates-and-clocking.org][Dates and clocking]].
116
112117** Capture
113118
114119| Control | Default | Key |
@@ -179,6 +184,8 @@ A key you remove from the file goes back to its default. A key that isn't in the
179184| =org-agenda-span= | integer | =10= | Days the agenda shows. Mirrors =org-agenda-span=. |
180185| =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=. |
181186| =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=. |
187| =org-clock-idle-time= | integer | =0= | Minutes without keyboard or mouse input, with a clock running, before Orgstar asks what to do with the idle time. =0= never asks (Emacs's =nil=). Mac only. Mirrors =org-clock-idle-time=. |
188| =org-clock-history-length= | integer | =5= | How many recently clocked entries Orgstar remembers. Mirrors =org-clock-history-length=. |
182189
183190The default =org-todo-keywords= is the first sequence of Doom Emacs's default:
184191
@@ -423,7 +430,7 @@ Any other =org-= or =appt-= variable is listed as having no equivalent.
423430
424431Capture 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.
425432
426Key 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 "…")=; bindings with key vectors such as =[f5]= are skipped. In a Doom configuration, bindings without a state go to the =normal= state.
433Key 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=. The clock commands =org-clock-in=, =org-clock-out=, =org-clock-cancel=, =org-clock-goto=, =org-clock-in-last=, =org-resolve-clocks= and =org-clock-mark-default-task= map to Clock In, Clock Out, Cancel Clock, Go to Clocked Entry, Clock In to Last Entry, Resolve Open Clocks… and Mark as Default Clock Task. Keys must be a string or =(kbd "…")=; bindings with key vectors such as =[f5]= are skipped. In a Doom configuration, bindings without a state go to the =normal= state.
427434
428435** Limits of the Lisp reader
429436
@@ -550,4 +557,4 @@ The editor uses one font for everything: body text, headings, code and tables. C
550557- 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.
551558- =line-spacing= adds space between lines, in points.
552559
553On iPhone and iPad, the theme and font settings don't apply; see [[file:14-ios.org][iPhone and iPad]].
560On iPhone and iPad, the editor and reader use the same theme, read from the synced configuration folder. =font= applies when the family is installed on the device, otherwise the system's monospaced font is used, and =font-size= is the size at the default Dynamic Type setting, scaled with the size chosen on the device. The =selection= color and the =syntax-*= colors aren't used there. See [[file:14-ios.org][iPhone and iPad]].
docs/manual/guide/14-ios.org +52 −8
@@ -33,8 +33,9 @@ There is no way to open a single file from the Files app. Add the folder that co
3333Tap a file in Folders, Search or the agenda to read it.
3434
3535- 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.
36- The file opens with the visibility its =#+STARTUP= line and =VISIBILITY= properties ask for. Drawers and blocks are folded as =org-cycle-hide-drawer-startup= and =org-cycle-hide-block-startup= say, or as the file's =#+STARTUP= says (=hidedrawers=, =nohideblocks= and the like).
37- Text is styled as in the editor, in the theme's colours, font, size, line spacing and heading sizes, on the theme's background: TODO keywords, priorities, tags, emphasis, code, timestamps and links. Text can be selected and copied.
38- The reader doesn't apply =show-markup=, =org-pretty-entities=, =org-startup-indented=, inline images or truncated lines. Markup shows as typed, and bodies are indented by their heading's level.
3839- Tap a link to follow it. Links to headings and files in your folders open in the reader; web links open in the browser.
3940- The toolbar has Outline (a list of headings to jump to), Export, and Edit.
4041
@@ -42,13 +43,13 @@ Tap a file in Folders, Search or the agenda to read it.
4243
4344Tap Edit in the reader. The title shows the buffer name, with =•= while there are unsaved changes. The tab bar is hidden while you edit.
4445
45The 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 follows =spell-check= in =config.toml= and is off by default.
46The editor folds headings, drawers and blocks, styles text with the theme from the configuration folder (see Themes and display below), and runs the same Org commands as the Mac. Autocorrection, smart quotes and smart dashes are off; spell checking follows =spell-check= in =config.toml= and is off by default.
4647
4748The toolbar has:
4849
4950- Conflict :: shown while the file and your edits conflict; opens the conflict sheet.
5051- Undo
51- More :: Commands, Clock In, Export, Sync Conflict Copies, and Recovered Versions.
52- More :: Commands, Clock In, Show Markup, Recent Entries, Export, Sync Conflict Copies, and Recovered Versions.
5253
5354Messages from commands show at the top of the editor for a few seconds; tap one to dismiss it.
5455
@@ -58,6 +59,38 @@ The iOS app always saves automatically: one second after you stop typing, when y
5859
5960Files that aren't valid UTF-8 open read-only; commands that would change them say so.
6061
62** Themes and display
63
64The editor and the reader use the theme set in the configuration folder's =config.toml=, stacked as on the Mac: the default theme, then the theme file named by =theme-file=, then the colours in =[theme]=, =[theme.light]=, =[theme.dark]= and =[theme.todo]=. Colours follow the system's light or dark appearance. Problems in the theme show in the Settings tab with the other problems. A change to =config.toml= or the theme file applies as it syncs, to open editors too. See [[file:13-configuration.org][Configuration]] for the colour keys.
65
66- Font :: =font= when that family is installed on the device, otherwise the system's monospaced font.
67- Size :: =font-size= is the size at the default Dynamic Type setting, 13 pt by default. Text grows and shrinks with the text size chosen in the system Settings app.
68- Line spacing and headings :: =line-spacing= and =heading-size-step= apply as on the Mac.
69- Caret and selection :: the caret and the selection highlight take the theme's =cursor= colour; =selection= isn't used.
70
71The editor applies these display settings; the reader applies only the drawer and block folding. The startup settings (=org-cycle-hide-*-startup=, =org-startup-*=, =org-hide-leading-stars=) apply when a file opens, and a =#+STARTUP= keyword in the file overrides them, as on the Mac.
72
73| Setting | In the iOS editor | =#+STARTUP= |
74|----------------------------------+--------------------------------------------------------------------------------+----------------------------------|
75| =show-markup= | Link brackets and targets, and emphasis markers, show | |
76| =org-hide-emphasis-markers= | Emphasis markers hide while markup is hidden | |
77| =org-pretty-entities= | Entities and sub- and superscripts show as characters while markup is hidden | |
78| =org-cycle-hide-drawer-startup= | Drawers start folded | =hidedrawers=, =nohidedrawers= |
79| =org-cycle-hide-block-startup= | Blocks start folded | =hideblocks=, =nohideblocks= |
80| =org-startup-indented= | Bodies are indented under their headings | =indent=, =noindent= |
81| =org-hide-leading-stars= | Without indentation, only a heading's last star shows | =hidestars=, =showstars= |
82| =org-startup-with-inline-images= | Image links show as images | =inlineimages=, =noinlineimages= |
83| =org-startup-align-all-tables= | Every table is aligned | =align=, =noalign= |
84| =org-startup-truncated= | Long lines run off the right edge, and the editor scrolls sideways | |
85
86While markup is hidden, the line with the caret shows its markup, so you can edit it. More ▸ Show Markup, or Show or Hide Markup in Commands, switches markup in every editor. The switch lasts until =show-markup= in =config.toml= changes; then the file's value applies.
87
88The visibility from =#+STARTUP= applies first, then each heading's =VISIBILITY= property. As on the Mac, =VISIBILITY= properties apply only when =#+STARTUP= sets a visibility (=overview=, =content=, =showall= and the like).
89
90An image line shows its image, and the link text is hidden except on the caret's line. =#+ATTR_ORG: :width N= sets the width in points; images are never wider than the editor. Show or Hide Inline Images in Commands, or =C-c C-x C-v= on a hardware keyboard, switches images in the open file. Truncate or Wrap Long Lines in Commands, or =C-x x t=, switches long lines. See [[file:02-the-editor.org][The editor]] for which lines show as images.
91
92The Mac editor's code highlighting in src blocks (the =syntax-*= colours) and =#+STARTUP: shrink= aren't on iOS.
93
6194** The key bar
6295
6396A 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.
@@ -170,8 +203,15 @@ Clock in from the editor (More ▸ Clock In, or Clock In in Commands) or from an
170203- Clock Out
171204- Cancel Clock
172205- Go to Clocked Entry
206- Recent Entries
173207- Clock Report
174208
209Recent Entries, in the bar and in the editor's More menu, lists the recently clocked entries; tap one to clock in to it. It also has Clock In to Recent Entry… and Go to Recent Clocked Entry…, and is disabled until you have clocked in once. Commands has Clock In to Recent Entry…, Clock In to Last Entry, Go to Recent Clocked Entry…, Mark as Default Clock Task and Resolve Open Clocks….
210
211Clock questions open in a sheet: the task selection and the resolution keys as lists to tap, and minutes or a date and time as a field. Cancel answers nothing, as =q= does. Clocking in with no clock running first asks about open clocks in your folders, except from the agenda or a capture template; Resolve Open Clocks… asks about every open clock. Both work as on the Mac.
212
213The iOS app has no idle detection, so =org-clock-idle-time= doesn't apply. =org-clock-history-length= does.
214
175215Clock 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.
176216
177217See [[file:06-dates-and-clocking.org][Dates and clocking]].
@@ -231,20 +271,23 @@ Changes to the files apply as they sync, and again each time you return to the a
231271
232272Stop Using This Folder returns every setting to its default.
233273
234The In use section shows the TODO keywords, the agenda span and start (for example =10 days, starting 3 days before today=), the reminder lead time, and the capture template keys in effect.
274The In use section shows the TODO keywords, the agenda span and start (for example =10 days, starting 3 days before today=), the reminder lead time, the capture template keys, the theme (=Default=, or the theme file's name), and the font with its size. When =font= names a family that isn't installed on the device, Font shows the system's font with a note, as =System monospaced, 13 pt (JetBrains Mono isn't installed)=.
235275
236276These settings from =config.toml= apply on iOS:
237277
238278- =org-todo-keywords=, =org-list-allow-alphabetical=
239279- =org-tags-column=, =org-insert-heading-respect-content=, =org-M-RET-may-split-line=, =fill-column=
240- =org-hide-emphasis-markers= and =org-pretty-entities=, for how tag and table alignment and filling measure text, as on the Mac
280- =org-hide-emphasis-markers= and =org-pretty-entities=, for what hidden markup shows and for how tag and table alignment and filling measure text, as on the Mac
281- =show-markup=, =org-startup-indented=, =org-hide-leading-stars=, =org-startup-with-inline-images=, =org-startup-align-all-tables=, =org-startup-truncated=, =org-cycle-hide-drawer-startup=, =org-cycle-hide-block-startup=
282- =[theme]= (=font=, =font-size=, =line-spacing=, =heading-size-step=, =theme-file= and colours), =[theme.light]=, =[theme.dark]=, =[theme.todo]=
241283- =org-log-done=, =org-log-reschedule=, =org-log-redeadline=, =org-log-into-drawer=
242284- =org-use-speed-commands=, with a hardware keyboard
243285- =electric-pair-mode=, =spell-check=
244286- =org-agenda-span=, =org-agenda-start-day=, =agenda-include-subfolders=
245287- =reminders=, =appt-message-warning-time=
288- =org-clock-history-length=
246289
247=capture.toml= and =views.toml= in the folder apply too. Other settings, including =keymap=, =save=, the theme and font, and the startup settings (=org-startup-*=, =org-hide-leading-stars=, =org-cycle-hide-*-startup=), don't change what the iOS reader and editor show. See [[file:13-configuration.org][Configuration]].
290=capture.toml= and =views.toml= in the folder apply too. Other settings, including =keymap=, =save= and =org-clock-idle-time=, don't apply on iOS. See [[file:13-configuration.org][Configuration]].
248291
249292* Spotlight and Quick Look
250293
@@ -257,7 +300,8 @@ Quick Look in the Files app shows org files as the HTML export renders them.
257300- Running code blocks in languages other than Emacs Lisp, Emacs Lisp beyond Orgstar's interpreter, and tables that need Emacs.
258301- PDF, ODT, LaTeX and plain-text export.
259302- The Mac and Doom keymaps, Vim keys, and =keymap.toml=.
260- Themes, fonts and font sizes. The iOS editor uses the default theme and the system's monospaced font at the Dynamic Type size.
303- The =selection= colour, code highlighting in src blocks, and =#+STARTUP: shrink=.
304- Idle detection while a clock runs.
261305- Import from Emacs.
262306- The board, column view, the backlinks pane, and the buffer list and tab bar.
263307- The global capture hotkey and the Settings window.