From: Ihor Radchenko <yantar92@posteo.net>
To: Rick Lupton <mail@ricklupton.name>
Cc: "Y. E." <emacs-orgmode@gnu.org>
Subject: Re: [PATCH v2] org-id: allow using parent's existing id in links to headlines
Date: Thu, 08 Feb 2024 13:02:42 +0000 [thread overview]
Message-ID: <87wmrfw1l9.fsf@localhost> (raw)
In-Reply-To: <2a4b236c-c377-4493-b5ed-632c5518d514@app.fastmail.com>
[-- Attachment #1: Type: text/plain, Size: 2958 bytes --]
"Rick Lupton" <mail@ricklupton.name> writes:
>> It looks like we cannot simply rely on narrowing to determine the
>> created heading level.
>
> I think you're right. I have extended `org-link-search' to accept an optional argument describing the org element where newly created headings should go as subheadings.
>
> My thought was that this was not significantly more complicated than just passing the numeric level for new headings, but actually more flexible (e.g. you could if you wanted (with additional future elisp) create missing headings as part of a "To be filed" subtree within the file, rather than always at the end).
>
> Does that look ok?
Yes.
> [is it useful to keep attaching the unchanged first patch so they are available as a set?]
Yes, it is useful. Makes it easier for my to batch-apply the patchset
using https://git.kyleam.com/piem/about/
I have some thoughts about rewording your changes to the manual and
ORG-NEWS. See the attached patch on top of yours.
> Subject: [PATCH 1/2] lisp/org.el (org-insert-heading): allow specifying
> heading level
*Allow
> * lisp/org.el (org-insert-heading): Change optional argument TOP to
> LEVEL, accepting a number to force a specific heading level.
> * testing/lisp/test-org.el (test-org/insert-heading): Add tests
> * etc/ORG-NEWS: Document changes
Please end sentences with period.
> From d5759dd95bec88be38ddbde07fa4437c0528469a Mon Sep 17 00:00:00 2001
> From: Rick Lupton <mail@ricklupton.name>
> Date: Sun, 19 Nov 2023 14:52:05 +0000
> Subject: [PATCH 2/2] org-id.el: Add search strings, inherit parent IDs
>
> ...
> (org-link-try-link-store-functions): Extract logic to call external
> link store functions. Pass them a new `interactive?' argument.
> ...
> (org-id-store-link): Consider IDs of parent headings as link targets
> when current heading has no ID and `org-id-link-consider-parent-id' is
> set. Add a search string to the link when enabled.
Please, use two spaces between sentences.
> * lisp/org-lint.el: add checker for "::" in ID properties.
... and start sentences from capital letter: *Add
> -(defun org-link-search (s &optional avoid-pos stealth)
> +(defun org-link-search (s &optional avoid-pos stealth new-heading-container)
The new optional argument to a public function should be announced in ORG-NEWS.
> + (new-heading-level (if new-heading-container
> + (+ 1 (org-element-property :level new-heading-container))
What if new-heading-container is not a heading?
> + 1)))
> + (goto-char new-heading-position)
This is err when container ends after narrowed region boundary.
> +(defun org-link-precise-link-target ()
> ...
> + (cond
> + (name
> + (list name
> + name
> + (org-element-begin element)))
It would make sense to use #+caption as default description when available.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Amendments-to-org-manual.org-and-ORG-NEWS.patch --]
[-- Type: text/x-patch, Size: 4327 bytes --]
From 0f9a4503d95f7682229ae1c1ad8a4e2d069fc644 Mon Sep 17 00:00:00 2001
Message-ID: <0f9a4503d95f7682229ae1c1ad8a4e2d069fc644.1707396844.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Thu, 8 Feb 2024 13:53:44 +0100
Subject: [PATCH] Amendments to org-manual.org and ORG-NEWS
---
doc/org-manual.org | 18 ++++++++++--------
etc/ORG-NEWS | 27 ++++++++++++++-------------
2 files changed, 24 insertions(+), 21 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 49fce9113..e933a2d63 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3489,14 +3489,16 @@ ** Handling Links
#+vindex: org-id-link-consider-parent-id
#+vindex: org-id-link-use-context
- When ~org-id-link-consider-parent-id~ is ~t~ (and
- ~org-link-context-for-files~ and ~org-id-link-use-context~ are both
- enabled), parent =ID= properties are considered. This allows
- linking to specific targets, named blocks, or headlines (which may
- not have a globally unique =ID= themselves) within the context of a
- parent headline or file which does.
-
- For example, given this org file with those variables set:
+ #+vindex: org-link-context-for-files
+ When ~org-id-link-consider-parent-id~ is ~t~[fn:: Also,
+ ~org-link-context-for-files~ and ~org-id-link-use-context~ should be
+ both enabled (which they are, by default).], parent =ID= properties
+ are considered. This allows linking to specific targets, named
+ blocks, or headlines (which may not have a globally unique =ID=
+ themselves) within the context of a parent headline or file which
+ does.
+
+ For example, given this org file:
#+begin_src org
,* Parent
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 84bbc5243..e29d2895f 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -477,22 +477,23 @@ The change is breaking when ~org-use-property-inheritance~ is set to ~t~.
The =TEST= parameter is better served by Emacs debugging tools.
-*** ~org-id-store-link~ now adds search strings for precise link targets
+*** =id:= links support search options; ~org-id-store-link~ adds search option by default
-This new behaviour can be disabled generally by setting
-~org-id-link-use-context~ to ~nil~, or the setting can be toggled for
-a single call to ~org-store-link~ with a universal argument.
+Adding search option by ~org-id-store-link~ can be disabled by setting
+~org-id-link-use-context~ to ~nil~, or toggled for a single call by
+passing universal argument.
When using this feature, IDs should not include =::=, which is used in
links to indicate the start of the search string. For backwards
compability, existing IDs including =::= will still be matched (but
-cannot be used together with precise link targets). An org-lint
-checker has been added to warn about this.
+cannot be used together with search option). A new org-lint checker
+has been added to warn about this.
*** ~org-store-link~ behaviour storing additional =CUSTOM_ID= links has changed
-As well as an =id:= link, ~org-store-link~ stores an additional "human
-readable" link using a node's =CUSTOM_ID= property, if available.
+Previously, when storing =id:= link, ~org-store-link~ stored an
+additional "human readable" link using a node's =CUSTOM_ID= property.
+
This behaviour has been expanded to store an additional =CUSTOM_ID=
link when storing any type of external link type in an Org file, not
just =id:= links.
@@ -778,11 +779,11 @@ For =id:= links, when this option is enabled, ~org-store-link~ will
look for ids from parent/ancestor headlines, if the current headline
does not have an id.
-Combined with the new ability for =id:= links to use search strings
-for precise link targets (when =org-id-link-use-context= is =t=, which
-is the default), this allows linking to specific headlines without
-requiring every headline to have an id property, as long as the
-headline is unique within a subtree that does have an id property.
+Combined with the new ability for =id:= links to use search options
+ [fn:: when =org-id-link-use-context= is =t=, which is the default],
+this allows linking to specific headlines without requiring every
+headline to have an id property, as long as the headline is unique
+within a subtree that does have an id property.
For example, given this org file:
--
2.43.0
[-- Attachment #3: Type: text/plain, Size: 224 bytes --]
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
next prev parent reply other threads:[~2024-02-08 13:00 UTC|newest]
Thread overview: 47+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-07-24 11:40 [PATCH] org-id: allow using parent's existing id in links to headlines Rick Lupton
2023-07-25 7:43 ` Ihor Radchenko
2023-07-25 15:16 ` Max Nikulin
2023-07-26 8:10 ` Ihor Radchenko
2023-07-27 0:16 ` Samuel Wales
2023-07-27 7:42 ` IDs below headline level (for paragraphs, lists, etc) (was: [PATCH] org-id: allow using parent's existing id in links to headlines) Ihor Radchenko
2023-07-28 20:00 ` Rick Lupton
2023-07-28 19:56 ` [PATCH] org-id: allow using parent's existing id in links to headlines Rick Lupton
2023-07-29 8:33 ` Ihor Radchenko
2023-11-09 20:56 ` Rick Lupton
2023-11-10 10:03 ` Ihor Radchenko
2023-11-19 15:21 ` Rick Lupton
2023-12-04 13:23 ` Rick Lupton
2023-12-10 13:35 ` Ihor Radchenko
2023-12-14 20:42 ` Rick Lupton
2023-12-15 12:55 ` Ihor Radchenko
2023-12-15 16:16 ` Rick Lupton
2023-12-16 14:20 ` Ihor Radchenko
2023-12-17 19:07 ` [PATCH v2] " Rick Lupton
2023-12-18 12:27 ` Ihor Radchenko
2024-01-02 16:13 ` Rick Lupton
2024-01-03 14:17 ` Ihor Radchenko
2024-01-28 22:47 ` Rick Lupton
2024-01-29 0:20 ` Samuel Wales
2024-01-29 13:06 ` Ihor Radchenko
2024-01-30 0:03 ` Samuel Wales
2024-02-03 15:08 ` Ihor Radchenko
2024-01-29 13:00 ` Ihor Radchenko
2024-01-31 18:11 ` Rick Lupton
2024-02-01 12:13 ` Ihor Radchenko
2024-02-01 16:37 ` Rick Lupton
2024-02-03 13:10 ` Ihor Radchenko
2024-02-08 8:24 ` [PATCH] lisp/ol.el: Improve docstring Rick Lupton
2024-02-08 14:52 ` Ihor Radchenko
2024-02-08 8:46 ` [PATCH v2] org-id: allow using parent's existing id in links to headlines Rick Lupton
2024-02-08 13:02 ` Ihor Radchenko [this message]
2024-02-08 22:30 ` Rick Lupton
2024-02-09 12:09 ` Ihor Radchenko
2024-02-09 12:47 ` Rick Lupton
2024-02-09 12:57 ` Ihor Radchenko
2024-02-24 10:48 ` Bastien Guerry
2024-02-24 13:02 ` Ihor Radchenko
2024-02-24 15:57 ` Rick Lupton
2024-03-05 14:05 ` Stefan
2024-03-05 14:51 ` Ihor Radchenko
2023-11-04 23:01 ` [PATCH] " Rick Lupton
2023-11-05 12:31 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87wmrfw1l9.fsf@localhost \
--to=yantar92@posteo.net \
--cc=emacs-orgmode@gnu.org \
--cc=mail@ricklupton.name \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).