docs/manual/guide/14-ios.org
311 lines · 23238 bytes
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
7The 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
14Files 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
18Orgstar 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
201. Open the Folders tab and tap Add Folder (the folder icon with a plus).
212. Choose a folder in the picker.
22
23Orgstar 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
25Files 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
27Orgstar 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
29There is no way to open a single file from the Files app. Add the folder that contains it.
30
31* The reader
32
33Tap 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 asks for, then each heading's =VISIBILITY= property when =#+STARTUP= sets a visibility. 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, links, and the code in src blocks. Text can be selected and copied.
38- The reader follows the editor's display settings (see Themes and display below): Show Markup, hidden emphasis markers, pretty entities, indentation, leading stars, inline images and truncated lines. Tables show at full width, without narrowed columns.
39- Tap a link to follow it. Links to headings and files in your folders open in the reader; web links open in the browser.
40- The toolbar has Outline (a list of headings to jump to), Export, and Edit.
41
42* The editor
43
44Tap Edit in the reader. The title shows the buffer name, with =•= while there are unsaved changes. The tab bar is hidden while you edit.
45
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.
47
48The toolbar has:
49
50- Conflict :: shown while the file and your edits conflict; opens the conflict sheet.
51- Undo
52- More :: Commands, Clock In, Show Markup, Recent Entries, Export, Sync Conflict Copies, and Recovered Versions.
53
54Messages from commands show at the top of the editor for a few seconds; tap one to dismiss it.
55
56** Saving
57
58The 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.
59
60Files that aren't valid UTF-8 open read-only; commands that would change them say so.
61
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 selection highlight takes the theme's =selection= colour, over block bands too; the caret and the selection handles take =cursor=.
70
71The editor and the reader apply these display settings; only the editor aligns tables when a file opens. 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 and in the reader. 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
92Code in src blocks is highlighted in the theme's =syntax-*= colours, as on the Mac (see [[file:11-code-blocks.org][Code blocks]]).
93
94Table columns with width cookies narrow as on the Mac: =#+STARTUP: shrink= narrows them when the file opens, and Shrink or Expand Table Column (=C-c TAB=), Shrink Table Columns with Widths and Expand Table Columns are in Commands when the caret is in a table. See [[file:10-tables.org][Tables]].
95
96** The key bar
97
98A 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.
99
100| Button | Key |
101|----------------------+-------------|
102| Commands | the command list |
103| Fold | =TAB= |
104| Overview | =S-TAB= |
105| Promote | =M-<left>= |
106| Demote | =M-<right>= |
107| Move up | =M-<up>= |
108| Move down | =M-<down>= |
109| New heading or item | =M-RET= |
110| TODO | =C-c C-t= |
111| Act at point | =C-c C-c= |
112| Schedule | =C-c C-s= |
113| Deadline | =C-c C-d= |
114| Tags | =C-c C-q= |
115| Open link | =C-c C-o= |
116| Hide keyboard | |
117
118** Commands
119
120Commands (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.
121
122When a command asks a question, a sheet opens:
123
124- 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.
125- Date questions have a calendar as well as the field; Org's date syntax (=+2d=, =fri=, =14:00=) works in the field.
126- 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.
127
128Cancel answers nothing, as =C-g= does.
129
130=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.
131
132** Hardware keyboard
133
134With a hardware keyboard, the editor uses the Emacs keymap, whatever =keymap= is set to on the Mac. =keymap.toml= isn't read on iOS.
135
136- Option works as Meta when it begins a binding (=M-RET=, =M-<left>=). Otherwise Option types characters as usual.
137- Command shortcuts are the system's.
138- 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.
139- 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=.
140- A sequence bound to a command that can't run at the caret, or that the iOS app doesn't have, shows why, as on the Mac: the command's own message (such as =Not on a heading=), or =Not available on iOS yet=.
141
142See [[file:03-keys.org][Keys and commands]] for the Emacs bindings.
143
144* Search
145
146The Search tab finds:
147
148- Files :: up to eight org files whose path matches what you type, ranked as Quick Open ranks them on the Mac.
149- Headings :: headings whose title or text contains your words, including unsaved edits in the open file.
150
151Tap a result to open it in the reader. A heading result opens at that heading.
152
153* The agenda
154
155The 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.
156
157- 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.
158- 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.
159- Tap an entry to read it, at its heading.
160- Swipe a TODO entry to the left to mark it done with the first done keyword of its sequence, as the file defines its keywords (with the default keywords, its =#+TODO= lines and its setup files).
161- Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile…, and Archive….
162
163Commands 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.
164
165See [[file:07-agenda.org][The agenda]] for the views and matches.
166
167* Capture
168
169Tap Capture (the pencil icon) in the Agenda or Folders tab.
170
1711. Choose a template. The first template is selected.
1722. Answer the template's questions (=%^{…}=, =%^g=, =%^t= and the like), then tap Continue. A template without questions skips this step.
1733. Edit the text. The caret is where =%?= was.
1744. Tap File.
175
176Templates 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.
177
178=org-protocol://capture= links opened on the device open the capture sheet with the link's template, URL, title and text. When the link names a template key that =capture.toml= doesn't have, the sheet starts on the first template and shows =No capture template "x"= with the key.
179
180** From the share sheet
181
182Orgstar appears in the share sheet of other apps for a web link or text.
183
1841. Share a page or text and choose Orgstar.
1852. Choose a template, edit the link's title, and add text.
1863. Tap Capture.
187
188The 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.
189
190** From Shortcuts
191
192Shortcuts has a Capture to Orgstar action, and Siri responds to "Capture to Orgstar". The action takes:
193
194- Text :: the text to capture, available to the template as =%i=.
195- Template Key :: a key from =capture.toml=; empty uses the first template.
196
197The 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.
198
199See [[file:08-capture.org][Capture]] for the template format.
200
201* Clocking
202
203Clock 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:
204
205- Clock Out
206- Cancel Clock
207- Go to Clocked Entry
208- Recent Entries
209- Clock Report
210
211Recent 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….
212
213Clock 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, from the editor, an agenda entry's Clock In or a capture template with =clock-in=; Resolve Open Clocks… asks about every open clock. Both work as on the Mac.
214
215The iOS app has no idle detection, so =org-clock-idle-time= doesn't apply. =org-clock-history-length= does.
216
217Clock 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.
218
219See [[file:06-dates-and-clocking.org][Dates and clocking]].
220
221* Reminders
222
223With =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.
224
225iOS 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.
226
227* Export
228
229Export (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.
230
231PDF, ODT, LaTeX and plain-text export need Emacs and aren't available on iOS. See [[file:12-export.org][Export]].
232
233* Code blocks and tables
234
235=C-c C-c= on a source block asks whether to run it (yes, no, or always for this block), as on the Mac.
236
237On iOS, only Emacs Lisp blocks run. Orgstar evaluates them with its own Emacs Lisp interpreter, which covers a subset of the language. Other results:
238
239- A block in another language: "/language/ blocks need the Mac to run."
240- Emacs Lisp the interpreter doesn't have: "This block uses Emacs Lisp that runs only in Emacs, on the Mac."
241
242Table 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.
243
244Tangling (=C-c C-v t=, in Commands) works on iOS and writes the tangled files next to the org file, or where =:tangle= says.
245
246See [[file:11-code-blocks.org][Code blocks]] and [[file:10-tables.org][Tables]].
247
248* Conflicts and versions
249
250When 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:
251
252- Keep Mine :: write your version over the disk version.
253- Use Disk Version :: replace your edits with the disk version.
254- Merge with Markers :: put both versions in the editor, with conflicting lines between =<<<<<<<= and =>>>>>>>= markers, to fix and save.
255- Later :: decide later. The Conflict button in the toolbar opens the sheet again. Nothing is saved until you decide.
256
257The version you don't keep goes to the recovery folder.
258
259More ▸ 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.
260
261More ▸ 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.
262
263See [[file:15-alongside-emacs.org][Working alongside Emacs and other tools]] for how merging and recovery work.
264
265* Settings
266
267The 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.
268
2691. Open the Settings tab.
2702. Tap Choose Folder… and choose the folder.
271
272Changes 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=.
273
274Stop Using This Folder returns every setting to its default.
275
276The 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)=.
277
278These settings from =config.toml= apply on iOS:
279
280- =org-todo-keywords=, =org-list-allow-alphabetical=
281- =org-tags-column=, =org-insert-heading-respect-content=, =org-M-RET-may-split-line=, =fill-column=
282- =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
283- =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=
284- =[theme]= (=font=, =font-size=, =line-spacing=, =heading-size-step=, =theme-file= and colours), =[theme.light]=, =[theme.dark]=, =[theme.todo]=
285- =org-log-done=, =org-log-reschedule=, =org-log-redeadline=, =org-log-into-drawer=
286- =org-use-speed-commands=, with a hardware keyboard
287- =electric-pair-mode=, =spell-check=
288- =org-agenda-span=, =org-agenda-start-day=, =agenda-include-subfolders=
289- =reminders=, =appt-message-warning-time=
290- =org-clock-history-length=
291
292=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]].
293
294* Spotlight and Quick Look
295
296Orgstar 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.
297
298Quick Look in the Files app shows org files as the HTML export renders them.
299
300* What the Mac has that iOS doesn't
301
302- Running code blocks in languages other than Emacs Lisp, Emacs Lisp beyond Orgstar's interpreter, and tables that need Emacs.
303- PDF, ODT, LaTeX and plain-text export.
304- The Mac and Doom keymaps, Vim keys, and =keymap.toml=.
305- Idle detection while a clock runs.
306- Import from Emacs.
307- The board, column view, the backlinks pane, and the buffer list and tab bar.
308- The global capture hotkey and the Settings window.
309- Explicit saving.
310
311Commands the iOS app can't carry out show a message instead, such as "Not available on iOS yet" or "/Command/ isn't available on iPhone and iPad." Only tables that need Emacs say that Emacs is needed. Commands that only appear on the Mac, such as Refile from the editor, aren't listed in Commands; refile and archive from the agenda instead.