From 1bcbd93360d06a5d88bfea7b3b2f6151262c64aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20A=2E=20Gomes?= Date: Wed, 6 Oct 2021 11:59:37 +0300 Subject: [PATCH 03/76] Fix docstrings. These changes don't impact the user. --- lisp/oc.el | 4 +- lisp/ol-bibtex.el | 28 +-- lisp/ol.el | 12 +- lisp/org-agenda.el | 94 +++++----- lisp/org-archive.el | 28 +-- lisp/org-capture.el | 14 +- lisp/org-clock.el | 16 +- lisp/org-colview.el | 6 +- lisp/org-compat.el | 10 +- lisp/org-crypt.el | 4 +- lisp/org-datetree.el | 6 +- lisp/org-element.el | 20 +- lisp/org-faces.el | 32 ++-- lisp/org-feed.el | 14 +- lisp/org-goto.el | 8 +- lisp/org-id.el | 4 +- lisp/org-indent.el | 8 +- lisp/org-inlinetask.el | 4 +- lisp/org-keys.el | 10 +- lisp/org-list.el | 8 +- lisp/org-macs.el | 2 +- lisp/org-mouse.el | 18 +- lisp/org-num.el | 40 ++-- lisp/org-refile.el | 28 +-- lisp/org.el | 408 ++++++++++++++++++++--------------------- lisp/ox-ascii.el | 26 +-- lisp/ox-beamer.el | 22 +-- lisp/ox-html.el | 24 +-- lisp/ox-icalendar.el | 16 +- lisp/ox-koma-letter.el | 26 +-- lisp/ox-latex.el | 22 +-- lisp/ox-man.el | 4 +- lisp/ox-md.el | 10 +- lisp/ox-odt.el | 12 +- lisp/ox-org.el | 10 +- lisp/ox-publish.el | 4 +- lisp/ox-texinfo.el | 26 +-- lisp/ox.el | 88 ++++----- 38 files changed, 558 insertions(+), 558 deletions(-) diff --git a/lisp/oc.el b/lisp/oc.el index 501c7a5c3..e186df6de 100644 --- a/lisp/oc.el +++ b/lisp/oc.el @@ -1049,7 +1049,7 @@ the same object, call `org-cite-adjust-note' first." The return value is suitable as a replacement for a \"print_bibliography\" keyword. As a consequence, the function -raises an error if S contains a headline." +raises an error if S contains a heading." (with-temp-buffer (insert s) (pcase (org-element-contents (org-element-parse-buffer)) @@ -1057,7 +1057,7 @@ raises an error if S contains a headline." (`(,(and section (guard (eq 'section (org-element-type section))))) (org-element-contents section)) (_ - (error "Headlines cannot replace a keyword"))))) + (error "Headings cannot replace a keyword"))))) (defun org-cite-parse-objects (s &optional affix) "Parse string S as a secondary string. diff --git a/lisp/ol-bibtex.el b/lisp/ol-bibtex.el index 23b00d5d8..812f57f10 100644 --- a/lisp/ol-bibtex.el +++ b/lisp/ol-bibtex.el @@ -248,8 +248,8 @@ For example setting to `BIB_' would allow interoperability with fireforg." (string))) (defcustom org-bibtex-treat-headline-as-title t - "Treat headline text as title if title property is absent. -If an entry is missing a title property, use the headline text as + "Treat heading text as title if title property is absent. +If an entry is missing a title property, use the heading text as the property. If this value is t, `org-bibtex-check' will ignore a missing title field." :group 'org-bibtex @@ -258,7 +258,7 @@ a missing title field." (defcustom org-bibtex-headline-format-function (lambda (entry) (cdr (assq :title entry))) - "Function returning the headline text for `org-bibtex-write'. + "Function returning the heading text for `org-bibtex-write'. It should take a single argument, the bibtex entry (an alist as returned by `org-bibtex-read'). The default value simply returns the entry title." @@ -279,7 +279,7 @@ not placed in the exported bibtex entry." (defcustom org-bibtex-key-property "CUSTOM_ID" "Property that holds the bibtex key. By default, this is CUSTOM_ID, which enables easy linking to -bibtex headlines from within an org file. This can be set to ID +bibtex headings from within an org file. This can be set to ID to enable global links, but only with great caution, as global IDs must be unique." :group 'org-bibtex @@ -354,7 +354,7 @@ and `org-tags-exclude-from-inheritance'." value))) (defun org-bibtex-headline () - "Return a bibtex entry of the given headline as a string." + "Return a bibtex entry of the given heading as a string." (letrec ((val (lambda (key lst) (cdr (assoc key lst)))) (to (lambda (string) (intern (concat ":" string)))) (from (lambda (key) (substring (symbol-name key) 1))) @@ -433,7 +433,7 @@ and `org-tags-exclude-from-inheritance'." (when (> (length result) 0) result))))) (defun org-bibtex-autokey () - "Generate an autokey for the current headline." + "Generate an autokey for the current heading." (org-bibtex-put org-bibtex-key-property (if org-bibtex-autogen-keys (let* ((entry (org-bibtex-headline)) @@ -580,8 +580,8 @@ ARG, when non-nil, is a universal prefix argument. See ;;; Bibtex <-> Org heading translation functions (defun org-bibtex (filename) - "Export each headline in the current file to a bibtex entry. -Headlines are exported using `org-bibtex-headline'." + "Export each heading in the current file to a bibtex entry. +Headings are exported using `org-bibtex-headline'." (interactive (list (read-file-name "Bibtex file: " nil nil nil @@ -607,7 +607,7 @@ Headlines are exported using `org-bibtex-headline'." (message "Bibtex error at %S" (nth 4 (org-heading-components)))))) (defun org-bibtex-check (&optional optional) - "Check the current headline for required fields. + "Check the current heading for required fields. With prefix argument OPTIONAL also prompt for optional fields." (interactive "P") (save-restriction @@ -617,14 +617,14 @@ With prefix argument OPTIONAL also prompt for optional fields." (when type (org-bibtex-fleshout type optional))))) (defun org-bibtex-check-all (&optional optional) - "Check all headlines in the current file. + "Check all headings in the current file. With prefix argument OPTIONAL also prompt for optional fields." (interactive) (org-map-entries (lambda () (org-bibtex-check optional)))) (defun org-bibtex-create (&optional arg nonew) "Create a new entry at the given level. With a prefix arg, query for optional fields as well. -If nonew is t, add data to the headline of the entry at point." +If nonew is t, add data to the heading of the entry at point." (interactive "P") (let* ((type (completing-read "Type: " (mapcar (lambda (type) @@ -732,7 +732,7 @@ Return the number of saved entries." (mapc togtag org-bibtex-tags))) (defun org-bibtex-yank () - "If kill ring holds a bibtex entry yank it as an Org headline." + "If kill ring holds a bibtex entry yank it as an Org heading." (interactive) (let (entry) (with-temp-buffer (yank 1) (setf entry (org-bibtex-read))) @@ -741,7 +741,7 @@ Return the number of saved entries." (error "Yanked text does not appear to contain a BibTeX entry")))) (defun org-bibtex-import-from-file (file) - "Read bibtex entries from FILE and insert as Org headlines after point." + "Read bibtex entries from FILE and insert as Org headings after point." (interactive "fFile: ") (dotimes (_ (org-bibtex-read-file file)) (save-excursion (org-bibtex-write)) @@ -749,7 +749,7 @@ Return the number of saved entries." (open-line 1) (forward-char 1))) (defun org-bibtex-export-to-kill-ring () - "Export current headline to kill ring as bibtex entry." + "Export current heading to kill ring as bibtex entry." (interactive) (let ((result (org-bibtex-headline))) (kill-new result) result)) diff --git a/lisp/ol.el b/lisp/ol.el index 3b93ad721..4a26efc2d 100644 --- a/lisp/ol.el +++ b/lisp/ol.el @@ -337,11 +337,11 @@ another window." (const wl-other-frame))))) (defcustom org-link-search-must-match-exact-headline 'query-to-create - "Non-nil means internal fuzzy links can only match headlines. + "Non-nil means internal fuzzy links can only match headings. When nil, the a fuzzy link may point to a target or a named construct in the document. When set to the special value -`query-to-create', offer to create a new headline when none +`query-to-create', offer to create a new heading when none matched. Spaces and statistics cookies are ignored during heading searches." @@ -349,8 +349,8 @@ Spaces and statistics cookies are ignored during heading searches." :version "24.1" :type '(choice (const :tag "Use fuzzy text search" nil) - (const :tag "Match only exact headline" t) - (const :tag "Match exact headline or query to create it" + (const :tag "Match only exact heading" t) + (const :tag "Match exact heading or query to create it" query-to-create)) :safe #'symbolp) @@ -1261,13 +1261,13 @@ of matched result, which is either `dedicated' or `fuzzy'." type)) (defun org-link-heading-search-string (&optional string) - "Make search string for the current headline or STRING. + "Make search string for the current heading or STRING. Search string starts with an asterisk. COMMENT keyword and statistics cookies are removed, and contiguous spaces are packed into a single one. -When optional argument STRING is non-nil, assume it a headline, +When optional argument STRING is non-nil, assume it a heading, without any asterisk, TODO or COMMENT keyword, and without any priority cookie or tag." (concat "*" diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 5fb136fb5..ddfaf9a66 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -313,7 +313,7 @@ the daily/weekly agenda, see `org-agenda-skip-function'.") (choice :tag "Setting" (list :tag "Heading for this block" (const org-agenda-overriding-header) - (string :tag "Headline")) + (string :tag "Heading")) (list :tag "Files to be searched" (const org-agenda-files) (list @@ -461,7 +461,7 @@ desc A description of the command, when omitted or nil, a default type The command type, any of the following symbols: agenda The daily/weekly agenda. todo Entries with a specific TODO keyword, in all agenda files. - search Entries containing search words entry or headline. + search Entries containing search words entry or heading. tags Tags/Property/TODO match in all agenda files. tags-todo Tags/P/T match in all agenda files, TODO entries only. todo-tree Sparse tree of specific TODO keyword in *current* file. @@ -595,13 +595,13 @@ you can then use it to define a custom command." This is a list of four items: 1. A tags/todo/property matcher string that is used to identify a project. See the manual for a description of tag and property searches. - The entire tree below a headline matched by this is considered one project. + The entire tree below a heading matched by this is considered one project. 2. A list of TODO keywords identifying non-stuck projects. - If the project subtree contains any headline with one of these todo + If the project subtree contains any heading with one of these todo keywords, the project is considered to be not stuck. If you specify \"*\" as a keyword, any TODO keyword will mark the project unstuck. 3. A list of tags identifying non-stuck projects. - If the project subtree contains any headline with one of these tags, + If the project subtree contains any heading with one of these tags, the project is considered to be not stuck. If you specify \"*\" as a tag, any tag will mark the project unstuck. Note that this is about the explicit presence of a tag somewhere in the subtree, inherited @@ -674,7 +674,7 @@ files will be included.") (defcustom org-agenda-restriction-lock-highlight-subtree t "Non-nil means highlight the whole subtree when restriction is active. -Otherwise only highlight the headline. Highlighting the whole subtree is +Otherwise only highlight the heading. Highlighting the whole subtree is useful to ensure no edits happen beyond the restricted region." :group 'org-agenda :type 'boolean) @@ -1012,7 +1012,7 @@ The buffer is still writable when the hook is called. You can modify some of the buffer substrings but you should be extra careful not to modify the text properties of the agenda -headlines as the agenda display heavily relies on them." +headings as the agenda display heavily relies on them." :group 'org-agenda-startup :type 'hook) @@ -1480,7 +1480,7 @@ When nil, they may also match part of a word." (defcustom org-agenda-search-view-max-outline-level 0 "Maximum outline level to display in search view. E.g. when this is set to 1, the search view will only -show headlines of level 1. When set to 0, the default +show headings of level 1. When set to 0, the default value, don't limit agenda view by outline level." :group 'org-agenda-search-view :version "26.1" @@ -1493,12 +1493,12 @@ value, don't limit agenda view by outline level." :group 'org-agenda) (defcustom org-agenda-search-headline-for-time t - "Non-nil means search headline for a time-of-day. -If the headline contains a time-of-day in one format or another, it will + "Non-nil means search heading for a time-of-day. +If the heading contains a time-of-day in one format or another, it will be used to sort the entry into the time sequence of items for a day. -Some people have time stamps in the headline that refer to the creation +Some people have time stamps in the heading that refer to the creation time or so, and then this produces an unwanted side effect. If this is -the case for your, use this variable to turn off searching the headline +the case for your, use this variable to turn off searching the heading for a time." :group 'org-agenda-time-grid :type 'boolean) @@ -1608,8 +1608,8 @@ user-defined-up Sort according to `org-agenda-cmp-user-defined', high last. user-defined-down Sort according to `org-agenda-cmp-user-defined', high first. habit-up Put entries that are habits first. habit-down Put entries that are habits last. -alpha-up Sort headlines alphabetically. -alpha-down Sort headlines alphabetically, reversed. +alpha-up Sort headings alphabetically. +alpha-down Sort headings alphabetically, reversed. The different possibilities will be tried in sequence, and testing stops if one comparison returns a \"not-equal\". For example, the default @@ -1827,14 +1827,14 @@ to capture the number of days." (defcustom org-agenda-remove-times-when-in-prefix t "Non-nil means remove duplicate time specifications in agenda items. When the format `org-agenda-prefix-format' contains a `%t' specifier, a -time-of-day specification in a headline or diary entry is extracted and +time-of-day specification in a heading or diary entry is extracted and placed into the prefix. If this option is non-nil, the original specification \(a timestamp or -range, or just a plain time(range) specification like 11:30-4pm) will be removed for agenda display. This makes the agenda less cluttered. The option can be t or nil. It may also be the symbol `beg', indicating that the time should only be removed when it is located at the beginning of -the headline/diary entry." +the heading/diary entry." :group 'org-agenda-line-format :type '(choice (const :tag "Always" t) @@ -1922,7 +1922,7 @@ Nil means don't hide any tags." 'org-agenda-remove-tags) (defcustom org-agenda-remove-tags nil - "Non-nil means remove the tags from the headline copy in the agenda. + "Non-nil means remove the tags from the heading copy in the agenda. When this is the symbol `prefix', only remove tags when `org-agenda-prefix-format' contains a `%T' specifier." :group 'org-agenda-line-format @@ -2825,9 +2825,9 @@ a Call `org-agenda-list' to display the agenda for current day or week. t Call `org-todo-list' to display the global todo list. T Call `org-todo-list' to display the global todo list, select only entries with a specific TODO keyword (the user gets a prompt). -m Call `org-tags-view' to display headlines with tags matching +m Call `org-tags-view' to display headings with tags matching a condition (the user is prompted for the condition). -M Like `m', but select only TODO entries, no ordinary headlines. +M Like `m', but select only TODO entries, no ordinary headings. e Export views to associated files. s Search entries for keywords. S Search entries for keywords, only with TODO keywords. @@ -3364,7 +3364,7 @@ item is a list of comma-separated values, like this: category,head,type,todo,tags,date,time,extra,priority-l,priority-n category The category of the item -head The headline, without TODO kwd, TAGS and PRIORITY +head The heading, without TODO kwd, TAGS and PRIORITY type The type of the agenda entry, can be todo selected in TODO match tagsmatch selected in tags match @@ -4574,7 +4574,7 @@ regular expressions that must or (when preceded with \"-\") must not match in the entry. Snippets enclosed into double quotes will be taken as a whole, to include whitespace. -- If the search string starts with an asterisk, search only in headlines. +- If the search string starts with an asterisk, search only in headings. - If (possibly after the leading star) the search string starts with an exclamation mark, this also means to look at TODO entries only, an effect that can also be achieved with a prefix argument. @@ -4949,7 +4949,7 @@ to search again: (0)[ALL]")) ;;;###autoload (defun org-tags-view (&optional todo-only match) - "Show all headlines for all `org-agenda-files' matching a TAGS criterion. + "Show all headings for all `org-agenda-files' matching a TAGS criterion. The prefix arg TODO-ONLY limits the search to TODO entries." (interactive "P") (when org-agenda-overriding-arguments @@ -5014,7 +5014,7 @@ The prefix arg TODO-ONLY limits the search to TODO entries." (setq rtnall (append rtnall rtn)))))))) (org-agenda--insert-overriding-header (with-temp-buffer - (insert "Headlines with TAGS match: ") + (insert "Headings with TAGS match: ") (add-text-properties (point-min) (1- (point)) (list 'face 'org-agenda-structure 'short-heading @@ -6675,7 +6675,7 @@ specifier in the format. DOTIME, when non-nil, indicates that a time-of-day should be extracted from TXT for sorting of this entry, and for the `%t' specifier in the format. When DOTIME is a string, this string is searched for a time before TXT is. -TAGS can be the tags of the headline. +TAGS can be the tags of the heading. Any match of REMOVE-RE will be removed from TXT." ;; We keep the org-prefix-* variable values along with a compiled ;; formatter, so that multiple agendas existing at the same time do @@ -7237,7 +7237,7 @@ The optional argument TYPE tells the agenda type." ((< lb la) +1)))) (defsubst org-cmp-alpha (a b) - "Compare the headlines, alphabetically." + "Compare the headings, alphabetically." (let* ((pla (text-property-any 0 (length a) 'org-heading t a)) (plb (text-property-any 0 (length b) 'org-heading t b)) (ta (and pla (substring a pla))) @@ -7366,7 +7366,7 @@ their type." ;;; Agenda restriction lock (defvar org-agenda-restriction-lock-overlay (make-overlay 1 1) - "Overlay to mark the headline to which agenda commands are restricted.") + "Overlay to mark the heading to which agenda commands are restricted.") (overlay-put org-agenda-restriction-lock-overlay 'face 'org-agenda-restriction-lock) (overlay-put org-agenda-restriction-lock-overlay @@ -7395,7 +7395,7 @@ Argument ARG is the prefix argument." When in a restricted subtree, remove it. The restriction will span over the entire file if TYPE is `file', -or if type is '(4), or if the cursor is before the first headline +or if type is '(4), or if the cursor is before the first heading in the file. Otherwise, only apply the restriction to the current subtree." (interactive "P") @@ -7687,7 +7687,7 @@ filter." (t (error "No category at point")))))) (defun org-find-top-headline (&optional pos) - "Find the topmost parent headline and return it. + "Find the topmost parent heading and return it. POS when non-nil is the marker or buffer position to start the search from." (save-excursion @@ -7702,8 +7702,8 @@ search from." (defvar org-agenda-filtered-by-top-headline nil) (defun org-agenda-filter-by-top-headline (strip) - "Keep only those lines that are descendants from the same top headline. -The top headline is that of the current line. With prefix arg STRIP, hide + "Keep only those lines that are descendants from the same top heading. +The top heading is that of the current line. With prefix arg STRIP, hide all lines of the category at point." (interactive "P") (if org-agenda-filtered-by-top-headline @@ -7713,7 +7713,7 @@ all lines of the category at point." (org-agenda-filter-show-all-top-filter)) (let ((toph (org-find-top-headline (org-get-at-bol 'org-hd-marker)))) (if toph (org-agenda-filter-top-headline-apply toph strip) - (error "No top-level headline at point"))))) + (error "No top-level heading at point"))))) (defvar org-agenda-regexp-filter nil) (defun org-agenda-filter-by-regexp (strip-or-accumulate) @@ -8231,7 +8231,7 @@ grouptags." (ignore-errors (org-agenda-previous-line)))) (defun org-agenda-filter-top-headline-apply (hl &optional negative) - "Filter by top headline HL." + "Filter by top heading HL." (org-agenda-set-mode-name) (save-excursion (goto-char (point-min)) @@ -9410,7 +9410,7 @@ the dedicated frame." (org-tree-to-indirect-buffer arg))))) (defvar org-last-heading-marker (make-marker) - "Marker pointing to the headline that last changed its TODO state + "Marker pointing to the heading that last changed its TODO state by a remote command from the agenda.") (defun org-agenda-todo-nextset () @@ -9428,7 +9428,7 @@ by a remote command from the agenda.") (defun org-agenda-todo (&optional arg) "Cycle TODO state of line at point, also in Org file. This changes the line at point, all other lines in the agenda referring to -the same tree node, and the headline of the tree node in the Org file." +the same tree node, and the heading of the tree node in the Org file." (interactive "P") (org-agenda-check-no-diary) (org-agenda-maybe-loop @@ -9608,7 +9608,7 @@ current line." (defun org-agenda-priority (&optional force-direction) "Set the priority of line at point, also in Org file. This changes the line at point, all other lines in the agenda -referring to the same tree node, and the headline of the tree +referring to the same tree node, and the heading of the tree node in the Org file. Called with one universal prefix arg, show the priority instead @@ -9639,7 +9639,7 @@ When called programmatically, FORCE-DIRECTION can be `set', `up', ;; FIXME: should fix the tags property of the agenda line. (defun org-agenda-set-tags (&optional tag onoff) - "Set tags for the current headline." + "Set tags for the current heading." (interactive) (org-agenda-check-no-diary) (if (and (org-region-active-p) (called-interactively-p 'any)) @@ -9664,7 +9664,7 @@ When called programmatically, FORCE-DIRECTION can be `set', `up', (beginning-of-line 1))))) (defun org-agenda-set-property () - "Set a property for the current headline." + "Set a property for the current heading." (interactive) (org-agenda-check-no-diary) (org-agenda-maybe-loop @@ -9683,7 +9683,7 @@ When called programmatically, FORCE-DIRECTION can be `set', `up', (call-interactively 'org-set-property)))))) (defun org-agenda-set-effort () - "Set the effort property for the current headline." + "Set the effort property for the current heading." (interactive) (org-agenda-check-no-diary) (org-agenda-maybe-loop @@ -10049,7 +10049,7 @@ top-level as top-level entries at the end of the file." (defun org-agenda-add-entry-to-org-agenda-diary-file (type text &optional d1 d2) "Add a diary entry with TYPE to `org-agenda-diary-file'. -If TEXT is not empty, it will become the headline of the new entry, and +If TEXT is not empty, it will become the heading of the new entry, and the resulting entry will not be shown. When TEXT is empty, switch to `org-agenda-diary-file' and let the user finish the entry there." (let ((cw (current-window-configuration))) @@ -10126,7 +10126,7 @@ the resulting entry will not be shown. When TEXT is empty, switch to (defun org-agenda-insert-diary-as-top-level (text) "Make new entry as a top-level entry at the end of the file. -Add TEXT as headline, and position the cursor in the second line so that +Add TEXT as heading, and position the cursor in the second line so that a timestamp can be added there." (widen) (goto-char (point-max)) @@ -10444,17 +10444,17 @@ bulk action." :type 'boolean) (defcustom org-agenda-loop-over-headlines-in-active-region t - "Shall some commands act upon headlines in the active region? + "Shall some commands act upon headings in the active region? -When set to t, some commands will be performed in all headlines +When set to t, some commands will be performed in all headings within the active region. When set to `start-level', some commands will be performed in all -headlines within the active region, provided that these headlines +headlines within the active region, provided that these headings are of the same level than the first one. When set to a regular expression, those commands will be -performed on the matching headlines within the active region. +performed on the matching headings within the active region. The list of commands is: `org-agenda-schedule', `org-agenda-deadline', `org-agenda-date-prompt', @@ -10463,8 +10463,8 @@ The list of commands is: `org-agenda-schedule', See `org-loop-over-headlines-in-active-region' for the equivalent option for Org buffers." :type '(choice (const :tag "Don't loop" nil) - (const :tag "All headlines in active region" t) - (const :tag "In active region, headlines at the same level than the first one" start-level) + (const :tag "All headings in active region" t) + (const :tag "In active region, headings at the same level than the first one" start-level) (regexp :tag "Regular expression matcher")) :version "27.1" :package-version '(Org . "9.4") @@ -10794,7 +10794,7 @@ either `headline' or `category'. For example: \\='((headline \"IMPORTANT\") (category \"Work\")) -will only add headlines containing IMPORTANT or headlines +will only add headings containing IMPORTANT or headings belonging to the \"Work\" category. ARGS are symbols indicating what kind of entries to consider. diff --git a/lisp/org-archive.el b/lisp/org-archive.el index fc73f5926..24d4aad1b 100644 --- a/lisp/org-archive.el +++ b/lisp/org-archive.el @@ -119,11 +119,11 @@ This variable can be a list of any of the following symbols: time The time of archiving. file The file where the entry originates. -ltags The local tags, in the headline of the subtree. +ltags The local tags, in the heading of the subtree. itags The tags the subtree inherits from further up the hierarchy. todo The pre-archive TODO state. category The category, taken from file name or #+CATEGORY lines. -olpath The outline path to the item. These are all headlines above +olpath The outline path to the item. These are all headings above the current item, separated by /, like a file path. For each symbol present in the list, a property will be created in @@ -207,8 +207,8 @@ trees without any open TODO items and archive them (after getting confirmation from the user). When called with a double prefix argument, find whole trees with timestamps before today and archive them (after getting confirmation from the user). If the -cursor is not at a headline when these commands are called, try -all level 1 trees. If the cursor is on a headline, only try the +cursor is not at a heading when these commands are called, try +all level 1 trees. If the cursor is on a heading, only try the direct children of this heading." (interactive "P") (if (and (org-region-active-p) org-loop-over-headlines-in-active-region) @@ -494,8 +494,8 @@ Archiving time is retained in the ARCHIVE_TIME node property." (defun org-archive-all-done (&optional tag) "Archive sublevels of the current tree without open TODO items. -If the cursor is not on a headline, try all level 1 trees. If -it is on a headline, try all direct children. +If the cursor is not on a heading, try all level 1 trees. If +it is on a heading, try all direct children. When TAG is non-nil, don't move trees, but mark them with the ARCHIVE tag." (org-archive-all-matches (lambda (_beg end) @@ -506,8 +506,8 @@ When TAG is non-nil, don't move trees, but mark them with the ARCHIVE tag." (defun org-archive-all-old (&optional tag) "Archive sublevels of the current tree with timestamps prior to today. -If the cursor is not on a headline, try all level 1 trees. If -it is on a headline, try all direct children. +If the cursor is not on a heading, try all level 1 trees. If +it is on a heading, try all direct children. When TAG is non-nil, don't move trees, but mark them with the ARCHIVE tag." (org-archive-all-matches (lambda (_beg end) @@ -527,14 +527,14 @@ When TAG is non-nil, don't move trees, but mark them with the ARCHIVE tag." "Archive sublevels of the current tree that match PREDICATE. PREDICATE is a function of two arguments, BEG and END, which -specify the beginning and end of the headline being considered. -It is called with point positioned at BEG. The headline will be +specify the beginning and end of the heading being considered. +It is called with point positioned at BEG. The heading will be archived if PREDICATE returns non-nil. If the return value of PREDICATE is a string, it should describe the reason for archiving the heading. -If the cursor is not on a headline, try all level 1 trees. If it -is on a headline, try all direct children. When TAG is non-nil, +If the cursor is not on a heading, try all level 1 trees. If it +is on a heading, try all direct children. When TAG is non-nil, don't move trees, but mark them with the ARCHIVE tag." (let ((rea (concat ".*:" org-archive-tag ":")) re1 (begm (make-marker)) @@ -579,8 +579,8 @@ don't move trees, but mark them with the ARCHIVE tag." ;;;###autoload (defun org-toggle-archive-tag (&optional find-done) - "Toggle the archive tag for the current headline. -With prefix ARG, check all children of current headline and offer tagging + "Toggle the archive tag for the current heading. +With prefix ARG, check all children of current heading and offer tagging the children that do not contain any open TODO items." (interactive "P") (if (and (org-region-active-p) org-loop-over-headlines-in-active-region) diff --git a/lisp/org-capture.el b/lisp/org-capture.el index 837ef3a80..0657ff12d 100644 --- a/lisp/org-capture.el +++ b/lisp/org-capture.el @@ -158,7 +158,7 @@ description A short string describing the template, will be shown during selection. type The type of entry. Valid types are: - entry an Org node, with a headline. Will be filed + entry an Org node, with a heading. Will be filed as the child of the target entry or as a top-level entry. Its default template is: \"* %?\n %a\" @@ -195,7 +195,7 @@ target Specification of where the captured item should be placed. (id \"id of existing Org entry\") File as child of this entry, or in the body of the entry - (file+headline \"path/to/file\" \"node headline\") + (file+headline \"path/to/file\" \"node heading\") Fast configuration if the target heading is unique in the file (file+olp \"path/to/file\" \"Level 1 heading\" \"Level 2\" ...) @@ -296,7 +296,7 @@ properties are: The template defines the text to be inserted. Often this is an Org mode entry (so the first line should start with a star) that -will be filed as a child of the target headline. It can also be +will be filed as a child of the target heading. It can also be freely formatted text. Furthermore, the following %-escapes will be replaced with content and expanded: @@ -402,15 +402,15 @@ you can escape ambiguous cases with a backward slash, e.g., \\%i." (list :tag "ID" (const :format "" id) (string :tag " ID")) - (list :tag "File & Headline" + (list :tag "File & Heading" (const :format "" file+headline) ,file-variants - (string :tag " Headline")) + (string :tag " Heading")) (list :tag "File & Outline path" (const :format "" file+olp) ,file-variants (repeat :tag "Outline path" :inline t - (string :tag "Headline"))) + (string :tag "Heading"))) (list :tag "File & Regexp" (const :format "" file+regexp) ,file-variants @@ -419,7 +419,7 @@ you can escape ambiguous cases with a backward slash, e.g., \\%i." (const :format "" file+olp+datetree) ,file-variants (option (repeat :tag "Outline path" :inline t - (string :tag "Headline")))) + (string :tag "Heading")))) (list :tag "File & function" (const :format "" file+function) ,file-variants diff --git a/lisp/org-clock.el b/lisp/org-clock.el index c590680a6..26fbc28c0 100644 --- a/lisp/org-clock.el +++ b/lisp/org-clock.el @@ -182,7 +182,7 @@ which case all digits and capital letters are used up by the (defcustom org-clock-heading-function nil "When non-nil, should be a function to create `org-clock-heading'. This is the string shown in the mode line when a clock is running. -The function is called with point at the beginning of the headline." +The function is called with point at the beginning of the heading." :group 'org-clock :type '(choice (const nil) (function))) @@ -2037,10 +2037,10 @@ Use `\\[org-clock-remove-overlays]' to remove the subtree times." (defvar-local org-clock-overlays nil) (defun org-clock-put-overlay (time) - "Put an overlay on the headline at point, displaying TIME. + "Put an overlay on the heading at point, displaying TIME. Create a new overlay and store it in `org-clock-overlays', so that it will be easy to remove. This function assumes point is -on a headline." +on a heading." (org-match-line org-complex-heading-regexp) (goto-char (match-beginning 4)) (let* ((headline (match-string 4)) @@ -2904,17 +2904,17 @@ the correct buffer is current, and that the wanted restriction is in place. The return value will be a list with the file name and the total file time (in minutes) as 1st and 2nd elements. The third element -of this list will be a list of headline entries. Each entry has the +of this list will be a list of heading entries. Each entry has the following structure: - (LEVEL HEADLINE TAGS TIMESTAMP TIME PROPERTIES) + (LEVEL HEADING TAGS TIMESTAMP TIME PROPERTIES) -LEVEL: The level of the headline, as an integer. This will be +LEVEL: The level of the heading, as an integer. This will be the reduced level, so 1,2,3,... even if only odd levels are being used. -HEADLINE: The text of the headline. Depending on PARAMS, this may +HEADLINE: The text of the heading. Depending on PARAMS, this may already be formatted like a link. -TAGS: The list of tags of the headline. +TAGS: The list of tags of the heading. TIMESTAMP: If PARAMS require it, this will be a time stamp found in the entry, any of SCHEDULED, DEADLINE, NORMAL, or first inactive, in this sequence. diff --git a/lisp/org-colview.el b/lisp/org-colview.el index ca3de4cb8..5275b03bf 100644 --- a/lisp/org-colview.el +++ b/lisp/org-colview.el @@ -85,7 +85,7 @@ or (LABEL SUMMARIZE COLLECT) where a string summarizing the list of values. COLLECT is a function called with one argument, a property - name. It is called in the context of a headline and must + name. It is called in the context of a heading and must return the collected property, or the empty string. You can use this to only collect a property if a related conditional properties is set, e.g., to return VACATION_DAYS only if @@ -724,7 +724,7 @@ an integer, select that value." (`(,_ ,_ ,_ ,(or "X" "X/" "X%") ,_) '("[ ]" "[X]"))) (org-colview-construct-allowed-dates value)))) (if previous (reverse all) all)))) - (when (equal key "ITEM") (error "Cannot edit item headline from here")) + (when (equal key "ITEM") (error "Cannot edit item heading from here")) (unless (or allowed (member key '("SCHEDULED" "DEADLINE" "CLOCKSUM"))) (error "Allowed values for this property have not been defined")) (let* ((l (length allowed)) @@ -1461,7 +1461,7 @@ PARAMS is a property list of parameters: `:maxlevel' - When set to a number, don't capture headlines below this level. + When set to a number, don't capture headings below this level. `:skip-empty-rows' diff --git a/lisp/org-compat.el b/lisp/org-compat.el index 24c4b35f2..8f0bbde29 100644 --- a/lisp/org-compat.el +++ b/lisp/org-compat.el @@ -602,17 +602,17 @@ use of this function is for the stuck project list." (define-obsolete-function-alias 'org-get-tags-at 'org-get-tags "9.2") (defun org-get-local-tags () - "Get a list of tags defined in the current headline." + "Get a list of tags defined in the current heading." (declare (obsolete "use `org-get-tags' instead." "9.2")) (org-get-tags nil 'local)) (defun org-get-local-tags-at (&optional pos) - "Get a list of tags defined in the current headline." + "Get a list of tags defined in the current heading." (declare (obsolete "use `org-get-tags' instead." "9.2")) (org-get-tags pos 'local)) (defun org-get-tags-string () - "Get the TAGS string in the current headline." + "Get the TAGS string in the current heading." (declare (obsolete "use `org-make-tag-string' instead." "9.2")) (org-make-tag-string (org-get-tags nil t))) @@ -865,7 +865,7 @@ attention to case differences." :group 'org-structure) (defcustom org-imenu-depth 2 - "The maximum level for Imenu access to Org headlines. + "The maximum level for Imenu access to Org headings. This also applied for speedbar access." :group 'org-imenu-and-speedbar :type 'integer) @@ -977,7 +977,7 @@ To get rid of the restriction, use `\\[org-agenda-remove-restriction-lock]'." ;;;; Add Log (defun org-add-log-current-headline () - "Return current headline or nil. + "Return current heading or nil. This function ignores inlinetasks. It is meant to be used as `add-log-current-defun-function' value." (org-with-limited-levels (org-get-heading t t t t))) diff --git a/lisp/org-crypt.el b/lisp/org-crypt.el index 3ccc526bc..55b96f65b 100644 --- a/lisp/org-crypt.el +++ b/lisp/org-crypt.el @@ -205,7 +205,7 @@ Assume `epg-context' is set." ;;;###autoload (defun org-encrypt-entry () - "Encrypt the content of the current headline." + "Encrypt the content of the current heading." (interactive) (unless (org-at-encrypted-entry-p) (require 'epg) @@ -248,7 +248,7 @@ Assume `epg-context' is set." ;;;###autoload (defun org-decrypt-entry () - "Decrypt the content of the current headline." + "Decrypt the content of the current heading." (interactive) (pcase (org-at-encrypted-entry-p) (`(,beg . ,end) diff --git a/lisp/org-datetree.el b/lisp/org-datetree.el index 74442b038..1e73c2109 100644 --- a/lisp/org-datetree.el +++ b/lisp/org-datetree.el @@ -55,7 +55,7 @@ Added time stamp is active unless value is `inactive'." If KEEP-RESTRICTION is non-nil, do not widen the buffer. When it is nil, the buffer will be widened to make sure an existing date tree can be found. If it is the symbol `subtree-at-point', then the tree -will be built under the headline at point." +will be built under the heading at point." (org-datetree--find-create-group d 'day keep-restriction)) ;;;###autoload @@ -66,7 +66,7 @@ entries grouped by month instead of days. If KEEP-RESTRICTION is non-nil, do not widen the buffer. When it is nil, the buffer will be widened to make sure an existing date tree can be found. If it is the symbol `subtree-at-point', then the tree -will be built under the headline at point." +will be built under the heading at point." (org-datetree--find-create-group d 'month keep-restriction)) (defun org-datetree--find-create-group @@ -114,7 +114,7 @@ Compared to `org-datetree-find-date-create' this function creates entries ordered by week instead of months. When it is nil, the buffer will be widened to make sure an existing date tree can be found. If it is the symbol `subtree-at-point', then the tree -will be built under the headline at point." +will be built under the heading at point." (setq-local org-datetree-base-level 1) (save-restriction (if (eq keep-restriction 'subtree-at-point) diff --git a/lisp/org-element.el b/lisp/org-element.el index 9127105ca..da682c4a2 100644 --- a/lisp/org-element.el +++ b/lisp/org-element.el @@ -948,7 +948,7 @@ CONTENTS is the contents of the footnote-definition." ;;;; Heading (defun org-element--get-node-properties () - "Return node properties associated to headline at point. + "Return node properties associated to heading at point. Upcase property names. It avoids confusion between properties obtained through property drawer and default properties from the parser (e.g. `:end' and :END:). Return value is a plist." @@ -966,7 +966,7 @@ parser (e.g. `:end' and :END:). Return value is a plist." properties)))) (defun org-element--get-time-properties () - "Return time properties associated to headline at point. + "Return time properties associated to heading at point. Return value is a plist." (save-excursion (when (progn (forward-line) (looking-at org-planning-line-re)) @@ -984,7 +984,7 @@ Return value is a plist." plist)))) (defun org-element-headline-parser (limit &optional raw-secondary-p) - "Parse a headline. + "Parse a heading. Return a list whose CAR is `headline' and CDR is a plist containing `:raw-value', `:title', `:begin', `:end', @@ -1000,10 +1000,10 @@ beginning (e.g., `:CUSTOM_ID'). LIMIT is a buffer position bounding the search. -When RAW-SECONDARY-P is non-nil, headline's title will not be +When RAW-SECONDARY-P is non-nil, heading's title will not be parsed as a secondary string, but as a plain string instead. -Assume point is at beginning of the headline." +Assume point is at beginning of the heading." (save-excursion (let* ((begin (point)) (level (prog1 (org-reduced-level (skip-chars-forward "*")) @@ -4239,9 +4239,9 @@ buffer. Optional argument GRANULARITY determines the depth of the recursion. It can be set to the following symbols: -`headline' Only parse headlines. +`headline' Only parse headings. `greater-element' Don't recurse into greater elements except - headlines and sections. Thus, elements + headings and sections. Thus, elements parsed are the top-level ones. `element' Parse everything but objects and plain text. `object' Parse the complete buffer (default). @@ -4353,7 +4353,7 @@ and `example-block' elements in it: (org-element-map tree \\='(example-block src-block) #\\='identity) -The following snippet will find the first headline with a level +The following snippet will find the first heading with a level of 1 and a \"phone\" tag, and will return its beginning position: (org-element-map tree \\='headline @@ -5609,7 +5609,7 @@ request." "Parse elements in current section, down to POS. Start parsing from the closest between the last known element in -cache or headline above. Return the smallest element containing +cache or heading above. Return the smallest element containing POS. When optional argument SYNCP is non-nil, return the parent of the @@ -5751,7 +5751,7 @@ the process stopped before finding the expected result." ":\\(?:\\w\\|[-_]\\)+:[ \t]*$" "\\)") "Regexp matching a sensitive line, structure wise. -A sensitive line is a headline, inlinetask, block, drawer, or +A sensitive line is a heading, inlinetask, block, drawer, or latex-environment boundary. When such a line is modified, structure changes in the document may propagate in the whole section, possibly making cache invalid.") diff --git a/lisp/org-faces.el b/lisp/org-faces.el index b151045a9..aabf1f825 100644 --- a/lisp/org-faces.el +++ b/lisp/org-faces.el @@ -41,7 +41,7 @@ '((default :inherit fixed-pitch) (((background light)) (:foreground "white")) (((background dark)) (:foreground "black"))) - "Face used to hide leading stars in headlines. + "Face used to hide leading stars in headings. The foreground color of this face should be equal to the background color of the frame." :group 'org-faces) @@ -61,35 +61,35 @@ color of the frame." :group 'org-faces) (defface org-level-1 '((t :inherit outline-1)) - "Face used for level 1 headlines." + "Face used for level 1 headings." :group 'org-faces) (defface org-level-2 '((t :inherit outline-2)) - "Face used for level 2 headlines." + "Face used for level 2 headings." :group 'org-faces) (defface org-level-3 '((t :inherit outline-3)) - "Face used for level 3 headlines." + "Face used for level 3 headings." :group 'org-faces) (defface org-level-4 '((t :inherit outline-4)) - "Face used for level 4 headlines." + "Face used for level 4 headings." :group 'org-faces) (defface org-level-5 '((t :inherit outline-5)) - "Face used for level 5 headlines." + "Face used for level 5 headings." :group 'org-faces) (defface org-level-6 '((t :inherit outline-6)) - "Face used for level 6 headlines." + "Face used for level 6 headings." :group 'org-faces) (defface org-level-7 '((t :inherit outline-7)) - "Face used for level 7 headlines." + "Face used for level 7 headings." :group 'org-faces) (defface org-level-8 '((t :inherit outline-8)) - "Face used for level 8 headlines." + "Face used for level 8 headings." :group 'org-faces) (defface org-special-keyword '((t :inherit font-lock-keyword-face)) @@ -165,7 +165,7 @@ set the properties in the `org-column' face. For example, set :group 'org-faces) (defface org-archived '((t :inherit shadow)) - "Face for headline with the ARCHIVE tag." + "Face for heading with the ARCHIVE tag." :group 'org-faces) (defface org-cite '((t :inherit link)) @@ -271,18 +271,18 @@ of the frame, for example." '((((class color) (min-colors 16) (background light)) (:foreground "Red4")) (((class color) (min-colors 16) (background dark)) (:foreground "Pink2")) (((class color) (min-colors 8) (background light)) (:bold t))) - "Face used to indicate that a headline is marked as TODO. + "Face used to indicate that a heading is marked as TODO. This face is only used if `org-fontify-todo-headline' is set. If applies -to the part of the headline after the TODO keyword." +to the part of the heading after the TODO keyword." :group 'org-faces) (defface org-headline-done ;Copied from `font-lock-string-face' '((((class color) (min-colors 16) (background light)) (:foreground "RosyBrown")) (((class color) (min-colors 16) (background dark)) (:foreground "LightSalmon")) (((class color) (min-colors 8) (background light)) (:bold nil))) - "Face used to indicate that a headline is DONE. + "Face used to indicate that a heading is DONE. This face is only used if `org-fontify-done-headline' is set. If applies -to the part of the headline after the DONE keyword." +to the part of the heading after the DONE keyword." :group 'org-faces) (defcustom org-faces-easy-properties @@ -670,8 +670,8 @@ month and 365.24 days for a year)." org-level-5 org-level-6 org-level-7 org-level-8)) (defcustom org-n-level-faces (length org-level-faces) - "The number of different faces to be used for headlines. -Org mode defines 8 different headline faces, so this can be at most 8. + "The number of different faces to be used for headings. +Org mode defines 8 different heading faces, so this can be at most 8. If it is less than 8, the level-1 face gets re-used for level N+1 etc." :type 'integer :group 'org-faces) diff --git a/lisp/org-feed.el b/lisp/org-feed.el index 5df3b6976..ea93d8704 100644 --- a/lisp/org-feed.el +++ b/lisp/org-feed.el @@ -118,7 +118,7 @@ URL the Feed URL file the target Org file where entries should be listed, when nil the target becomes the current buffer (may be an indirect buffer) each time the feed update is invoked -headline the headline under which entries should be listed +headline the heading under which entries should be listed Additional arguments can be given using keyword-value pairs. Many of these specify functions that receive one or a list of \"entries\" as their single @@ -144,7 +144,7 @@ Here are the keyword-value pair allows in `org-feed-alist'. :template template-string The default action on new items in the feed is to add them as children - under the headline for the feed. The template describes how the entry + under the heading for the feed. The template describes how the entry should be formatted. If not given, it defaults to `org-feed-default-template'. @@ -161,13 +161,13 @@ Here are the keyword-value pair allows in `org-feed-alist'. list. The handler should do what needs to be done, and org-feed will mark all items given to this handler as \"handled\", i.e. they will not be passed to this handler again in future readings of the feed. - When the handler is called, point will be at the feed headline. + When the handler is called, point will be at the feed heading. :changed-handler function This function gets passed a list of all entries that have been handled before, but are now still in the feed and have *changed* since last handled (as evidenced by a different sha1 hash). - When the handler is called, point will be at the feed headline. + When the handler is called, point will be at the feed heading. :parse-feed function This function gets passed a buffer, and should return a list @@ -187,7 +187,7 @@ Here are the keyword-value pair allows in `org-feed-alist'. (string :tag "Name") (string :tag "Feed URL") (file :tag "File for inbox") - (string :tag "Headline for inbox") + (string :tag "Heading for inbox") (repeat :inline t (choice (list :inline t :tag "Filter" @@ -452,7 +452,7 @@ it can be a list structured like an entry in `org-feed-alist'." (defun org-feed-goto-inbox-internal (file heading) "Find or create HEADING in FILE. -Switch to that buffer, and return the position of that headline." +Switch to that buffer, and return the position of that heading." (find-file file) (widen) (goto-char (point-min)) @@ -496,7 +496,7 @@ This will find DRAWER and extract the alist." (insert (pp-to-string status))))) (defun org-feed-add-items (pos entries) - "Add the formatted items to the headline as POS." + "Add the formatted items to the heading as POS." (let (entry level) (save-excursion (goto-char pos) diff --git a/lisp/org-goto.el b/lisp/org-goto.el index 0a3470f54..d55ff9bd8 100644 --- a/lisp/org-goto.el +++ b/lisp/org-goto.el @@ -38,7 +38,7 @@ (defconst org-goto-help "Browse buffer copy, to find location or copy text.%s RET=jump to location C-g=quit and return to previous location -\[Up]/[Down]=next/prev headline TAB=cycle visibility [/] org-occur") +\[Up]/[Down]=next/prev heading TAB=cycle visibility [/] org-occur") @@ -62,7 +62,7 @@ Allowed values are: `outline-path-completion' - Headlines in the current buffer are offered via completion. + headings in the current buffer are offered via completion. This is the interface also used by the refile command." :group 'org-goto :type '(choice @@ -137,7 +137,7 @@ When nil, you can use these keybindings to navigate the buffer: (define-key org-goto-local-auto-isearch-map [return] nil)) (defun org-goto--local-search-headings (string bound noerror) - "Search and make sure that any matches are in headlines." + "Search and make sure that any matches are in headings." (catch 'return (while (if isearch-forward (search-forward string bound noerror) @@ -254,7 +254,7 @@ into the tree in that copy, use `org-occur' and incremental search to find a location. When pressing RET or `Q', the command returns to the original buffer in which the visibility is still unchanged. After RET it will also jump to the location selected -in the indirect buffer and expose the headline hierarchy above. +in the indirect buffer and expose the heading hierarchy above. With a prefix argument, use the alternative interface: e.g., if `org-goto-interface' is `outline' use `outline-path-completion'." diff --git a/lisp/org-id.el b/lisp/org-id.el index 56783d108..1ecf1fb7b 100644 --- a/lisp/org-id.el +++ b/lisp/org-id.el @@ -110,7 +110,7 @@ use-existing Use existing ID, do not create one. nil Never use an ID to make a link, instead link using a text search for - the headline text." + the heading text." :group 'org-link-store :group 'org-id :version "24.3" @@ -297,7 +297,7 @@ In any case, the ID of the entry is returned." (defun org-id-get-with-outline-path-completion (&optional targets) "Use `outline-path-completion' to retrieve the ID of an entry. TARGETS may be a setting for `org-refile-targets' to define -eligible headlines. When omitted, all headlines in the current +eligible headings. When omitted, all headings in the current file are eligible. This function returns the ID of the entry. If necessary, the ID is created." (let* ((org-refile-targets (or targets '((nil . (:maxlevel . 10))))) diff --git a/lisp/org-indent.el b/lisp/org-indent.el index 66e3b941a..2768fffeb 100644 --- a/lisp/org-indent.el +++ b/lisp/org-indent.el @@ -72,7 +72,7 @@ Delay used when the buffer to initialize isn't current.") "Position of initialization before interrupt. This is used locally in each buffer being initialized.") (defvar org-indent-modified-headline-flag nil - "Non-nil means the last deletion operated on a headline. + "Non-nil means the last deletion operated on a heading. It is modified by `org-indent-notify-modified-headline'.") @@ -110,16 +110,16 @@ useful to make it ever so slightly different." "Vector containing line prefixes strings for regular text.") (defvar org-indent--heading-line-prefixes nil - "Vector containing line prefix strings for headlines.") + "Vector containing line prefix strings for headings.") (defvar org-indent--inlinetask-line-prefixes nil "Vector containing line prefix strings for inline tasks.") (defconst org-indent--deepest-level 50 - "Maximum theoretical headline depth.") + "Maximum theoretical heading depth.") (defun org-indent--compute-prefixes () - "Compute prefix strings for regular text and headlines." + "Compute prefix strings for regular text and headings." (setq org-indent--heading-line-prefixes (make-vector org-indent--deepest-level nil)) (setq org-indent--inlinetask-line-prefixes diff --git a/lisp/org-inlinetask.el b/lisp/org-inlinetask.el index e8f373286..17ba88729 100644 --- a/lisp/org-inlinetask.el +++ b/lisp/org-inlinetask.el @@ -86,7 +86,7 @@ :group 'org-structure) (defcustom org-inlinetask-min-level 15 - "Minimum level a headline must have before it is treated as an inline task. + "Minimum level a heading must have before it is treated as an inline task. Don't set it to something higher than `29' or clocking will break since this is the hardcoded maximum number of stars `org-clock-sum' will work with. @@ -277,7 +277,7 @@ If the task has an end part, also demote it." (defvar org-indent-indentation-per-level) ; defined in org-indent.el (defface org-inlinetask '((t :inherit shadow)) - "Face for inlinetask headlines." + "Face for inlinetask headings." :group 'org-faces) (defun org-inlinetask-fontify (limit) diff --git a/lisp/org-keys.el b/lisp/org-keys.el index a10db7e66..9de71f080 100644 --- a/lisp/org-keys.el +++ b/lisp/org-keys.el @@ -674,19 +674,19 @@ COMMANDS is a list of alternating OLDDEF NEWDEF command names." ;;; Speed keys (defcustom org-use-speed-commands nil - "Non-nil means activate single letter commands at beginning of a headline. + "Non-nil means activate single letter commands at beginning of a heading. This may also be a function to test for appropriate locations where speed commands should be active. For example, to activate speed commands when the point is on any -star at the beginning of the headline, you can do this: +star at the beginning of the heading, you can do this: (setq org-use-speed-commands (lambda () (and (looking-at org-outline-regexp) (looking-back \"^\\**\"))))" :group 'org-structure :type '(choice (const :tag "Never" nil) - (const :tag "At beginning of headline stars" t) + (const :tag "At beginning of heading stars" t) (function))) (defcustom org-speed-command-hook @@ -777,7 +777,7 @@ command." :package-version '(Org . "9.5") :type '(repeat :value ("k" . ignore) (choice :value ("k" . ignore) - (list :tag "Descriptive Headline" (string :tag "Headline")) + (list :tag "Descriptive Heading" (string :tag "Heading")) (cons :tag "Letter and Command" (string :tag "Command letter") (choice @@ -820,7 +820,7 @@ command." (setq truncate-lines t))) (defun org-speed-move-safe (cmd) - "Execute CMD, but make sure that the cursor always ends up in a headline. + "Execute CMD, but make sure that the cursor always ends up in a heading. If not, return to the original position and throw an error." (interactive) (let ((pos (point))) diff --git a/lisp/org-list.el b/lisp/org-list.el index 93aa00a73..b8a62e355 100644 --- a/lisp/org-list.el +++ b/lisp/org-list.el @@ -2353,7 +2353,7 @@ When there is an active region, toggle status or presence of the first checkbox there, and make every item inside have the same status or presence, respectively. -If point is on a headline, apply this to all checkbox items in +If point is on a heading, apply this to all checkbox items in the text below the heading, taking as reference the first item in subtree, ignoring planning line and any drawer following it." (interactive "P") @@ -2884,7 +2884,7 @@ a function to be called with point at the beginning of the record. It must return a value that is compatible with COMPARE-FUNC, the function used to compare entries. -Sorting is done against the visible part of the headlines, it +Sorting is done against the visible part of the headings, it ignores hidden links. A non-nil value for INTERACTIVE? is used to signal that this @@ -2983,8 +2983,8 @@ function is being called interactively." "Convert headings or normal lines to items, items to normal lines. If there is no active region, only the current line is considered. -If the first non blank line in the region is a headline, convert -all headlines to items, shifting text accordingly. +If the first non blank line in the region is a heading, convert +all headings to items, shifting text accordingly. If it is an item, convert all items to normal lines. diff --git a/lisp/org-macs.el b/lisp/org-macs.el index 52fc09a06..258352411 100644 --- a/lisp/org-macs.el +++ b/lisp/org-macs.el @@ -1138,7 +1138,7 @@ the value in cadr." "Non-nil if the character after POS is invisible. If POS is nil, use `point' instead. When optional argument FOLDING-ONLY is non-nil, only consider invisible parts due to -folding of a headline, a block or a drawer, i.e., not because of +folding of a heading, a block or a drawer, i.e., not because of fontification." (let ((value (get-char-property (or pos (point)) 'invisible))) (cond ((not value) nil) diff --git a/lisp/org-mouse.el b/lisp/org-mouse.el index 66a153c9c..8f61f48eb 100644 --- a/lisp/org-mouse.el +++ b/lisp/org-mouse.el @@ -177,7 +177,7 @@ Changing this variable requires a restart of Emacs to get activated." (const :tag "Mouse-3 shows context menu" context-menu) (const :tag "C-mouse-1 and mouse-3 move trees" move-tree) (const :tag "S-mouse-2 and drag-mouse-3 yank link" yank-link) - (const :tag "Activate headline stars" activate-stars) + (const :tag "Activate heading stars" activate-stars) (const :tag "Activate item bullets" activate-bullets) (const :tag "Activate checkboxes" activate-checkboxes))) @@ -187,7 +187,7 @@ Changing this variable requires a restart of Emacs to get activated." (re-search-forward regexp (point-at-eol) t)) (defun org-mouse-end-headline () - "Go to the end of current headline (ignoring tags)." + "Go to the end of current heading (ignoring tags)." (interactive) (end-of-line) (skip-chars-backward "\t ") @@ -355,7 +355,7 @@ nor a function, elements of KEYWORDS are used directly." :selected ,(not (member (match-string group) keywords))])))) (defun org-mouse-show-headlines () - "Change the visibility of the current org buffer to only show headlines." + "Change the visibility of the current org buffer to only show headings." (interactive) (let ((this-command 'org-cycle) (last-command 'org-cycle) @@ -364,13 +364,13 @@ nor a function, elements of KEYWORDS are used directly." (org-cycle '(4)))) (defun org-mouse-show-overview () - "Change visibility of current org buffer to first-level headlines only." + "Change visibility of current org buffer to first-level headings only." (interactive) (let ((org-cycle-global-status nil)) (org-cycle '(4)))) (defun org-mouse-set-priority (priority) - "Set the priority of the current headline to PRIORITY." + "Set the priority of the current heading to PRIORITY." (org-priority priority)) (defvar org-mouse-priority-regexp "\\[#\\([A-Z]\\)\\]" @@ -379,8 +379,8 @@ Differs from `org-priority-regexp' in that it doesn't contain the leading `.*?'.") (defun org-mouse-get-priority (&optional default) - "Return the priority of the current headline. -DEFAULT is returned if no priority is given in the headline." + "Return the priority of the current heading. +DEFAULT is returned if no priority is given in the heading." (save-excursion (if (org-mouse-re-search-line org-mouse-priority-regexp) (match-string 1) @@ -485,7 +485,7 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:" (popup-menu `("Main Menu" ["Show Overview" org-mouse-show-overview t] - ["Show Headlines" org-mouse-show-headlines t] + ["Show Headings" org-mouse-show-headlines t] ["Show All" org-show-all t] ["Remove Highlights" org-remove-occur-highlights :visible org-occur-highlights] @@ -789,7 +789,7 @@ This means, between the beginning of line and the point." ((and (assq :headline contextlist) (not (eolp))) (let ((priority (org-mouse-get-priority t))) (popup-menu - `("Headline Menu" + `("Heading Menu" ("Tags and Priorities" ,@(org-mouse-keyword-menu (org-mouse-priority-list) diff --git a/lisp/org-num.el b/lisp/org-num.el index 849368481..35ce61155 100644 --- a/lisp/org-num.el +++ b/lisp/org-num.el @@ -82,12 +82,12 @@ (defcustom org-num-face nil "Face to use for numbering. -When nil, use the same face as the headline. This value is +When nil, use the same face as the heading. This value is ignored if `org-num-format-function' specifies a face for its output." :group 'org-appearance :package-version '(Org . "9.3") - :type '(choice (const :tag "Like the headline" nil) + :type '(choice (const :tag "Like the heading" nil) (face :tag "Use face")) :safe (lambda (val) (or (null val) (facep val)))) @@ -102,8 +102,8 @@ Any `face' text property on the returned string overrides :type 'function) (defcustom org-num-max-level nil - "Level below which headlines are not numbered. -When set to nil, all headlines are numbered." + "Level below which headings are not numbered. +When set to nil, all headings are numbered." :group 'org-appearance :package-version '(Org . "9.3") :type '(choice (const :tag "Number everything" nil) @@ -149,23 +149,23 @@ control tag inheritance." ;;; Internal Variables (defconst org-num--comment-re (format "\\`%s\\(?: \\|$\\)" org-comment-string) - "Regexp matching a COMMENT keyword at headline beginning.") + "Regexp matching a COMMENT keyword at heading beginning.") (defvar-local org-num--overlays nil "Ordered list of overlays used for numbering outlines.") (defvar-local org-num--skip-level nil - "Level below which headlines from current tree are not numbered. -When nil, all headlines are numbered. It is used to handle + "Level below which headings from current tree are not numbered. +When nil, all headings are numbered. It is used to handle inheritance of no-numbering attributes.") (defvar-local org-num--numbering nil - "Current headline numbering. + "Current heading numbering. A numbering is a list of integers, in reverse order. So numbering -for headline \"1.2.3\" is (3 2 1).") +for heading \"1.2.3\" is (3 2 1).") (defvar-local org-num--missing-overlay nil - "Buffer position signaling a headline without an overlay.") + "Buffer position signaling a heading without an overlay.") (defvar-local org-num--invalid-flag nil "Non-nil means an overlay became invalid since last update.") @@ -174,7 +174,7 @@ for headline \"1.2.3\" is (3 2 1).") ;;; Internal Functions (defsubst org-num--headline-regexp () - "Return regexp matching a numbered headline." + "Return regexp matching a numbered heading." (if (null org-num-max-level) (org-with-limited-levels org-outline-regexp-bol) (format "^\\*\\{1,%d\\} " (if org-odd-levels-only (1- (* 2 org-num-max-level)) @@ -200,13 +200,13 @@ Update `org-num--invalid-flag' accordingly." (setq org-num--overlays nil)) (defun org-num--make-overlay (numbering level skip) - "Return overlay for numbering headline at point. + "Return overlay for numbering heading at point. NUMBERING is the numbering to use, as a list of integers, or nil if nothing should be displayed. LEVEL is the level of the headline. SKIP is its skip value. -Assume point is at a headline." +Assume point is at a heading." (let ((after-edit-functions (list (lambda (o &rest _) (org-num--invalidate-overlay o)))) (o (save-excursion @@ -242,8 +242,8 @@ nil if nothing should be displayed. Assume OVERLAY is valid." (overlay-put overlay 'after-string display))) (defun org-num--skip-value () - "Return skip value for headline at point. -Value is t when headline should not be numbered, and nil + "Return skip value for heading at point. +Value is t when heading should not be numbered, and nil otherwise." (org-match-line org-complex-heading-regexp) (let ((title (match-string 4)) @@ -267,9 +267,9 @@ otherwise." t)))) (defun org-num--current-numbering (level skip) - "Return numbering for current headline. -LEVEL is headline's level, and SKIP its skip value. Return nil -if headline should be skipped." + "Return numbering for current heading. +LEVEL is heading's level, and SKIP its skip value. Return nil +if heading should be skipped." (cond ;; Skipped by inheritance. ((and org-num--skip-level (> level org-num--skip-level)) nil) @@ -452,12 +452,12 @@ NUMBERING is a list of numbers." ;;;###autoload (define-minor-mode org-num-mode - "Dynamic numbering of headlines in an Org buffer." + "Dynamic numbering of headings in an Org buffer." :lighter " o#" (cond (org-num-mode (unless (derived-mode-p 'org-mode) - (user-error "Cannot activate headline numbering outside Org mode")) + (user-error "Cannot activate heading numbering outside Org mode")) (setq org-num--numbering nil) (setq org-num--overlays (nreverse (org-num--number-region nil nil))) (add-hook 'after-change-functions #'org-num--verify nil t) diff --git a/lisp/org-refile.el b/lisp/org-refile.el index e5908e9d8..69d459b98 100644 --- a/lisp/org-refile.el +++ b/lisp/org-refile.el @@ -74,16 +74,16 @@ This is a list of cons cells. Each cell contains: - A specification of how to find candidate refile targets. This may be any of: - a cons cell (:tag . \"TAG\") to identify refile targets by a tag. - This tag has to be present in all target headlines, inheritance will + This tag has to be present in all target headings, inheritance will not be considered. - a cons cell (:todo . \"KEYWORD\") to identify refile targets by todo keyword. - a cons cell (:regexp . \"REGEXP\") with a regular expression matching - headlines that are refiling targets. - - a cons cell (:level . N). Any headline of level N is considered a target. + headings that are refiling targets. + - a cons cell (:level . N). Any heading of level N is considered a target. Note that, when `org-odd-levels-only' is set, level corresponds to order in hierarchy, not to the number of stars. - - a cons cell (:maxlevel . N). Any headline with level <= N is a target. + - a cons cell (:maxlevel . N). Any heading with level <= N is a target. Note that, when `org-odd-levels-only' is set, level corresponds to order in hierarchy, not to the number of stars. @@ -92,9 +92,9 @@ The union of these sets is presented (with completion) to the user by `org-refile'. You can set the variable `org-refile-target-verify-function' to a function -to verify each headline found by the simple criteria above. +to verify each heading found by the simple criteria above. -When this variable is nil, all top-level headlines in the current buffer +When this variable is nil, all top-level headings in the current buffer are used, equivalent to the value `((nil . (:level . 1))'." :group 'org-refile :type '(repeat @@ -103,7 +103,7 @@ are used, equivalent to the value `((nil . (:level . 1))'." (const :tag "All agenda files" org-agenda-files) (const :tag "Current buffer" nil) (function) (variable) (file)) - (choice :tag "Identify target headline by" + (choice :tag "Identify target heading by" (cons :tag "Specific tag" (const :value :tag) (string)) (cons :tag "TODO keyword" (const :value :todo) (string)) (cons :tag "Regular expression" (const :value :regexp) (regexp)) @@ -111,10 +111,10 @@ are used, equivalent to the value `((nil . (:level . 1))'." (cons :tag "Max Level number" (const :value :maxlevel) (integer)))))) (defcustom org-refile-target-verify-function nil - "Function to verify if the headline at point should be a refile target. + "Function to verify if the heading at point should be a refile target. The function will be called without arguments, with point at the -beginning of the headline. It should return t and leave point -where it is if the headline is a valid target for refiling. +beginning of the heading. It should return t and leave point +where it is if the heading is a valid target for refiling. If the target should not be selected, the function must return nil. In addition to this, it may move point to a place from where the search @@ -143,7 +143,7 @@ if you find that easier, \ (defcustom org-refile-use-outline-path nil "Non-nil means provide refile targets as paths. -So a level 3 headline will be available as level1/level2/level3. +So a level 3 heading will be available as level1/level2/level3. When the value is `file', also include the file name (without directory) into the path. In this case, you can also stop the completion after @@ -164,7 +164,7 @@ When `buffer-name', use the buffer name." "Non-nil means complete the outline path in hierarchical steps. When Org uses the refile interface to select an outline path (see `org-refile-use-outline-path'), the completion of the path can be -done in a single go, or it can be done in steps down the headline +done in a single go, or it can be done in steps down the heading hierarchy. Going in steps is probably the best if you do not use a special completion package like `ido' or `icicles'. However, when using these packages, going in one step can be very fast, @@ -195,7 +195,7 @@ heading." By default `org-refile' doesn't allow refiling regions if they don't contain a set of subtrees, but it might be convenient to do so sometimes: in that case, the first line of the region is -converted to a headline before refiling." +converted to a heading before refiling." :group 'org-refile :version "24.1" :type 'boolean) @@ -677,7 +677,7 @@ this function appends the default value from (user-error "Invalid target location"))))) (defun org-refile-check-position (refile-pointer) - "Check if the refile pointer matches the headline to which it points." + "Check if the refile pointer matches the heading to which it points." (let* ((file (nth 1 refile-pointer)) (re (nth 2 refile-pointer)) (pos (nth 3 refile-pointer)) diff --git a/lisp/org.el b/lisp/org.el index 01d15aa91..5dca48f59 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -100,15 +100,15 @@ ;; `org-outline-regexp' ought to be a defconst but is let-bound in ;; some places -- e.g. see the macro `org-with-limited-levels'. (defvar org-outline-regexp "\\*+ " - "Regexp to match Org headlines.") + "Regexp to match Org headings.") (defvar org-outline-regexp-bol "^\\*+ " - "Regexp to match Org headlines. + "Regexp to match Org headings. This is similar to `org-outline-regexp' but additionally makes sure that we are at the beginning of the line.") (defvar org-heading-regexp "^\\(\\*+\\)\\(?: +\\(.*?\\)\\)?[ \t]*$" - "Matches a headline, putting stars and text into groups. + "Matches a heading, putting stars and text into groups. Stars are put in group 1 and the trimmed body in group 2.") (declare-function calendar-check-holidays "holidays" (date)) @@ -578,14 +578,14 @@ Group 1 contains drawer's name or \"END\".") (defconst org-heading-keyword-regexp-format "^\\(\\*+\\)\\(?: +%s\\)\\(?: +\\(.*?\\)\\)?[ \t]*$" - "Printf format for a regexp matching a headline with some keyword. + "Printf format for a regexp matching a heading with some keyword. This regexp will match the headline of any node which has the exact keyword that is put into the format. The keyword isn't in any group by default, but the stars and the body are.") (defconst org-heading-keyword-maybe-regexp-format "^\\(\\*+\\)\\(?: +%s\\)?\\(?: +\\(.*?\\)\\)?[ \t]*$" - "Printf format for a regexp matching a headline, possibly with some keyword. + "Printf format for a regexp matching a heading, possibly with some keyword. This regexp can match any headline with the specified keyword, or without a keyword. The keyword isn't in any group by default, but the stars and the body are.") @@ -605,7 +605,7 @@ without the enclosing colons.") (defconst org-tag-line-re "^\\*+ \\(?:.*[ \t]\\)?\\(:\\([[:alnum:]_@#%:]+\\):\\)[ \t]*$" - "Regexp matching tags in a headline. + "Regexp matching tags in a heading. Tags are stored in match group 1. Match group 2 stores the tags without the enclosing colons.") @@ -876,7 +876,7 @@ outside these special contexts, under control of this variable. The default of this variable is nil, to avoid confusing behavior. Shifted cursor keys will then execute Org commands in the following contexts: -- on a headline, changing TODO state (left/right) and priority (up/down) +- on a heading, changing TODO state (left/right) and priority (up/down) - on a time stamp, changing the time - in a plain list item, changing the bullet type - in a property definition line, switching between allowed values @@ -891,7 +891,7 @@ cycling will no longer happen anywhere in an item line, but only if the cursor is exactly on the bullet. If you set this variable to the symbol `always', then the keys -will not be special in headlines, property lines, item lines, and +will not be special in headings, property lines, item lines, and table cells, to make shift selection work there as well. If this is what you want, you can use the following alternative commands: `\\[org-todo]' and `\\[org-priority]' \ @@ -910,17 +910,17 @@ will still edit the time stamp - this is just too good to give up." (const :tag "Everywhere except timestamps" always))) (defcustom org-loop-over-headlines-in-active-region t - "Shall some commands act upon headlines in the active region? + "Shall some commands act upon headings in the active region? -When set to t, some commands will be performed in all headlines +When set to t, some commands will be performed in all headings within the active region. When set to `start-level', some commands will be performed in all -headlines within the active region, provided that these headlines +headlines within the active region, provided that these headings are of the same level than the first one. When set to a string, those commands will be performed on the -matching headlines within the active region. Such string must be +matching headings within the active region. Such string must be a tags/property/todo match as it is used in the agenda tags view. The list of commands is: `org-schedule', `org-deadline', @@ -932,8 +932,8 @@ already archived entries. See `org-agenda-loop-over-headlines-in-active-region' for the equivalent option for agenda views." :type '(choice (const :tag "Don't loop" nil) - (const :tag "All headlines in active region" t) - (const :tag "In active region, headlines at the same level than the first one" start-level) + (const :tag "All headings in active region" t) + (const :tag "In active region, headings at the same level than the first one" start-level) (string :tag "Tags/Property/Todo matcher")) :package-version '(Org . "9.4") :group 'org-todo @@ -963,7 +963,7 @@ time." (const :tag "fold: show three levels" show3levels) (const :tag "fold: show four levels" show4evels) (const :tag "fold: show five levels" show5levels) - (const :tag "content: all headlines" content) + (const :tag "content: all headings" content) (const :tag "show everything, even drawers" showeverything))) (defcustom org-startup-truncated t @@ -1199,27 +1199,27 @@ or context. Valid contexts are Allowed visibility spans are - minimal show current headline; if point is not on heading, + minimal show current heading; if point is not on heading, also show entry - local show current headline, entry and next headline + local show current heading, entry and next heading - ancestors show current headline and its direct ancestors; if - point is not on headline, also show entry + ancestors show current heading and its direct ancestors; if + point is not on heading, also show entry ancestors-full show current subtree and its direct ancestors - lineage show current headline, its direct ancestors and all + lineage show current heading, its direct ancestors and all their children; if point is not on heading, also show entry and first child - tree show current headline, its direct ancestors and all + tree show current heading, its direct ancestors and all their children; if point is not on heading, also show entry and all children - canonical show current headline, its direct ancestors along with + canonical show current heading, its direct ancestors along with their entries and children; if point is not located on - the headline, also show current entry and all children + the heading, also show current entry and all children As special cases, a nil or t value means show all contexts in `minimal' or `canonical' view, respectively. @@ -1458,9 +1458,9 @@ is not set." (defcustom org-cycle-max-level nil "Maximum level which should still be subject to visibility cycling. -Levels higher than this will, for cycling, be treated as text, not a headline. +Levels higher than this will, for cycling, be treated as text, not a heading. When `org-odd-levels-only' is set, a value of N in this variable actually -means 2N-1 stars as the limiting headline. +means 2N-1 stars as the limiting heading. When nil, cycle all levels. Note that the limiting level of cycling is also influenced by `org-inlinetask-min-level'. When `org-cycle-max-level' is not set but @@ -1482,12 +1482,12 @@ This can also be set in on a per-file basis with :type 'boolean) (defcustom org-cycle-global-at-bob nil - "Cycle globally if cursor is at beginning of buffer and not at a headline. + "Cycle globally if cursor is at beginning of buffer and not at a heading. This makes it possible to do global cycling without having to use `S-TAB' or `\\[universal-argument] TAB'. For this special case to work, the first \ line of the buffer -must not be a headline -- it may be empty or some other text. +must not be a heading -- it may be empty or some other text. When used in this way, `org-cycle-hook' is disabled temporarily to make sure the cursor stays at the beginning of the buffer. @@ -1500,10 +1500,10 @@ the buffer." (defcustom org-cycle-level-after-item/entry-creation t "Non-nil means cycle entry level or item indentation in new empty entries. -When the cursor is at the end of an empty headline, i.e., with only stars +When the cursor is at the end of an empty heading, i.e., with only stars and maybe a TODO keyword, TAB will then switch the entry to become a child, and then all possible ancestor states, before returning to the original state. -This makes data entry extremely fast: M-RET to create a new headline, +This makes data entry extremely fast: M-RET to create a new heading, on TAB to make it a child, two or more tabs to make it a (grand-)uncle. When the cursor is at the end of an empty plain list item, one TAB will @@ -1517,26 +1517,26 @@ higher up in the item hierarchy." nil Never white Only in completely white lines whitestart Only at the beginning of lines, before the first non-white char -t Everywhere except in headlines -exc-hl-bol Everywhere except at the start of a headline +t Everywhere except in headings +exc-hl-bol Everywhere except at the start of a heading If TAB is used in a place where it does not emulate TAB, the current subtree visibility is cycled." :group 'org-cycle :type '(choice (const :tag "Never" nil) (const :tag "Only in completely white lines" white) (const :tag "Before first char in a line" whitestart) - (const :tag "Everywhere except in headlines" t) - (const :tag "Everywhere except at bol in headlines" exc-hl-bol))) + (const :tag "Everywhere except in headings" t) + (const :tag "Everywhere except at bol in headings" exc-hl-bol))) (defcustom org-cycle-separator-lines 2 "Number of empty lines needed to keep an empty line between collapsed trees. If you leave an empty line between the end of a subtree and the following -headline, this empty line is hidden when the subtree is folded. +heading, this empty line is hidden when the subtree is folded. Org mode will leave (exactly) one empty line visible if the number of empty lines is equal or larger to the number given in this variable. So the default 2 means at least 2 empty lines after the end of a subtree are needed to produce free space between a collapsed subtree and the -following headline. +following heading. If the number is negative, and the number of empty lines is at least -N, all empty lines are shown. @@ -1595,10 +1595,10 @@ lines to the buffer: "Non-nil means adapt indentation to outline node level. When set to t, Org assumes that you write outlines by indenting -text in each node to align with the headline, after the stars. +text in each node to align with the heading, after the stars. When this variable is set to `headline-data', Org only adapts the -indentation of the data lines right below the headline, such as +indentation of the data lines right below the heading, such as planning/clock lines and property/logbook drawers. The following issues are influenced by this variable: @@ -1606,14 +1606,14 @@ The following issues are influenced by this variable: - The indentation is increased by one space in a demotion command, and decreased by one in a promotion command. However, in the latter case, if shifting some line in the entry body - would alter document structure (e.g., insert a new headline), + would alter document structure (e.g., insert a new heading), indentation is not changed at all. - Property drawers and planning information is inserted indented when this variable is set. When nil, they will not be indented. - TAB indents a line relative to current level. The lines below - a headline will be indented when this variable is set to t. + a heading will be indented when this variable is set to t. Note that this is all about true indentation, by adding and removing space characters. See also \"org-indent.el\" which does @@ -1622,7 +1622,7 @@ time in Emacs." :group 'org-edit-structure :type '(choice (const :tag "Adapt indentation for all lines" t) - (const :tag "Adapt indentation for headline data lines" + (const :tag "Adapt indentation for heading data lines" headline-data) (const :tag "Do not adapt indentation at all" nil)) :safe (lambda (x) (memq x '(t nil headline-data)))) @@ -1630,16 +1630,16 @@ time in Emacs." (defvaralias 'org-special-ctrl-a 'org-special-ctrl-a/e) (defcustom org-special-ctrl-a/e nil - "Non-nil means `C-a' and `C-e' behave specially in headlines and items. + "Non-nil means `C-a' and `C-e' behave specially in headings and items. When t, `C-a' will bring back the cursor to the beginning of the -headline text, i.e. after the stars and after a possible TODO +heading text, i.e. after the stars and after a possible TODO keyword. In an item, this will be the position after bullet and check-box, if any. When the cursor is already at that position, another `C-a' will bring it to the beginning of the line. -`C-e' will jump to the end of the headline, ignoring the presence -of tags in the headline. A second `C-e' will then jump to the +`C-e' will jump to the end of the heading, ignoring the presence +of tags in the heading. A second `C-e' will then jump to the true end of the line, after any tags. This also means that, when this variable is non-nil, `C-e' also will never jump beyond the end of the heading of a folded section, i.e. not after the @@ -1668,20 +1668,20 @@ This may also be a cons cell where the behavior for `C-a' and (const :tag "reversed: after tags first" reversed))))) (defcustom org-special-ctrl-k nil - "Non-nil means `C-k' will behave specially in headlines. + "Non-nil means `C-k' will behave specially in headings. When nil, `C-k' will call the default `kill-line' command. -When t, the following will happen while the cursor is in the headline: +When t, the following will happen while the cursor is in the heading: -- When at the beginning of a headline, kill the entire subtree. -- When in the middle of the headline text, kill the text up to the tags. -- When after the headline text and before the tags, kill all the tags." +- When at the beginning of a heading, kill the entire subtree. +- When in the middle of the heading text, kill the text up to the tags. +- When after the heading text and before the tags, kill all the tags." :group 'org-edit-structure :type 'boolean) (defcustom org-ctrl-k-protect-subtree nil "Non-nil means, do not delete a hidden subtree with `C-k'. When set to the symbol `error', simply throw an error when `C-k' is -used to kill (part-of) a headline that has hidden text behind it. +used to kill (part-of) a heading that has hidden text behind it. Any other non-nil value will result in a query to the user, if it is OK to kill that hidden subtree. When nil, kill without remorse." :group 'org-edit-structure @@ -1742,7 +1742,7 @@ new line. You may also set this option in a different way for different contexts. Valid contexts are: -headline when creating a new headline +headline when creating a new heading item when creating a new item table in a table field default the value to be used for all contexts not explicitly @@ -1863,7 +1863,7 @@ angle Links in angular brackets that may contain whitespace like . plain Plain links in normal text, no whitespace, like https://gnu.org. radio Text that is matched by a radio target, see manual for details. -tag Tag settings in a headline (link to tag search). +tag Tag settings in a heading (link to tag search). date Time stamps (link to calendar). footnote Footnote labels. @@ -2032,7 +2032,7 @@ are followed by a letter in parenthesis, like TODO(t)." (defcustom org-provide-todo-statistics t "Non-nil means update todo statistics after insert and toggle. -ALL-HEADLINES means update todo statistics by including headlines +ALL-HEADLINES means update todo statistics by including headings with no TODO keyword as well, counting them as not done. A list of TODO keywords means the same, but skip keywords that are not in this list. @@ -2321,7 +2321,7 @@ because Agenda Log mode depends on the format of these entries." (defcustom org-log-into-drawer nil "Non-nil means insert state change notes and time stamps into a drawer. -When nil, state changes notes will be inserted after the headline and +When nil, state changes notes will be inserted after the heading and any scheduling and clock lines, but not inside a drawer. The value of this variable should be the name of the drawer to use. @@ -2365,7 +2365,7 @@ be used instead of the default value." (defcustom org-log-state-notes-insert-after-drawers nil "Non-nil means insert state change notes after any drawers in entry. -Only the drawers that *immediately* follow the headline and the +Only the drawers that *immediately* follow the heading and the deadline/scheduled line are skipped. When nil, insert notes right after the heading and perhaps the line with deadline/scheduling if present. @@ -2520,9 +2520,9 @@ See also `org-priority-default'." (defvaralias 'org-get-priority-function 'org-priority-get-priority-function) (defcustom org-priority-get-priority-function nil "Function to extract the priority from a string. -The string is normally the headline. If this is nil, Org +The string is normally the heading. If this is nil, Org computes the priority from the priority cookie like [#A] in the -headline. It returns an integer, increasing by 1000 for each +heading. It returns an integer, increasing by 1000 for each priority level. The user can set a different function here, which should take a @@ -2890,18 +2890,18 @@ displaying the tags menu is not even shown, until you press `C-c' again." This is an undocumented feature, you should not rely on it.") (defcustom org-tags-column -77 - "The column to which tags should be indented in a headline. + "The column to which tags should be indented in a heading. If this number is positive, it specifies the column. If it is negative, it means that the tags should be flushright to that column. For example, -80 works well for a normal 80 character screen. -When 0, place tags directly after headline text, with only one space in +When 0, place tags directly after heading text, with only one space in between." :group 'org-tags :type 'integer) (defcustom org-auto-align-tags t - "Non-nil keeps tags aligned when modifying headlines. -Some operations (i.e. demoting) change the length of a headline and + "Non-nil keeps tags aligned when modifying headings. +Some operations (i.e. demoting) change the length of a heading and therefore shift the tags around. With this option turned on, after each such operation the tags are again aligned to `org-tags-column'." :group 'org-tags @@ -2948,7 +2948,7 @@ see the variable `org-use-tag-inheritance'." (t (error "Invalid setting of `org-use-tag-inheritance'")))) (defcustom org-tags-match-list-sublevels t - "Non-nil means list also sublevels of headlines matching a search. + "Non-nil means list also sublevels of headings matching a search. This variable applies to tags/property searches, and also to stuck projects because this search is based on a tags match as well. @@ -2956,7 +2956,7 @@ When set to the symbol `indented', sublevels are indented with leading dots. Because of tag inheritance (see variable `org-use-tag-inheritance'), -the sublevels of a headline matching a tag search often also match +the sublevels of a heading matching a tag search often also match the same search. Listing all of them can create very long lists. Setting this variable to nil causes subtrees of a match to be skipped. @@ -3583,15 +3583,15 @@ Make sure that you only list packages here which: :group 'org) (defcustom org-level-color-stars-only nil - "Non-nil means fontify only the stars in each headline. -When nil, the entire headline is fontified. + "Non-nil means fontify only the stars in each heading. +When nil, the entire heading is fontified. Changing it requires restart of `font-lock-mode' to become effective also in regions already fontified." :group 'org-appearance :type 'boolean) (defcustom org-hide-leading-stars nil - "Non-nil means hide the first N-1 stars in a headline. + "Non-nil means hide the first N-1 stars in a heading. This works by using the face `org-hide' for these stars. This face is white for a light background, and black for a dark background. You may have to customize the face `org-hide' to @@ -3628,9 +3628,9 @@ hide them with `org-toggle-custom-properties-visibility'." :type '(repeat (string :tag "Property Name"))) (defcustom org-fontify-todo-headline nil - "Non-nil means change the face of a headline if it is marked as TODO. -Normally, only the TODO/DONE keyword indicates the state of a headline. -When this is non-nil, the headline after the keyword is set to the + "Non-nil means change the face of a heading if it is marked as TODO. +Normally, only the TODO/DONE keyword indicates the state of a heading. +When this is non-nil, the heading after the keyword is set to the `org-headline-todo' as an additional indication." :group 'org-appearance :package-version '(Org . "9.4") @@ -3638,9 +3638,9 @@ When this is non-nil, the headline after the keyword is set to the :safe #'booleanp) (defcustom org-fontify-done-headline t - "Non-nil means change the face of a headline if it is marked DONE. -Normally, only the TODO/DONE keyword indicates the state of a headline. -When this is non-nil, the headline after the keyword is set to the + "Non-nil means change the face of a heading if it is marked DONE. +Normally, only the TODO/DONE keyword indicates the state of a heading. +When this is non-nil, the heading after the keyword is set to the `org-headline-done' as an additional indication." :group 'org-appearance :package-version '(Org . "9.4") @@ -3861,7 +3861,7 @@ This is needed for font-lock setup.") (defvar org-clock-marker (make-marker) "Marker recording the last clock-in.") (defvar org-clock-hd-marker (make-marker) - "Marker recording the last clock-in, but the headline position.") + "Marker recording the last clock-in, but the heading position.") (defvar org-clock-heading "" "The heading of the current clock entry.") (defun org-clocking-buffer () @@ -4088,35 +4088,35 @@ Since TODO keywords are case-sensitive, `case-fold-search' is expected to be bound to nil when matching against this regexp.") (defvar-local org-not-done-heading-regexp nil - "Matches a TODO headline that is not done. + "Matches a TODO heading that is not done. Since TODO keywords are case-sensitive, `case-fold-search' is expected to be bound to nil when matching against this regexp.") (defvar-local org-todo-line-regexp nil - "Matches a headline and puts TODO state into group 2 if present. + "Matches a heading and puts TODO state into group 2 if present. Since TODO keywords are case-sensitive, `case-fold-search' is expected to be bound to nil when matching against this regexp.") (defvar-local org-complex-heading-regexp nil - "Matches a headline and puts everything into groups: + "Matches a heading and puts everything into groups: group 1: Stars group 2: The TODO keyword, maybe group 3: Priority cookie -group 4: True headline +group 4: True heading group 5: Tags Since TODO keywords are case-sensitive, `case-fold-search' is expected to be bound to nil when matching against this regexp.") (defvar-local org-complex-heading-regexp-format nil - "Printf format to make regexp to match an exact headline. -This regexp will match the headline of any node which has the -exact headline text that is put into the format, but may have any + "Printf format to make regexp to match an exact heading. +This regexp will match the heading of any node which has the +exact heading text that is put into the format, but may have any TODO state, priority and tags.") (defvar-local org-todo-line-tags-regexp nil - "Matches a headline and puts TODO state into group 2 if present. + "Matches a heading and puts TODO state into group 2 if present. Also put tags into group 4 if tags are present.") (defconst org-plain-time-of-day-regexp @@ -5261,7 +5261,7 @@ See also the `org-block' face." (defcustom org-allow-promoting-top-level-subtree nil "When non-nil, allow promoting a top level subtree. -The leading star of the top level headline will be replaced +The leading star of the top level heading will be replaced by a #." :type 'boolean :version "24.1" @@ -5601,7 +5601,7 @@ highlighting was done, nil otherwise." (defun org-outline-level () "Compute the outline level of the heading at point. -If this is called at a normal headline, the level is the number +If this is called at a normal heading, the level is the number of stars. Use `org-reduced-level' to remove the effect of `org-odd-levels'. Unlike to `org-current-level', this function takes into consideration inlinetasks." @@ -5864,7 +5864,7 @@ needs to be inserted at a specific position in the font-lock sequence.") (buffer-string)))) (defun org-get-level-face (n) - "Get the right face for match N in font-lock matching of headlines." + "Get the right face for match N in font-lock matching of headings." (let* ((org-l0 (- (match-end 2) (match-beginning 1) 1)) (org-l (if org-odd-levels-only (1+ (/ org-l0 2)) org-l0)) (org-f (if org-cycle-level-faces @@ -6011,7 +6011,7 @@ and subscripts." (delete-overlay o)))) (defun org-show-empty-lines-in-parent () - "Move to the parent and re-show empty lines before visible headlines." + "Move to the parent and re-show empty lines before visible headings." (save-excursion (let ((context (if (org-up-heading-safe) 'children 'overview))) (org-cycle-show-empty-lines context)))) @@ -6042,7 +6042,7 @@ open and agenda-wise Org files." (save-excursion (org-end-of-subtree t) (point)))) (defun org-first-headline-recenter () - "Move cursor to the first headline and recenter the headline." + "Move cursor to the first heading and recenter the heading." (let ((window (get-buffer-window))) (when window (goto-char (point-min)) @@ -6314,8 +6314,8 @@ in special contexts. When this function is called with a `\\[universal-argument]' prefix, rotate \ the entire buffer through 3 states (global cycling) - 1. OVERVIEW: Show only top-level headlines. - 2. CONTENTS: Show all headlines of all levels, but no body text. + 1. OVERVIEW: Show only top-level headings. + 2. CONTENTS: Show all headings of all levels, but no body text. 3. SHOW ALL: Show everything. With a `\\[universal-argument] \\[universal-argument]' prefix argument, \ @@ -6329,31 +6329,31 @@ any drawers. When inside a table, re-align the table and move to the next field. -When point is at the beginning of a headline, rotate the subtree started +When point is at the beginning of a heading, rotate the subtree started by this line through 3 different states (local cycling) - 1. FOLDED: Only the main headline is shown. - 2. CHILDREN: The main headline and the direct children are shown. + 1. FOLDED: Only the main heading is shown. + 2. CHILDREN: The main heading and the direct children are shown. From this state, you can move to one of the children and zoom in further. 3. SUBTREE: Show the entire subtree, including body text. If there is no subtree, switch directly from CHILDREN to FOLDED. -When point is at the beginning of an empty headline and the variable +When point is at the beginning of an empty heading and the variable `org-cycle-level-after-item/entry-creation' is set, cycle the level -of the headline by demoting and promoting it to likely levels. This +of the heading by demoting and promoting it to likely levels. This speeds up creation document structure by pressing `TAB' once or several -times right after creating a new headline. +times right after creating a new heading. When there is a numeric prefix, go up to a heading with level ARG, do a `show-subtree' and return to the previous cursor position. If ARG is negative, go up that many levels. -When point is not at the beginning of a headline, execute the global +When point is not at the beginning of a heading, execute the global binding for `TAB', which is re-indenting the line. See the option `org-cycle-emulate-tab' for details. As a special case, if point is at the very beginning of the buffer, if -there is no headline there, and if the variable `org-cycle-global-at-bob' +there is no heading there, and if the variable `org-cycle-global-at-bob' is non-nil, this function acts as if called with prefix argument \ \(`\\[universal-argument] TAB', same as `S-TAB') also when called without prefix argument." @@ -6603,7 +6603,7 @@ Use `\\[org-edit-special]' to edit table.el tables")) (defun org-global-cycle (&optional arg) "Cycle the global visibility. For details see `org-cycle'. With `\\[universal-argument]' prefix ARG, switch to startup visibility. -With a numeric prefix, show all headlines up to that level." +With a numeric prefix, show all headings up to that level." (interactive "P") (cond ((integerp arg) @@ -6669,7 +6669,7 @@ With a numeric prefix, show all headlines up to that level." (org-end-of-subtree))))))) (defun org-overview () - "Switch to overview mode, showing only top-level headlines." + "Switch to overview mode, showing only top-level headings." (interactive) (org-show-all '(headings drawers)) (save-excursion @@ -6686,7 +6686,7 @@ With a numeric prefix, show all headlines up to that level." (org-flag-region last (point) t 'outline))))) (defun org-content (&optional arg) - "Show all headlines in the buffer, like a table of contents. + "Show all headings in the buffer, like a table of contents. With numerical argument N, show content up to level N." (interactive "p") (org-show-all '(headings drawers)) @@ -6755,11 +6755,11 @@ This function is the default value of the hook `org-cycle-hook'." (org-cycle-show-empty-lines 'overview))))) (defun org-cycle-show-empty-lines (state) - "Show empty lines above all visible headlines. + "Show empty lines above all visible headings. The region to be covered depends on STATE when called through `org-cycle-hook'. Lisp program can use t for STATE to get the entire buffer covered. Note that an empty line is only shown if there -are at least `org-cycle-separator-lines' empty lines before the headline." +are at least `org-cycle-separator-lines' empty lines before the heading." (when (/= org-cycle-separator-lines 0) (save-excursion (let* ((n (abs org-cycle-separator-lines)) @@ -6849,7 +6849,7 @@ DETAIL is either nil, `minimal', `local', `ancestors', "Hook run before revealing a location.") (defun org-reveal (&optional siblings) - "Show current entry, hierarchy above it, and the following headline. + "Show current entry, hierarchy above it, and the following heading. This can be used to show a consistent set of context around locations exposed with `org-show-context'. @@ -6968,7 +6968,7 @@ frame is not changed." (defun org--blank-before-heading-p (&optional parent) "Non-nil when an empty line should precede a new heading here. When optional argument PARENT is non-nil, consider parent -headline instead of current one." +heading instead of current one." (pcase (assq 'heading org-blank-before-new-entry) (`(heading . auto) (save-excursion @@ -6992,13 +6992,13 @@ headline instead of current one." "Insert a new heading or an item with the same depth at point. If point is at the beginning of a heading, insert a new heading -or a new headline above the current one. When at the beginning +or a new heading above the current one. When at the beginning of a regular line of text, turn it into a heading. If point is in the middle of a line, split it and create a new -headline with the text in the current line after point (see +heading with the text in the current line after point (see `org-M-RET-may-split-line' on how to modify this behavior). As -a special case, on a headline, splitting can only happen on the +a special case, on a heading, splitting can only happen on the title itself. E.g., this excludes breaking stars or tags. With a `\\[universal-argument]' prefix, set \ @@ -7013,7 +7013,7 @@ above the current heading. For example, if point is within a 2nd-level heading, then it will insert a 2nd-level heading at the end of the 1st-level parent subtree. -When INVISIBLE-OK is set, stop at invisible headlines when going +When INVISIBLE-OK is set, stop at invisible headings when going back. This is important for non-interactive uses of the command. @@ -7139,7 +7139,7 @@ This is a list with the following elements: - the reduced level, different if `org-odd-levels-only' is set. - the TODO keyword, or nil - the priority character, like ?A, or nil if no priority is given -- the headline text itself, or the tags string if no headline text +- the heading text itself, or the tags string if no heading text - the tags string, or nil." (save-excursion (org-back-to-heading t) @@ -7158,7 +7158,7 @@ This is a list with the following elements: (buffer-substring (point-at-bol 2) (org-end-of-subtree t)))) (defun org-edit-headline (&optional heading) - "Edit the current headline. + "Edit the current heading. Set it to HEADING when provided." (interactive) (org-with-wide-buffer @@ -7309,18 +7309,18 @@ headings in the region." ((equal (char-after) ?\s) (forward-char 1)))))) (defun org-current-level () - "Return the level of the current entry, or nil if before the first headline. + "Return the level of the current entry, or nil if before the first heading. The level is the number of stars at the beginning of the -headline. Use `org-reduced-level' to remove the effect of +heading. Use `org-reduced-level' to remove the effect of `org-odd-levels'. Unlike to `org-outline-level', this function ignores inlinetasks." (let ((level (org-with-limited-levels (org-outline-level)))) (and (> level 0) level))) (defun org-get-previous-line-level () - "Return the outline depth of the last headline before the current line. -Returns 0 for the first headline in the buffer, and nil if before the -first headline." + "Return the outline depth of the last heading before the current line. +Returns 0 for the first heading in the buffer, and nil if before the +first heading." (and (org-current-level) (or (and (/= (line-beginning-position) (point-min)) (save-excursion (beginning-of-line 0) (org-current-level))) @@ -7336,7 +7336,7 @@ This takes into account the setting of `org-odd-levels-only'." (defun org-level-increment () "Return the number of stars that will be added or removed at a -time to headlines when structure editing, based on the value of +time to headings when structure editing, based on the value of `org-odd-levels-only'." (if org-odd-levels-only 2 1)) @@ -7387,7 +7387,7 @@ odd number. Returns values greater than 0." (run-hooks 'org-after-demote-entry-hook)))) (defun org-cycle-level () - "Cycle the level of an empty headline through possible states. + "Cycle the level of an empty heading through possible states. This goes first to child, then to parent, level, then up the hierarchy. After top level, it switches back to sibling level." (interactive) @@ -7456,7 +7456,7 @@ DIFF is an integer. Indentation is done according to the following rules: - Planning information and property drawers are always indented - according to the new level of the headline; + according to the new level of the heading; - Footnote definitions and their contents are ignored; @@ -7612,12 +7612,12 @@ case." ;;; Vertical tree motion, cutting and pasting of subtrees (defun org-move-subtree-up (&optional arg) - "Move the current subtree up past ARG headlines of the same level." + "Move the current subtree up past ARG headings of the same level." (interactive "p") (org-move-subtree-down (- (prefix-numeric-value arg)))) (defun org-move-subtree-down (&optional arg) - "Move the current subtree down past ARG headlines of the same level." + "Move the current subtree down past ARG headings of the same level." (interactive "p") (setq arg (prefix-numeric-value arg)) (org-preserve-local-variables @@ -7731,16 +7731,16 @@ useful if the caller implements cut-and-paste as copy-then-paste-then-cut." (length org-subtree-clip)))))) (defun org-paste-subtree (&optional level tree for-yank remove) - "Paste the clipboard as a subtree, with modification of headline level. + "Paste the clipboard as a subtree, with modification of heading level. -The entire subtree is promoted or demoted in order to match a new headline +The entire subtree is promoted or demoted in order to match a new heading level. -If the cursor is at the beginning of a headline, the same level as -that headline is used to paste the tree. +If the cursor is at the beginning of a heading, the same level as +that heading is used to paste the tree. If not, the new level is derived from the *visible* headings -before and after the insertion point, and taken to be the inferior headline +before and after the insertion point, and taken to be the inferior heading level of the two. So if the previous visible heading is level 3 and the next is level 4 (or vice versa), level 4 will be used for insertion. This makes sure that the subtree remains an independent subtree and does @@ -7839,8 +7839,8 @@ When REMOVE is non-nil, remove the subtree from the clipboard." (defun org-kill-is-subtree-p (&optional txt) "Check if the current kill is an outline subtree, or a set of trees. -Returns nil if kill does not start with a headline, or if the first -headline level is not the largest headline level in the tree. +Returns nil if kill does not start with a heading, or if the first +heading level is not the largest heading level in the tree. So this will actually accept several entries of equal levels as well, which is OK for `org-paste-subtree'. If optional TXT is given, check this string instead of the current kill." @@ -8049,13 +8049,13 @@ of strings describing the outline path for that entry, in reverse order.") (defun org--get-outline-path-1 (&optional use-cache) - "Return outline path to current headline. + "Return outline path to current heading. Outline path is a list of strings, in reverse order. When optional argument USE-CACHE is non-nil, make use of a cache. See `org-get-outline-path' for details. -Assume buffer is widened and point is on a headline." +Assume buffer is widened and point is on a heading." (or (and use-cache (cdr (assq (point) org-outline-path-cache))) (let ((p (point)) (heading (let ((case-fold-search nil)) @@ -8082,12 +8082,12 @@ Assume buffer is widened and point is on a headline." (defun org-get-outline-path (&optional with-self use-cache) "Return the outline path to the current entry. -An outline path is a list of ancestors for current headline, as +An outline path is a list of ancestors for current heading, as a list of strings. Statistics cookies are removed and links are replaced with their description, if any, or their path otherwise. When optional argument WITH-SELF is non-nil, the path also -includes the current headline. +includes the current heading. When optional argument USE-CACHE is non-nil, cache outline paths between calls to this function so as to avoid backtracking. This @@ -8254,7 +8254,7 @@ compare entries. Comparing entries ignores case by default. However, with an optional argument WITH-CASE, the sorting considers case as well. -Sorting is done against the visible part of the headlines, it ignores hidden +Sorting is done against the visible part of the headings, it ignores hidden links. When sorting is done, call `org-after-sorting-entries-or-items-hook'. @@ -8588,8 +8588,8 @@ the value of the drawer property." The refresh happens only for the current entry, or the whole sub-tree if optional argument INHERIT is non-nil. -If point is before first headline, the function applies to the -part before the first headline. In that particular case, when +If point is before first heading, the function applies to the +part before the first heading. In that particular case, when optional argument INHERIT is non-nil, it refreshes properties for the whole buffer." (save-excursion @@ -8949,7 +8949,7 @@ When point is a footnote definition, move to the first reference found. If it is on a reference, move to the associated definition. -When point is on a headline, display a list of every link in the +When point is on a heading, display a list of every link in the entry, so it is possible to pick one, or all, of them. If point is on a tag, call `org-tags-view' instead. @@ -10135,7 +10135,7 @@ all statistics cookies in the buffer." (defvar org-entry-property-inherited-from) ;; defined below (defun org-update-parent-todo-statistics () - "Update any statistics cookie in the parent of the current headline. + "Update any statistics cookie in the parent of the current heading. When `org-hierarchical-todo-statistics' is nil, statistics will cover the entire subtree and this will travel up the hierarchy and update statistics everywhere." @@ -10234,7 +10234,7 @@ and the number of done entries. For example, the following function, when added to this hook, will switch an entry to DONE when all children are done, and back to TODO when new entries are set to a TODO status. Note that this hook is only called -when there is a statistics cookie in the headline! +when there is a statistics cookie in the heading! (defun org-summary-todo (n-done n-not-done) \"Switch entry to DONE when all subentries are done, to TODO otherwise.\" @@ -10447,7 +10447,7 @@ repeater from there instead." (defvar org-log-note-extra) (defvar org-log-setup nil) (defun org-auto-repeat-maybe (done-word) - "Check if the current headline contains a repeated time-stamp. + "Check if the current heading contains a repeated time-stamp. If yes, set TODO state back to what it was and change the base date of repeating deadline/scheduled time stamps to new date. @@ -10571,7 +10571,7 @@ enough to shift date past today. Continue? " (message msg)))) (defun org-show-todo-tree (arg) - "Make a compact tree which shows all headlines marked with TODO. + "Make a compact tree which shows all headings marked with TODO. The tree will show the lines where the regexp matches, and all higher headlines above the match. With a `\\[universal-argument]' prefix, prompt for a regexp to match. @@ -11251,7 +11251,7 @@ match is found." (user-error "No more matches")))) (defun org-highlight-new-match (beg end) - "Highlight from BEG to END and mark the highlight is an occur headline." + "Highlight from BEG to END and mark the highlight is an occur heading." (let ((ov (make-overlay beg end))) (overlay-put ov 'face 'secondary-selection) (overlay-put ov 'org-type 'org-occur) @@ -11452,18 +11452,18 @@ as N.") (defvar org--matcher-tags-todo-only nil) (defun org-scan-tags (action matcher todo-only &optional start-level) - "Scan headline tags with inheritance and produce output ACTION. + "Scan heading tags with inheritance and produce output ACTION. ACTION can be `sparse-tree' to produce a sparse tree in the current buffer, or `agenda' to produce an entry list for an agenda view. It can also be -a Lisp form or a function that should be called at each matched headline, in +a Lisp form or a function that should be called at each matched heading, in this case the return value is a list of all return values from these calls. MATCHER is a function accepting three arguments, returning -a non-nil value whenever a given set of tags qualifies a headline +a non-nil value whenever a given set of tags qualifies a heading for inclusion. See `org-make-tags-matcher' for more information. As a special case, it can also be set to t (respectively nil) in -order to match all (respectively none) headline. +order to match all (respectively none) heading. When TODO-ONLY is non-nil, only lines with a TODO keyword are included in the output. @@ -11699,12 +11699,12 @@ Returns a cons of the selection string MATCH and a function implementing the matcher. The matcher is to be called at an Org entry, with point on the -headline, and returns non-nil if the entry matches the selection +heading, and returns non-nil if the entry matches the selection string MATCH. It must be called with three arguments: the TODO keyword at the entry (or nil if none), the list of all tags at the entry including inherited ones and the reduced level of the -headline. Additionally, the category of the entry, if any, must -be specified as the text property `org-category' on the headline. +heading. Additionally, the category of the entry, if any, must +be specified as the text property `org-category' on the heading. This function sets the variable `org--matcher-tags-todo-only' to a non-nil value if the matcher restricts matching to TODO @@ -11981,8 +11981,8 @@ If ONOFF is `on' or `off', don't toggle but set to this state." res))) (defun org--align-tags-here (to-col) - "Align tags on the current headline to TO-COL. -Assume point is on a headline. Preserve point when aligning + "Align tags on the current heading to TO-COL. +Assume point is on a heading. Preserve point when aligning tags." (when (org-match-line org-tag-line-re) (let* ((tags-start (match-beginning 1)) @@ -12114,7 +12114,7 @@ visible part of the buffer." TAGS may be a tags string like \":aa:bb:cc:\", or a list of tags. If TAGS is nil or the empty string, all tags are removed. -This function assumes point is on a headline." +This function assumes point is on a heading." (org-with-wide-buffer (let ((tags (pcase tags ((pred listp) tags) @@ -12238,7 +12238,7 @@ Also insert END." (defvar org-last-tag-selection-key nil) (defun org-fast-tag-selection (current inherited table &optional todo-table) "Fast tag selection with single keys. -CURRENT is the current list of tags in the headline, INHERITED is the +CURRENT is the current list of tags in the heading, INHERITED is the list of inherited tags, and TABLE is an alist of tags and corresponding keys, possibly with grouping information. TODO-TABLE is a similar table with TODO keywords, should these have keys assigned to them. @@ -12455,25 +12455,25 @@ TAGS is a list of strings." (format ":%s:" (mapconcat #'identity tags ":")))) (defun org--get-local-tags () - "Return list of tags for the current headline. -Assume point is at the beginning of the headline." + "Return list of tags for the current heading. +Assume point is at the beginning of the heading." (and (looking-at org-tag-line-re) (split-string (match-string-no-properties 2) ":" t))) (defun org-get-tags (&optional pos local) - "Get the list of tags specified in the current headline. + "Get the list of tags specified in the current heading. -When argument POS is non-nil, retrieve tags for headline at POS. +When argument POS is non-nil, retrieve tags for heading at POS. According to `org-use-tag-inheritance', tags may be inherited -from parent headlines, and from the whole document, through +from parent headings, and from the whole document, through `org-file-tags'. In this case, the returned list of tags contains tags in this order: file tags, tags inherited from -parent headlines, local tags. If a tag appears multiple times, +parent headings, local tags. If a tag appears multiple times, only the most local tag is returned. However, when optional argument LOCAL is non-nil, only return -tags specified at the headline. +tags specified at the heading. Inherited tags have the `inherited' text property." (if (and org-trust-scanner-tags @@ -12508,16 +12508,16 @@ Inherited tags have the `inherited' text property." (defvar org-agenda-skip-comment-trees) (defvar org-agenda-skip-function) (defun org-map-entries (func &optional match scope &rest skip) - "Call FUNC at each headline selected by MATCH in SCOPE. + "Call FUNC at each heading selected by MATCH in SCOPE. FUNC is a function or a Lisp form. The function will be called without -arguments, with the cursor positioned at the beginning of the headline. +arguments, with the cursor positioned at the beginning of the heading. The return values of all calls to the function will be collected and returned as a list. The call to FUNC will be wrapped into a `save-excursion' form, so FUNC does not need to preserve point. After evaluation, the cursor will be -moved to the end of the line (presumably of the headline of the +moved to the end of the line (presumably of the heading of the processed entry) and search continues from there. Under some circumstances, this may not produce the wanted results. For example, if you have removed (e.g. archived) the current (sub)tree it could @@ -12527,8 +12527,8 @@ FUNC set the variable `org-map-continue-from' to the desired buffer position. MATCH is a tags/property/todo match as it is used in the agenda tags view. -Only headlines that are matched by this query will be considered during -the iteration. When MATCH is nil or t, all headlines will be +Only headings that are matched by this query will be considered during +the iteration. When MATCH is nil or t, all headings will be visited by the iteration. SCOPE determines the scope of this command. It can be any of: @@ -12681,7 +12681,7 @@ Modifications are made by side-effect. Return new alist." (defun org-get-property-block (&optional beg force) "Return the (beg . end) range of the body of the property drawer. BEG is the beginning of the current subtree or the beginning of -the document if before the first headline. If it is not given, +the document if before the first heading. If it is not given, it will be found. If the drawer does not exist, create it if FORCE is non-nil, or return nil." (org-with-wide-buffer @@ -13423,7 +13423,7 @@ Point is left between drawer's boundaries." (beginning-of-line) (when (save-excursion (re-search-forward org-outline-regexp-bol rend t)) - (user-error "Drawers cannot contain headlines")) + (user-error "Drawers cannot contain headings")) ;; Position point at the beginning of the first ;; non-blank line in region. Insert drawer's opening ;; there, then indent it. @@ -13757,8 +13757,8 @@ a priority cookie and tags in the standard locations." (move-marker (make-marker) (match-beginning 0)))))))) (defun org-find-exact-heading-in-directory (heading &optional dir) - "Find Org node headline HEADING in all \".org\" files in directory DIR. -When the target headline is found, return a marker to this location." + "Find Org node heading HEADING in all \".org\" files in directory DIR. +When the target heading is found, return a marker to this location." (let ((files (directory-files (or dir default-directory) t "\\`[^.#].*\\.org\\'")) visiting m buffer) @@ -16844,9 +16844,9 @@ The detailed reaction depends on the user option `org-catch-invisible-edits'." (user-error "Edit in invisible region aborted, repeat to confirm with text visible")))))))) (defun org-fix-tags-on-the-fly () - "Align tags in headline at point. + "Align tags in heading at point. Unlike `org-align-tags', this function does nothing if point is -either not currently on a tagged headline or on a tag." +either not currently on a tagged heading or on a tag." (when (and (org-match-line org-tag-line-re) (< (point) (match-beginning 1))) (org-align-tags))) @@ -16976,7 +16976,7 @@ cycling) will not occur.") "Hook for functions to attach themselves to TAB. See `org-ctrl-c-ctrl-c-hook' for more information. This hook runs after it has been established that the cursor is not in a -table, but before checking if the cursor is in a headline or if global cycling +table, but before checking if the cursor is in a heading or if global cycling should be done. If any function in this hook returns t, not other actions like visibility cycling will be done.") @@ -17052,13 +17052,13 @@ See `org-ctrl-c-ctrl-c-hook' for more information.") (defun org-modifier-cursor-error () "Throw an error, a modified cursor command was applied in wrong context." - (user-error "This command is active in special context like tables, headlines or items")) + (user-error "This command is active in special context like tables, headings or items")) (defun org-shiftselect-error () "Throw an error because Shift-Cursor command was applied in wrong context." (if (and (boundp 'shift-select-mode) shift-select-mode) (user-error "To use shift-selection with Org mode, customize `org-support-shift-select'") - (user-error "This command works only in special context like headlines or timestamps"))) + (user-error "This command works only in special context like headings or timestamps"))) (defun org-call-for-shift-select (cmd) (let ((this-command-keys-shift-translated t)) @@ -17218,7 +17218,7 @@ and returns at first non-nil value." (t (call-interactively 'forward-word)))) (defun org-check-for-hidden (what) - "Check if there are hidden headlines/items in the current visual line. + "Check if there are hidden headings/items in the current visual line. WHAT can be either `headlines' or `items'. If the current line is an outline or item heading and it has a folded subtree below it, this function returns t, nil otherwise." @@ -17371,7 +17371,7 @@ individual commands for more information." This does one of the following: - switch a timestamp at point one day into the future -- on a headline, switch to the next TODO keyword +- on a heading, switch to the next TODO keyword - on an item, switch entire list to the next bullet type - on a property line, switch to the next allowed value - on a clocktable definition line, move time block into the future @@ -17411,7 +17411,7 @@ This does one of the following: This does one of the following: - switch a timestamp at point one day into the past -- on a headline, switch to the previous TODO keyword. +- on a heading, switch to the previous TODO keyword. - on an item, switch entire list to the previous bullet type - on a property line, switch to the previous allowed value - on a clocktable definition line, move time block into the past @@ -17638,7 +17638,7 @@ Otherwise, return a user error." (_ (user-error "No special environment to edit here")))))))) (defun org-ctrl-c-ctrl-c (&optional arg) - "Set tags in headline, or update according to changed information at point. + "Set tags in heading, or update according to changed information at point. This command does many different things, depending on context: @@ -17651,7 +17651,7 @@ This command does many different things, depending on context: - If the cursor is on a statistics cookie, update it. -- If the cursor is in a headline, in an agenda or an org buffer, +- If the cursor is in a heading, in an agenda or an org buffer, prompt for tags and insert them into the current line, aligned to `org-tags-column'. When called with prefix arg, realign all tags in the current buffer. @@ -17937,7 +17937,7 @@ Move point to the beginning of first heading or end of buffer." (defun org-delete-indentation (&optional arg) "Join current line to previous and fix whitespace at join. -If previous line is a headline add to headline title. Otherwise +If previous line is a heading add to heading title. Otherwise the function calls `delete-indentation'. I.e. with a non-nil optional argument, join the line with the @@ -18136,8 +18136,8 @@ point into heading. In a region: -- If the first non blank line is a headline, remove the stars - from all headlines in the region. +- If the first non blank line is a heading, remove the stars + from all headings in the region. - If it is a normal line, turn each and every normal line (i.e., not an heading or an item) in the region into headings. If you @@ -18756,11 +18756,11 @@ Each context entry is a list with a symbol naming the context, and two positions indicating start and end of the context. Possible contexts are: -:headline anywhere in a headline -:headline-stars on the leading stars in a headline -:todo-keyword on a TODO keyword (including DONE) in a headline -:tags on the TAGS in a headline -:priority on the priority cookie in a headline +:headline anywhere in a heading +:headline-stars on the leading stars in a heading +:todo-keyword on a TODO keyword (including DONE) in a heading +:tags on the TAGS in a heading +:priority on the priority cookie in a heading :item on the first line of a plain list item :item-bullet on the bullet/number of a plain list item :checkbox on the checkbox in a plain list item @@ -18873,7 +18873,7 @@ and :keyword." Also return a non-nil value when point is on one of the matches. Optional arguments LIM-UP and LIM-DOWN bound the search; they are -buffer positions. Default values are the positions of headlines +buffer positions. Default values are the positions of headings surrounding the point. The functions returns a cons cell whose car (resp. cdr) is the @@ -19011,7 +19011,7 @@ earliest time on the cursor date that Org treats as that date "Mark the current subtree. This puts point at the start of the current subtree, and mark at the end. If a numeric prefix UP is given, move up into the -hierarchy of headlines by UP levels before marking the subtree." +hierarchy of headings by UP levels before marking the subtree." (interactive "P") (org-with-limited-levels (cond ((org-at-heading-p) (beginning-of-line)) @@ -19148,7 +19148,7 @@ Alignment is done according to `org-property-format', which see." Indentation is done according to the following rules: - - Footnote definitions, diary sexps, headlines and inline tasks + - Footnote definitions, diary sexps, headings and inline tasks have to start at column 0. - On the very first line of an element, consider, in order, the @@ -20179,10 +20179,10 @@ package ox-bibtex by Taru Karttunen." (defun org-beginning-of-line (&optional n) "Go to the beginning of the current visible line. -If this is a headline, and `org-special-ctrl-a/e' is not nil or +If this is a heading, and `org-special-ctrl-a/e' is not nil or symbol `reversed', on the first attempt move to where the -headline text starts, and only move to beginning of line when the -cursor is already before the start of the text of the headline. +heading text starts, and only move to beginning of line when the +cursor is already before the start of the text of the heading. If `org-special-ctrl-a/e' is symbol `reversed' then go to the start of the text on the second attempt. @@ -20242,10 +20242,10 @@ With argument N not nil or 1, move forward N - 1 lines first." (defun org-end-of-line (&optional n) "Go to the end of the line, but before ellipsis, if any. -If this is a headline, and `org-special-ctrl-a/e' is not nil or +If this is a heading, and `org-special-ctrl-a/e' is not nil or symbol `reversed', ignore tags on the first attempt, and only move to after the tags when the cursor is already beyond the end -of the headline. +of the heading. If `org-special-ctrl-a/e' is symbol `reversed' then ignore tags on the second attempt. @@ -20362,7 +20362,7 @@ depending on context." (when (and (get-char-property (line-end-position) 'invisible) org-ctrl-k-protect-subtree (or (eq org-ctrl-k-protect-subtree 'error) - (not (y-or-n-p "Kill hidden subtree along with headline? ")))) + (not (y-or-n-p "Kill hidden subtree along with heading? ")))) (user-error (substitute-command-keys "`\\[org-kill-line]' aborted as it would kill a hidden subtree"))) @@ -20385,7 +20385,7 @@ depending on context." This command will look at the current kill and check if is a single subtree, or a series of subtrees[1]. If it passes the test, and if the cursor is at the beginning of a line or after the stars of a currently -empty headline, then the yank is handled specially. How exactly depends +empty heading, then the yank is handled specially. How exactly depends on the value of the following variables. `org-yank-folded-subtrees' @@ -20487,7 +20487,7 @@ interactive command with similar behavior." (condition-case nil (outline-back-to-heading invisible-ok) (error - (user-error "Before first headline at position %d in buffer %s" + (user-error "Before first heading at position %d in buffer %s" (point) (current-buffer))))) (defun org-back-to-heading-or-point-min (&optional invisible-ok) @@ -20507,12 +20507,12 @@ instead of back to heading." (null (re-search-backward org-outline-regexp-bol nil t))))) (defun org-at-heading-p (&optional _) - "Non-nil when on a headline." + "Non-nil when on a heading." (outline-on-heading-p t)) (defun org-in-commented-heading-p (&optional no-inheritance) "Non-nil if point is under a commented heading. -This function also checks ancestors of the current headline, +This function also checks ancestors of the current heading, unless optional argument NO-INHERITANCE is non-nil." (cond ((org-before-first-heading-p) nil) @@ -20527,7 +20527,7 @@ unless optional argument NO-INHERITANCE is non-nil." (defun org-in-archived-heading-p (&optional no-inheritance) "Non-nil if point is under an archived heading. -This function also checks ancestors of the current headline, +This function also checks ancestors of the current heading, unless optional argument NO-INHERITANCE is non-nil." (cond ((org-before-first-heading-p) nil) @@ -20564,7 +20564,7 @@ unless optional argument NO-INHERITANCE is non-nil." (looking-at org-block-regexp))) (defun org-point-at-end-of-empty-headline () - "If point is at the end of an empty headline, return t, else nil. + "If point is at the end of an empty heading, return t, else nil. If the heading only contains a TODO keyword, it is still considered empty." (let ((case-fold-search nil)) @@ -20591,7 +20591,7 @@ With argument, move up ARG levels." (defun org-up-heading-safe () "Move to the heading line of which the present line is a subheading. This version will not throw an error. It will return the level of the -headline found, or nil if no higher level is found. +heading found, or nil if no higher level is found. Also, this function will be a lot faster than `outline-up-heading', because it relies on stars being the outline starters. This can really @@ -20624,8 +20624,8 @@ make a significant difference in outlines with very many siblings." "Move to the heading line of which the present is a subheading, or point-min. This version is needed to make point-min behave like a virtual heading of level 0 for property-inheritance. It will return the -level of the headline found (down to 0) or nil if already at a -point before the first headline or at point-min." +level of the heading found (down to 0) or nil if already at a +point before the first heading or at point-min." (when (ignore-errors (org-back-to-heading t)) (if (< 1 (funcall outline-level)) (org-up-heading-safe) @@ -20666,7 +20666,7 @@ move point." nil)))) (defun org-show-siblings () - "Show all siblings of the current headline." + "Show all siblings of the current heading." (save-excursion (while (org-goto-sibling) (org-flag-heading nil))) (save-excursion @@ -21454,7 +21454,7 @@ Started from `gnus-info-find-node'." (export-block . "(org) ASCII/Latin-1/UTF-8 export") (fixed-width . ,default-org-info-node) (footnote-definition . "(org) Creating Footnotes") - (headline . "(org) Document Structure") + (heading . "(org) Document Structure") (horizontal-rule . "(org) Built-in Table Editor") (inlinetask . ,default-org-info-node) (item . "(org) Plain Lists") diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el index a18cf5e31..185f1fe1f 100644 --- a/lisp/ox-ascii.el +++ b/lisp/ox-ascii.el @@ -172,7 +172,7 @@ This number includes margin size, as set in (defcustom org-ascii-inner-margin 2 "Width of the inner margin, in number of characters. -Inner margin is applied between each headline." +Inner margin is applied between each heading." :group 'org-export-ascii :version "24.4" :package-version '(Org . "8.0") @@ -205,10 +205,10 @@ This number ignores any margin." :type 'integer) (defcustom org-ascii-headline-spacing '(1 . 2) - "Number of blank lines inserted around headlines. + "Number of blank lines inserted around headings. This variable can be set to a cons cell. In that case, its car -represents the number of blank lines present before headline +represents the number of blank lines present before heading contents whereas its cdr reflects the number of blank lines after contents. @@ -273,8 +273,8 @@ and whose value is a list of characters. For each supported charset, this variable associates a sequence of underline characters. In a sequence, the characters will be -used in order for headlines level 1, 2, ... If no character is -available for a given level, the headline won't be underlined." +used in order for headings level 1, 2, ... If no character is +available for a given level, the heading won't be underlined." :group 'org-export-ascii :version "24.4" :package-version '(Org . "8.0") @@ -292,7 +292,7 @@ available for a given level, the headline won't be underlined." (defcustom org-ascii-bullets '((ascii ?* ?+ ?-) (latin1 ?§ ?¶) (utf-8 ?◊)) - "Bullet characters for headlines converted to lists in ASCII export. + "Bullet characters for headings converted to lists in ASCII export. Alist whose key is a symbol among `ascii', `latin1' and `utf-8' and whose value is a list of characters. @@ -307,18 +307,18 @@ representation." :version "24.4" :package-version '(Org . "8.0") :type '(list - (cons :tag "Bullet characters for low level headlines" + (cons :tag "Bullet characters for low level headings" (const :tag "ASCII charset" ascii) (repeat character)) - (cons :tag "Bullet characters for low level headlines" + (cons :tag "Bullet characters for low level headings" (const :tag "Latin-1 charset" latin1) (repeat character)) - (cons :tag "Bullet characters for low level headlines" + (cons :tag "Bullet characters for low level headings" (const :tag "UTF-8 charset" utf-8) (repeat character)))) (defcustom org-ascii-links-to-notes t - "Non-nil means convert links to notes before the next headline. + "Non-nil means convert links to notes before the next heading. When nil, the link will be exported in place. If the line becomes long in this way, it will be wrapped." :group 'org-export-ascii @@ -857,7 +857,7 @@ generation. INFO is a plist used as a communication channel." (defun org-ascii--unique-links (element info) "Return a list of unique link references in ELEMENT. -ELEMENT is either a headline element or a section element. INFO +ELEMENT is either a heading element or a section element. INFO is a plist used as a communication channel." (let* (seen (unique-link-p @@ -2104,7 +2104,7 @@ asynchronously. The resulting buffer should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -2139,7 +2139,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-beamer.el b/lisp/ox-beamer.el index dd7c3555c..fbed11f58 100644 --- a/lisp/ox-beamer.el +++ b/lisp/ox-beamer.el @@ -53,21 +53,21 @@ :version "24.2") (defcustom org-beamer-frame-level 1 - "The level at which headlines become frames. + "The level at which headings become frames. Headlines at a lower level will be translated into a sectioning structure. At a higher level, they will be translated into blocks. -If a headline with a \"BEAMER_env\" property set to \"frame\" is +If a heading with a \"BEAMER_env\" property set to \"frame\" is found within a tree, its level locally overrides this number. -This variable has no effect on headlines with the \"BEAMER_env\" +This variable has no effect on headings with the \"BEAMER_env\" property set to either \"ignoreheading\", \"appendix\", or \"note\", which will respectively, be invisible, become an appendix or a note. -This integer is relative to the minimal level of a headline +This integer is relative to the minimal level of a heading within the parse tree, defined as 1." :group 'org-export-beamer :type 'integer) @@ -109,10 +109,10 @@ open The opening template for the environment, with the following escapes %R the raw BEAMER_act value %o the options argument, with square brackets %O the raw BEAMER_opt value - %h the headline text - %r the raw headline text (i.e. without any processing) - %H if there is headline text, that raw text in {} braces - %U if there is headline text, that raw text in [] brackets + %h the heading text + %r the raw heading text (i.e. without any processing) + %H if there is heading text, that raw text in {} braces + %U if there is heading text, that raw text in [] brackets close The closing string of the environment." :group 'org-export-beamer :version "24.4" @@ -972,7 +972,7 @@ asynchronously. The resulting buffer should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -1007,7 +1007,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -1041,7 +1041,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-html.el b/lisp/ox-html.el index 163d96ade..7acf82418 100644 --- a/lisp/ox-html.el +++ b/lisp/ox-html.el @@ -223,8 +223,8 @@ "progress" "section" "summary" "video") "New elements in html5. -For blocks that should contain headlines, use the HTML_CONTAINER -property on the headline itself.") +For blocks that should contain headings, use the HTML_CONTAINER +property on the heading itself.") (defconst org-html-special-string-regexps '(("\\\\-" . "­") ; shy @@ -693,8 +693,8 @@ by the footnotes themselves." (defcustom org-html-toplevel-hlevel 2 "The level for level 1 headings in HTML export. -This is also important for the classes that will be wrapped around headlines -and outline structure. If this variable is 1, the top-level headlines will +This is also important for the classes that will be wrapped around headings +and outline structure. If this variable is 1, the top-level headings will be

, and the corresponding classes will be outline-1, section-number-1, and outline-text-1. If this is 2, all of these will get a 2 instead. The default for this variable is 2, because we use

for formatting the @@ -704,13 +704,13 @@ document title." (defcustom org-html-format-headline-function 'org-html-format-headline-default-function - "Function to format headline text. + "Function to format heading text. This function will be called with six arguments: TODO the todo keyword (string or nil). TODO-TYPE the type of todo (symbol: `todo', `done', nil) -PRIORITY the priority of the headline (integer or nil) -TEXT the main headline text (string). +PRIORITY the priority of the heading (integer or nil) +TEXT the main heading text (string). TAGS the tags (string or nil). INFO the export options (plist). @@ -732,7 +732,7 @@ but without \"name\" attribute." :type 'boolean) (defcustom org-html-self-link-headlines nil - "When non-nil, the headlines contain a hyperlink to themselves." + "When non-nil, the headings contain a hyperlink to themselves." :group 'org-export-html :package-version '(Org . "9.3") :type 'boolean @@ -1650,7 +1650,7 @@ DATUM is an element or a `target' type object. INFO is the current export state, as a plist. When NAMED-ONLY is non-nil and DATUM has no NAME keyword, return -nil. This doesn't apply to headlines, inline tasks, radio +nil. This doesn't apply to headings, inline tasks, radio targets and targets." (let* ((type (org-element-type datum)) (user-label @@ -2675,7 +2675,7 @@ holding contextual information." (defun org-html-format-headline-default-function (todo _todo-type priority text tags info) - "Default format function for a headline. + "Default format function for a heading. See `org-html-format-headline-function' for details." (let ((todo (org-html--todo todo info)) (priority (org-html--priority priority info)) @@ -3799,7 +3799,7 @@ asynchronously. The resulting buffer should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -3844,7 +3844,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-icalendar.el b/lisp/ox-icalendar.el index e82a55645..b293636e0 100644 --- a/lisp/ox-icalendar.el +++ b/lisp/ox-icalendar.el @@ -212,7 +212,7 @@ These are entries like in the diary, but directly in an Org file." :type 'boolean) (defcustom org-icalendar-include-body t - "Amount of text below headline to be included in iCalendar export. + "Amount of text below heading to be included in iCalendar export. This is a number of characters that should maximally be included. Properties, scheduling and clocking lines will always be removed. The text will be inserted into the DESCRIPTION field." @@ -315,7 +315,7 @@ re-read the iCalendar file.") ;;; Internal Functions (defun org-icalendar-create-uid (file &optional bell) - "Set ID property on headlines missing it in FILE. + "Set ID property on headings missing it in FILE. When optional argument BELL is non-nil, inform the user with a message if the file was modified." (let (modified-flag) @@ -442,7 +442,7 @@ format (e.g. \"Europe/London\"). In either case, the value of (defun org-icalendar-get-categories (entry info) "Return categories according to `org-icalendar-categories'. -ENTRY is a headline or an inlinetask element. INFO is a plist +ENTRY is a heading or an inlinetask element. INFO is a plist used as a communication channel." (mapconcat #'identity @@ -539,10 +539,10 @@ BACK-END and INFO are ignored." (defun org-icalendar-entry (entry contents info) "Transcode ENTRY element into iCalendar format. -ENTRY is either a headline or an inlinetask. CONTENTS is +ENTRY is either a heading or an inlinetask. CONTENTS is ignored. INFO is a plist used as a communication channel. -This function is called on every headline, the section below +This function is called on every heading, the section below it (minus inlinetasks) being its contents. It tries to create VEVENT and VTODO components out of scheduled date, deadline date, plain timestamps, diary sexps. It also calls itself on every @@ -683,7 +683,7 @@ inlinetask within the section." (entry timestamp uid summary location description categories timezone class) "Create a VEVENT component. -ENTRY is either a headline or an inlinetask element. TIMESTAMP +ENTRY is either a heading or an inlinetask element. TIMESTAMP is a timestamp object defining the date-time of the event. UID is the unique identifier for the event. SUMMARY defines a short summary or subject for the event. LOCATION defines the intended @@ -725,7 +725,7 @@ Return VEVENT component as a string." (entry uid summary location description categories timezone class) "Create a VTODO component. -ENTRY is either a headline or an inlinetask element. UID is the +ENTRY is either a heading or an inlinetask element. UID is the unique identifier for the task. SUMMARY defines a short summary or subject for the task. LOCATION defines the intended venue for the task. DESCRIPTION provides the complete description of the @@ -862,7 +862,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-koma-letter.el b/lisp/ox-koma-letter.el index 6cb8e0cda..50ef8c04e 100644 --- a/lisp/ox-koma-letter.el +++ b/lisp/ox-koma-letter.el @@ -249,7 +249,7 @@ Moreover, when: (1) Either `org-koma-letter-prefer-special-headings' is non-nil or there is no LOCATION keyword or the LOCATION keyword is empty; - (2) the letter contains a headline with the special + (2) the letter contains a heading with the special tag \"location\"; then the location will be set as the content of the location special heading. @@ -266,9 +266,9 @@ when: (1) Either `org-koma-letter-prefer-special-headings' is non-nil or the CLOSING keyword is empty (2) `org-koma-letter-headline-is-opening-maybe' is non-nil; - (3) the letter contains a headline without a special + (3) the letter contains a heading without a special tag (e.g. \"to\" or \"ps\"); -then the opening will be implicitly set as the untagged headline title." +then the opening will be implicitly set as the untagged heading title." :type 'string) (defcustom org-koma-letter-closing "" @@ -278,7 +278,7 @@ when: (1) Either `org-koma-letter-prefer-special-headings' is non-nil or the CLOSING keyword is empty; (2) `org-koma-letter-headline-is-opening-maybe' is non-nil; - (3) the letter contains a headline with the special + (3) the letter contains a heading with the special tag \"closing\"; then the opening will be set as the title of the closing special heading title." @@ -291,7 +291,7 @@ Moreover, when: (1) Either `org-koma-letter-prefer-special-headings' is non-nil or there is no CLOSING keyword or the CLOSING keyword is empty; (2) `org-koma-letter-headline-is-opening-maybe' is non-nil; - (3) the letter contains a headline with the special + (3) the letter contains a heading with the special tag \"closing\"; then the signature will be set as the content of the closing special heading. @@ -300,7 +300,7 @@ Note if the content is empty the signature will not be set." :type 'string) (defcustom org-koma-letter-prefer-special-headings nil - "Non-nil means prefer headlines over keywords for TO and FROM. + "Non-nil means prefer headings over keywords for TO and FROM. This option can also be set with the OPTIONS keyword, e.g.: \"special-headings:t\"." :type 'boolean) @@ -436,7 +436,7 @@ The value must be a member of `org-latex-classes'." :type 'string) (defcustom org-koma-letter-headline-is-opening-maybe t - "Non-nil means a headline may be used as an opening and closing. + "Non-nil means a heading may be used as an opening and closing. See also `org-koma-letter-opening' and `org-koma-letter-closing'." :type 'boolean) @@ -546,7 +546,7 @@ e.g. \"title-subject:t\"." ;; Thanks, Luis! (defun org-koma-letter--get-tagged-contents (key) - "Get contents from a headline tagged with KEY. + "Get contents from a heading tagged with KEY. The contents is stored in `org-koma-letter-special-contents'." (let ((value (cdr (assoc-string (org-koma-letter--get-value key) org-koma-letter-special-contents)))) @@ -655,8 +655,8 @@ special tag headline." (defun org-koma-letter--keyword-or-headline (plist-key pred info) "Return the correct version of opening or closing. PLIST-KEY should be a key in info, typically :opening -or :closing. PRED is a predicate run on headline to determine -which title to use which takes two arguments, a headline element +or :closing. PRED is a predicate run on heading to determine +which title to use which takes two arguments, a heading element and an info plist. INFO is a plist holding contextual information. Return the preferred candidate for the exported of PLIST-KEY." @@ -888,7 +888,7 @@ asynchronously. The resulting buffer should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -925,7 +925,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -963,7 +963,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el index 17698601d..ee627f780 100644 --- a/lisp/ox-latex.el +++ b/lisp/ox-latex.el @@ -363,7 +363,7 @@ advance. One reason to do this is that it allows you to refer to various elements using a single label both in Org's link syntax and in embedded LaTeX code. -For example, when this variable is non-nil, a headline like this: +For example, when this variable is non-nil, a heading like this: ** Some section :PROPERTIES: @@ -394,7 +394,7 @@ numbers, and the following punctuation: `_' `.' `-' `:'.) There are no such limitations on CUSTOM_ID and NAME when this variable is nil. -For headlines that do not define the CUSTOM_ID property or +For headings that do not define the CUSTOM_ID property or elements without a NAME, Org will continue to use its default labeling scheme to generate labels and resolve links into proper references." @@ -533,8 +533,8 @@ should have a %s to represent the section title. Instead of a list of sectioning commands, you can also specify a function name. That function will be called with two -parameters, the (reduced) level of the headline, and a predicate -non-nil when the headline should be numbered. It must return +parameters, the (reduced) level of the heading, and a predicate +non-nil when the heading should be numbered. It must return a format string in which the section title will be added." :group 'org-export-latex :type '(repeat @@ -647,13 +647,13 @@ precedence over this variable." (defcustom org-latex-format-headline-function 'org-latex-format-headline-default-function - "Function for formatting the headline's text. + "Function for formatting the heading's text. This function will be called with six arguments: TODO the todo keyword (string or nil) TODO-TYPE the type of todo (symbol: `todo', `done', nil) -PRIORITY the priority of the headline (integer or nil) -TEXT the main headline text (string) +PRIORITY the priority of the heading (integer or nil) +TEXT the main heading text (string) TAGS the tags (list of strings or nil) INFO the export options (plist) @@ -2084,7 +2084,7 @@ holding contextual information." (defun org-latex-format-headline-default-function (todo _todo-type priority text tags _info) - "Default format function for a headline. + "Default format function for a heading. See `org-latex-format-headline-function' for details." (concat (and todo (format "{\\bfseries\\sffamily %s} " todo)) @@ -3612,7 +3612,7 @@ asynchronously. The resulting buffer should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -3656,7 +3656,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -3688,7 +3688,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-man.el b/lisp/ox-man.el index b825dc67b..59ddaf284 100644 --- a/lisp/ox-man.el +++ b/lisp/ox-man.el @@ -1066,7 +1066,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -1099,7 +1099,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-md.el b/lisp/ox-md.el index 5a407048a..fa0247ca0 100644 --- a/lisp/ox-md.el +++ b/lisp/ox-md.el @@ -44,7 +44,7 @@ :package-version '(Org . "8.0")) (defcustom org-md-headline-style 'atx - "Style used to format headlines. + "Style used to format headings. This variable can be set to either `atx' or `setext'." :group 'org-export-md :type '(choice @@ -201,9 +201,9 @@ of contents can refer to headlines." info t)))) (defun org-md--headline-title (style level title &optional anchor tags) - "Generate a headline title in the preferred Markdown headline style. + "Generate a heading title in the preferred Markdown heading style. STYLE is the preferred style (`atx' or `setext'). LEVEL is the -header level. TITLE is the headline title. ANCHOR is the HTML +header level. TITLE is the heading title. ANCHOR is the HTML anchor tag for the section as a string. TAGS are the tags set on the section." (let ((anchor-lines (and anchor (concat anchor "\n\n")))) @@ -719,7 +719,7 @@ asynchronously. The resulting buffer should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -756,7 +756,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el index 60660e9ab..a506658b1 100644 --- a/lisp/ox-odt.el +++ b/lisp/ox-odt.el @@ -654,16 +654,16 @@ The default value simply returns the value of CONTENTS." (defcustom org-odt-format-headline-function 'org-odt-format-headline-default-function - "Function to format headline text. + "Function to format heading text. This function will be called with 5 arguments: TODO the todo keyword (string or nil). TODO-TYPE the type of todo (symbol: `todo', `done', nil) -PRIORITY the priority of the headline (integer or nil) -TEXT the main headline text (string). +PRIORITY the priority of the heading (integer or nil) +TEXT the main heading text (string). TAGS the tags string, separated with colons (string or nil). -The function result will be used as headline text." +The function result will be used as heading text." :group 'org-export-odt :version "26.1" :package-version '(Org . "8.3") @@ -1852,7 +1852,7 @@ holding contextual information." (defun org-odt-format-headline-default-function (todo todo-type priority text tags) - "Default format function for a headline. + "Default format function for a heading. See `org-odt-format-headline-function' for details." (concat ;; Todo. @@ -4152,7 +4152,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-org.el b/lisp/ox-org.el index 3fe836e7e..842c3668b 100644 --- a/lisp/ox-org.el +++ b/lisp/ox-org.el @@ -112,13 +112,13 @@ setting of `org-html-htmlize-output-type' is `css'." :filters-alist '((:filter-parse-tree . org-org--add-missing-sections))) (defun org-org--add-missing-sections (tree _backend _info) - "Ensure each headline has an associated section. + "Ensure each heading has an associated section. TREE is the parse tree being exported. -Footnotes relative to the headline are inserted in the section, +Footnotes relative to the heading are inserted in the section, using `org-org-section'. However, this function is not called if -the headline doesn't contain any section in the first place, so +the heading doesn't contain any section in the first place, so we make sure it is always called." (org-element-map tree 'headline (lambda (h) @@ -252,7 +252,7 @@ asynchronously. The resulting buffer should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -287,7 +287,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox-publish.el b/lisp/ox-publish.el index 774ad27e4..711573486 100644 --- a/lisp/ox-publish.el +++ b/lisp/ox-publish.el @@ -1025,7 +1025,7 @@ The index relative to current file is stored as an alist. An association has the following shape: (TERM FILE-NAME PARENT), where TERM is the indexed term, as a string, FILE-NAME is the original full path of the file where the term in encountered, and -PARENT is a reference to the headline, if any, containing the +PARENT is a reference to the heading, if any, containing the original index keyword. When non-nil, this reference is a cons cell. Its CAR is a symbol among `id', `custom-id' and `name' and its CDR is a string." @@ -1161,7 +1161,7 @@ option, e.g., [[file:file.org::#custom-id][description]] [[file:file.org::fuzzy][description]] -When PREFER-CUSTOM is non-nil, and SEARCH targets a headline in +When PREFER-CUSTOM is non-nil, and SEARCH targets a heading in FILE, return its custom ID, if any. It only makes sense to use this if export back-end builds diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el index b0dad2541..5eef93353 100644 --- a/lisp/ox-texinfo.el +++ b/lisp/ox-texinfo.el @@ -213,13 +213,13 @@ section string and will be replaced by the title of the section." (defcustom org-texinfo-format-headline-function 'org-texinfo-format-headline-default-function - "Function to format headline text. + "Function to format heading text. This function will be called with 5 arguments: TODO the todo keyword (string or nil). TODO-TYPE the type of todo (symbol: `todo', `done', nil) -PRIORITY the priority of the headline (integer or nil) -TEXT the main headline text (string). +PRIORITY the priority of the heading (integer or nil) +TEXT the main heading text (string). TAGS the tags as a list of strings (list of strings or nil). The function result will be used in the section format string." @@ -419,12 +419,12 @@ If two strings share the same prefix (e.g. \"ISO-8859-1\" and (replace-regexp-in-string "\n\\(?:\n[ \t]*\\)*\\'" "\n\n" headline)) (defun org-texinfo--normalize-headlines (tree _backend info) - "Normalize headlines in TREE. + "Normalize headings in TREE. BACK-END is the symbol specifying back-end used for export. INFO is a plist used as a communication channel. -Make sure every headline in TREE contains a section, since those +Make sure every heading in TREE contains a section, since those are required to install a menu. Also put exactly one blank line at the end of each section. @@ -467,7 +467,7 @@ INFO is a plist used as a communication channel. See (defun org-texinfo--get-node (datum info) "Return node or anchor associated to DATUM. -DATUM is a headline, a radio-target or a target. INFO is a plist +DATUM is a heading, a radio-target or a target. INFO is a plist used as a communication channel. The function guarantees the node or anchor name is unique." (let ((cache (plist-get info :texinfo-node-cache))) @@ -929,7 +929,7 @@ holding contextual information." (defun org-texinfo-format-headline-default-function (todo _todo-type priority text tags) - "Default format function for a headline. + "Default format function for a heading. See `org-texinfo-format-headline-function' for details." (concat (and todo (format "@strong{%s} " todo)) (and priority (format "@emph{#%s} " priority)) @@ -1153,7 +1153,7 @@ current state of the export, as a plist." (defun org-texinfo-make-menu (scope info &optional master) "Create the menu for inclusion in the Texinfo document. -SCOPE is a headline or a full parse tree. INFO is the +SCOPE is a heading or a full parse tree. INFO is the communication channel, as a plist. When optional argument MASTER is non-nil, generate a master menu, @@ -1179,7 +1179,7 @@ including detailed node listing." (defun org-texinfo--build-menu (scope info &optional level) "Build menu for entries within SCOPE. -SCOPE is a headline or a full parse tree. INFO is a plist +SCOPE is a heading or a full parse tree. INFO is a plist containing contextual information. When optional argument LEVEL is an integer, build the menu recursively, down to this depth." (cond @@ -1201,7 +1201,7 @@ is an integer, build the menu recursively, down to this depth." (defun org-texinfo--format-entries (entries info) "Format all direct menu entries in SCOPE, as a string. -SCOPE is either a headline or a full Org document. INFO is +SCOPE is either a heading or a full Org document. INFO is a plist containing contextual information." (org-element-normalize-string (mapconcat @@ -1225,7 +1225,7 @@ a plist containing contextual information." (defun org-texinfo--menu-entries (scope info) "List direct children in SCOPE needing a menu entry. -SCOPE is a headline or a full parse tree. INFO is a plist +SCOPE is a heading or a full parse tree. INFO is a plist holding contextual information." (let* ((cache (or (plist-get info :texinfo-entries-cache) (plist-get (plist-put info :texinfo-entries-cache @@ -1628,7 +1628,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -1679,7 +1679,7 @@ asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties +at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export diff --git a/lisp/ox.el b/lisp/ox.el index b367def86..da8cc1475 100644 --- a/lisp/ox.el +++ b/lisp/ox.el @@ -100,7 +100,7 @@ ;; options, shared between every exporter, and how they are acquired. (defconst org-export-max-depth 19 - "Maximum nesting depth for headlines, counting from 0.") + "Maximum nesting depth for headings, counting from 0.") (defconst org-export-options-alist '((:title "TITLE" nil nil parse) @@ -339,14 +339,14 @@ according to the back-end used.") This can have three different values: nil Do not export, pretend this tree is not present. t Do export the entire tree. -`headline' Only export the headline, but skip the tree below it. +`headline' Only export the heading, but skip the tree below it. This option can also be set with the OPTIONS keyword, e.g. \"arch:nil\"." :group 'org-export-general :type '(choice (const :tag "Not at all" nil) - (const :tag "Headline only" headline) + (const :tag "Heading only" headline) (const :tag "Entirely" t)) :safe (lambda (x) (memq x '(t nil headline)))) @@ -509,7 +509,7 @@ t Allow export of math snippets." :safe (lambda (x) (memq x '(t nil verbatim)))) (defcustom org-export-headline-levels 3 - "The last level which is still exported as a headline. + "The last level which is still exported as a heading. Inferior levels will usually produce itemize or enumerate lists when exported, but back-end behavior may differ. @@ -605,10 +605,10 @@ e.g. \"prop:t\"." (and (listp x) (cl-every #'stringp x))))) (defcustom org-export-with-section-numbers t - "Non-nil means add section numbers to headlines when exporting. + "Non-nil means add section numbers to headings when exporting. When set to an integer n, numbering will only happen for -headlines whose relative level is higher or equal to n. +headings whose relative level is higher or equal to n. This option can also be set with the OPTIONS keyword, e.g. \"num:t\"." @@ -714,13 +714,13 @@ frequently in plain text." (defcustom org-export-with-toc t "Non-nil means create a table of contents in exported files. -The table of contents contains headlines with levels up to +The table of contents contains headings with levels up to `org-export-headline-levels'. When this variable is set to an integer N, include levels up to N in the table of contents. Although it may then be different from `org-export-headline-levels', it is cannot be larger than -the number of headline levels. +the number of heading levels. When nil, no table of contents is created. @@ -746,10 +746,10 @@ e.g. \"|:nil\"." :safe #'booleanp) (defcustom org-export-with-tags t - "If nil, do not export tags, just remove them from headlines. + "If nil, do not export tags, just remove them from headings. If this is the symbol `not-in-toc', tags will be removed from -table of contents entries, but still be shown in the headlines of +table of contents entries, but still be shown in the headings of the document. This option can also be set with the OPTIONS keyword, @@ -1623,12 +1623,12 @@ is a list holding export options. Following tree properties are set or updated: -`:headline-offset' Offset between true level of headlines and - local level. An offset of -1 means a headline +`:headline-offset' Offset between true level of headings and + local level. An offset of -1 means a heading of level 2 should be considered as a level - 1 headline in the context. + 1 heading in the context. -`:headline-numbering' Alist of all headlines as key and the +`:headline-numbering' Alist of all headings as key and the associated numbering as value. `:id-alist' Alist of all ID references as key and associated file @@ -1657,7 +1657,7 @@ Return updated plist." (and file (cons id (file-relative-name file)))))))))) (defun org-export--get-min-level (data options) - "Return minimum exportable headline's level in DATA. + "Return minimum exportable heading's level in DATA. DATA is parsed tree as returned by `org-element-parse-buffer'. OPTIONS is a plist holding export options." (catch 'exit @@ -1673,12 +1673,12 @@ OPTIONS is a plist holding export options." (if (= min-level 10000) 1 min-level)))) (defun org-export--collect-headline-numbering (data options) - "Return numbering of all exportable, numbered headlines in a parse tree. + "Return numbering of all exportable, numbered headings in a parse tree. DATA is the parse tree. OPTIONS is the plist holding export options. -Return an alist whose key is a headline and value is its +Return an alist whose key is a heading and value is its associated numbering \(in the shape of a list of numbers) or nil for a footnotes section." (let ((numbering (make-vector org-export-max-depth 0))) @@ -1699,7 +1699,7 @@ for a footnotes section." options))) (defun org-export--selected-trees (data info) - "List headlines and inlinetasks with a select tag in their tree. + "List headings and inlinetasks with a select tag in their tree. DATA is parsed data as returned by `org-element-parse-buffer'. INFO is a plist holding export options." (let ((select (cl-mapcan (lambda (tag) (org-tags-expand tag t)) @@ -1740,9 +1740,9 @@ INFO is a plist holding export options." (defun org-export--skip-p (datum options selected excluded) "Non-nil when element or object DATUM should be skipped during export. OPTIONS is the plist holding export options. SELECTED, when -non-nil, is a list of headlines or inlinetasks belonging to +non-nil, is a list of headings or inlinetasks belonging to a tree with a select tag. EXCLUDED is a list of tags, as -strings. Any headline or inlinetask marked with one of those is +strings. Any heading or inlinetask marked with one of those is not exported." (cl-case (org-element-type datum) ((comment comment-block) @@ -2196,7 +2196,7 @@ as a string, the back-end, as a symbol, and the communication channel, as a plist. It must return a string or nil.") (defvar org-export-filter-headline-functions nil - "List of functions applied to a transcoded headline. + "List of functions applied to a transcoded heading. Each filter is called with three arguments: the transcoded data, as a string, the back-end, as a symbol, and the communication channel, as a plist. It must return a string or nil.") @@ -2914,7 +2914,7 @@ narrowed part. If a region is active, transcode that region. When optional argument SUBTREEP is non-nil, transcode the -sub-tree at point, extracting information from the headline +sub-tree at point, extracting information from the heading properties first. When optional argument VISIBLE-ONLY is non-nil, don't export @@ -3423,10 +3423,10 @@ Optional argument IND, when non-nil, is an integer specifying the global indentation of returned contents. Since its purpose is to allow an included file to stay in the same environment it was created (e.g., a list item), it doesn't apply past the first -headline encountered. +heading encountered. Optional argument MINLEVEL, when non-nil, is an integer -specifying the level that any top-level headline in the included +specifying the level that any top-level heading in the included file should have. Optional argument ID is an integer that will be inserted before @@ -3986,7 +3986,7 @@ When non-nil, optional argument TAGS should be a list of strings. Any tag belonging to this list will also be removed. When optional argument INHERITED is non-nil, tags can also be -inherited from parent headlines and FILETAGS keywords." +inherited from parent headings and FILETAGS keywords." (cl-remove-if (lambda (tag) (member tag tags)) (if (not inherited) (org-element-property :tags element) @@ -4007,7 +4007,7 @@ PROPERTY is an upcase symbol (e.g., `:COOKIE_DATA'). DATUM is an element or object. If optional argument INHERITED is non-nil, the value can be -inherited from a parent headline. +inherited from a parent heading. Return value is a string or nil." (let ((headline (if (eq (org-element-type datum) 'headline) datum @@ -4025,7 +4025,7 @@ Return value is a string or nil." INFO is a plist used as a communication channel. -CATEGORY is automatically inherited from a parent headline, from +CATEGORY is automatically inherited from a parent heading, from #+CATEGORY: keyword or created out of original file name. If all fail, the fall-back value is \"???\"." (or (org-export-get-node-property :CATEGORY blob t) @@ -4048,7 +4048,7 @@ If no optional title is defined, fall-back to the regular title." (defun org-export-first-sibling-p (blob info) "Non-nil when BLOB is the first sibling in its parent. -BLOB is an element or an object. If BLOB is a headline, non-nil +BLOB is an element or an object. If BLOB is a heading, non-nil means it is the first sibling in the sub-tree. INFO is a plist used as a communication channel." (memq (org-element-type (org-export-get-previous-element blob info)) @@ -4264,7 +4264,7 @@ A search cell follows the pattern (TYPE . SEARCH) where SEARCH is the string a link is expected to match. More accurately, it is - - headline's title, as a list of strings, if TYPE is + - heading's title, as a list of strings, if TYPE is `headline'. - CUSTOM_ID value, as a string, if TYPE is `custom-id'. @@ -4298,7 +4298,7 @@ ignores white spaces and statistics cookies, if applicable." (defun org-export-string-to-search-cell (s) "Return search cells associated to string S. S is either the path of a fuzzy link or a search option, i.e., it -tries to match either a headline (through custom ID or title), +tries to match either a heading (through custom ID or title), a target or a named element." (pcase (string-to-char s) (?* (list (cons 'headline (split-string (substring s 1))))) @@ -4325,7 +4325,7 @@ Return value can be an object or an element: - If LINK path exactly matches the name affiliated keyword (i.e. #+NAME: path) of an element, return that element. -- If LINK path exactly matches any headline name, return that +- If LINK path exactly matches any heading name, return that element. - Otherwise, throw an error. @@ -4367,11 +4367,11 @@ significant." link-cache))))) (defun org-export-resolve-id-link (link info) - "Return headline referenced as LINK destination. + "Return heading referenced as LINK destination. INFO is a plist used as a communication channel. -Return value can be the headline element matched in current parse +Return value can be the heading element matched in current parse tree or a file name. Assume LINK type is either \"id\" or \"custom-id\". Throw an error if no match is found." (let ((id (org-element-property :path link))) @@ -4414,7 +4414,7 @@ INFO is a plist holding contextual information. Return value can be an object or an element: -- If LINK path matches an ID or a custom ID, return the headline. +- If LINK path matches an ID or a custom ID, return the heading. - If LINK path matches a fuzzy link, return its destination. @@ -4543,11 +4543,11 @@ accepts two arguments: the element or object being considered and the plist used as a communication channel. This allows counting only a certain type of object (i.e. inline images). -Return value is a list of numbers if ELEMENT is a headline or an +Return value is a list of numbers if ELEMENT is a heading or an item. It is nil for keywords. It represents the footnote number for footnote definitions and footnote references. If ELEMENT is a target, return the same value as if ELEMENT was the closest -table, item or headline containing the target. In any other +table, item or heading containing the target. In any other case, return the sequence number of ELEMENT among elements or objects of the same type." ;; Ordinal of a target object refer to the ordinal of the closest @@ -5266,22 +5266,22 @@ return nil." ;; useful to export table of contents' entries. (defun org-export-collect-headlines (info &optional n scope) - "Collect headlines in order to build a table of contents. + "Collect headings in order to build a table of contents. INFO is a plist used as a communication channel. When optional argument N is an integer, it specifies the depth of the table of contents. Otherwise, it is set to the value of the -last headline level. See `org-export-headline-levels' for more +last heading level. See `org-export-headline-levels' for more information. Optional argument SCOPE, when non-nil, is an element. If it is -a headline, only children of SCOPE are collected. Otherwise, -collect children of the headline containing provided element. If -there is no such headline, collect all headlines. In any case, -argument N becomes relative to the level of that headline. +a heading, only children of SCOPE are collected. Otherwise, +collect children of the heading containing provided element. If +there is no such heading, collect all headings. In any case, +argument N becomes relative to the level of that heading. -Return a list of all exportable headlines as parsed elements. +Return a list of all exportable headings as parsed elements. Footnote sections are ignored." (let* ((scope (cond ((not scope) (plist-get info :parse-tree)) ((eq (org-element-type scope) 'headline) scope) @@ -5700,7 +5700,7 @@ Return the new string." ;; defsubst org-export-get-parent must be defined before first use (defun org-export-get-parent-headline (blob) - "Return BLOB parent headline or nil. + "Return BLOB parent heading or nil. BLOB is the element or object being considered." (org-element-lineage blob '(headline))) -- 2.33.0