docs/manual/guide/13-configuration.org
607 lines · 57749 bytes
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
7Orgstar 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
12The 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, and reloads it when you edit it there.
13
14The 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
26When 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
33Saving the buffer applies the file, the same as saving it from another editor.
34
35** Problems in the files
36
37If =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
44A 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
48Open 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
63Automatic 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| Long lines run off the edge instead of wrapping (org-startup-truncated) | On or off | Off | =org-startup-truncated= |
75| Emacs hides emphasis markers (org-hide-emphasis-markers) | On or off | On | =org-hide-emphasis-markers= |
76| Emacs shows entities as characters (org-pretty-entities) | On or off | On | =org-pretty-entities= |
77| Default TODO keywords | Text in =#+TODO= syntax, one sequence per line | See below | =org-todo-keywords= |
78| Entries can't be done before their TODO children (org-enforce-todo-dependencies) | On or off | Off | =org-enforce-todo-dependencies= |
79| Entries can't be done with unchecked boxes (org-enforce-todo-checkbox-dependencies) | On or off | Off | =org-enforce-todo-checkbox-dependencies= |
80
81The 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.
82
83The Tags picker offers two values. =config.toml= accepts any integer; with a value other than =-77= or =0= the picker shows no selection.
84
85The long-lines switch applies to files as they open; View ▸ Truncate or Wrap Long Lines switches the file in front.
86
87Default 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.
88
89The two dependency switches are described under Dependencies in [[file:05-todos-and-tags.org][TODOs and tags]].
90
91** Appearance
92
93| Control | Range | Default | Key |
94|---------------------------------+-----------------------------------------------+--------------------+---------------------|
95| Font | System monospaced, or any installed monospaced family | System monospaced | =font= |
96| Size | 8 to 36 pt | 13 pt | =font-size= |
97| Line spacing | 0 to 16 pt | 2 pt | =line-spacing= |
98| Headings grow by N pt a level | 0 to 8 pt | 1 pt | =heading-size-step= |
99| Colors: Edit in config.toml | Opens =config.toml= | | |
100| Colors: Show Default Theme | Opens =default-theme.toml= | | |
101
102See Themes and Fonts below.
103
104** Agenda
105
106| Control | Range | Default | Key |
107|-------------------------------------+------------------------+--------------+-----------------------------|
108| Agenda shows N days | 1 to 366 | 10 | =org-agenda-span= |
109| Agenda starts N days before today | 0 to 14 days before | 3 days | =org-agenda-start-day= |
110| Include files in subfolders | On or off | Off | =agenda-include-subfolders= |
111| Show days without entries | On or off | Off | =org-agenda-show-all-dates= |
112| Blocked entries | Dimmed; Hidden; Shown as usual | Dimmed | =org-agenda-dim-blocked-tasks= |
113| Show events from Calendar | On or off | Off | =calendar-events= |
114| A checkbox for each calendar | On or off | All on | =calendar-event-calendars= |
115| Notify before timed agenda entries | On or off | On | =reminders= |
116| N minutes before | 0 to 120 | 12 | =appt-message-warning-time= |
117| Ask what to do with idle time while clocked in | On or off | Off | =org-clock-idle-time= |
118| After N minutes without keyboard or mouse input | 1 to 240 | 15 when turned on | =org-clock-idle-time= |
119| Remember N recently clocked entries | 1 to 35 | 5 | =org-clock-history-length= |
120
121An entry's =APPT_WARNTIME= property overrides the lead time. The agenda is covered in [[file:07-agenda.org][The agenda]].
122
123The calendar checkboxes appear once Show events from Calendar is on and Orgstar may read your calendars; turning the switch on asks for that access. While every calendar is checked, =calendar-event-calendars= is empty, so calendars you add later show too. The last checked calendar can't be unchecked; turn off Show events from Calendar instead.
124
125Turning 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]].
126
127** Capture
128
129| Control | Default | Key |
130|----------------------------------------+---------+-------------------------|
131| ⌃⌥Space opens Capture from any app | On | =global-capture-hotkey= |
132
133The footer shows the path of =capture.toml=. Templates are covered in [[file:08-capture.org][Capture]].
134
135** Settings only in config.toml
136
137These settings have no control in the Settings window. Some are in the View menu.
138
139| Key | Also in |
140|----------------------------------+----------------------------|
141| =org-log-done= | |
142| =org-log-reschedule= | |
143| =org-log-redeadline= | |
144| =org-log-into-drawer= | |
145| =org-startup-indented= | |
146| =org-hide-leading-stars= | |
147| =org-startup-align-all-tables= | |
148| =org-startup-with-inline-images= | |
149| =org-cycle-hide-drawer-startup= | |
150| =org-cycle-hide-block-startup= | |
151| =org-use-speed-commands= | |
152| =spell-check= | |
153| =electric-pair-mode= | |
154| =display-line-numbers-type= | View ▸ Show Line Numbers (=⇧⌘L=) |
155| =tab-bar= | View ▸ Show Tab Bar |
156| =show-markup= | View ▸ Show Markup (=⇧⌘M=) |
157| =ignored-folders= | |
158| =org-agenda-skip-scheduled-if-done= | |
159| =org-agenda-skip-deadline-if-done= | |
160| =org-agenda-search-view-always-boolean= | |
161| =org-agenda-search-view-force-full-words= | |
162| =[org-agenda-prefix-format]= | |
163| =theme-file= | |
164
165* config.toml reference
166
167Settings 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]=.
168
169A key you remove from the file goes back to its default. A key that isn't in the table below is reported as unknown.
170
171** Top level
172
173| Key | Type | Default | Effect |
174|--------------------------------------+---------+---------+----------------------------------------------------------------------------------------------------------------|
175| =fill-column= | integer | =80= | The column =M-q= fills to. Mirrors =fill-column=. |
176| =org-tags-column= | integer | =-77= | Negative: tags end at that column. =0=: one space between title and tags. Mirrors =org-tags-column=. |
177| =org-insert-heading-respect-content= | boolean | =true= | =M-RET= adds the new heading after the current subtree. Mirrors =org-insert-heading-respect-content=. |
178| =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=. |
179| =org-list-allow-alphabetical= | boolean | =true= | =a.=, =b)=, =A.= are list bullets. Mirrors =org-list-allow-alphabetical=. |
180| =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=. |
181| =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=. |
182| =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=. |
183| =org-log-done= | string | ="nil"= | =nil=, =time= (a =CLOSED= timestamp) or =note= (=CLOSED= and a note). Mirrors =org-log-done=. |
184| =org-log-reschedule= | string | ="nil"= | =nil=, =time= or =note=: log changing or removing a =SCHEDULED= date. Mirrors =org-log-reschedule=. |
185| =org-log-redeadline= | string | ="nil"= | =nil=, =time= or =note=: log changing or removing a =DEADLINE=. Mirrors =org-log-redeadline=. |
186| =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=. |
187| =org-enforce-todo-dependencies= | boolean | =false= | An entry can't become done while a descendant has an active TODO keyword, or under an =ORDERED= parent while an earlier sibling has one. Mirrors =org-enforce-todo-dependencies=. |
188| =org-enforce-todo-checkbox-dependencies= | boolean | =false= | An entry can't become done while its text has an unchecked checkbox. Mirrors =org-enforce-todo-checkbox-dependencies=. |
189| =org-startup-indented= | boolean | =true= | Indent bodies under their headings, as =org-indent-mode=. =#+STARTUP: indent= / =noindent= override it. Mirrors =org-startup-indented=. |
190| =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=. |
191| =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=. |
192| =org-startup-truncated= | boolean | =false= | Long lines run off the right edge instead of wrapping. Mirrors =org-startup-truncated=. |
193| =spell-check= | boolean | =false= | Check spelling while typing, outside code, links, dates, tags and keywords. |
194| =electric-pair-mode= | boolean | =true= | Type brackets, =<>= and quotes in pairs. Mirrors =electric-pair-mode=. |
195| =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=. |
196| =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=. |
197| =org-cycle-hide-drawer-startup= | boolean | =true= | Fold drawers when a file opens. =#+STARTUP: hidedrawers= / =nohidedrawers= override it. Mirrors =org-cycle-hide-drawer-startup=. |
198| =org-cycle-hide-block-startup= | boolean | =false= | Fold blocks when a file opens. =#+STARTUP: hideblocks= / =nohideblocks= override it. Mirrors =org-cycle-hide-block-startup=. |
199| =display-line-numbers-type= | boolean | =true= | Line numbers in the editor's gutter. Orgstar numbers lines absolutely; there is no relative or visual mode. |
200| =org-agenda-span= | integer | =10= | Days the agenda shows. Mirrors =org-agenda-span=. |
201| =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=. |
202| =org-agenda-show-all-dates= | boolean | =false= | Show days without entries in the agenda; today always shows. Emacs's default is =t=. Mirrors =org-agenda-show-all-dates=. |
203| =org-agenda-skip-scheduled-if-done= | boolean | =false= | Leave a done entry's scheduled date out of the agenda, even on its own day. Mirrors =org-agenda-skip-scheduled-if-done=. |
204| =org-agenda-skip-deadline-if-done= | boolean | =false= | Leave a done entry's deadline out of the agenda, even on its own day. Mirrors =org-agenda-skip-deadline-if-done=. |
205| =org-agenda-search-view-always-boolean= | boolean | =false= | The agenda's text search reads every string as =+word -word {regexp}= snippets, never as a phrase. Mirrors =org-agenda-search-view-always-boolean=. |
206| =org-agenda-search-view-force-full-words= | boolean | =false= | Text search snippets match whole words only, as a leading =:= does. Mirrors =org-agenda-search-view-force-full-words=. |
207| =org-agenda-dim-blocked-tasks= | string | ="t"= | =t= dims entries the two enforce settings block, =invisible= hides them (entries blocked only by checkboxes are still dimmed), =nil= shows them as usual. Mirrors =org-agenda-dim-blocked-tasks=. |
208| =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=. |
209| =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=. |
210| =org-clock-history-length= | integer | =5= | How many recently clocked entries Orgstar remembers. Mirrors =org-clock-history-length=. |
211
212The default =org-todo-keywords= is the first sequence of Doom Emacs's default:
213
214#+BEGIN_SRC toml
215org-todo-keywords = "TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) | DONE(d) KILL(k)"
216#+END_SRC
217
218The 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.
219
220** [org-agenda-prefix-format]
221
222| Key | Type | Default | Effect |
223|----------+--------+--------------------------+-------------------------------------|
224| =agenda= | string | =" %i %-12:c%?-12t% s"= | Prefix of lines in the day view |
225| =todo= | string | =" %i %-12:c"= | Prefix of lines in the TODO list |
226| =tags= | string | =" %i %-12:c"= | Prefix of tag and property matches |
227
228These mirror the entries of =org-agenda-prefix-format=. The agenda's rows don't show a prefix, so the formats don't change how the agenda looks. The one effect left is that a time written in heading text leaves the title when the =agenda= format contains =%t=. See [[file:07-agenda.org][The agenda]].
229
230** [theme]
231
232| Key | Type | Default | Effect |
233|---------------------+---------+---------+----------------------------------------------------------------------------------------------|
234| =font= | string | =""= | A font family. =""= uses the system's monospaced font. |
235| =font-size= | integer | =13= | Points. |
236| =line-spacing= | integer | =2= | Points between lines. |
237| =heading-size-step= | integer | =1= | Points a heading is larger than the level below. Level 4 and deeper are body size. |
238| =theme-file= | string | =""= | A theme in its own file in the configuration folder, applied under the colors in =config.toml=. |
239
240Any other key in =[theme]= is a color; see Themes below.
241
242** [orgstar]
243
244| Key | Type | Default | Effect |
245|-----------------------------+---------+---------------+-----------------------------------------------------------------------------------------|
246| =save= | string | ="automatic"= | =automatic= (one second after typing stops) or =explicit= (only with =⌘S=). |
247| =keymap= | string | ="emacs"= | =emacs=, =mac= or =doom=. Your own bindings go in =keymap.toml=. |
248| =option-as-meta= | string | ="left"= | Which Option key is Meta: =left=, =right=, =both= or =none=. |
249| =tab-bar= | boolean | =false= | A tab for each open buffer above the editor. |
250| =show-markup= | boolean | =false= | Show link brackets and emphasis markers. |
251| =show-hidden-files= | boolean | =true= | List dotfiles and dot folders in your folders. |
252| =ignored-folders= | string | see below | Folder names never listed or searched, separated by spaces. |
253| =agenda-include-subfolders= | boolean | =false= | The agenda reads org files in subfolders too. |
254| =reminders= | boolean | =true= | Notify before timed entries. |
255| =calendar-events= | boolean | =false= | Show events from Calendar in the agenda, read-only. |
256| =calendar-event-calendars= | string | =""= | The calendars whose events show, by title or identifier, separated by commas; =""= for all. |
257| =global-capture-hotkey= | boolean | =true= | =⌃⌥Space= opens Capture from any app. |
258
259The default =ignored-folders= is:
260
261#+BEGIN_SRC toml
262ignored-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"
263#+END_SRC
264
265** An example
266
267#+BEGIN_SRC toml
268fill-column = 72
269org-tags-column = 0
270org-todo-keywords = "TODO(t) NEXT(n) WAIT(w@/!) | DONE(d!) CANCELED(c@)"
271org-log-done = "time"
272org-log-into-drawer = "LOGBOOK"
273org-startup-truncated = true
274org-agenda-span = 7
275org-agenda-start-day = "+0d"
276
277[theme]
278font = "JetBrains Mono"
279font-size = 14
280link = "#0a7ea4"
281
282[theme.todo]
283WAIT = "#bf8700"
284
285[orgstar]
286keymap = "doom"
287save = "explicit"
288#+END_SRC
289
290** Names from earlier versions
291
292Earlier versions used keys such as =editor.fill-column= and =agenda.span=. Orgstar still reads them. At launch, each such key in the file is renamed in place to its current name and moved to its current section; the rest of the file, and the comments on those lines, stay as they are. When a setting is in the file under both names, the current name wins and the old line is removed. A section the move leaves empty is removed. A file that lacks a whole section (such as =[theme]=) gets that section added at the end.
293
294* keymap.toml and capture.toml
295
296=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]].
297
298#+BEGIN_SRC toml
299[[bind]]
300keys = "C-c a"
301command = "app.agenda"
302#+END_SRC
303
304=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]].
305
306=views.toml= holds =[[view]]= tables for the agenda; see [[file:07-agenda.org][The agenda]].
307
308* In-file settings
309
310Keyword lines in a file set options for that file, as in Emacs. Orgstar reads them outside blocks; for =#+STARTUP= only keyword lines count, so a =#+STARTUP= line inside a paragraph or a block changes nothing: not folding, logging or inline images.
311
312** Keywords Orgstar reads
313
314| Keyword | Effect |
315|-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------|
316| =#+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. |
317| =#+TYP_TODO= | A type sequence. As in Org, type sequences come first, then =#+TODO=, then =#+SEQ_TODO=. |
318| =#+PRIORITIES= | Three values: highest, lowest, default, as =A C B= or =1 5 3=. The default is =A C B=. |
319| =#+STARTUP= | Startup options; see below. |
320| =#+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. |
321| =#+FILETAGS= | Tags every heading in the file inherits, as =:work:project:=. |
322| =#+PROPERTY= | A file-wide property, as =#+PROPERTY: header-args :results output=. =NAME+= appends to the value. |
323| =#+CATEGORY= | The file's category in the agenda. Without it the category is the file name. |
324| =#+ARCHIVE= | Where =C-c C-x C-a= archives to. The default is =%s_archive::=. |
325| =#+COLUMNS= | The default column view format. |
326| =#+LINK= | A link abbreviation, as =#+LINK: gh https://github.com/%s=. |
327| =#+CONSTANTS= | Constants for table formulas, as =#+CONSTANTS: c=299792458 pi=3.14=. |
328| =#+SETUPFILE= | A file whose keyword lines count as this file's; see below. |
329| =#+TITLE=, =#+AUTHOR=, =#+DESCRIPTION= | Used by export, Quick Look and Spotlight. |
330| =#+OPTIONS=, =#+MACRO=, =#+INCLUDE=, =#+EXCLUDE_TAGS=, =#+SELECT_TAGS= | Export settings; see [[file:12-export.org][Export]]. |
331
332#+BEGIN_SRC org
333,#+TODO: TODO(t) NEXT(n) WAIT(w@/!) | DONE(d!) CANCELED(c@)
334,#+PRIORITIES: A E C
335,#+STARTUP: content logdrawer
336,#+FILETAGS: :work:
337,#+CATEGORY: acme
338#+END_SRC
339
340After 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.
341
342** #+STARTUP options
343
344| Option | Effect |
345|-----------------------------------------------+--------------------------------------------------------------------------|
346| =overview=, =fold= | Only top-level headings show when the file opens. |
347| =content= | All headings show, no bodies. |
348| =showall=, =nofold= | Everything shows. |
349| =show2levels= … =show5levels= (any =showNlevels=) | Headings down to level N show. |
350| =showeverything= | Everything shows, including drawers and blocks; =VISIBILITY= properties are ignored. |
351| =hidedrawers=, =nohidedrawers= | Fold or don't fold drawers at startup. |
352| =hideblocks=, =nohideblocks= | Fold or don't fold blocks at startup. |
353| =indent=, =noindent= | Virtual indentation on or off. |
354| =hidestars=, =showstars= | Hide leading stars or show them. |
355| =align=, =noalign= | Align every table when the file opens, or don't. |
356| =inlineimages=, =noinlineimages= | Show image links as images, or don't. |
357| =shrink= | Shrink table columns that have a width cookie. |
358| =logdone=, =lognotedone=, =nologdone= | Record a time, a note, or nothing when an entry becomes done. |
359| =logrepeat=, =lognoterepeat=, =nologrepeat= | The same, when a repeating entry is completed. |
360| =logreschedule=, =lognotereschedule=, =nologreschedule= | The same, when a scheduled date changes. |
361| =logredeadline=, =lognoteredeadline=, =nologredeadline= | The same, when a deadline changes. |
362| =logdrawer=, =nologdrawer= | Notes go in =LOGBOOK=, or under the heading. |
363
364After the startup visibility, Orgstar applies each heading's =VISIBILITY= property and folds subtrees tagged =ARCHIVE=, unless =showeverything= is set.
365
366Completion 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.
367
368** Setup files
369
370=#+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:
371
372- 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.
373- A setup file can name further setup files; each is read once, and a file never reads itself.
374- URLs (anything starting with =scheme://=) aren't fetched.
375- A setup file that can't be read, or isn't UTF-8, is skipped without a message.
376
377Keywords 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.
378
379* Import from Emacs
380
381Import 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.
382
383** Running it
384
3851. Open Settings ▸ General and click Import from Emacs…, or run Import from Emacs… from the command palette (=⇧⌘P=).
3862. 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.
3873. 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.
3884. 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.
3895. Click Import. The sheet then summarizes what was imported and any problems.
390
391What Import does with each kind of item:
392
393- Settings are written to =config.toml=.
394- Folders are added to the sidebar if they exist and aren't there already.
395- Capture templates are appended to =capture.toml=, except those whose key is already in the file.
396- Key bindings are appended to =keymap.toml=, except those already in the file with the same keys, command and state. Running the import again adds no duplicates.
397
398The 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.
399
400A literate configuration (=config.org=) isn't read. Point Choose… at the =config.el= it tangles to.
401
402** Doom Emacs
403
404A 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.
405
406A Doom configuration, or any configuration that enables =evil=, adds =keymap = "doom"=.
407
408** What it reads
409
410Orgstar reads the configuration as Lisp data; it never runs it. It looks at these forms:
411
412| Form | What Orgstar takes |
413|----------------------------------------------------------------------+---------------------------------------------------------------------------------|
414| =setq=, =setq-default=, =setq!=, =setopt=, =csetq= | Each variable and value |
415| =defvar=, =defcustom= | The value, below every other assignment |
416| =custom-set-variables= | Each quoted =(variable value)= |
417| =after!=, =with-eval-after-load=, =eval-after-load= | The forms inside, ranked above plain assignments |
418| =use-package=, =use-package!= | Forms in =:config= and =:init=, and pairs in =:custom= |
419| =progn=, =when=, =unless=, =if=, =let=, =let*=, =with-no-warnings= | The forms inside. Conditions aren't evaluated, so every branch is read. |
420| =map!= (Doom) | Bindings, with =:leader= (=SPC=), =:localleader= (=SPC m=), =:prefix=, and state keywords such as =:n=, =:i=, =:v=, =:nv= |
421| =define-key=, =keymap-set=, =global-set-key=, =keymap-global-set= | Bindings |
422| =evil-define-key=, =evil-define-key*= | Bindings in the =normal=, =insert= or =visual= state |
423
424When 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.
425
426Orgstar 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.
427
428Only 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.
429
430** How variables map
431
432| Emacs variable | Becomes |
433|--------------------------------------------------------------------+-----------------------------------------------------------------------------------------------|
434| =fill-column=, =org-tags-column=, =appt-message-warning-time= | The same key, when the value is a number |
435| =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= |
436| =org-hide-drawer-startup=, =org-hide-block-startup= | =org-cycle-hide-drawer-startup=, =org-cycle-hide-block-startup= |
437| =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 |
438| =org-agenda-prefix-format= | =[org-agenda-prefix-format]=: a string sets all three views; an alist sets =agenda=, =todo= and =tags= |
439| =org-log-done=, =org-log-reschedule=, =org-log-redeadline= | The same key: =nil=, =time= (also =t=) or =note= |
440| =org-log-into-drawer= | A string as given; =t= becomes ="LOGBOOK"=; =nil= becomes =""= |
441| =display-line-numbers-type= | =true= unless =nil=; =relative= and =visual= become absolute numbers |
442| =org-agenda-span= | A number, or =day= (1), =week= (7), =fortnight= (14), =month= (30), =year= (365) |
443| =org-clock-idle-time= | Minutes; =nil= becomes =0= (never) |
444| =org-clock-history-length= | The same key, when the value is a positive number |
445| =org-agenda-start-day= | A day offset such as ="-3d"=; =nil= becomes ="+0d"=. Other forms aren't supported. |
446| =org-todo-keywords= | =org-todo-keywords=, one line per sequence. Keywords with spaces are left out; =type= sequences are read as sequences. |
447| =org-directory= | A folder to add |
448| =org-agenda-files= | A folder for each entry; for a =.org= file, its folder |
449| =org-capture-templates= | Templates for =capture.toml=; see below |
450| =doom-font= | =font= and =font-size=, from =(font-spec :family … :size …)= or ="Family-14"= |
451| =doom-variable-pitch-font= | Not imported: Orgstar uses one font |
452| =doom-theme= | Not imported: set colors under =[theme]= |
453| =evil-mode= in use, or Doom | =keymap = "doom"= |
454
455Any other =org-= or =appt-= variable is listed as having no equivalent.
456
457Capture 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.
458
459Key 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.
460
461** Limits of the Lisp reader
462
463- Comments (=;=) are skipped. Strings understand =\n=, =\t=, =\"= and line continuations; other escapes give the character itself.
464- =#'= reads as =function=. Other =#= syntax is read as a symbol, so forms using it aren't understood.
465- 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.
466- 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.
467
468* Themes
469
470Orgstar has one built-in theme, the default theme, with light and dark colors after GitHub's light and dark themes for text and code. TODO keywords, priorities and the agenda's statuses use the system's red, orange, blue and green, as iOS and macOS show them. You change it by setting colors in =config.toml=, or by keeping a theme in its own file.
471
472Colors are strings in the form ="#rrggbb"= or ="#rrggbbaa"=. They go in these tables:
473
474| Table | Effect |
475|----------------+------------------------------------------------------------------------|
476| =[theme]= | Sets a color for both light and dark appearance |
477| =[theme.light]= | Sets a color for light appearance only |
478| =[theme.dark]= | Sets a color for dark appearance only |
479| =[theme.todo]= | Colors TODO keywords by name, in both appearances, as =org-todo-keyword-faces= |
480| =[theme.category]= | Colors agenda categories by name, in both appearances |
481
482#+BEGIN_SRC toml
483[theme]
484heading-1 = "#005cc5"
485
486[theme.dark]
487background = "#1e1e1e"
488foreground = "#d4d4d4"
489
490[theme.todo]
491WAIT = "#bf8700"
492PROJ = "#8250df"
493
494[theme.category]
495work = "#0a66d8"
496#+END_SRC
497
498A keyword without its own color takes its class's color. Case doesn't matter in these lists:
499
500| Class | Key | Keywords |
501|--------------+------------------+----------------------------------------------------------------------------------|
502| Under way | =todo-next= | =NEXT=, =STRT=, =START=, =STARTED=, =DOING=, =ACTIVE=, =INPROGRESS=, =IN-PROGRESS= |
503| On hold | =todo-waiting= | =WAIT=, =WAITING=, =HOLD=, =ONHOLD=, =BLOCKED=, =DEFERRED=, =SOMEDAY=, =MAYBE= |
504| Cancelled | =todo-cancelled= | Done keywords =KILL=, =KILLED=, =CANCELLED=, =CANCELED=, =CANCEL=, =SKIPPED=, =SKIP=, =ABORTED=, =NO=, =WONTFIX= |
505| Other open | =todo= | Any other keyword that isn't done |
506| Other done | =done= | Any other done keyword |
507
508The classes color keywords in the editors, the iOS reader, the agenda and its widgets.
509
510A category without its own color gets a hue worked out from its name, the same on every run and device, at a lightness that reads on the appearance's background.
511
512=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.
513
514** Theme files
515
516To keep a theme in its own file, put it in the configuration folder with the same tables (=[theme]=, =[theme.light]=, =[theme.dark]=, =[theme.todo]=, =[theme.category]=) and name it in =config.toml=:
517
518#+BEGIN_SRC toml
519[theme]
520theme-file = "solarized.toml"
521#+END_SRC
522
523The colors stack in this order, each over the one before: the default theme, the theme file, then the colors in =config.toml=. The path is relative to the configuration folder and may name a subfolder, as =themes/solarized.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.
524
525** Color keys
526
527| Key | Colors |
528|-------------------------+--------------------------------------------------------------|
529| =background= | the editor's background |
530| =foreground= | body text |
531| =cursor= | the caret |
532| =selection= | selected text's background |
533| =heading-1= … =heading-7= | headings of that level |
534| =heading-8= | level 8 and deeper headings |
535| =todo= | TODO keywords not yet done |
536| =todo-next= | keywords of work under way: =NEXT=, =STRT= and the others above |
537| =todo-waiting= | keywords of work on hold: =WAIT=, =HOLD= and the others above |
538| =done= | DONE keywords |
539| =todo-cancelled= | done keywords that cancel: =KILL=, =CANCELLED= and the others above |
540| =priority= | =[#A]= cookies; in the agenda, priorities other than A, B and C |
541| =priority-a= | agenda: priority A |
542| =priority-b= | agenda: priority B |
543| =priority-c= | agenda: priority C |
544| =tags= | =:tags:= |
545| =link= | links |
546| =timestamp= | timestamps |
547| =code= | =~code~= and inline source |
548| =verbatim= | ~=verbatim=~ |
549| =inline-background= | behind =~code~= and ~=verbatim=~ |
550| =markup= | link brackets and emphasis markers |
551| =comment= | comments |
552| =keyword= | =#+KEYWORD= lines |
553| =metadata= | planning lines, drawers, properties and clocks |
554| =special= | footnotes, statistics cookies, targets, macros and LaTeX |
555| =block-background= | the band behind blocks |
556| =block-delimiter= | =#+begin_= and =#+end_= lines |
557| =table= | tables |
558| =line-number= | line numbers |
559| =line-number-current= | the caret's line number |
560| =syntax-keyword= | code: keywords |
561| =syntax-string= | code: strings |
562| =syntax-comment= | code: comments |
563| =syntax-function= | code: functions |
564| =syntax-type= | code: types and modules |
565| =syntax-number= | code: numbers, constants and escapes |
566| =syntax-property= | code: properties, attributes and tags |
567| =syntax-label= | code: labels |
568| =sidebar-background= | the folder sidebar and the outline |
569| =sidebar-foreground= | file and heading names there |
570| =sidebar-header= | folder names there |
571| =modeline-background= | the modeline and message line |
572| =modeline-foreground= | modeline text |
573| =modeline-highlight= | the outline path and the clock in the modeline |
574| =state-normal= | the NORMAL tag (Doom keys) |
575| =state-insert= | the INSERT tag |
576| =state-visual= | the VISUAL and V-LINE tags |
577| =agenda-background= | the agenda and board; the iOS widgets |
578| =agenda-date= | agenda day headers after today |
579| =agenda-today= | today's header and the now line |
580| =agenda-time= | times and statuses of agenda rows with the normal status |
581| =agenda-category= | categories |
582| =agenda-overdue= | agenda: the status of entries past their deadline or scheduled date, and the Overdue group |
583| =agenda-due-soon= | agenda: the status of deadlines due today or coming up |
584| =agenda-event= | agenda: calendar events whose calendar has no color |
585| =habit-clear= | habit graph: not due yet |
586| =habit-ready= | habit graph: due |
587| =habit-alert= | habit graph: due today, last chance |
588| =habit-overdue= | habit graph: overdue |
589
590The 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.
591
592An 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.
593
594* Appearance
595
596Orgstar 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]=.
597
598* Fonts
599
600The editor uses one font for everything: body text, headings, code and tables. Choose it in Settings ▸ Appearance or with =font= under =[theme]=.
601
602- 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.
603- =font-size= is the body size, at least 6 points.
604- 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.
605- =line-spacing= adds space between lines, in points.
606
607On 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, the =cursor= color and the =syntax-*= colors apply there too. See [[file:14-ios.org][iPhone and iPad]].