From 37c32ca52f2e0740d34685e9e3f807349a247e85 Mon Sep 17 00:00:00 2001 From: Ben Siraphob Date: Sat, 13 Sep 2025 18:26:09 +0700 Subject: [PATCH] doc/org-manual.org: Fix typos and improve readability --- doc/org-manual.org | 301 +++++++++++++++++++++++---------------------- 1 file changed, 151 insertions(+), 150 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 8c6962d..51d30dd 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -30,7 +30,7 @@ As an authoring tool, Org helps you write structured documents and 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 @@ entries, and any files related to the projects. 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 @@ place and their results can be captured in the file. This makes it 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 @@ of Org, as well as additional information, frequently asked questions #+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 @@ book from the Network Theory Ltd. publishing company, closed in 2009. :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 @@ with {{{kbd(M-x list-packages)}}}. See [[info:emacs::Package Menu][Package Menu #+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 @@ -168,14 +169,15 @@ Org Build System page on [[https://orgmode.org/worg/dev/org-build-system.html][W :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: @@ -188,8 +190,8 @@ exhaustive. #+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 @@ -248,13 +250,13 @@ ideas about it, please send an email to the Org mailing list [[mailto:emacs-orgmode@gnu.org]]. 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 @@ -265,22 +267,22 @@ is quite possible that the bug has been fixed already. If the bug 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 #+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 @@ -302,8 +304,8 @@ shown below. (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 @@ -325,7 +327,7 @@ information about: #+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. @@ -370,14 +372,14 @@ error occurred. Here is how to produce a useful backtrace: :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: @@ -395,17 +397,17 @@ Emacs profiler, we recommend the following steps: 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. == 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. @@ -418,8 +420,8 @@ Emacs profiler, we recommend the following steps: : /path/to/profile-file-to-be-saved 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 @@ -468,7 +470,7 @@ conventions: :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 @@ -485,13 +487,13 @@ call ~org-table-move-column-right~. #+cindex: document structure #+cindex: structure of document Org is an outliner. Outlines allow a document to be organized in -a hierarchical structure, which, least for me, is the best +a hierarchical structure, which, at least for me, is the best representation of notes and thoughts. An overview of this 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: @@ -522,8 +524,8 @@ The name defined in ~org-footnote-section~ is reserved. Do not use it 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 @@ -713,7 +715,7 @@ for this property are =folded=, =children=, =content=, and =all=. #+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~. @@ -779,7 +781,7 @@ The following commands jump to other headlines in the buffer. | {{{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. | @@ -908,7 +910,7 @@ The following commands jump to other headlines in the buffer. #+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~) :: @@ -1056,7 +1058,7 @@ commands can be accessed through a dispatcher: 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 @@ -1140,18 +1142,18 @@ Org knows ordered lists, unordered lists, and description 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 @@ -1182,7 +1184,7 @@ indented to signal that they belong to a particular item. 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 @@ -1222,7 +1224,7 @@ to disable them individually. 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)}}} :: @@ -1316,8 +1318,8 @@ to disable them individually. #+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 ^)}}} :: @@ -1335,7 +1337,7 @@ to disable them individually. #+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: @@ -1363,7 +1365,7 @@ Completion over drawer keywords is also possible using {{{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. @@ -1434,7 +1436,7 @@ header lines. A table might look like this: #+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 @@ -1525,14 +1527,14 @@ you, configure the option ~org-table-auto-blank-field~. #+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: @@ -1561,7 +1563,7 @@ you, configure the option ~org-table-auto-blank-field~. #+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~) :: @@ -1774,7 +1776,7 @@ you, configure the option ~org-table-auto-blank-field~. #+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~. @@ -1795,7 +1797,7 @@ The alignment of a column is determined automatically from the 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 @@ -1862,7 +1864,7 @@ with the following tools: 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. @@ -2000,12 +2002,12 @@ The row specification only counts data lines and ignores horizontal 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 @@ -2094,7 +2096,7 @@ and ~org-table-current-column~. Examples: 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 @@ -2156,7 +2158,7 @@ valid in the referenced table. 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 @@ -2250,8 +2252,8 @@ formatting[fn:9]. A few examples: | =$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= | +| =($3-32)*5/9= | Fahrenheit to Celsius 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 ~printf~ specifier for display | | =vmean($2..$7)= | Compute column range mean, using vector function | @@ -2269,7 +2271,7 @@ Operations]]). For example - =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. @@ -2277,7 +2279,7 @@ Operations]]). For example 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. @@ -2291,7 +2293,7 @@ Operations]]). For example - =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. @@ -2364,7 +2366,7 @@ interpret everything past =;= as format specifier: : '(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 ";"); @@ -2496,7 +2498,7 @@ current column, evaluated and the current field replaced with the 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 @@ -2550,7 +2552,7 @@ Org has three predefined Emacs Lisp functions for lookups in tables. #+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. @@ -2784,7 +2786,7 @@ becomes the string =#ERROR=. If you want to see what is going on 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: @@ -3131,7 +3133,7 @@ Draw an ASCII bar in a table. {{{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 @@ -3173,8 +3175,7 @@ or alternatively #+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 =[=, @@ -3208,7 +3209,7 @@ incomplete and the internals are again displayed as plain text. 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: @@ -3679,8 +3680,8 @@ generally, act on 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)}}} :: @@ -3731,7 +3732,7 @@ generally, act on 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)}}}. @@ -3992,7 +3993,7 @@ The most important commands to work with TODO entries are: #+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 @@ -4099,9 +4100,9 @@ Using TODO types, it would be set up like this: #+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 @@ -4392,7 +4393,7 @@ of the DONE states, a line =CLOSED: [timestamp]= is inserted just 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=.] @@ -4421,7 +4422,7 @@ inserted after the headline as an itemized list, the newest first[fn:: See the variable ~org-log-states-order-reversed~.]. When taking a lot of notes, you might want to get the notes out of the way into a drawer (see [[*Drawers]]). Customize the variable ~org-log-into-drawer~ to -get this behavior---the recommended drawer for this is called +get this behavior---the recommended drawer for this to be called =LOGBOOK=[fn:: Note that the =LOGBOOK= drawer is unfolded when pressing {{{kbd(SPC)}}} in the agenda to show an entry---use {{{kbd(C-u SPC)}}} to keep it folded here.]. You can also overrule @@ -4448,9 +4449,9 @@ and that a note is recorded when switching to =WAIT= or 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 @@ -4614,7 +4615,7 @@ right after the TODO keyword, like this: #+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~, @@ -4626,7 +4627,7 @@ You can also use numeric values for priorities, such as When using numeric priorities, you need to set ~org-priority-highest~, ~org-priority-lowest~ and ~org-priority-default~ to integers, which -must all be strictly inferior to 65. +must all be strictly less than 65. Priorities can be attached to any heading; they do not need to be TODO items. @@ -4702,7 +4703,7 @@ updated each time the TODO status of a child changes, or when pressing #+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 @@ -5309,10 +5310,10 @@ related information into special lists. 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 +Boolean logic ...like =+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]]. @@ -6800,14 +6801,14 @@ special repeaters =++= and =.+=. For example: #+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 @@ -6815,11 +6816,11 @@ special repeaters =++= and =.+=. For example: ,** 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 @@ -6901,8 +6902,8 @@ about what to do with it. #+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 @@ -7002,7 +7003,7 @@ about what to do with it. #+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. @@ -7198,7 +7199,7 @@ using the =:formatter= parameter. 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= :: @@ -7722,7 +7723,7 @@ global searches like the construction of agenda views fast. #+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~) :: @@ -7772,7 +7773,7 @@ location as the value (see [[*Properties and Columns]]). #+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. @@ -7913,9 +7914,9 @@ You may also define a global key for capturing new material (see #+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~) :: @@ -8505,8 +8506,8 @@ remote, computer, like emails or source code files belonging to a 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: @@ -13231,7 +13232,7 @@ should in principle be exportable as a Beamer presentation. 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. @@ -17279,7 +17280,7 @@ non-Org files, you always need to specify the publishing function: - ~: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 @@ -17585,7 +17586,7 @@ to include attachments such as JPG, CSS or PNG files in the project 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 @@ -17735,7 +17736,7 @@ resources. For example, consider the following Org mode snippet : 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: @@ -18111,7 +18112,7 @@ A source code block conforms to this structure: ,#+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 @@ -18246,7 +18247,7 @@ Org expand =:noweb= references by default. (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:~, where @@ -18295,7 +18296,7 @@ Properties defined through ~org-set-property~ function, bound to {{{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:= where {{{var()}}} is the language @@ -18846,9 +18847,9 @@ to the end of the code block for execution. #+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: @@ -19315,7 +19316,7 @@ follows from the type specified above. The =wrap= header argument unconditionally marks the results block by appending strings to =#+BEGIN_= and =#+END_=. If no string is specified, Org wraps the results in a =#+BEGIN_results= -... =#+END_results= block. It takes precedent over the =results= +... =#+END_results= block. It takes precedence over the =results= value listed above. E.g., #+begin_example @@ -19746,7 +19747,7 @@ code block header arguments: #+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 @@ -20462,11 +20463,11 @@ including the user-defined ones. #+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 @@ -20640,7 +20641,7 @@ manual, but here is a consolidated list for easy reference. - 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. @@ -21321,7 +21322,7 @@ moves across a special context. #+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 @@ -22024,7 +22025,7 @@ A review of =ol-man.el=: :END: #+cindex: hyperlinks, adding preview behavior -By default, Org supports previewing external links for links ot type +By default, Org supports previewing external links for links of type =file= and =attachment= that point to image files. (See [[*Images]].) Support for previewing other link types inline can be added to Org in @@ -22978,7 +22979,7 @@ Since the first release, literally thousands of emails to me or to the [[mailto:emacs-orgmode@gnu.org][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 +a list here 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. @@ -23081,9 +23082,9 @@ I received support from so many users that it is clearly impossible to 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 @@ -23159,7 +23160,7 @@ community and the code. - 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