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/)]
Thanks so much, Ihor. On Sat, 14 May 2022 at 06:08, Ihor Radchenko wrote: > > Phil Hudson 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
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/)]
Phil Hudson 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
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/)]
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 wrote: > > Phil Hudson 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 >
[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/)]
Phil Hudson 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 >From 6041817f426aa0976f557f4c108203b8eed37ac1 Mon Sep 17 00:00:00 2001 Message-Id: <6041817f426aa0976f557f4c108203b8eed37ac1.1651549348.git.yanta...@gmail.com> From: Ihor Radchenko 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 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
[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/)]
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/)