Update the manual for the Emacs differences fixed !167

merged merged by cmc on 2026-10-08 05:14 UTC · krz/orgstar:manual-differences into main

7 files changed, +40 −19

Layout: unified · split

docs/manual/guide/02-the-editor.org +1 −1

		@@ -270,7 +270,7 @@ Long lines wrap at the edge of the editor by default. Truncate or Wrap Long Line
270	270
271	271	To truncate lines in every file, set =org-startup-truncated = true= in =config.toml=. The default is to wrap, as Doom does; Emacs's own default is to truncate.
272	272
273		Wrapping is display only. To rewrap the text of a paragraph, use Org ▸ Fill Paragraph (=org-fill-paragraph=), which breaks the paragraph's lines at the fill column: =M-q= in the Emacs preset and in every Doom state, =⌃⌘P= in the Mac preset. In Doom's normal and visual states, =gq= and =gw= with a motion fill the paragraphs in the lines it covers (=gqq= and =gww= for the current lines); =gq= leaves the caret on the last line, =gw= where it was. See [[file:03-keys.org][Keys and commands]]. The fill column is Settings ▸ Editing ▸ "M-q fills to column N" (80 by default, 40 to 200), or =fill-column= in =config.toml=. Orgstar has no auto-fill: lines are not broken as you type.
	273	Wrapping is display only. To rewrap the text of a paragraph, use Org ▸ Fill Paragraph (=org-fill-paragraph=), which breaks the paragraph's lines at the fill column: =M-q= in the Emacs preset and in every Doom state, =⌃⌘P= in the Mac preset. With a selection, it fills every paragraph the selection touches. In Doom's normal and visual states, =gq= and =gw= with a motion fill the paragraphs in the lines it covers (=gqq= and =gww= for the current lines); =gq= leaves the caret on the last line, =gw= where it was. Unlike Fill Paragraph, =gq= and =gw= keep extra spaces between words and at the ends of lines, as Doom does. See [[file:03-keys.org][Keys and commands]]. The fill column is Settings ▸ Editing ▸ "M-q fills to column N" (80 by default, 40 to 200), or =fill-column= in =config.toml=. Orgstar has no auto-fill: lines are not broken as you type.
274	274
275	275	* View toggles
276	276

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

		@@ -332,8 +332,8 @@ Motions move the caret in normal state, extend the selection in visual states, a
332	332	\| =$=, =<end>= \| End of the line; with a count, of the line count − 1 lines down. \|
333	333	\| =g_= \| Last non-blank of the line. \|
334	334	\| =gg=, =G= \| First line, last line; with a count, that line. The column is kept (=evil-start-of-line= nil). \|
335		\| =f= /x/, =F= /x/, =t= /x/, =T= /x/ \| To, or to just before, the next or previous /x/ on the line. \|
336		\| =;=, =,= \| Repeats the last =f=, =F=, =t=, =T=, =s= or =S=, forward or reversed. A snipe repeated this way searches all the text the window shows, not only the caret's line (=evil-snipe-repeat-scope=, as Doom sets it). \|
	335	\| =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). \|
	336	\| =;=, =,= \| 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. \|
337	337	\| =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. \|
338	338	\| =%= \| The bracket matching the next =()=, =[]= or ={}= on the line. \|
339	339	\| ={=, =}= \| Previous, next blank line. \|
		@@ -356,9 +356,9 @@ Search patterns are ICU regular expressions as macOS uses them, close to PCRE; E
