* [BUG] org-element-map doco should refer to org-element-parse-buffer [9.5.2 (9.5.2-gfbff08 @ /home/phil/.emacs.d/elpa/org-9.5.2/)] @ 2022-03-30 6:12 Phil Hudson 2022-05-03 3:44 ` [PATCH] " Ihor Radchenko 0 siblings, 1 reply; 5+ messages in thread From: Phil Hudson @ 2022-03-30 6:12 UTC (permalink / raw) To: emacs orgmode-mailinglist The documentation for function `org-element-parse-buffer' helpfully directs the user to that of function `org-element-map', but the documentation for the latter makes no mention of `org-element-parse-buffer'. It contains lengthy and helpful explanations of what to do with its `data' parameter, but no hint as to how to obtain that data. Emacs : GNU Emacs 27.2 (build 1, x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll bars) of 2021-08-28 Package: Org mode version 9.5.2 (9.5.2-gfbff08 @ /home/phil/.emacs.d/elpa/org-9.5.2/) ^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH] Re: [BUG] org-element-map doco should refer to org-element-parse-buffer [9.5.2 (9.5.2-gfbff08 @ /home/phil/.emacs.d/elpa/org-9.5.2/)] 2022-03-30 6:12 [BUG] org-element-map doco should refer to org-element-parse-buffer [9.5.2 (9.5.2-gfbff08 @ /home/phil/.emacs.d/elpa/org-9.5.2/)] Phil Hudson @ 2022-05-03 3:44 ` Ihor Radchenko 2022-05-03 8:10 ` Phil Hudson 0 siblings, 1 reply; 5+ messages in thread From: Ihor Radchenko @ 2022-05-03 3:44 UTC (permalink / raw) To: Phil Hudson; +Cc: emacs orgmode-mailinglist [-- Attachment #1: Type: text/plain, Size: 465 bytes --] Phil Hudson <phil.hudson@iname.com> writes: > The documentation for function `org-element-parse-buffer' helpfully > directs the user to that of function `org-element-map', but the > documentation for the latter makes no mention of > `org-element-parse-buffer'. It contains lengthy and helpful explanations > of what to do with its `data' parameter, but no hint as to how to obtain > that data. Sounds reasonable. Will something like the attached do? Best, Ihor [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-org-element-map-Refer-to-org-element-parse-buffer-in.patch --] [-- Type: text/x-patch, Size: 2160 bytes --] From 6041817f426aa0976f557f4c108203b8eed37ac1 Mon Sep 17 00:00:00 2001 Message-Id: <6041817f426aa0976f557f4c108203b8eed37ac1.1651549348.git.yantar92@gmail.com> From: Ihor Radchenko <yantar92@gmail.com> Date: Tue, 3 May 2022 11:40:26 +0800 Subject: [PATCH] org-element-map: Refer to `org-element-parse-buffer' in the docstring * lisp/org-element.el (org-element-map): Update docstring. Mention that parse tree can be obtained using `org-element-parse-buffer'. Add an example. --- lisp/org-element.el | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/lisp/org-element.el b/lisp/org-element.el index 3856079aa..4be345001 100644 --- a/lisp/org-element.el +++ b/lisp/org-element.el @@ -4524,12 +4524,12 @@ (defun org-element-map (data types fun &optional info first-match no-recursion with-affiliated) "Map a function on selected elements or objects. -DATA is a parse tree, an element, an object, a string, or a list -of such constructs. TYPES is a symbol or list of symbols of -elements or objects types (see `org-element-all-elements' and -`org-element-all-objects' for a complete list of types). FUN is -the function called on the matching element or object. It has to -accept one argument: the element or object itself. +DATA is a parse tree (e.g. returned by `org-element-parse-buffer'), an element, +an object, a string, or a list of such constructs. TYPES is a symbol +or list of symbols of elements or objects types (see `org-element-all-elements' +and `org-element-all-objects' for a complete list of types). FUN is the function +called on the matching element or object. It has to accept one +argument: the element or object itself. When optional argument INFO is non-nil, it should be a plist holding export options. In that case, parts of the parse tree @@ -4557,6 +4557,7 @@ (defun org-element-map the following example will return a flat list of all `src-block' and `example-block' elements in it: + (setq tree (org-element-parse-buffer)) (org-element-map tree \\='(example-block src-block) #\\='identity) The following snippet will find the first headline with a level -- 2.35.1 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] Re: [BUG] org-element-map doco should refer to org-element-parse-buffer [9.5.2 (9.5.2-gfbff08 @ /home/phil/.emacs.d/elpa/org-9.5.2/)] 2022-05-03 3:44 ` [PATCH] " Ihor Radchenko @ 2022-05-03 8:10 ` Phil Hudson 2022-05-14 5:09 ` Ihor Radchenko 0 siblings, 1 reply; 5+ messages in thread From: Phil Hudson @ 2022-05-03 8:10 UTC (permalink / raw) To: Ihor Radchenko; +Cc: emacs orgmode-mailinglist Thanks Ihor, that's great! One tiny nit-pick: I think "e.g." is deprecated in favor of the explicit literal "for example". My source for this is (info "(elisp) Documentation Tips"). Also, just spotted what I think is a pre-existing typo, "objects types", which I think should probably be just "object types". Might as well fix that while we're at it. Best, Phil On Tue, 3 May 2022 at 04:43, Ihor Radchenko <yantar92@gmail.com> wrote: > > Phil Hudson <phil.hudson@iname.com> writes: > > > The documentation for function `org-element-parse-buffer' helpfully > > directs the user to that of function `org-element-map', but the > > documentation for the latter makes no mention of > > `org-element-parse-buffer'. It contains lengthy and helpful explanations > > of what to do with its `data' parameter, but no hint as to how to obtain > > that data. > > Sounds reasonable. > Will something like the attached do? > > Best, > Ihor > ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Re: [BUG] org-element-map doco should refer to org-element-parse-buffer [9.5.2 (9.5.2-gfbff08 @ /home/phil/.emacs.d/elpa/org-9.5.2/)] 2022-05-03 8:10 ` Phil Hudson @ 2022-05-14 5:09 ` Ihor Radchenko 2022-05-14 8:01 ` Phil Hudson 0 siblings, 1 reply; 5+ messages in thread From: Ihor Radchenko @ 2022-05-14 5:09 UTC (permalink / raw) To: Phil Hudson; +Cc: emacs orgmode-mailinglist Phil Hudson <phil.hudson@iname.com> writes: > Thanks Ihor, that's great! > > One tiny nit-pick: I think "e.g." is deprecated in favor of the > explicit literal "for example". My source for this is (info "(elisp) > Documentation Tips"). Fair point, though searching across org-element.el reveals that e.g. is used in many places. I do not see it as too much of a big deal. Will just update the patch here. > Also, just spotted what I think is a pre-existing typo, "objects > types", which I think should probably be just "object types". Might as > well fix that while we're at it. Fixed. Applied the new version of the patch onto main as 3996ea99a. Best, Ihor ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Re: [BUG] org-element-map doco should refer to org-element-parse-buffer [9.5.2 (9.5.2-gfbff08 @ /home/phil/.emacs.d/elpa/org-9.5.2/)] 2022-05-14 5:09 ` Ihor Radchenko @ 2022-05-14 8:01 ` Phil Hudson 0 siblings, 0 replies; 5+ messages in thread From: Phil Hudson @ 2022-05-14 8:01 UTC (permalink / raw) To: Ihor Radchenko; +Cc: emacs orgmode-mailinglist Thanks so much, Ihor. On Sat, 14 May 2022 at 06:08, Ihor Radchenko <yantar92@gmail.com> wrote: > > Phil Hudson <phil.hudson@iname.com> writes: > > > Thanks Ihor, that's great! > > > > One tiny nit-pick: I think "e.g." is deprecated in favor of the > > explicit literal "for example". My source for this is (info "(elisp) > > Documentation Tips"). > > Fair point, though searching across org-element.el reveals that e.g. is > used in many places. I do not see it as too much of a big deal. Will > just update the patch here. > > > Also, just spotted what I think is a pre-existing typo, "objects > > types", which I think should probably be just "object types". Might as > > well fix that while we're at it. > > Fixed. > > Applied the new version of the patch onto main as 3996ea99a. > > Best, > Ihor ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2022-05-14 8:04 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2022-03-30 6:12 [BUG] org-element-map doco should refer to org-element-parse-buffer [9.5.2 (9.5.2-gfbff08 @ /home/phil/.emacs.d/elpa/org-9.5.2/)] Phil Hudson 2022-05-03 3:44 ` [PATCH] " Ihor Radchenko 2022-05-03 8:10 ` Phil Hudson 2022-05-14 5:09 ` Ihor Radchenko 2022-05-14 8:01 ` Phil Hudson
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.