Update org-mode manual to 9.7

docs/org/1 Introduction.md

@@ -2,10 +2,8 @@
 slug: Introduction
 ---
 
-|                                          |    |                                              |
-| :--------------------------------------- | -- | :------------------------------------------- |
-| • [Summary](/docs/org/Summary)           |    | Brief summary of what Org does.              |
-| • [Installation](/docs/org/Installation) |    | Installing Org.                              |
-| • [Activation](/docs/org/Activation)     |    | How to activate Org for certain buffers.     |
-| • [Feedback](/docs/org/Feedback)         |    | Bug reports, ideas, patches, etc.            |
-| • [Conventions](/docs/org/Conventions)   |    | Typesetting conventions used in this manual. |
+*   [Summary](/docs/org/Summary)
+*   [Installation](/docs/org/Installation)
+*   [Activation](/docs/org/Activation)
+*   [Feedback](/docs/org/Feedback)
+*   [Typesetting Conventions Used in this Manual](/docs/org/Conventions)

docs/org/1.1 Summary.md

@@ -2,9 +2,13 @@
 slug: Summary
 ---
 
-Org is a mode for keeping notes, maintaining TODO lists, and project planning with a fast and effective plain-text markup language. It also is an authoring system with unique support for literate programming and reproducible research.
+Org Mode is an authoring tool and a TODO lists manager for GNU Emacs. It relies on a lightweight plain-text markup language used in files with the ‘`.org`’ extension.
 
-Org is implemented on top of Outline mode, which makes it possible to keep the content of large files well structured. Visibility cycling and structure editing help to work with the tree. Tables are easily created with a built-in table editor. Plain text URL-like links connect to websites, emails, Usenet messages, BBDB entries, and any files related to the projects.
+Authoring Org files is best supported by Emacs, but you can view, understand, and change them with any text editor.
+
+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 tasks, exporting your agendas, etc.
+
+Org mode is implemented on top of Outline mode, which makes it possible to keep the content of large files well structured. Visibility cycling and structure editing help to work with the tree. Tables are easily created with a built-in table editor. Plain text URL-like links connect to websites, emails, Usenet messages, BBDB 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 node. Based on this data, specific entries can be extracted in queries and 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.
 
