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