Ihor Radchenko <[email protected]> writes: > I will have to. Will add to my long todo list.
I had some availability before going bed. :) Attached is the original patch, minus conflicts, plus my suggestions, and - "must all be strictly less than 65" skipped, as it does not exist anymore - hertz/centimeter units are spelled out, to match Celsius/Fahrenheit. Rudy
>From 2890f464c60a6bfaee77240048880248fb147b0c Mon Sep 17 00:00:00 2001 From: Ben Siraphob <[email protected]> Date: Sat, 13 Sep 2025 18:26:09 +0700 Subject: [PATCH] doc/org-manual.org: Fix typos and improve readability MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rudolf Adamkovič [email protected] Link: https://orgmode.org/list/[email protected] --- doc/org-manual.org | 326 +++++++++++++++++++++++---------------------- 1 file changed, 164 insertions(+), 162 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 7e9756d09..3bde7855c 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -30,7 +30,7 @@ ** Summary provides exporting facilities. Org files can also be used for literate programming and reproducible research. As a TODO lists manager, Org helps you organize your tasks in a flexible way, from daily needs to -detailed project-planning, allowing logging, multiple views on your +detailed project planning, allowing logging, multiple views of your tasks, exporting your agendas, etc. Org mode is implemented on top of Outline mode, which makes it @@ -42,13 +42,13 @@ ** Summary Org develops organizational tasks around notes files that contain lists or information about projects as plain text. Project planning -and task management make use of metadata which is part of an outline +and task management make use of metadata, which is part of an outline node. Based on this data, specific entries can be extracted in -queries and create dynamic /agenda views/ that also integrate the Emacs +queries to create dynamic /agenda views/ that also integrate the Emacs calendar and diary. Org can be used to implement many different project planning schemes, such as David Allen's GTD system. -Org files can serve as a single source authoring system with export to +Org files can serve as a single-source authoring system with export to many different formats such as HTML, LaTeX, Open Document, and Markdown. New export backends can be derived from existing ones, or defined from scratch. @@ -60,7 +60,7 @@ ** Summary possible to create a single file reproducible research compendium. Org keeps simple things simple. When first fired up, it should feel -like a straightforward, easy to use outliner. Complexity is not +like a straightforward, easy-to-use outliner. Complexity is not imposed, but a large amount of functionality is available when needed. Org is a toolbox. Many users actually run only a---very personal---fraction of Org's capabilities, and know that there is more @@ -79,7 +79,8 @@ ** Summary #+cindex: print edition An earlier version (7.3) of this manual was available as a paperback -book from the Network Theory Ltd. publishing company, closed in 2009. +book from the Network Theory Ltd. publishing company, which closed +in 2009. ** Installation :PROPERTIES: @@ -87,13 +88,13 @@ ** Installation :END: #+cindex: installation -Org is included in distributions of GNU Emacs, you probably do not +Org is included in distributions of GNU Emacs, so you probably do not need to install it. Most users will simply activate Org and begin exploring its features. -If, for one reason or another, you want to install Org on top of this +If, for one reason or another, you want to install Org on top of the pre-packaged version, you can use the Emacs package system or clone -Org's git repository. We *strongly recommend* sticking to a single +Org's Git repository. We *strongly recommend* sticking to a single installation method. When installing Org on top of the pre-packaged version, please note @@ -116,19 +117,19 @@ *** Using Emacs packaging system #+attr_texinfo: :tag Important #+begin_quote You need to do this in a session where no =.org= file has been -visited, i.e., where no Org built-in function have been loaded. -Otherwise, autoload Org functions will mess up the installation. +visited, i.e., where no Org built-in functions have been loaded. +Otherwise, autoloaded Org functions will mess up the installation. #+end_quote -To avoid interference with built-in Org mode, you can use command line -(you need Emacs 30 or later): +To avoid interference with the built-in Org mode, you can use the +command line (you need Emacs 30 or later): #+begin_src sh emacs -Q -batch -eval "(progn (require 'package) (package-initialize) (package-refresh-contents) (package-upgrade 'org))" #+end_src This approach has the advantage of isolating the upgrade process from -a running Emacs session, ensuring that version conflicts can not +a running Emacs session, ensuring that version conflicts cannot arise. *** Using Org's git repository @@ -170,14 +171,15 @@ *** Installing Org's contributed packages :UNNUMBERED: notoc :END: -Org's repository used to contain =contrib/= directory for add-ons +Org's repository used to contain the =contrib/= directory for add-ons contributed by others. As of Org 9.5, the directory has been moved to the dedicated org-contrib [[https://git.sr.ht/~bzg/org-contrib][repository]], which you can install separately as a [[https://elpa.nongnu.org/nongnu/org-contrib.html][package]] from NonGNU ELPA. -There are enough valuable packages maintained outside the Org repository. -Worg has a list of [[https://orgmode.org/worg/org-contrib/index.html][org-contrib and external packages]], certainly it is not -exhaustive. +There are many valuable packages maintained outside the Org +repository. Worg has a list of +[[https://orgmode.org/worg/org-contrib/index.html][org-contrib and +external packages]]; it is certainly not exhaustive. ** Activation :PROPERTIES: @@ -190,8 +192,8 @@ ** Activation #+cindex: key bindings, global Org mode buffers need Font Lock to be turned on: this is the default -in Emacs[fn:: If you do not use Font Lock globally turn it on in Org -buffer with =(add-hook 'org-mode-hook #'turn-on-font-lock)=.]. +in Emacs[fn:: If you do not use Font Lock globally, turn it on in an +Org buffer with =(add-hook 'org-mode-hook #'turn-on-font-lock)=.]. There are compatibility issues between Org mode and some other Elisp packages (see [[*Packages that conflict with Org mode]]). Please take the @@ -250,13 +252,13 @@ ** Feedback [[mailto:[email protected]]]. You can subscribe to the list [[https://lists.gnu.org/mailman/listinfo/emacs-orgmode][from this web page]]. If you are not a member of the mailing list, your mail will -be passed to the list after a moderator has approved it[fn:: Please +be passed to the list after a moderator approves it[fn:: Please consider subscribing to the mailing list in order to minimize the work the mailing list moderators have to do.]. We ask you to read and respect the [[https://www.gnu.org/philosophy/kind-communication.html][GNU Kind Communications Guidelines]] when sending messages on this mailing -list. Please allow up to one month for the response and follow up if +list. Please allow up to one month for a response and follow up if no response is received on the bug report. #+findex: org-version @@ -267,22 +269,22 @@ ** Feedback persists, prepare a report and provide as much information as possible, including the version information of Emacs ({{{kbd(M-x emacs-version)}}}) and Org ({{{kbd(M-x org-version)}}}), as well as -the Org related setup in the Emacs init file. The easiest way to do +the Org-related setup in the Emacs init file. The easiest way to do this is to use the command : M-x org-submit-bug-report <RET> #+texinfo: @noindent which puts all this information into an Emacs mail buffer so that you -only need to add your description. If you are not sending the Email -from within Emacs, please copy and paste the content into your Email +only need to add your description. If you are not sending the email +from within Emacs, please copy and paste the content into your email program. Sometimes you might face a problem due to an error in your Emacs or Org mode setup. Before reporting a bug, it is very helpful to start -Emacs with minimal customizations and reproduce the problem. Doing so -often helps you determine if the problem is with your customization or -with Org mode itself. You can start a typical minimal session with +Emacs with minimal customizations and to reproduce the problem. Doing +so often helps you determine if the problem is with your customization +or with Org mode itself. You can start a typical minimal session with a command like the example below. : $ emacs -Q -l /path/to/minimal-org.el @@ -304,8 +306,8 @@ ** Feedback (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) #+end_src -If you are using Org mode version from Git repository, you can start -minimal session using make. +If you are using Org mode version from the Git repository, you can +start a minimal session using =make=. : # Bare Emacs : make repro @@ -327,7 +329,7 @@ ** Feedback #+cindex: laggy #+cindex: not responsive If you experience degraded performance, you can record a "profile" and -share it on the Org mailing list. See below for the instructions how +share it on the Org mailing list. See below for instructions on how to record a useful profile. Thank you for helping to improve this program. @@ -372,14 +374,14 @@ *** How to profile Org performance :END: #+cindex: profiler -Sometimes, Org is becoming slow for no apparent reason. Such slowdown +Sometimes, Org becomes slow for no apparent reason. Such slowdown is often caused by interaction between third-party packages and Org mode. However, identifying the root cause is not always straightforward. Emacs is able to record performance statistics, which can then be used -to find out which functions are taking most of the time to execute. -To record the statistics, one can use so-called profiler. To use the -Emacs profiler, we recommend the following steps: +to find out which functions are taking the most time to execute. To +record the statistics, one can use a profiler. To use the Emacs +profiler, we recommend the following steps: 1. Make sure that no profiler is currently active: @@ -397,17 +399,17 @@ *** How to profile Org performance This command will display a summary of the commands and functions that have been executed between ~profiler-start~ and - ~profiler-report~ invocations, with command taking most of the time - displayed on top. + ~profiler-report~ invocations, with the command taking the most + time displayed on top. =<TAB>= key can be used to fold and unfold lines in the profiler buffer. The child items revealed upon unfolding are the functions and commands called by the unfolded parent. - The root causes are often buried deep inside sub-children items in + The root causes are often buried deep inside child items in the profiler. You can press =B= (~profiler-report-render-reversed-calltree~) - to quickly reveal the actual function/command that takes most of - the time to run. + to quickly reveal the actual function/command that takes the most + time to run. Pressing =C= ~profiler-report-render-calltree~ will recover the original view. @@ -420,8 +422,8 @@ *** How to profile Org performance : /path/to/profile-file-to-be-saved <RET> Then, you can attach the saved file to your email to the Org - mailing list, alongside with details about what you did to trigger - the slowdown. + mailing list, along with details about what you did to trigger the + slowdown. Note that the saved statistics will only contain the function names and how long their execution takes. No private data will be @@ -470,7 +472,7 @@ *** Key bindings and commands :END: The manual lists both the keys and the corresponding commands for -accessing a functionality. Org mode often uses the same key for +accessing functionality. Org mode often uses the same key for different functions, depending on context. The command that is bound to such keys has a generic name, like ~org-metaright~. In the manual we will, wherever possible, give the function that is internally @@ -492,8 +494,8 @@ * Document Structure is achieved by folding, i.e., hiding large parts of the document to show only the general document structure and the parts currently being worked on. Org greatly simplifies the use of outlines by compressing -the entire show and hide functionalities into a single command, -~org-cycle~, which is bound to the {{{kbd(TAB)}}} key. +the show and hide functionalities into a single command, ~org-cycle~, +which is bound to the {{{kbd(TAB)}}} key. ** Headlines :PROPERTIES: @@ -524,8 +526,8 @@ ** Headlines as a title for your own headings. Some people find the many stars too noisy and would prefer an outline -that has whitespace followed by a single star as headline starters. -This can be achieved using an Org Indent minor mode. See [[*A Cleaner +that has whitespace followed by a single star as headline markers. +This can be achieved using the Org Indent minor mode. See [[*A Cleaner Outline View]] for more information. Headlines are not numbered. However, you may want to dynamically @@ -717,7 +719,7 @@ *** Catching invisible edits #+vindex: org-fold-catch-invisible-edits #+vindex: org-fold-catch-invisible-edits-commands Sometimes you may inadvertently edit an invisible part of the buffer -and be confused on what has been edited and how to undo the mistake. +and be confused about what has been edited and how to undo the mistake. By default, Org prevents such edits for a limited set of user commands. Users can control which commands are affected by customizing ~org-fold-catch-invisible-edits-commands~. @@ -783,7 +785,7 @@ ** Motion | {{{kbd(/)}}} | Do a Sparse-tree search | #+texinfo: @noindent - The following keys work if you turn off ~org-goto-auto-isearch~ + The following keys work if you turn off ~org-goto-auto-isearch~. #+attr_texinfo: :columns 0.3 0.7 | {{{kbd(n)}}} / {{{kbd(p)}}} | Next/previous visible headline. | @@ -912,7 +914,7 @@ ** Structure Editing #+kindex: C-c @@ #+findex: org-mark-subtree - Mark the subtree at point. Hitting repeatedly marks subsequent + Mark the subtree at point. Hitting it repeatedly marks subsequent subtrees of the same level as the marked subtree. - {{{kbd(C-c C-x C-w)}}} (~org-cut-subtree~) :: @@ -1061,7 +1063,7 @@ ** Sparse Trees Prompts for a regexp (see [[*Regular Expressions]]) and shows a sparse tree with all matches. If the match is in a headline, the headline is made visible. If the match is in the body of an entry, - headline and body are made visible. In order to provide minimal + the headline and body are made visible. In order to provide minimal context, also the full hierarchy of headlines above the match is shown, as well as the headline following the match. Each match is also highlighted; the highlights disappear when the buffer is @@ -1145,18 +1147,18 @@ ** Plain Lists - /Description/ list items are unordered list items, and contain the separator =::= to distinguish the description /term/ from the - description. + description text. Items belonging to the same list must have the same indentation on the first line. In particular, if an ordered list reaches number =10.=, then the 2-digit numbers must be written left-aligned with the other -numbers in the list. An item ends before the next line that is less -or equally indented than its bullet/number. +numbers in the list. An item ends before the next line that has an +indentation less than or equal to its bullet/number. A list ends whenever every item has ended, which means before any line -less or equally indented than items at top level. It also ends before -two blank lines. In that case, all items are closed. Here is an -example: +with an indentation less than or equal to that of the top-level items. +It also ends before two blank lines. In that case, all items are +closed. Here is an example: #+begin_example ,* Lord of the Rings @@ -1187,7 +1189,7 @@ ** Plain Lists If you find that using a different bullet for a sub-list---than that used for the current list-level---improves readability, customize the variable ~org-list-demote-modify-bullet~. To get a greater difference -of indentation between items and theirs sub-items, customize +of indentation between items and their sub-items, customize ~org-list-indent-offset~. #+vindex: org-list-automatic-rules @@ -1227,7 +1229,7 @@ ** Plain Lists in the middle of an item, that item is /split/ in two, and the second part becomes the new item[fn:: If you do not want the item to be split, customize the variable ~org-M-RET-may-split-line~.]. If - this command is executed /before item's body/, the new item is + this command is executed /before the item's body/, the new item is created /before/ the current one. - {{{kbd(M-S-RET)}}} :: @@ -1321,8 +1323,8 @@ ** Plain Lists #+vindex: org-support-shift-select #+kindex: S-LEFT #+kindex: S-RIGHT - This command also cycles bullet styles when point is in on the - bullet or anywhere in an item line, details depending on + This command also cycles bullet styles when point is on the bullet + or anywhere in an item line, details depending on ~org-support-shift-select~. - {{{kbd(C-c ^)}}} :: @@ -1340,7 +1342,7 @@ ** Drawers #+cindex: visibility cycling, drawers Sometimes you want to keep information associated with an entry, but -you normally do not want to see it. For this, Org mode has /drawers/. +you do not normally want to see it. For this, Org mode has /drawers/. They can contain anything but a headline and another drawer. Drawers look like this: @@ -1368,7 +1370,7 @@ ** Drawers {{{kbd(M-TAB)}}}[fn:6]. Visibility cycling (see [[*Visibility Cycling]]) on the headline hides and -shows the entry, but keep the drawer collapsed to a single line. In +shows the entry, but keeps the drawer collapsed to a single line. In order to look inside the drawer, you need to move point to the drawer line and press {{{kbd(TAB)}}} there. @@ -1439,7 +1441,7 @@ ** Built-in Table Editor #+end_example A table is re-aligned automatically each time you press -{{{kbd(TAB)}}}, {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} inside the table. +{{{kbd(TAB)}}}, {{{kbd(RET)}}}, or {{{kbd(C-c C-c)}}} inside the table. {{{kbd(TAB)}}} also moves to the next field---{{{kbd(RET)}}} to the next row---and creates new table rows at the end of the table or before horizontal lines. The indentation of the table is set by the @@ -1530,14 +1532,14 @@ *** Re-aligning and field motion #+kindex: M-a #+findex: org-table-beginning-of-field - Move to beginning of the current table field, or on to the previous + Move to beginning of the current table field, or onto the previous field. - {{{kbd(M-e)}}} (~org-table-end-of-field~) :: #+kindex: M-e #+findex: org-table-end-of-field - Move to end of the current table field, or on to the next field. + Move to end of the current table field, or onto the next field. *** Column and row editing :PROPERTIES: @@ -1566,7 +1568,7 @@ *** Column and row editing #+kindex: M-S-RIGHT #+findex: org-table-insert-column - Insert a new column at point position. Move the recent column and + Insert a new column at point position. Move the current column and all cells to the right of this column to the right. - {{{kbd(M-UP)}}} (~org-table-move-row-up~) :: @@ -1779,7 +1781,7 @@ *** Miscellaneous #+findex: org-table-header-line-mode #+vindex: org-table-header-line-p Turn on the display of the first data row of the table at point in - the window header line when this first row is not visible anymore in + the window header line when this first row is not visible any more in the buffer. You can activate this minor mode by default by setting the option ~org-table-header-line-p~ to ~t~. @@ -1800,7 +1802,7 @@ ** Column Width and Alignment fraction of number-like versus non-number fields in the column. #+vindex: org-table-automatic-realign -Editing a field may modify alignment of the table. Moving +Editing a field may modify the alignment of the table. Moving a contiguous row or column---i.e., using {{{kbd(TAB)}}} or {{{kbd(RET)}}}---automatically re-aligns it. If you want to disable this behavior, set ~org-table-automatic-realign~ to ~nil~. In any @@ -1867,7 +1869,7 @@ ** Column Width and Alignment Expand all columns. To see the full text of a shrunk field, hold the mouse over it: -a tool-tip window then shows the full contents of the field. +a tooltip window then shows the full contents of the field. Alternatively, {{{kbd(C-h .)}}} (~display-local-help~) reveals them, too. For convenience, any change near the shrunk part of a column expands it. @@ -2005,12 +2007,12 @@ **** Field references separator lines, or "hlines". Like with columns, you can use absolute row numbers =@1=, =@2=, ..., =@N=, and row numbers relative to the current row like =@+3= or =@-1=. =@<= and =@>= are immutable -references the first and last row in the table, respectively. You may -also specify the row relative to one of the hlines: =@I= refers to the -first hline, =@II= to the second, etc. =@-I= refers to the first such -line above the current line, =@+I= to the first such line below the -current line. You can also write =@III+2= which is the second data -line after the third hline in the table. +references to the first and last row in the table, respectively. You +may also specify the row relative to one of the hlines: =@I= refers to +the first hline, =@II= to the second, etc. =@-I= refers to the first +such line above the current line, =@+I= to the first such line below +the current line. You can also write =@III+2= which is the second +data line after the third hline in the table. =@0= and =$0= refer to the current row and column, respectively, i.e., to the row/column for the field being computed. Also, if you omit @@ -2099,7 +2101,7 @@ **** Field coordinates in formulas For the second and third examples, table {{{var(FOO)}}} must have at least as many rows or columns as the current table. Note that this is inefficient[fn:: The computation time scales as O(N^2) because table -{{{var(FOO)}}} is parsed for each field to be copied.] for large +{{{var(FOO)}}} is parsed for each field to be copied.] for a large number of rows. **** Named references @@ -2161,7 +2163,7 @@ **** Remote references When {{{var(NAME)}}} has the format =@ROW$COLUMN=, it is substituted with the name or ID found in this field of the current table. For example =remote($1, @@>$2)= \Rightarrow =remote(year_2013, @@>$1)=. The format -=B3= is not supported because it can not be distinguished from a plain +=B3= is not supported because it cannot be distinguished from a plain table name or ID. *** Formula syntax for Calc @@ -2249,17 +2251,17 @@ *** Formula syntax for Calc to reformat the Calc result after it has been passed back to Org instead of letting Calc handle the formatting. A few examples: -| =$1+$2= | Sum of first and second field | -| =$1+$2;%.2f= | Same, format result to two decimals | -| =exp($2)+exp($1)= | Math functions can be used | -| =$0;%.1f= | Reformat current cell to 1 decimal | -| =($3-32)*5/9= | Degrees F \to C conversion | -| =$c/$1/$cm= | Hz \to cm conversion, using =constants.el= | -| =tan($1);Dp3s1= | Compute in degrees, precision 3, display SCI 1 | -| =sin($1);Dp3%.1e= | Same, but use ~format~ specifier for display | -| =vmean($2..$7)= | Compute column range mean, using vector function | -| =vmean($2..$7);EN= | Same, but treat empty fields as 0 | -| =taylor($3,x=7,2)= | Taylor series of $3, at x=7, second degree | +| =$1+$2= | Sum of first and second field | +| =$1+$2;%.2f= | Same, format result to two decimals | +| =exp($2)+exp($1)= | Math functions can be used | +| =$0;%.1f= | Reformat current cell to 1 decimal | +| =($3-32)*5/9= | Fahrenheit to Celsius conversion | +| =$c/$1/$cm= | Herz to centimeter conversion, using =constants.el= | +| =tan($1);Dp3s1= | Compute in degrees, precision 3, display SCI 1 | +| =sin($1);Dp3%.1e= | Same, but use ~format~ specifier for display | +| =vmean($2..$7)= | Compute column range mean, using vector function | +| =vmean($2..$7);EN= | Same, but treat empty fields as 0 | +| =taylor($3,x=7,2)= | Taylor series of $3, at x=7, second degree | Calc also contains a complete set of logical operations (see [[info:calc#Logical Operations][Logical Operations]]). For example @@ -2272,7 +2274,7 @@ *** Formula syntax for Calc - =if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1= :: Sum of the first two columns. When at least one of the input fields - is empty the Org table result field is set to empty. =E= is + is empty, the Org table result field is set to empty. =E= is required to not convert empty fields to 0. =f-1= is an optional Calc format string similar to =%.1f= but leaves empty results empty. @@ -2280,7 +2282,7 @@ *** Formula syntax for Calc Mean value of a range unless there is any empty field. Every field in the range that is empty is replaced by =nan= which lets =vmean= - result in =nan=. Then =typeof == 12= detects the =nan= from ~vmean~ + return =nan=. Then =typeof == 12= detects the =nan= from ~vmean~ and the Org table result field is set to empty. Use this when the sample set is expected to never have missing values. @@ -2294,7 +2296,7 @@ *** Formula syntax for Calc - =vmean($1..$7); EN= :: - To complete the example before: Mean value of a range with empty + To complete the previous example: Mean value of a range with empty fields counting as samples with value 0. Use this only when incomplete sample sets should be padded with 0 to the full size. @@ -2367,7 +2369,7 @@ *** Emacs Lisp forms as formulas : '(concat $1 ";") #+texinfo: @noindent -You can put an extra tailing =;= to indicate that all the earlier +You can put an extra trailing =;= to indicate that all the earlier instances of =;= belong to the formula itself: : '(concat $1 ";"); @@ -2499,7 +2501,7 @@ *** Column formulas result. If the field contains only ===, the previously stored formula for this column is used. For each column, Org only remembers the most recently used formula. In the =TBLFM= keyword, column formulas look -like =$4=$1+$2=. The left-hand side of a column formula can not be +like =$4=$1+$2=. The left-hand side of a column formula cannot be the name of column, it must be the numeric column reference or =$>=. Instead of typing an equation into the field, you may also use the @@ -2553,7 +2555,7 @@ *** Lookup functions #+findex: org-lookup-all Similar to ~org-lookup-first~, but searches for /all/ elements for which {{{var(PREDICATE)}}} is non-~nil~, and returns /all/ - corresponding values. This function can not be used by itself in + corresponding values. This function cannot be used by itself in a formula, because it returns a list of values. However, powerful lookups can be built when this function is combined with other Emacs Lisp functions. @@ -2787,7 +2789,7 @@ **** Debugging formulas during variable substitution and calculation in order to find a bug, turn on formula debugging in the Tbl menu and repeat the calculation, for example by pressing {{{kbd(C-u C-u C-c = RET)}}} in a field. -Detailed information are displayed. +Detailed information is displayed. *** Updating the table :PROPERTIES: @@ -3134,7 +3136,7 @@ *** ASCII bar plots {{{var(VALUE)}}} is the value to plot. {{{var(MIN)}}} is the value displayed as an empty bar. {{{var(MAX)}}} -is the value filling all the {{{var(WIDTH)}}}. Sources values outside +is the value filling all the {{{var(WIDTH)}}}. Source values outside this range are displayed as =too small= or =too large=. {{{var(WIDTH)}}} is the number of characters of the bar plot. It @@ -3176,8 +3178,7 @@ ** Link Format #+cindex: backslashes, in links Some =\=, =[= and =]= characters in the {{{var(LINK)}}} part need to be "escaped", i.e., preceded by another =\= character. More -specifically, the following characters, and only them, must be -escaped: +specifically, only the following characters must be escaped: 1. all =[= and =]= characters, 2. every =\= character preceding either =]= or =[=, @@ -3211,7 +3212,7 @@ ** Link Format Inserting the missing bracket hides the link internals again. To show the internal structure of all links, use the menu: Org \rarr Hyperlinks \rarr Literal links, customize ~org-link-descriptive~, or use -=literallinks= [[*Summary of In-Buffer Settings][startup option]]. +the =literallinks= [[*Summary of In-Buffer Settings][startup option]]. ** Internal Links :PROPERTIES: @@ -3682,8 +3683,8 @@ ** Handling Links a {{{kbd(C-u C-u)}}} prefix. #+vindex: org-link-frame-setup - If point is on a headline, but not on a link, offer all links in the - headline and entry text. If you want to set up the frame + If point is on a headline, but not on a link, Org offers all links + in the headline and entry text. If you want to set up the frame configuration for following links, customize ~org-link-frame-setup~. - {{{kbd(RET)}}} :: @@ -3734,7 +3735,7 @@ ** Handling Links #+kindex: C-c C-x C-n #+findex: org-next-link #+cindex: links, finding next/previous - Move forward/backward to the next link in the buffer. At the limit + Move forward/backward to the next/previous link in the buffer. At the limit of the buffer, the search fails once, and then wraps around. The key bindings for this are really too long; you might want to bind this also to {{{kbd(M-n)}}} and {{{kbd(M-p)}}}. @@ -3995,7 +3996,7 @@ ** Basic TODO Functionality #+vindex: org-todo-keywords #+findex: org-show-todo-tree View TODO items in a /sparse tree/ (see [[*Sparse Trees]]). Folds the - entire buffer, but shows all TODO items---with not-DONE state---and + entire buffer, but shows all TODO items---with a not-DONE state---and the headings hierarchy above them. With a prefix argument, or by using {{{kbd(C-c / T)}}}, search for a specific TODO. You are prompted for the keyword, and you can also give a list of keywords @@ -4102,9 +4103,9 @@ *** TODO keywords as types #+end_src In this case, different keywords do not indicate states, but rather -different types. So the normal work flow would be to assign a task to +different types. So the normal workflow would be to assign a task to a person, and later to mark it DONE. Org mode supports this style by -adapting the workings of the command {{{kbd(C-c C-t)}}}[fn:: This is +adapting the working of the command {{{kbd(C-c C-t)}}}[fn:: This is also true for the {{{kbd(t)}}} command in the agenda buffer.]. When used several times in succession, it still cycles through all names, in order to first select the right type for a task. But when you @@ -4395,7 +4396,7 @@ *** Closing items after the headline. If you turn the entry back into a TODO item through further state cycling, that line is removed again. If you turn the entry back to a non-TODO state (by pressing {{{kbd(C-c C-t -SPC)}}} for example), that line is also removed, unless you set +SPC)}}}, for example), that line is also removed, unless you set ~org-closed-keep-when-no-todo~ to non-~nil~. If you want to record a note along with the timestamp, use[fn:: The corresponding in-buffer setting is: =#+STARTUP: lognotedone=.] @@ -4451,9 +4452,9 @@ *** Tracking TODO state changes entering the state, a timestamp should be recorded when /leaving/ the =WAIT= state, if and only if the /target/ state does not configure logging for entering it. So it has no effect when switching from -=WAIT= to =DONE=, because =DONE= is configured to record a timestamp -only. But when switching from =WAIT= back to =TODO=, the =/!= in the -=WAIT= setting now triggers a timestamp even though =TODO= has no +=WAIT= to =DONE=, because =DONE= is configured to record only a +timestamp. But when switching from =WAIT= back to =TODO=, the =/!= in +the =WAIT= setting now triggers a timestamp even though =TODO= has no logging configured. You can use the exact same syntax for setting logging preferences local @@ -4617,7 +4618,7 @@ ** Priorities #+vindex: org-priority-faces By default, Org mode supports three priorities: =A=, =B=, and =C=. =A= is the highest priority. An entry without a cookie is treated as -equivalent if it had priority =B=. Priorities make a difference only +if it had priority =B=. Priorities make a difference only for sorting in the agenda (see [[*Weekly/daily agenda]]). Outside the agenda, they have no inherent meaning to Org mode. The cookies are displayed with the face defined by the variable ~org-priority-faces~, @@ -4707,7 +4708,7 @@ ** Breaking Down Tasks into Subtasks #+cindex: @samp{COOKIE_DATA}, property If a heading has both checkboxes and TODO children below it, the -meaning of the statistics cookie become ambiguous. Set the property +meaning of the statistics cookie becomes ambiguous. Set the property =COOKIE_DATA= to either =checkbox= or =todo= to resolve this issue. #+vindex: org-hierarchical-todo-statistics @@ -5314,12 +5315,12 @@ ** Tag Searches only TODO items. These commands all prompt for a match string which allows basic -Boolean logic like =+boss+urgent-project1=, to find entries with tags -=boss= and =urgent=, but not =project1=, or =Kathy|Sally= to find -entries which are tagged, like =Kathy= or =Sally=. The full syntax of -the search string is rich and allows also matching against TODO -keywords, entry levels and properties. For a complete description -with many examples, see [[*Matching tags and properties]]. +Boolean logic, such as =+boss+urgent-project1= to find entries with +tags =boss= and =urgent=, but not =project1= or =Kathy|Sally= to find +entries tagged with either =Kathy= or =Sally=. The full syntax of the +search string is rich and allows also matching against TODO keywords, +entry levels and properties. For a complete description with many +examples, see [[*Matching tags and properties]]. * Properties and Columns :PROPERTIES: @@ -6809,14 +6810,14 @@ *** Repeated tasks #+begin_example ,** TODO Call Father DEADLINE: <2008-02-10 Sun ++1w> - Marking this DONE shifts the date by at least one week, but also + Marking this as DONE shifts the date by at least one week, but also by as many weeks as it takes to get this date into the future. However, it stays on a Sunday, even if you called and marked it done on Saturday. ,** TODO Empty kitchen trash DEADLINE: <2008-02-08 Fri 20:00 ++1d> - Marking this DONE shifts the date by at least one day, and also + Marking this as DONE shifts the date by at least one day, and also by as many days as it takes to get the timestamp into the future. Since there is a time in the timestamp, the next deadline in the future will be on today's date if you complete the task before @@ -6824,11 +6825,11 @@ *** Repeated tasks ,** TODO Check the batteries in the smoke detectors DEADLINE: <2005-11-01 Tue .+1m> - Marking this DONE shifts the date to one month after today. + Marking this as DONE shifts the date to one month after today. ,** TODO Wash my hands DEADLINE: <2019-04-05 08:00 Fri .+1h> - Marking this DONE shifts the date to exactly one hour from now. + Marking this as DONE shifts the date to exactly one hour from now. #+end_example #+vindex: org-agenda-skip-scheduled-repeats-after-deadline @@ -6910,8 +6911,8 @@ *** Clocking commands #+vindex: org-clock-in-prepare-hook While the clock is running, Org shows the current clocking time in the mode line, along with the title of the task. The clock time - shown is all time ever clocked for this task and its children. If - the task has an effort estimate (see [[*Effort Estimates]]), the + shown is all time ever clocked in for this task and its children. + If the task has an effort estimate (see [[*Effort Estimates]]), the mode line displays the current clocking time against it[fn:: To add an effort estimate "on the fly", hook a function doing this to ~org-clock-in-prepare-hook~.]. If the task is a repeating one (see @@ -7011,7 +7012,7 @@ *** Clocking commands #+kindex: C-c C-x C-j #+findex: or-clock-goto - Jump to the headline of the currently clocked in task. With + Jump to the headline of the currently clocked-in task. With a {{{kbd(C-u)}}} prefix argument, select the target task from a list of recently clocked tasks. @@ -7207,7 +7208,7 @@ *** The clock table An integer to limit the width of the headline column in the Org table. If you write it like =50!=, then the headline is also - shortened in export. + shortened during export. - =:indent= :: @@ -7731,7 +7732,7 @@ *** Moving a tree to an archive file #+cindex: external archiving The most common archiving action is to move a project tree to another -file, the archive file. +file, called the archive file. - {{{kbd(C-c C-x C-s)}}} or short {{{kbd(C-c $)}}} (~org-archive-subtree~) :: @@ -7781,7 +7782,7 @@ *** Moving a tree to an archive file #+vindex: org-archive-save-context-info When a subtree is moved, it receives a number of special properties that record context information like the file from where the entry -came, its outline path the archiving time etc. Configure the variable +came, its outline path, the archiving time etc. Configure the variable ~org-archive-save-context-info~ to adjust the amount of information added. @@ -7922,9 +7923,9 @@ *** Using capture #+findex: org-capture Display the capture templates menu. If you have templates defined (see [[*Capture templates]]), it offers these templates for - selection. It inserts the template into the target file and switch - to an indirect buffer narrowed to this new node. You may then - insert the information you want. + selection. It inserts the template into the target file and + switches to an indirect buffer narrowed to this new node. You may + then insert the information you want. - {{{kbd(C-c C-c)}}} (~org-capture-finalize~) :: @@ -8516,8 +8517,8 @@ ** Attachments project. Another method is /attachments/, which are files located in a -directory belonging to heading/subtree. Org uses directories either -named by =ID= property of a heading, or by a =DIR= property. +directory belonging to heading/subtree. Org uses directories named +either by the =ID= property of a heading or by a =DIR= property. *** Attachment defaults and dispatcher :PROPERTIES: @@ -13244,7 +13245,7 @@ *** Frames and Blocks in Beamer environment. #+cindex: @samp{BEAMER_SUBTITLE}, property - If =BEAMER_SUBTITLE= is set, org exports its value as the subtitle + If =BEAMER_SUBTITLE= is set, Org exports its value as the subtitle for the headline's frame. This property has no effect on headlines which are not exported as frames. @@ -17300,7 +17301,7 @@ *** Publishing action - ~:htmlized-source~ :: - Non-~nil~ means, publish htmlized source. + Non-~nil~ means, publish an htmlized version of the source. The function must accept three arguments: a property list containing at least a ~:publishing-directory~ property, the name of the file to @@ -17606,7 +17607,7 @@ ** Uploading Files definition since the third-party tool syncs them. Publishing to a local directory is also much faster than to a remote -one, so that you can afford more easily to republish entire projects. +one, so that you can more easily afford to republish entire projects. If you set ~org-publish-use-timestamps-flag~ to ~nil~, you gain the main benefit of re-including any changed external files such as source example files you might include with =INCLUDE= keyword. The timestamp @@ -17756,7 +17757,7 @@ * Citation handling : Org mode is used by various communities [cite:teaching: @orgteaching; : and TeX: @orgtex]. [cite/author/caps:@orgtex] uses Org mode to simplify : writing scientific publications, while [cite/author/caps:@orgteaching] -: experiment with Org babel to improve teaching. +: experiments with Org babel to improve teaching. : : #+print_bibliography: @@ -18132,7 +18133,7 @@ ** Structure of Code Blocks ,#+END_SRC #+end_example -Do not be put-off by having to remember the source block syntax. Org +Do not be put off by having to remember the source block syntax. Org mode offers a command for wrapping existing text in a block (see [[*Structure Templates]]). Org also works with other completion systems in Emacs, some of which predate Org and have custom domain-specific @@ -18267,7 +18268,7 @@ *** System-wide header arguments (assq-delete-all :noweb org-babel-default-header-args))) #+end_src -#+cindex: language specific default header arguments +#+cindex: language-specific default header arguments #+cindex: default header arguments per language Each language can have separate default header arguments by customizing the variable ~org-babel-default-header-args:<LANG>~, where @@ -18316,7 +18317,7 @@ *** Header arguments in Org mode properties {{{kbd(C-c C-x p)}}}, apply to all active languages. They override properties set in ~org-babel-default-header-args~. -#+cindex: language specific header arguments properties +#+cindex: language-specific header arguments properties #+cindex: header arguments per language Language-specific header arguments are also read from properties =header-args:<LANG>= where {{{var(<LANG>)}}} is the language @@ -18867,9 +18868,9 @@ ** Evaluating Code Blocks #+cindex: @samp{RESULTS}, keyword A note about security: With code evaluation comes the risk of harm. -Org safeguards by prompting for user's permission before executing any -code in the source block. To customize this safeguard, or disable it, -see [[*Code Evaluation and Security Issues]]. +Org provides safeguards by prompting for the user's permission before +executing any code. To customize this safeguard, or disable it, see +[[*Code Evaluation and Security Issues]]. *** How to evaluate source code :PROPERTIES: @@ -19775,7 +19776,7 @@ ** Languages #+cindex: code block, languages Code blocks in dozens of languages are supported. See Worg website -for [[https://orgmode.org/worg/org-contrib/babel/languages/index.html][language specific documentation]]. +for [[https://orgmode.org/worg/org-contrib/babel/languages/index.html][language-specific documentation]]. #+vindex: org-babel-load-languages By default, only Emacs Lisp is enabled for evaluation. To enable or @@ -20491,11 +20492,11 @@ ** A Cleaner Outline View #+cindex: odd-levels-only outlines #+cindex: clean outline view -Org's outline with stars and no indents can look cluttered for short -documents. For /book-like/ long documents, the effect is not as -noticeable. Org provides an alternate stars and indentation scheme, -as shown on the right in the following table. It displays only one -star and indents text to line up with the heading: +Org's outline, with its stars and lack of indents, can look cluttered +in short documents. For /book-like/ long documents, the effect is not +as noticeable. Org provides an alternate stars and indentation +scheme, as shown on the right in the following table. It displays +only one star and indents text to line up with the heading: #+begin_example ,* Top level headline | * Top level headline @@ -20669,7 +20670,7 @@ ** The Very Busy {{{kbd(C-c C-c)}}} Key - If point is in one of the special =KEYWORD= lines, scan the buffer for these lines and update the information. Also reset the Org file - cache used to temporary store the contents of URLs used as values + cache used to temporarily store the contents of URLs used as values for keywords like =SETUPFILE=. - If point is inside a table, realign the table. @@ -21350,7 +21351,7 @@ *** Packages that conflict with Org mode #+cindex: @file{yasnippet.el} The way Org mode binds the {{{kbd(TAB)}}} key (binding to ~[tab]~ instead of ~"\t"~) overrules YASnippet's access to this key. The - following code fixed this problem: + following code fixes this problem: #+begin_src emacs-lisp (add-hook 'org-mode-hook @@ -23003,13 +23004,14 @@ ** From Carsten and intuitive editing features, and to incorporate project planning functionality directly into a notes file. -Since the first release, literally thousands of emails to me or to the -[[mailto:[email protected]][mailing list]] have provided a constant stream of bug reports, feedback, -new ideas, and sometimes patches and add-on code. Many thanks to -everyone who has helped to improve this package. I am trying to keep -here a list of the people who had significant influence in shaping one -or more aspects of Org. The list may not be complete, if I have -forgotten someone, please accept my apologies and let me know. +Since the first release, thousands of emails to me or to the +[[mailto:[email protected]][mailing list]] have provided a +constant stream of bug reports, feedback, new ideas, and sometimes +patches and add-on code. Many thanks to everyone who has helped to +improve this package. Below is a list of the people who had +significant influence in shaping one or more aspects of Org. The list +may not be complete, if I have forgotten someone, please accept my +apologies and let me know. Before I get to this list, a few special mentions are in order: @@ -23110,9 +23112,9 @@ ** From Bastien be fair when shortlisting a few of them, but Org's history would not be complete if the ones above were not mentioned in this manual. -Of course, I'm also grateful grateful to Carsten for his trust while -handing me over the maintainership of Org. His unremitting support is -what really helped me getting more confident over time, with both the +Of course, I'm also grateful to Carsten for his trust while handing +over the maintainership of Org to me. His unremitting support is what +really helped me getting more confident over time, with both the community and the code. ** List of Contributions @@ -23188,7 +23190,7 @@ ** List of Contributions - Eric Fraga drove the development of Beamer export with ideas and testing. -- Barry Gidden did proofreading the manual in preparation for the book +- Barry Gidden proofread the manual in preparation for the book publication through Network Theory Ltd. - Niels Giesen had the idea to automatically archive DONE trees. -- 2.50.1 (Apple Git-155)
-- "Simplicity is complexity resolved." --- Constantin Brâncuși, 1876-1957 Rudolf Adamkovič <[email protected]> [he/him] http://adamkovic.org