@@ -18,4 +22,4 @@ All of this is achieved with strictly plain text files, the most portable and fu
 
 There is a website for Org which provides links to the newest version of Org, as well as additional information, frequently asked questions (FAQ), links to tutorials, etc. This page is located at [https://orgmode.org](https://orgmode.org).
 
-An earlier version (7.3) of this manual is available as a [paperback book from Network Theory Ltd.](/docs/org/http://www.network-theory.co.uk/org/manual/).
+An earlier version (7.3) of this manual was available as a paperback book from the Network Theory Ltd. publishing company, closed in 2009.

docs/org/1.2 Installation.md

@@ -2,55 +2,45 @@
 slug: Installation
 ---
 
-Org is included in all recent distributions of GNU Emacs, so you probably do not need to install it. Most users will simply activate Org and begin exploring its many features.
+Org is included in distributions of GNU Emacs, 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 pre-packaged version, there are three ways to do it:
+If, for one reason or another, you want to install Org on top of this pre-packaged version, you can use the Emacs package system or clone Org’s git repository. We **strongly recommend** sticking to a single installation method.
 
-*   by using the Emacs package system;
-*   by downloading Org as an archive; or
-*   by using Org’s git repository.
+When installing Org on top of the pre-packaged version, please note that Org stable versions are meant to be fully compatible with the last three stable versions of Emacs but not with older Emacsen.
 
-We **strongly recommend** sticking to a single installation method.
+Some Org components also depend on third-party packages available through package archives. Org is only guaranteed to be compatible with the latest stable versions of these third-party packages.
 
 ## Using Emacs packaging system
 
-Recent Emacs distributions include a packaging system which lets you install Elisp libraries. You can install Org from the “package menu", with `M-x list-packages`. See [(emacs)Package Menu](https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Package-Menu).
+Recent Emacs distributions include a packaging system which lets you install Elisp libraries. You can install Org from the “package menu", with `M-x list-packages`. See [Package Menu](https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Package-Menu).
 
 > **Important:** 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.
 
-If you want to use Org’s package repository, check out the [Org ELPA page](https://orgmode.org/elpa.html).
-
-## Downloading Org as an archive
-
-You can download Org latest release from [Org’s website](https://orgmode.org/). In this case, make sure you set the load path correctly in your Emacs init file:
-
-```lisp
-(add-to-list 'load-path "~/path/to/orgdir/lisp")
-```
-
-The downloaded archive contains contributed libraries that are not included in Emacs. If you want to use them, add the ‘`contrib/`’ directory to your load path:
-
-```lisp
-(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
-```
-
-Optionally, you can compile the files and/or install them in your system. Run ‘`make help`’ to list compilation and installation options.
-
 ## Using Org’s git repository
 
 You can clone Org’s repository and install Org like this:
 
 ```lisp
 $ cd ~/src/
-$ git clone https://code.orgmode.org/bzg/org-mode.git
+$ git clone https://git.savannah.gnu.org/git/emacs/org-mode.git
 $ cd org-mode/
 $ make autoloads
 ```
 
 Note that in this case, ‘`make autoloads`’ is mandatory: it defines Org’s version in ‘`org-version.el`’ and Org’s autoloads in ‘`org-loaddefs.el`’.
 
-Remember to add the correct load path as described in the method above.
+Make sure you set the load path correctly in your Emacs init file:
+
+```lisp
+(add-to-list 'load-path "~/src/org-mode/lisp")
+```
 
 You can also compile with ‘`make`’, generate the documentation with ‘`make doc`’, create a local configuration with ‘`make config`’ and install Org with ‘`make install`’. Please run ‘`make help`’ to get the list of compilation/installation options.
 
 For more detailed explanations on Org’s build system, please check the Org Build System page on [Worg](https://orgmode.org/worg/dev/org-build-system.html).
+
+## Installing Org’s contributed packages
+
+Org’s repository used to contain ‘`contrib/`’ directory for add-ons contributed by others. As of Org 9.5, the directory has been moved to the dedicated org-contrib [repository](https://git.sr.ht/~bzg/org-contrib), which you can install separately as a [package](https://elpa.nongnu.org/nongnu/org-contrib.html) from NonGNU ELPA.
+
+There are enough valuable packages maintained outside of the Org repository. Worg has a list of [org-contrib and external packages](https://orgmode.org/worg/org-contrib/index.html), certainly it is not exhaustive.

docs/org/1.3 Activation.md

@@ -4,14 +4,14 @@ slug: Activation
 
 Org mode buffers need Font Lock to be turned on: this is the default in Emacs[^1].
 
-There are compatibility issues between Org mode and some other Elisp packages (see [Conflicts](/docs/org/Conflicts)). Please take the time to check the list.
+There are compatibility issues between Org mode and some other Elisp packages (see [Packages that conflict with Org mode](/docs/org/Conflicts)). Please take the time to check the list.
 
-For a better experience, the three Org commands `org-store-link`, `org-capture` and `org-agenda` ought to be accessible anywhere in Emacs, not just in Org buffers. To that effect, you need to bind them to globally available keys, like the ones reserved for users (see [(elisp)Key Binding Conventions](https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Key-Binding-Conventions)). Here are suggested bindings, please modify the keys to your own liking.
+For a better experience, the three Org commands `org-store-link`, `org-capture` and `org-agenda` ought to be accessible anywhere in Emacs, not just in Org buffers. To that effect, you need to bind them to globally available keys, like the ones reserved for users (see [(elisp)Key Binding Conventions](https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Key-Binding-Conventions)). Here are suggested bindings, please modify the keys to your own liking in your [personal init file](https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Init-File).
 
 ```lisp
-(global-set-key (kbd "C-c l") 'org-store-link)
-(global-set-key (kbd "C-c a") 'org-agenda)
-(global-set-key (kbd "C-c c") 'org-capture)
+(global-set-key (kbd "C-c l") #'org-store-link)
+(global-set-key (kbd "C-c a") #'org-agenda)
+(global-set-key (kbd "C-c c") #'org-capture)
 ```
 
 Files with the ‘`.org`’ extension use Org mode by default. To turn on Org mode in a file that does not have the extension ‘`.org`’, make the first line of a file look like this:
@@ -24,4 +24,4 @@ which selects Org mode for this buffer no matter what the file’s name is. See
 
 Many commands in Org work on the region if the region is *active*. To make use of this, you need to have Transient Mark mode turned on, which is the default. If you do not like it, you can create an active region by using the mouse to select a region, or pressing `C-SPC` twice before moving point.
 
-[^1]: If you do not use Font Lock globally turn it on in Org buffer with ‘`(add-hook 'org-mode-hook 'turn-on-font-lock)`’.
+[^1]: If you do not use Font Lock globally turn it on in Org buffer with ‘`(add-hook 'org-mode-hook #'turn-on-font-lock)`’.

docs/org/1.4 Feedback.md

@@ -2,7 +2,7 @@
 slug: Feedback
 ---
 
-If you find problems with Org, or if you have questions, remarks, or ideas about it, please send an email to the Org mailing list [emacs-orgmode@gnu.org](/docs/org/mailto:emacs-orgmode@gnu.org). You can subscribe to the list [from this web page](https://lists.gnu.org/mailman/listinfo/emacs-orgmode). If you are not a member of the mailing list, your mail will be passed to the list after a moderator has approved it[^1]. We ask you to read and respect the [GNU Kind Communications Guidelines](https://www.gnu.org/philosophy/kind-communication.html) when sending messages on this mailing list.
+If you find problems with Org, or if you have questions, remarks, or ideas about it, please send an email to the Org mailing list [mailto:emacs-orgmode@gnu.org](mailto:mailto:emacs-orgmode@gnu.org). You can subscribe to the list [from this web page](https://lists.gnu.org/mailman/listinfo/emacs-orgmode). If you are not a member of the mailing list, your mail will be passed to the list after a moderator has approved it[^1]. We ask you to read and respect the [GNU Kind Communications Guidelines](https://www.gnu.org/philosophy/kind-communication.html) when sending messages on this mailing list. Please allow up to one month for the response and followup if no response is received on the bug report.
 
 For bug reports, please first try to reproduce the bug with the latest version of Org available—if you are running an outdated version, it 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 (`M-x emacs-version`) and Org (`M-x org-version`), as well as the Org related setup in the Emacs init file. The easiest way to do this is to use the command
 
@@ -30,7 +30,15 @@ However if you are using Org mode as distributed with Emacs, a minimal setup is
 
 ;; Add latest Org mode to load path.
 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
-(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
+```
+
+If you are using Org mode version from Git repository, you can start minimal session using make.
+
+```lisp
+# Bare Emacs
+make repro
+# or pass extra arguments
+make repro REPRO_ARGS="-l /path/to/minimal/config.el /tmp/bug.org"
 ```
 
 If an error occurs, a “backtrace" can be very useful—see below on how to create one. Often a small example file helps, along with clear information about:
@@ -39,6 +47,8 @@ If an error occurs, a “backtrace" can be very useful—see below on how to cre
 2.  What did you expect to happen?
 3.  What happened instead?
 
+If you experience degraded performance, you can record a “profile" and share it on the Org mailing list. See below for the instructions how to record a useful profile.
+
 Thank you for helping to improve this program.
 
 ## How to create a useful backtrace
@@ -65,4 +75,51 @@ If working with Org produces an error with a message you do not understand, you
 
 4.  When you hit the error, a ‘`*Backtrace*`’ buffer appears on the screen. Save this buffer to a file—for example using `C-x C-w`—and attach it to your bug report.
 
+## How to profile Org performance
+
+Sometimes, Org is becoming 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:
+
+1.  Make sure that no profiler is currently active:
+
+    ```lisp
+    M-x profiler-stop <RET>
+    ```
+
+2.  Start a new CPU profiler session:
+
+    ```lisp
+    M-x profiler-start <RET> cpu <RET>
+    ```
+
+3.  Use Emacs as usual, performing the actions that are deemed slow.
+
+4.  Display and examine the recorded performance statistics:
+
+    ```lisp
+    M-x profiler-report <RET>
+    ```
+
+    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.
+
+    ‘`<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 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.
+
+    Pressing ‘`C`’ `profiler-report-render-calltree` will recover the original view.
+
+5.  If you need further help, you can share the statistics data.
+
+    Just save the data by issuing
+
+    ```lisp
+    M-x profiler-report-write-profile <RET>
+    /path/to/profile-file-to-be-saved <RET>
+    ```
+
+    Then, you can attached the saved file to your email to the Org mailing list, alongside 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 recorded.
+
 [^1]: Please consider subscribing to the mailing list in order to minimize the work the mailing list moderators have to do.

docs/org/1.5 Typesetting Conventions Used in this Manual.md

@@ -16,7 +16,7 @@ TODO keywords are written with all capitals, even if they are user-defined.
 
 ### ‘`ARCHIVE`’
 
-Tags are case-sensitive. User-defined tags are written in lowercase; built-in tags with special meaning are written as they should appear in the document, usually with all capitals.
+Tags are case-sensitive. User-defined tags are usually written in lowercase; built-in tags with special meaning are written as they should appear in the document, usually with all capitals.
 
 ### ‘`Release`’
 

docs/org/10 Capture and Attachments.md

@@ -2,10 +2,8 @@
 slug: Capture-and-Attachments
 ---
 
-An important part of any organization system is the ability to quickly capture new ideas and tasks, and to associate reference material with them. Org does this using a process called *capture*. It also can store files related to a task (*attachments*) in a special directory. Finally, it can parse RSS feeds for information. To learn how to let external programs (for example a web browser) trigger Org to capture material, see [Protocols](/docs/org/Protocols).
+An important part of any organization system is the ability to quickly capture new ideas and tasks, and to associate reference material with them. Org does this using a process called *capture*. It also can store files related to a task (*attachments*) in a special directory. Finally, it can parse RSS feeds for information. To learn how to let external programs (for example a web browser) trigger Org to capture material, see [Protocols for External Access](/docs/org/Protocols).
 
-|                                        |    |                               |
-| :------------------------------------- | -- | :---------------------------- |
-| • [Capture](/docs/org/Capture)         |    | Capturing new stuff.          |
-| • [Attachments](/docs/org/Attachments) |    | Attach files to outlines.     |
-| • [RSS Feeds](/docs/org/RSS-Feeds)     |    | Getting input from RSS feeds. |
+*   [Capture](/docs/org/Capture)
+*   [Attachments](/docs/org/Attachments)
+*   [RSS Feeds](/docs/org/RSS-Feeds)

docs/org/10.1 Capture.md

@@ -4,8 +4,6 @@ slug: Capture
 
 Capture lets you quickly store notes with little interruption of your work flow. Org’s method for capturing new items is heavily inspired by John Wiegley’s excellent Remember package.
 
-|                                                      |    |                                             |
-| :--------------------------------------------------- | -- | :------------------------------------------ |
-| • [Setting up capture](/docs/org/Setting-up-capture) |    | Where notes will be stored.                 |
-| • [Using capture](/docs/org/Using-capture)           |    | Commands to invoke and terminate capture.   |
-| • [Capture templates](/docs/org/Capture-templates)   |    | Define the outline of different note types. |
+*   [Setting up capture](/docs/org/Setting-up-capture)
+*   [Using capture](/docs/org/Using-capture)
+*   [Capture templates](/docs/org/Capture-templates)

docs/org/10.1.2 Using capture.md

@@ -30,6 +30,6 @@ Visit the target location of a capture template. You get to select the template
 
 Visit the last stored capture item in its buffer.
 
-You can also jump to the bookmark `org-capture-last-stored`, which is automatically created unless you set `org-capture-bookmark` to `nil`.
+You can also jump to the bookmark `org-capture-last-stored`, which is automatically created unless you customize `org-bookmark-names-plist`.
 
 To insert the capture at point in an Org buffer, call `org-capture` with a `C-0` prefix argument.