356	356	\| =>= /motion/, =<= /motion/ \| Indents or outdents lines by 8 spaces (=evil-shift-width=, which Doom sets to Org's =tab-width=). =>>= and =<<= act on lines. \|
357	357	\| =g~= /motion/, =gu= /motion/, =gU= /motion/ \| Toggles case, lowercases, uppercases. =g~~=, =guu=, =gUU= act on lines. \|
358	358	\| =gc= /motion/ \| Comments or uncomments lines with =#= (=evilnc-comment-operator=). =gcc= acts on lines. See [[*Commenting][Commenting]]. \|
359		\| =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. =gqq= and =gww= act on lines. \|
	359	\| =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. \|
360	360
361		=M-q= runs Fill Paragraph in normal, insert and visual state.
	361	=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.
362	362
363	363	Counts multiply: =2d3w= deletes six words. Doubling an operator with a count acts on that many lines: =3dd=.
364	364
		@@ -437,7 +437,7 @@ A macro replays the keys you typed, including keymap commands, leader keys and i
437	437
438	438	=m= /a/ sets mark /a/ (any letter) at the caret. Marks move with the text as you edit. ='= /a/ goes to the first non-blank of the mark's line, =`= /a/ to its exact position. =''= and =``= go back to where the last jump started.
439	439
440		Jumps are =G=, =gg=, =%=, ={=, =}=, =n=, =N=, =*=, =#=, ='=, =`=, =H=, =M=, =L=, and searches with =/= and =?=. Each jump adds its starting point to the jump list, which keeps the last 100. =C-o= goes back through the list and =C-i= forward again. A new jump after =C-o= drops the places you went back past.
	440	Jumps are =G=, =gg=, =%=, ={=, =}=, =n=, =N=, =*=, =#=, ='=, =`=, =H=, =M=, =L=, the snipes =s=, =S=, =f=, =F=, =t= and =T=, and searches with =/= and =?=. Each jump adds its starting point to the jump list, which keeps the last 100. =C-o= goes back through the list and =C-i= forward again. A new jump after =C-o= drops the places you went back past.
441	441
442	442	Lowercase marks belong to the buffer, and so do =C-o= and =C-i=. Uppercase marks (=mA= to =mZ=) are file marks, shared by every buffer: ='A= or =`A= in another buffer shows the buffer the mark was set in, at the mark. A file mark goes away when its buffer closes.
443	443
		@@ -742,7 +742,7 @@ When a key appears in several rows, it runs the command whose condition holds at
742	742	\| Find Previous (=edit.find-previous=) \| — \| — \| — \| Goes to the previous match. \|
743	743	\| Use Selection for Find (=edit.use-selection-for-find=) \| — \| — \| — \| Puts the selection in the find bar. \|
744	744	\| Complete at Point (=editor.complete=) \| =C-M-i= \| — \| =C-SPC= (I), =C-@= (I) \| Completes what is typed at the caret: =#+= keywords and their values, link types, entities, tags, TODO keywords, headings, drawers, properties, src languages and header arguments, and =<s=-style templates (=completion-at-point=). One candidate is inserted; several open a list. \|
745		\| Fill Paragraph (=org.fill-paragraph=) \| =M-q= \| =⌃⌘P= \| — \| Refills the paragraph or list item to the fill column (=org-fill-paragraph=). In the Doom preset, =gq= and =gw= fill the lines a motion covers; see [[*Operators][Operators]]. \|
	745	\| Fill Paragraph (=org.fill-paragraph=) \| =M-q= \| =⌃⌘P= \| — \| Refills the paragraph or list item to the fill column (=org-fill-paragraph=); with a selection, every paragraph it touches. In the Doom preset, =gq= and =gw= fill the lines a motion covers; see [[*Operators][Operators]]. \|
746	746
747	747	** Outline: visibility and narrowing
748	748

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

		@@ -53,7 +53,7 @@ The agenda also reads =<%%(…)>= timestamps and =%%(…)= lines with Emacs diar
53	53	\| Insert Timestamp \| =org-timestamp= \| =C-c .= \| ⌃⌘. \| =SPC m d t= \|
54	54	\| Insert Inactive Timestamp \| =org-timestamp-inactive= \| =C-c != \| ⌃⌥⌘. \| =SPC m d T= \|
55	55
56		Both ask for a date in the echo area (see "The date prompt"). With the caret on an existing timestamp, they replace it with the date you give, keep its repeater, and start from its date and time. Run the command again right after inserting a timestamp to add a second one and make a range, =<…>--<…>=.
	56	Both ask for a date in the echo area (see "The date prompt"). With the caret on an existing timestamp, they replace it with the date you give, keep its repeater, and start from its date and time. In a range of days, the caret picks the end: with the caret between the two dashes of =--= or after them, the second timestamp is replaced and the prompt starts from its date; before that, the first. Run the command again right after inserting a timestamp to add a second one and make a range, =<…>--<…>=; the second date starts from the timestamp at the caret.
57	57
58	58	Org's prefix arguments are not available: to include the current time, type it, or use a relative time such as =+0h= (see below).
59	59
		@@ -259,7 +259,7 @@ The time shown is the time since you clocked in, not the entry's total. Each of
259	259
260	260	You can edit clock lines by hand. =S-<up>=, =S-<down>=, =S-<left>= and =S-<right>= change their timestamps as anywhere else, and then write the duration after ~=>~ again, as =H:MM=. After typing changes yourself, press =C-c C-c= (or =C-c C-y=) on the line: Orgstar fixes both day names and writes the duration again (=org-clock-update-time-maybe=).
261	261
262		=C-c .= with the caret on the =--= between the two timestamps of a clock line inserts a new timestamp there. Emacs replaces the second timestamp instead.
	262	=C-c .= on a clock line's range replaces one of its timestamps, as in any range of days (see "Inserting timestamps").
263	263
264	264	A line of the form ~CLOCK: => 1:15~, with only a duration, counts towards clock tables.
265	265

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

		@@ -516,8 +516,11 @@ result. It looks for Emacs at the path in the =ORGSTAR_EMACS= environment variab
516	516	then =/opt/homebrew/bin/emacs=, =/usr/local/bin/emacs=,
517	517	=/Applications/Emacs.app/Contents/MacOS/Emacs=, =/run/current-system/sw/bin/emacs= and
518	518	=/usr/bin/emacs=. If none is found, the echo area says Emacs isn't installed and the
519		table is unchanged. The run stops after 60 seconds. If you edit the table while Emacs
520		is working, its result is discarded.
	519	table is unchanged. Emacs gets your =PATH= with =/opt/homebrew/bin=, =/usr/local/bin=,
	520	=/Library/TeX/texbin=, =/usr/bin= and =/bin= added, as code blocks and export do, so
	521	programs a formula starts are found when Orgstar was opened from the Dock. The run
	522	stops after 60 seconds. If you edit the table while Emacs is working, its result is
	523	discarded.
521	524
522	525	If the table's formulas contain Lisp, Orgstar asks first:
523	526	=This table's formulas run Lisp. Run them? (yes, no, always)=. =always= trusts this

docs/manual/guide/11-code-blocks.org +24 −5

		@@ -409,7 +409,7 @@ return [r + ["!"] for r in t]
409	409
410	410	** Standard input and arguments
411	411
412		For shell blocks, =:stdin name= sends a table, list or block result to standard input, a table as tab-separated lines. =:cmdline= gives the script arguments, and =:shebang= its first line. With any of the three, the block is written to an executable script and run by the shell (=org-babel-sh-evaluate=); without =:shebang=, the first line is =#!/usr/bin/env= and the shell's name.
	412	For shell blocks, =:stdin name= sends a table, list or block result to standard input, a table as tab-separated lines. =:cmdline= gives the script arguments, and =:shebang= its first line. With any of the three, the block is written to an executable script and run by the shell (=org-babel-sh-evaluate=); without =:shebang=, the first line is =#!/usr/bin/env= and the shell's name. A block with =:stdin= or =:cmdline= runs as a script even with a =:session=, and leaves the session untouched; =:shebang= alone runs in the session.
413	413
414	414	#+BEGIN_SRC org
415	415	,#+begin_src sh :cmdline one "two words" :results output
		@@ -445,6 +445,8 @@ With =:cache yes=, Orgstar computes a SHA-1 hash of the block's header arguments
445	445
446	446	Change the block or its arguments and it runs again. Results inserted with =append= or =prepend= carry no hash. Inline blocks are not cached. A cached block that has Lisp in its header arguments the interpreter cannot evaluate is refused.
447	447
	448	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.
	449
448	450	* Noweb
449	451
450	452	A noweb reference =<<name>>= in a block's body stands for other code. Whether references expand depends on =:noweb= and on what is happening:
		@@ -510,6 +512,8 @@ The full form is =#+CALL: name[inside](arguments) end=:
510	512	- =(arguments)= are =:var= assignments, separated by commas.
511	513	- =end= holds header arguments for the call's result, such as =:results verbatim=.
512	514
	515	The call also takes the =header-args= and =header-args:LANG= properties, and =#+PROPERTY:= lines, where the call is, with =LANG= the called block's language. They apply after the called block's own header arguments and before =[inside]=, as in Org.
	516
513	517	The result goes under the call. A =#+NAME:= line above the =#+CALL:= names the result.
514	518
515	519	** Inline calls and blocks
		@@ -522,7 +526,7 @@ Text src_sh{echo hi} {{{results(=hi=)}}} end.
522	526
523	527	Running again replaces the macro. With =:results raw= the result goes in as it is, without the macro. An inline result must be one line, and a table result must be a single cell.
524	528
525		An inline call, =call_double(n=6)=, has the same parts as a =#+CALL:= line: =call_name[inside](arguments)[end]=. =C-c C-c= on an inline call runs it, and its result is written after it as a =results= macro, as for inline blocks.
	529	An inline call, =call_double(n=6)=, has the same parts as a =#+CALL:= line: =call_name[inside](arguments)[end]=. =C-c C-c= on an inline call runs it, and its result is written after it as a =results= macro, as for inline blocks. It takes the properties where it is as a =#+CALL:= line does.
526	530
527	531	* Emacs Lisp blocks
528	532
		@@ -600,8 +604,22 @@ echo tool
600	604	\| =:comments= \| =no=, =link=, =yes=, =org=, =both=, =noweb= \| Comments around each block (below). \|
601	605	\| =:noweb= \| see Noweb above \| Expand or strip =<<name>>= references. \|
602	606	\| =:prologue=, =:epilogue= \| text \| A line before and after the block's code. \|
603		\| =:var= \| as for running \| Shell scalars become assignments, Python values become assignments, Emacs Lisp values are =let=-bound. \|
604		\| =:no-expand= \| any \| Write the body without =:var=, =:prologue= or =:epilogue=. \|
	607	\| =:var= \| as for running \| Shell scalars become assignments, Python values become assignments, Emacs Lisp values are =let=-bound. For the languages below, as their Org language files write them. \|
	608	\| =:no-expand= \| any \| Write the body without =:var=, =:prologue=, =:epilogue= or the language's wrapping. \|
	609
	610	A table in =:var= loses its first row when its only rule is under that row, or with =:colnames yes=, and its rules unless =:hlines yes=, as when the block runs. This holds for every language.
	611
	612	=C=, =C++=, =cpp=, =D=, =java=, =fortran= and =clojure= blocks are written as Org's =org-babel-expand-body:LANG= writes them:
	613
	614	\| Language \| Written \|
	615	\|----------------+--------------------------------------------------------------------------------------------------------------\|
	616	\| =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. \|
	617	\| =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. \|
	618	\| =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. \|
	619	\| =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. \|
	620	\| =clojure= \| =(ns …)= from =:ns=, the body in a =let= of the =:var= values, and a printer around it unless =:results output=. \|
	621
	622	With =:hlines yes=, a table that keeps rules is refused for C, C++, D and Fortran; Java writes =null= for each rule.
605	623
606	624	Block switches also apply. =-r= removes coderef labels such as =(ref:name)=, using the format from =-l= if given. =-i= keeps the block's indentation. Otherwise common indentation and surrounding blank lines are removed.
607	625
		@@ -631,7 +649,8 @@ Tangling stops, writes nothing and says why when:
631	649
632	650	- =:var= refers to a source block, which would have to run: "would run a block while tangling".
633	651	- A shell block's =:var= is a table or list.
634		- =:var= is used in a language other than shells, Python and Emacs Lisp.
	652	- =:var= is used in a language other than shells, Python, Emacs Lisp, C, C++, D, Java, Fortran and Clojure.
	653	- A C, C++, D or Fortran block's =:var= table keeps rules (with =:hlines yes=), or a value has no type the language takes.
635	654	- A Lisp header value cannot be evaluated: "is Lisp tangling can't evaluate yet; nothing was tangled."
636	655	- =:tangle-mode= is in a form it does not read.
637	656	- =:comments= needs a comment syntax it does not know.

docs/manual/guide/12-export.org +1 −1

		@@ -163,7 +163,7 @@ The block's =:exports= header argument decides what appears. Orgstar resolves it
163	163	\| =both= \| The code, then the results. \|
164	164	\| =none= \| Nothing. \|
165	165
166		A =#+CALL:= line exports its existing results, never the call itself; =:exports code= or =none= on the call exports nothing. An inline =src_= block has =:exports results= by default: the ={{{results(…)}}}= after it is exported and its code is not. With =:exports code= the code is exported in =<code>= and the results are not; with =both=, both. An inline =call_= exports its results the same way, and the call itself never appears.
	166	A =#+CALL:= line exports its existing results, never the call itself; =:exports code= or =none= on the call, or in the =header-args= properties where the call is, exports nothing. An inline =src_= block has =:exports results= by default: the ={{{results(…)}}}= after it is exported and its code is not. With =:exports code= the code is exported in =<code>= and the results are not; with =both=, both. An inline =call_= never appears itself, and the ={{{results(…)}}}= after it is always exported, whatever =:exports= says, as in Org.
167	167
168	168	** Other blocks and elements
169	169

docs/manual/guide/15-alongside-emacs.org +1 −2

		@@ -141,7 +141,7 @@ An app started from the Dock doesn't see your shell's =PATH=, which is why Orgst
141	141	- Orgstar writes a snapshot of the buffer to a temporary folder and runs Emacs on it, so unsaved edits are included. The working directory is the file's folder.
142	142	- File-local variables marked safe apply (=enable-local-variables= is =:safe=).
143	143	- Export doesn't run source blocks (=org-export-use-babel= is =nil=). The exported file is written next to the org file, as Emacs writes it, or moved to the place you chose.
144		- For export, Emacs gets your =PATH= with =/opt/homebrew/bin=, =/usr/local/bin=, =/Library/TeX/texbin=, =/usr/bin= and =/bin= added, as source blocks do, so the programs it starts, such as =pdflatex=, are found when Orgstar was opened from the Dock.
	144	- For export and table recalculation, Emacs gets your =PATH= with =/opt/homebrew/bin=, =/usr/local/bin=, =/Library/TeX/texbin=, =/usr/bin= and =/bin= added, as source blocks do, so the programs it starts, such as =pdflatex=, are found when Orgstar was opened from the Dock.
145	145	- PDF export needs a LaTeX installation that Org's LaTeX exporter can run.
146	146	- A table recalculation that takes more than 60 seconds, or an export that takes more than 120 seconds, is stopped. Source blocks have a limit of 300 seconds, and =⌘.= (Cancel Running Block) stops one.
147	147
		@@ -235,4 +235,3 @@ Other:
235	235	- =#+SETUPFILE= URLs aren't fetched.
236	236	- Most =#+STARTUP= options for footnotes, entities, LaTeX previews, numbering and odd levels are accepted and ignored; see [[file:13-configuration.org][Configuration]].
237	237	- =display-line-numbers-type= has no relative or visual mode.
238		- =C-c .= with the caret on the =--= of a clock line's range inserts a new timestamp; Emacs replaces the second timestamp.