Commit `d924123ec2`

d924123ec2d6bf58446f39623ad2f689971d8c27

parent: bba622a330

Verified · cmc

cmc <hello@cleberg.net> · 2026-10-09 02:49 UTC

Update the manual for the closed gaps

Running C, C++, D, Java, Fortran and Clojure blocks, their header
arguments, results and missing-program messages; output list results.
Mac keys for Cancel Clock, Recalculate Table Row and the single tangles.
Open-clock resolution on agenda and capture clock-in. Doom snipe
character folding and counts, M-q in visual block state. iOS src block
highlighting, narrowed table columns, reader display settings and the
selection colour.

Layout: unified · split

docs/manual/guide/03-keys.org +8 −8

 | =$=, =<end>= | End of the line; with a count, of the line count − 1 lines down. |
 | =g_= | Last non-blank of the line. |
 | =gg=, =G= | First line, last line; with a count, that line. The column is kept (=evil-start-of-line= nil). |
-| =f= /x/, =F= /x/, =t= /x/, =T= /x/ | To, or to just before, the next or previous /x/ on the line. These are one-character snipes, as Doom's =evil-snipe-override-mode= makes them: a lowercase /x/ matches either case, an uppercase one only itself; =t= and =T= skip a match right next to the caret; =f SPC= and =t SPC= skip a run of blanks after the caret and stop at the last blank before the next word, or just before it. Accented variants of /x/ don't match (=evil-snipe-char-fold= is not supported). |
+| =f= /x/, =F= /x/, =t= /x/, =T= /x/ | To, or to just before, the next or previous /x/ on the line. These are one-character snipes, as Doom's =evil-snipe-override-mode= makes them. /x/ also matches its accented and other variants, as Doom's =evil-snipe-char-fold= makes it: =a= matches =à=, =À=, =ª= and =ａ=. A lowercase /x/ matches either case, a capital only capitals; =t= and =T= skip a match right next to the caret; =f SPC= and =t SPC= skip a run of blanks after the caret and stop at the last blank before the next word, or just before it. |
-| =;=, =,= | Repeats the last snipe (=s=, =S=, =f=, =F=, =t= or =T=), forward or reversed. A repeat searches all the text the window shows, so it can go past the caret's line (=evil-snipe-repeat-scope=, as Doom sets it). Right after a snipe, its own key repeats it: =f= goes on in the same direction and =F= reverses, and the same for =t= and =T= and for =s= and =S=. A count before that repeating key is not supported. |
+| =;=, =,= | Repeats the last snipe (=s=, =S=, =f=, =F=, =t= or =T=), forward or reversed. A repeat searches all the text the window shows, so it can go past the caret's line (=evil-snipe-repeat-scope=, as Doom sets it). Right after a snipe, its own key repeats it: =f= goes on in the same direction and =F= reverses, and the same for =t= and =T= and for =s= and =S=. A count typed right after a snipe ends this: the key after the count starts a new snipe with that count, so =f a 2 f a= goes to the next /a/, then to the second /a/ after it. |
-| =s= /xy/, =S= /xy/ | evil-snipe: to the next or previous /xy/ on the line. All-lowercase /xy/ matches case-insensitively. Not available after an operator. |
+| =s= /xy/, =S= /xy/ | evil-snipe: to the next or previous /xy/ on the line. Each character matches its variants as for =f=, and /xy/ without a capital matches case-insensitively. =SPC= and =TAB= are read as a space and a tab. Not available after an operator. |
 | =%= | The bracket matching the next =()=, =[]= or ={}= on the line. |
 | ={=, =}= | Previous, next blank line. |
 | =/=, =?= | Asks in the echo area for a regular expression and searches forward or backward, wrapping around the file. |
 | =gc= /motion/ | Comments or uncomments lines with =#= (=evilnc-comment-operator=). =gcc= acts on lines. See [[*Commenting][Commenting]]. |
 | =gq= /motion/, =gw= /motion/ | Fills the paragraphs in the motion's lines to the fill column, as Fill Paragraph does; other elements in the lines are left alone. =gq= leaves the caret on the first non-blank of the last line, =gw= where it was. Extra spaces between words and at the ends of lines are kept, as Doom fills without squeezing them. =gqq= and =gww= act on lines. |
-=M-q= runs Fill Paragraph in normal, insert and visual state. In visual and visual-line state it fills every paragraph the selection touches and leaves the caret where it was; if the text changed, the editor returns to normal state, otherwise the selection stays.
+=M-q= runs Fill Paragraph in normal, insert and visual state. In visual and visual-line state it fills every paragraph the selection touches and leaves the caret where it was. In visual-block state it fills the paragraph at the caret, as evil does with =transient-mark-mode= off. In each, if the text changed, the editor returns to normal state, otherwise the selection stays.
 Counts multiply: =2d3w= deletes six words. Doubling an operator with a count acts on that many lines: =3dd=.
 | 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=). |
 | 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=). |
 | Clock Out (=app.clock.out=) | =C-c C-x C-o= | =⌃⇧⌘I= | =SPC m c o= (N) | Stops the clock (=org-clock-out=). |
-| 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=). |
+| Cancel Clock (=app.clock.cancel=) | =C-c C-x C-q= | =⌃⌘K= | =SPC m c c= (N) | Stops the clock and removes the running clock line (=org-clock-cancel=). |
 | 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=). |
 | 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=). |
 | 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=). |
 | Insert Table Row (=org.table.insert-row=) | =M-S-<down>= | =⌃⌥⌘↓= | =M-J=, =SPC m b i r= (N) | In a table, inserts a row (=org-table-insert-row=). |
 | Delete Table Row (=org.table.kill-row=) | =M-S-<up>= | =⌃⌥⌘↑= | =M-K=, =SPC m b d r= (N) | In a table, deletes the row (=org-table-kill-row=). |
 | Insert Table Rule (=org.table.insert-hline=) | =C-c -= | =⌃⌘-= | =SPC m b -= (N), =SPC m b i h= (N) | In a table, inserts a horizontal rule (=org-table-insert-hline=). |
-| Recalculate Table Row (=org.table.recalc=) | =C-c *= | — | — | In a table, recalculates the current row (=org-table-recalculate=). |
+| Recalculate Table Row (=org.table.recalc=) | =C-c *= | =⌃⌘*= | — | In a table, recalculates the current row (=org-table-recalculate=). On a US keyboard, =⌃⌘*= is typed =⌃⇧⌘8=. |
 | Recalculate Table (=org.table.recalc-all=) | =C-c C-c= | =⌃⌘X= | =SPC m b r= (N) | Recalculates the whole table; =C-c C-c= and =⌃⌘X= run it on a =#+TBLFM= line (=org-table-recalculate= with =C-u=). |
 | Set Column Formula (=org.table.column-formula=) | ~C-c =~ | — | — | Asks for the column's formula, offering the stored one (=org-table-eval-formula=). |
 | Edit Table Field (=org.table.edit-field=) | =C-c `= | — | — | In a table, edits the field in a separate editor (=org-table-edit-field=). |
 | Act at Point (=org.dwim=) | — | — | =RET= (N) | Doom's =+org/dwim-at-point=: follows a link, runs a src block, recalculates or aligns a table, toggles a checkbox, or switches a heading between TODO and done. |
 | Run Source Block (=org.babel.execute=) | =C-c C-c= | =⌃⌘X= | — | In a src block, runs it and inserts the results (=org-babel-execute-src-block=). |
 | Tangle File (=org.babel.tangle=) | =C-c C-v t=, =C-c C-v C-t= | =⌃⌘V= | — | Writes the file's src blocks to their tangle targets (=org-babel-tangle=). |
+| Tangle Block (=org.babel.tangle-block=) | — | =⌃⇧⌘V= | — | Tangles only the src block at point (=org-babel-tangle= with =C-u=). |
+| Tangle Block's Target (=org.babel.tangle-target=) | — | =⌃⌥⌘V= | — | Tangles every block that writes to the same file as the block at point (=org-babel-tangle= with =C-u C-u=). |
 | Insert Structure Template (=org.structure-template=) | =C-c C-,= | — | — | Asks for a block type and inserts the block, or wraps the selection (=org-insert-structure-template=). |
 | Edit Block (=org.edit-special=) | =C-c '= | =⌃⌘'= | =SPC m '= (N) | Edits the src, example or export block at point in a separate editor (=org-edit-special=). |
 | Show or Hide Markup (=app.toggle-markup=) | Shows or hides link brackets and emphasis markers. View ▸ Show Markup, =⇧⌘M=. |
 | Show or Hide Line Numbers (=app.toggle-line-numbers=) | Shows or hides line numbers. View ▸ Show Line Numbers, =⇧⌘L=. |
 | Show or Hide Tab Bar (=app.toggle-tab-bar=) | Shows or hides the tab bar. View ▸ Show Tab Bar. |
-| Tangle Block (=org.babel.tangle-block=) | Tangles only the src block at point (=org-babel-tangle= with =C-u=). |
-| Tangle Block's Target (=org.babel.tangle-target=) | Tangles every block that writes to the same file as the block at point (=org-babel-tangle= with =C-u C-u=). |
 | Column View of File (=org.columns.global=) | Shows the column view of the whole file (=org-columns= with =C-u=). |
 | Remove Schedule (=org.schedule.remove=) | Removes =SCHEDULED= (=org-schedule= with =C-u=). |
 | Remove Deadline (=org.deadline.remove=) | Removes =DEADLINE= (=org-deadline= with =C-u=). |

docs/manual/guide/06-dates-and-clocking.org +6 −4

 | Clock In to Recent Entry…   | =org-clock-in= with =C-u=     |                 | =⌃⌥⌘I=  |             |           |
 | Clock In to Last Entry      | =org-clock-in-last=           | =C-c C-x C-x=   |         | =SPC m c I= |           |
 | Clock Out                   | =org-clock-out=               | =C-c C-x C-o=   | =⌃⇧⌘I=  | =SPC m c o= | =O=       |
-| Cancel Clock                | =org-clock-cancel=            | =C-c C-x C-q=   |         | =SPC m c c= |           |
+| Cancel Clock                | =org-clock-cancel=            | =C-c C-x C-q=   | =⌃⌘K=   | =SPC m c c= |           |
 | Go to Clocked Entry         | =org-clock-goto=              | =C-c C-x C-j=   | =⌃⌘J=   | =SPC m c g= |           |
 | Go to Recent Clocked Entry… | =org-clock-goto= with =C-u=   |                 | =⌃⌥⌘J=  | =SPC m c G= |           |
 | Mark as Default Clock Task  | =org-clock-mark-default-task= |                 |         | =SPC m c d= |           |
 - Cancel Clock removes the running clock's line, and the drawer if it is left empty.
 - 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".
-With no clock running, Clock In first asks about open clocks; see Open clocks below.
+With no clock running, Clock In first asks about open clocks; see Open clocks below. So do the agenda's =I= and a capture template's =clock-in=.
 Orgstar 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.
 Dangling clock started 95 mins ago [jkKtTgGSscCiq]?
 #+END_EXAMPLE
-Resolve 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.
+Clocking in from the agenda (=I=) or from a capture template with =clock-in= asks too, as =org-clock-in= does in Org. A capture template resolves open clocks as of when the capture began, which is when its clock starts. On the Mac, the questions for an agenda or capture clock-in are asked in the main window's echo area.
+Resolve Open Clocks… asks the same about every open clock, the running one included, and says "No open clocks" when there are none.
 Unlike Org, Orgstar doesn't show the clock's line while it asks; =j= opens it afterwards, except while clocking in.
 While 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.
-When =K=, =T= or =S= ends a clock outside a clock-in, the next clock-in asks:
+When =K=, =T= or =S= ends a clock outside a clock-in, the next clock-in, from the agenda or a capture template too, asks:
 #+BEGIN_EXAMPLE
 You stopped another clock 12 mins ago; start this one from then? (y or n)

docs/manual/guide/07-agenda.org +2

	@@ -383,6 +383,8 @@ Select a line with the arrow keys or the mouse. These keys work in the agenda wi
383		383
384	=C-c C-w= brings the main window forward and asks for the target there, where the target list is searchable.	384	=C-c C-w= brings the main window forward and asks for the target there, where the target list is searchable.
385		385
		386	=I= clocks in as Clock In does, so with no clock running it first asks about open clocks, in the main window's echo area. See [[file:06-dates-and-clocking.org][Dates, scheduling and clocking]].
		387
386	Each action finds the entry again by its heading line before it changes anything, so an action on a line whose entry has since moved or changed reports that rather than editing the wrong text. Edits go through the open buffer when the file is open, and through the file otherwise.	388	Each action finds the entry again by its heading line before it changes anything, so an action on a line whose entry has since moved or changed reports that rather than editing the wrong text. Edits go through the open buffer when the file is open, and through the file otherwise.
387		389
388	** Bulk actions	390	** Bulk actions

docs/manual/guide/08-capture.org +1 −1

	@@ -139,7 +139,7 @@ Placement follows =org-capture-place-entry= and its siblings, including how blan
139		139
140	** Clocking while capturing	140	** Clocking while capturing
141		141
142	With =clock-in = true=, the captured entry gets a clock entry from when the template was filled to when you filed it, as Emacs clocks in while the capture buffer is open and out on finalize. With =clock-keep = true= as well, the clock keeps running in the new entry. With =clock-resume = true=, the clock that was running before the capture starts again after filing. See [[file:06-dates-and-clocking.org][Dates, scheduling and clocking]].	142	With =clock-in = true=, the captured entry gets a clock entry from when the template was filled to when you filed it, as Emacs clocks in while the capture buffer is open and out on finalize. With =clock-keep = true= as well, the clock keeps running in the new entry. With =clock-resume = true=, the clock that was running before the capture starts again after filing. With no clock running, clocking in to the entry first asks about open clocks, as Clock In does, as of when the capture began; on the Mac the questions are in the main window's echo area. See [[file:06-dates-and-clocking.org][Dates, scheduling and clocking]].
143		143
144	* Template escapes	144	* Template escapes
145		145

docs/manual/guide/10-tables.org +7 −2

 field widens its column again, as editing Org's overlays does. =#+STARTUP: shrink=
 narrows every column with a width cookie when the file opens.
+The iOS editor narrows columns the same way, with =#+STARTUP: shrink= and the three
+commands, which are in Commands when the caret is in a table. The iOS reader shows
+tables at full width.
 * Importing and exporting
 | Command                                | Org command        |
 | Command                          | Org command                       | Emacs                         | Mac                         | Doom                                |
 |----------------------------------+-----------------------------------+-------------------------------+-----------------------------+-------------------------------------|
 | Recalculate Table                | =org-table-recalculate= with =C-u= | =C-c C-c= on =#+TBLFM:=      | =⌃⌘X= on =#+TBLFM:=         | =SPC m b r=, =C-c C-c= on =#+TBLFM:= |
-| Recalculate Table Row            | =org-table-recalculate=           | =C-c *=                       | Org ▸ Recalculate Table Row | =C-c *=                             |
+| Recalculate Table Row            | =org-table-recalculate=           | =C-c *=                       | =⌃⌘*= (=⌃⇧⌘8= on a US keyboard) | =C-c *=                             |
 In Doom's normal state, =RET= in a table recalculates it when it has a =#+TBLFM:=
 line and aligns it otherwise; on a =#+TBLFM:= line it recalculates.
 The iOS app evaluates formulas natively with the same engine. Tables that need Emacs
 are not recalculated there; the app reports =This table needs Emacs, which runs on the
-Mac= with the reason. Table import and export are Mac only. See
+Mac= with the reason. Table import and export are Mac only. Narrow columns work in the
+editor, as described under /Narrow columns/. See
 [[file:14-ios.org][iOS]].

docs/manual/guide/11-code-blocks.org +71 −18

 ** Syntax highlighting
-On the Mac, the code in a block is highlighted in the editor and in the block editor. Highlighting uses tree-sitter grammars for these language names:
+The code in a block is highlighted in the editor on the Mac and on iOS, in the iOS reader, and in the Mac's block editor, in the theme's =syntax-*= colours. Highlighting uses tree-sitter grammars for these language names:
 | Language names                  | Grammar    |
 |---------------------------------+------------|
 | =toml=, =conf-toml=             | TOML       |
 | =lua=                           | Lua        |
-Names are matched without regard to case. Blocks in any other language show as plain monospaced text. The iOS app does not highlight code.
+Names are matched without regard to case. Blocks in any other language show as plain monospaced text.
 * Editing a block apart
 | =R=                                                              | =Rscript -=                                         |
 | =awk=                                                            | =awk -f /dev/stdin=                                 |
 | =dot=, =plantuml=, =mermaid=                                     | =dot=, =plantuml=, =mmdc=; see Graphics below       |
+| =C=, =C++=, =cpp=, =D=, =java=, =fortran=, =clojure=             | A compiler, or =bb= or =clojure=; see Compiled languages below |
 For =ruby=, =js=, =javascript=, =R= and =awk=, =:cmd= names a different program. These languages always return their standard output, and =:var= is refused for them.
 A run that takes longer than five minutes is stopped. Runs in a =:session= have no time limit.
+** Compiled languages
+On the Mac, =C=, =C++=, =cpp=, =D=, =java=, =fortran= and =clojure= blocks run as Org's =ob-C=, =ob-java=, =ob-fortran= and =ob-clojure= run them. Orgstar writes the body, expanded as tangling writes it (see Tangling below), to a source file in a temporary folder, compiles it and runs the program in the file's folder or =:dir=, with a newline on standard input. What the compiler prints is dropped.
+| Language        | Commands                                                                         |
+|-----------------+----------------------------------------------------------------------------------|
+| =C=             | =gcc -o bin FLAGS src LIBS=, then =bin CMDLINE=                                  |
+| =C++=, =cpp=    | =g++ -o bin FLAGS src LIBS=, then =bin CMDLINE=                                  |
+| =D=             | =rdmd FLAGS src CMDLINE=, which compiles and runs                                |
+| =fortran=       | =gfortran -o bin FLAGS src=, then =bin CMDLINE=                                  |
+| =java=          | =javac CMPFLAG Class.java=, then =java -cp dir CMDLINE Class CMDARGS=            |
+| =clojure=       | =bb src= (babashka) when =bb= is installed, otherwise =clojure -M src=           |
+FLAGS is =:flags=, LIBS is =:libs= or the inherited =LIBS= property, and CMDLINE is =:cmdline=. A Lisp list works for =:flags= and =:libs=; its items are joined with spaces.
+| Argument            | Languages             | Effect                                                                                  |
+|---------------------+-----------------------+-----------------------------------------------------------------------------------------|
+| =:flags=            | C, C++, D, Fortran    | Compiler options.                                                                       |
+| =:libs=             | C, C++                | Libraries, after the source file, such as =-lm=.                                        |
+| =:cmdline=          | C, C++, D, Fortran    | The program's arguments.                                                                |
+| =:cmdline=          | Java                  | Options for =java=, before the class name.                                              |
+| =:cmdargs=          | Java                  | The program's arguments.                                                                |
+| =:cmpflag=          | Java                  | Options for =javac=.                                                                    |
+| =:javac=, =:java=   | Java                  | The compiler and runtime commands, with options; =javac= and =java= by default.         |
+| =:classname=        | Java                  | The class to run; a dotted name gives its package.                                      |
+| =:backend=          | Clojure               | =babashka= runs =bb=, =clojure-cli= runs =clojure -M=.                                  |
+| =:includes=, =:defines=, =:namespaces=, =:imports=, =:main=, =:prologue=, =:epilogue=, =:ns=, =:var= | as for tangling | What the expansion writes; see Tangling below. |
+When =:imports= is absent, a D block reads the =IMPORTS= property where it is, and a Fortran block without =:includes= or =:defines= reads the =INCLUDES= and =DEFINES= properties, as Org does when it runs them. =:session= is ignored for these languages, as in Org.
+Java's defaults are =:results output= and =:dir .= (=org-babel-default-header-args:java=). The =.java= and =.class= files are written in the folder the block runs in, under folders for the class's package (=org/ex/Hello.java= for =:classname org.ex.Hello=), and are left there. The class is =:classname=, the body's own class with its =package=, or =Main=.
+Any other Clojure backend is refused: "The cider backend for clojure needs Emacs; Orgstar runs babashka or clojure-cli."
+Before a run, Orgstar checks that each program it needs is on the =PATH= described above. If not, the block fails with "gcc isn't installed, so C blocks can't run." (=g++= for C++, =rdmd=, =gfortran=, or the commands =:javac= and =:java= name). For Clojure without a =:backend=, the message is "Neither bb nor clojure is installed, so clojure blocks can't run."
 ** The trust prompt
 Before a block runs, Orgstar asks "Run this /language/ block? (yes, no, always)", as =org-confirm-babel-evaluate= does.
 | Python in a =:session=  | The value of the last expression.                                                             |
 | Emacs Lisp              | The value of the last form.                                                                   |
 | =ruby=, =js=, =R=, =awk= | Standard output, always.                                                                     |
+| C, C++, D               | Standard output without its common indentation, read as a table as for shells.                |
+| Fortran                 | The same, with blank space around the output trimmed.                                         |
+| Java                    | With =:results value=, what the body returns; it runs as =main=, so it needs =return=. Lists and arrays become tables, with =null= rows as rules, and a returned string is written without its quotes. Java's default is =:results output=. |
+| Clojure                 | The value of the last form as Clojure prints it. A number, or a string without its quotes, is written as that; vectors, lists and maps are written as printed, not as tables. |
 Python lists of lists become tables, with =None= rows as rules. A flat list becomes a one-row table. Emacs Lisp lists become tables the same way, with =hline= for rules. Numbers are written the way Emacs prints them.
 =:results verbatim= on an Emacs Lisp value writes it as =prin1= would, with quotes around strings.
+With =:results output list=, the list made from the output is written as an example, in lines such as =: - a=, as Org writes it:
+#+BEGIN_SRC org
+,#+begin_src sh :results output list
+printf 'a\nb\n'
+,#+end_src
+,#+RESULTS:
+: - a
+: - b
+#+END_SRC
 ** Result formats
 | Word     | Written as                                                     |
 | =:separator=      | text                                           | Column separator for tables in shell variables; a tab by default.                          |
 | =:hline-string=   | text                                           | What a rule becomes in a shell variable with =:hlines yes=; =hline= by default.            |
 | =:dir=            | folder                                         | Folder to run in, relative to the file's folder. It must exist.                            |
-| =:session=        | name, =none=                                   | Runs in a long-lived interpreter (see Sessions below). Shells and Python only.             |
+| =:session=        | name, =none=                                   | Runs in a long-lived interpreter (see Sessions below). Shells and Python only; ignored for the compiled languages. |
 | =:stdin=          | name of a table, list or block                 | Feeds the value to standard input. Shells only.                                            |
-| =:cmdline=        | arguments                                      | Command-line arguments. Shells, =dot=, =plantuml= and =mermaid= only.                      |
+| =:cmdline=        | arguments                                      | Command-line arguments. Shells, =dot=, =plantuml=, =mermaid= and the compiled languages only. |
 | =:shebang=        | =#!…= line                                     | Runs the block as a script with this first line. Shells only; also used by tangling.       |
 | =:padline=        | =no=                                           | No blank line after the shebang of a script, or between tangled blocks.                    |
 | =:python=         | program                                        | Python interpreter to use.                                                                 |
 | Argument                    | Refused for                                     | Message                                                  |
 |-----------------------------+-------------------------------------------------+----------------------------------------------------------|
-| =:prologue=, =:epilogue=, =:post= | every language when running (tangling uses =:prologue= and =:epilogue=) | "=:prologue= isn't supported yet; nothing was run."      |
+| =:prologue=, =:epilogue=, =:post= | every language when running, except =:prologue= and =:epilogue= for the compiled languages (tangling uses =:prologue= and =:epilogue=) | "=:prologue= isn't supported yet; nothing was run."      |
 | =:stdin=, =:shebang=        | languages other than shells                     | "=:stdin= isn't supported yet; nothing was run."         |
-| =:cmdline=                  | languages other than shells and graphics        | "=:cmdline= isn't supported for /language/ yet; nothing was run." |
+| =:cmdline=                  | languages other than shells, graphics and the compiled languages | "=:cmdline= isn't supported for /language/ yet; nothing was run." |
-| =:session=                  | languages other than shells and Python          | "=:session= isn't supported for /language/ yet; nothing was run." |
+| =:session=                  | languages other than shells, Python and the compiled languages, which ignore it | "=:session= isn't supported for /language/ yet; nothing was run." |
 | =:var=                      | =ruby=, =js=, =javascript=, =R=, =awk=          | "=:var= isn't supported for /language/ yet."             |
 * Variables
 | Python     | literal                 | list                           | list of lists, =None= for rules                              |
 | Emacs Lisp | =let=-bound value       | list                           | list of lists, =hline= for rules                             |
-For =shell= blocks, the bash forms are used when =SHELL= is bash.
+For =shell= blocks, the bash forms are used when =SHELL= is bash. C, C++, D, Java, Fortran and Clojure blocks get declarations as their expansion writes them; see Tangling below.
 #+BEGIN_SRC org
 ,#+NAME: kv
 - The first row is taken off as column names when =:colnames yes=, or when the table's only rule is under the first row. =:colnames no= keeps it as data.
 - The first column is taken off as row names when =:rownames yes=.
-If the result is a table of the same width (for columns) or height (for rows), the names are put back on it (=org-babel-reassemble-table=). =:colnames= and =:rownames= can also be Lisp lists of names to put on the result, such as =:colnames '("x" "y")=.
+If the result is a table of the same width (for columns) or height (for rows), the names are put back on it (=org-babel-reassemble-table=). Clojure results don't get them back, as in Org. =:colnames= and =:rownames= can also be Lisp lists of names to put on the result, such as =:colnames '("x" "y")=.
 #+BEGIN_SRC org
 ,#+NAME: tbl
 Change the block or its arguments and it runs again. Results inserted with =append= or =prepend= carry no hash. Inline blocks are not cached. A cached block that has Lisp in its header arguments the interpreter cannot evaluate is refused.
-C, C++, D, Fortran and Clojure blocks don't run in Orgstar, but their hash is taken over the body as tangling expands it (see Tangling below), as Emacs does. A result Emacs wrote for such a block with =:cache yes= is recognised as current, and =C-c C-c= shows it.
+The hash of a C, C++, D, Java, Fortran or Clojure block is taken over the body as the language expands it (see Tangling below), with the =IMPORTS=, =INCLUDES= and =DEFINES= properties where the block is, and Java's default header arguments, as Emacs does. A result Emacs wrote for such a block with =:cache yes= is recognised as current, and =C-c C-c= shows it.
 * Noweb
 Tangling writes source blocks to the files their =:tangle= argument names (=org-babel-tangle=).
-| Command                 | Emacs and Doom              | Mac    | What it tangles                                   |
+| Command                 | Emacs and Doom              | Mac     | What it tangles                                   |
-|-------------------------+-----------------------------+--------+---------------------------------------------------|
+|-------------------------+-----------------------------+---------+---------------------------------------------------|
-| Tangle File             | =C-c C-v t=, =C-c C-v C-t=  | =⌃⌘V=  | Every block in the file                            |
+| Tangle File             | =C-c C-v t=, =C-c C-v C-t=  | =⌃⌘V=   | Every block in the file                            |
-| Tangle Block            | none                        | none   | The block at the caret (Emacs: =C-u C-c C-v t=)    |
+| Tangle Block            | none                        | =⌃⇧⌘V=  | The block at the caret (Emacs: =C-u C-c C-v t=)    |
-| Tangle Block's Target   | none                        | none   | Every block going to the same file as the one at the caret (Emacs: =C-u C-u C-c C-v t=) |
+| Tangle Block's Target   | none                        | =⌃⌥⌘V=  | Every block going to the same file as the one at the caret (Emacs: =C-u C-u C-c C-v t=) |
 All three are in the Org menu and the command palette. Tangling uses the text in the editor, saved or not, and the message area reports "Tangled /N/ code blocks from /file/".
 | Language       | Written                                                                                                      |
 |----------------+--------------------------------------------------------------------------------------------------------------|
 | =C=, =C++=, =cpp= | =#include= lines from =:includes=, =#define= lines from =:defines=, =using namespace= lines from =:namespaces=, the =:var= declarations with table sizes and column-name helpers, then the body between =:prologue= and =:epilogue=, wrapped in =int main()= unless it has a =main= or =:main no= is given. |
-| =D=            | =module mmm;=, =import= lines from =:imports= plus =std.stdio= and =std.conv=, the =:var= declarations, and the body wrapped in =int main()= as for C. |
+| =D=            | =module mmm;=, =import= lines from =:imports= (or the =IMPORTS= property, except when tangling) plus =std.stdio= and =std.conv=, the =:var= declarations, and the body wrapped in =int main()= as for C. |
 | =java=         | The body between =:prologue= and =:epilogue=, wrapped in a =main= method when it has no method and in a class when it has none. The class is named by =:classname= or the body's own class; a dotted =:classname= adds a =package= line. =:imports= adds =import= lines, and =:var= values become static fields. |
-| =fortran=      | =#include= and =#define= lines from =:includes= and =:defines=, then the =:var= declarations and the body in =program main=, unless the body has its own =program= statement (then =:var= is refused) or =:main no= is given. |
+| =fortran=      | =#include= and =#define= lines from =:includes= and =:defines= (or the =INCLUDES= and =DEFINES= properties, except when tangling), then the =:var= declarations and the body in =program main=, unless the body has its own =program= statement (then =:var= is refused) or =:main no= is given. |
 | =clojure=      | =(ns …)= from =:ns=, the body in a =let= of the =:var= values, and a printer around it unless =:results output=. |
 With =:hlines yes=, a table that keeps rules is refused for C, C++, D and Fortran; Java writes =null= for each rule.
 * On iOS
-- Only Emacs Lisp blocks run, in Orgstar's own interpreter. Any other language fails with "/language/ blocks need the Mac to run.", and so does an Emacs Lisp block whose =:var= refers to a block in another language.
+- Only Emacs Lisp blocks run, in Orgstar's own interpreter. Any other language, compiled languages included, fails with "/language/ blocks need the Mac to run." (for example "C blocks need the Mac to run."), and so does an Emacs Lisp block whose =:var= refers to a block in another language.
 - There are no sessions and no graphics.
 - The trust prompt works the same way, with its own =trusted.json= on the device.
 - There is no cancel command.

docs/manual/guide/13-configuration.org +1 −1

	@@ -559,4 +559,4 @@ The editor uses one font for everything: body text, headings, code and tables. C
559	- 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.	559	- 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.
560	- =line-spacing= adds space between lines, in points.	560	- =line-spacing= adds space between lines, in points.
561		561
562	On 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]].	562	On 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]].

docs/manual/guide/14-ios.org +10 −9

 Tap a file in Folders, Search or the agenda to read it.
 - Tap a heading to fold or unfold it, as =TAB= cycles it on the Mac. A chevron marks headings with content.
-- 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).
+- 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).
-- 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.
+- 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.
-- 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.
+- 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.
 - Tap a link to follow it. Links to headings and files in your folders open in the reader; web links open in the browser.
 - The toolbar has Outline (a list of headings to jump to), Export, and Edit.
 - Font :: =font= when that family is installed on the device, otherwise the system's monospaced font.
 - 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.
 - Line spacing and headings :: =line-spacing= and =heading-size-step= apply as on the Mac.
-- Caret and selection :: the caret and the selection highlight take the theme's =cursor= colour; =selection= isn't used.
+- Caret and selection :: the selection highlight takes the theme's =selection= colour, over block bands too; the caret and the selection handles take =cursor=.
-The 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.
+The 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.
 | Setting                          | In the iOS editor                                                              | =#+STARTUP=                      |
 |----------------------------------+--------------------------------------------------------------------------------+----------------------------------|
 | =org-startup-align-all-tables=   | Every table is aligned                                                         | =align=, =noalign=               |
 | =org-startup-truncated=          | Long lines run off the right edge, and the editor scrolls sideways             |                                  |
-While 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.
+While 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.
 The 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).
 An 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.
-The Mac editor's code highlighting in src blocks (the =syntax-*= colours) and =#+STARTUP: shrink= aren't on iOS.
+Code in src blocks is highlighted in the theme's =syntax-*= colours, as on the Mac (see [[file:11-code-blocks.org][Code blocks]]).
+Table 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]].
 ** The key bar
 Recent 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….
-Clock 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.
+Clock 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.
 The iOS app has no idle detection, so =org-clock-idle-time= doesn't apply. =org-clock-history-length= does.
 - Running code blocks in languages other than Emacs Lisp, Emacs Lisp beyond Orgstar's interpreter, and tables that need Emacs.
 - PDF, ODT, LaTeX and plain-text export.
 - The Mac and Doom keymaps, Vim keys, and =keymap.toml=.
-- The =selection= colour, code highlighting in src blocks, and =#+STARTUP: shrink=.
 - Idle detection while a clock runs.
 - Import from Emacs.
 - The board, column view, the backlinks pane, and the buffer list and tab bar.

docs/manual/guide/15-alongside-emacs.org +4 −3

 Code blocks (see [[file:11-code-blocks.org][Code blocks]]):
-- =:cmdline= is supported only for shells, =dot=, =plantuml= and =mermaid=.
+- =:cmdline= is supported only for shells, =dot=, =plantuml=, =mermaid= and C, C++, D, Java, Fortran and Clojure.
-- =:prologue=, =:epilogue= and =:post= aren't supported; =:stdin= and =:shebang= only for shells.
+- =:post= isn't supported; =:prologue= and =:epilogue= only for C, C++, D, Java, Fortran and Clojure; =:stdin= and =:shebang= only for shells.
-- =:session= is supported only for shells and Python.
+- =:session= is supported only for shells and Python. C, C++, D, Java, Fortran and Clojure ignore it, as in Org.
+- Clojure runs with babashka or the Clojure CLI only; other =:backend= values are refused.
 - =:var= isn't supported for some languages; references with arguments, as =block(x=1)=, and using another source block's result in =:var= aren't supported.
 - Header arguments, =:var= values and =:cache= that need Lisp evaluated by Emacs are refused when Orgstar's interpreter can't evaluate them: "… is Lisp that only Emacs can evaluate; nothing was run."
 - Noweb references that run a block aren't supported.

Commit d924123ec2

Commit `d924123ec2`