[PATCH] Explain how to end a buffer narrowing.

[PATCH] Explain how to end a buffer narrowing.

[yuvallangerontheroad]

[-- Attachment #1: Type: text/plain, Size: 131 bytes --]

I have added information on how to exit a narrowing. I could have used this information when I started using org-narrow-to-subtree.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Explain-how-to-remove-restrictions-narrowing-from-cu.patch --]
[-- Type: text/x-patch; name=0001-Explain-how-to-remove-restrictions-narrowing-from-cu.patch, Size: 2065 bytes --]

From 680fbfc0a91552c5d73e853effadeaa683266ec9 Mon Sep 17 00:00:00 2001
From: Yuval Langer <yuvallangerontheroad@proton.me>
Date: Thu, 24 Nov 2022 19:27:00 +0200
Subject: [PATCH] Explain how to remove restrictions (narrowing) from current
 buffer.

---
 lisp/org.el | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 64b33e597..45650efb5 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7220,7 +7220,8 @@ If yes, remember the marker and the distance to BEG."
   (setq org-markers-to-move nil))
 
 (defun org-narrow-to-subtree (&optional element)
-  "Narrow buffer to the current subtree."
+  "Narrow buffer to the current subtree.
+   Use the command M-x widen <RET> to see the whole buffer again."
   (interactive)
   (if (org-element--cache-active-p)
       (let* ((heading (org-element-lineage
@@ -7242,7 +7243,8 @@ If yes, remember the marker and the distance to BEG."
 	         (point))))))))
 
 (defun org-toggle-narrow-to-subtree ()
-  "Narrow to the subtree at point or widen a narrowed buffer."
+  "Narrow to the subtree at point or widen a narrowed buffer.
+   Use the command M-x widen <RET> to see the whole buffer again."
   (interactive)
   (if (buffer-narrowed-p)
       (progn (widen) (message "Buffer widen"))
@@ -7250,7 +7252,8 @@ If yes, remember the marker and the distance to BEG."
     (message "Buffer narrowed to current subtree")))
 
 (defun org-narrow-to-block ()
-  "Narrow buffer to the current block."
+  "Narrow buffer to the current block.
+   Use the command M-x widen <RET> to see the whole buffer again."
   (interactive)
   (let* ((case-fold-search t)
 	 (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*"
@@ -21162,7 +21165,8 @@ ones already marked."
 	(goto-char (org-element-property :begin element))))))
 
 (defun org-narrow-to-element ()
-  "Narrow buffer to current element."
+  "Narrow buffer to current element.
+   Use the command M-x widen <RET> to see the whole buffer again."
   (interactive)
   (let ((elem (org-element-at-point)))
     (cond
-- 
2.30.2

Re: [PATCH] Explain how to end a buffer narrowing.

[Ihor Radchenko]

yuvallangerontheroad <yuvallangerontheroad@proton.me> writes:

> I have added information on how to exit a narrowing. I could have used this information when I started using org-narrow-to-subtree.
> ...
>  (defun org-narrow-to-subtree (&optional element)
> -  "Narrow buffer to the current subtree."
> +  "Narrow buffer to the current subtree.
> +   Use the command M-x widen <RET> to see the whole buffer again."

Thanks!
I am neutral wrt this addition. Could be useful.

But please use `\\[widen]' instead of M-x widen. Then, Emacs will
automatically display the actual key binding for widen or "M-x widen" if
no binding is present.

See 25.3 Substituting Key Bindings in Documentation section of Elisp
manual.

-- 
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>

Re: [PATCH] Explain how to end a buffer narrowing.

[yuvallangerontheroad]

[-- Attachment #1: Type: text/plain, Size: 304 bytes --]

On Friday, November 25th, 2022 at 16:32, Ihor Radchenko <yantar92@posteo.net> wrote:

> But please use `\\[widen]' instead of M-x widen. Then, Emacs will
> automatically display the actual key binding for widen or "M-x widen" if
> no binding is present.

Thank you. The change is in the attachment.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Explain-how-to-remove-restrictions-narrowing-from-cu.patch --]
[-- Type: text/x-patch; name=0001-Explain-how-to-remove-restrictions-narrowing-from-cu.patch, Size: 2037 bytes --]

From 5e0bef6c7e288191d9b7d2517fda29718e47baad Mon Sep 17 00:00:00 2001
From: Yuval Langer <yuvallangerontheroad@proton.me>
Date: Fri, 25 Nov 2022 16:40:50 +0200
Subject: [PATCH] Explain how to remove restrictions (narrowing) from current
 buffer.

---
 lisp/org.el | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 64b33e597..b4cd73ba0 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7220,7 +7220,8 @@ If yes, remember the marker and the distance to BEG."
   (setq org-markers-to-move nil))
 
 (defun org-narrow-to-subtree (&optional element)
-  "Narrow buffer to the current subtree."
+  "Narrow buffer to the current subtree.
+Use the command \\[[widen]] to see the whole buffer again."
   (interactive)
   (if (org-element--cache-active-p)
       (let* ((heading (org-element-lineage
@@ -7242,7 +7243,8 @@ If yes, remember the marker and the distance to BEG."
 	         (point))))))))
 
 (defun org-toggle-narrow-to-subtree ()
-  "Narrow to the subtree at point or widen a narrowed buffer."
+  "Narrow to the subtree at point or widen a narrowed buffer.
+Use the command \\[[widen]] to see the whole buffer again."
   (interactive)
   (if (buffer-narrowed-p)
       (progn (widen) (message "Buffer widen"))
@@ -7250,7 +7252,8 @@ If yes, remember the marker and the distance to BEG."
     (message "Buffer narrowed to current subtree")))
 
 (defun org-narrow-to-block ()
-  "Narrow buffer to the current block."
+  "Narrow buffer to the current block.
+Use the command \\[[widen]] to see the whole buffer again."
   (interactive)
   (let* ((case-fold-search t)
 	 (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*"
@@ -21162,7 +21165,8 @@ ones already marked."
 	(goto-char (org-element-property :begin element))))))
 
 (defun org-narrow-to-element ()
-  "Narrow buffer to current element."
+  "Narrow buffer to current element.
+Use the command \\[[widen]] to see the whole buffer again."
   (interactive)
   (let ((elem (org-element-at-point)))
     (cond
-- 
2.30.2

Re: [PATCH] Explain how to end a buffer narrowing.

[Ihor Radchenko]

yuvallangerontheroad <yuvallangerontheroad@proton.me> writes:

> +  "Narrow buffer to the current subtree.
> +Use the command \\[[widen]] to see the whole buffer again."

Extra [...] are redundant.
Please test the patch before submitting.

-- 
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>

Re: [PATCH] Explain how to end a buffer narrowing.

[yuvallangerontheroad]

[-- Attachment #1: Type: text/plain, Size: 387 bytes --]

On Friday, November 25th, 2022 at 16:52, Ihor Radchenko <yantar92@posteo.net> wrote:


> yuvallangerontheroad yuvallangerontheroad@proton.me writes:
> 
> > + "Narrow buffer to the current subtree.
> > +Use the command \\[[widen]] to see the whole buffer again."
> 
> 
> Extra [...] are redundant.
> Please test the patch before submitting.

Sorry. Removed redundant brackets.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Explain-how-to-remove-restrictions-narrowing-from-cu.patch --]
[-- Type: text/x-patch; name=0001-Explain-how-to-remove-restrictions-narrowing-from-cu.patch, Size: 2029 bytes --]

From 2c5a5fa3cdb06390d3c20a47c97720074a1af507 Mon Sep 17 00:00:00 2001
From: Yuval Langer <yuvallangerontheroad@proton.me>
Date: Fri, 25 Nov 2022 16:40:50 +0200
Subject: [PATCH] Explain how to remove restrictions (narrowing) from current
 buffer.

---
 lisp/org.el | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 64b33e597..b30d2997a 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7220,7 +7220,8 @@ If yes, remember the marker and the distance to BEG."
   (setq org-markers-to-move nil))
 
 (defun org-narrow-to-subtree (&optional element)
-  "Narrow buffer to the current subtree."
+  "Narrow buffer to the current subtree.
+Use the command \\[widen] to see the whole buffer again."
   (interactive)
   (if (org-element--cache-active-p)
       (let* ((heading (org-element-lineage
@@ -7242,7 +7243,8 @@ If yes, remember the marker and the distance to BEG."
 	         (point))))))))
 
 (defun org-toggle-narrow-to-subtree ()
-  "Narrow to the subtree at point or widen a narrowed buffer."
+  "Narrow to the subtree at point or widen a narrowed buffer.
+Use the command \\[widen] to see the whole buffer again."
   (interactive)
   (if (buffer-narrowed-p)
       (progn (widen) (message "Buffer widen"))
@@ -7250,7 +7252,8 @@ If yes, remember the marker and the distance to BEG."
     (message "Buffer narrowed to current subtree")))
 
 (defun org-narrow-to-block ()
-  "Narrow buffer to the current block."
+  "Narrow buffer to the current block.
+Use the command \\[widen] to see the whole buffer again."
   (interactive)
   (let* ((case-fold-search t)
 	 (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*"
@@ -21162,7 +21165,8 @@ ones already marked."
 	(goto-char (org-element-property :begin element))))))
 
 (defun org-narrow-to-element ()
-  "Narrow buffer to current element."
+  "Narrow buffer to current element.
+Use the command \\[widen] to see the whole buffer again."
   (interactive)
   (let ((elem (org-element-at-point)))
     (cond
-- 
2.30.2

Re: [PATCH] Explain how to end a buffer narrowing.

[Ihor Radchenko]

yuvallangerontheroad <yuvallangerontheroad@proton.me> writes:

>> Extra [...] are redundant.
>> Please test the patch before submitting.
>
> Sorry. Removed redundant brackets.

Thanks.

It is also a good idea to add quotes around the command key. See the
example in 25.3 Substituting Key Bindings in Documentation
(I am honestly not sure how important quoting is, but let's better
follow the Elisp manual).

Also, please make the commit message more concrete.

Maybe something like

org: Mention how to widen in docstrings of the commands that do narrowing 

Finally, please follow the commit message format as described in
https://orgmode.org/worg/org-contribute.html#commit-messages
In particular, add the changelog entries and TINYCHANGE cookie (I assume
that you don't have FSF copyright assignment).

-- 
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>

Re: [PATCH] Explain how to end a buffer narrowing.

[yuvallangerontheroad]

[-- Attachment #1: Type: text/plain, Size: 1046 bytes --]

On Saturday, November 26th, 2022 at 04:26, Ihor Radchenko <yantar92@posteo.net> wrote:


> yuvallangerontheroad yuvallangerontheroad@proton.me writes:
> 
> > > Extra [...] are redundant.
> > > Please test the patch before submitting.
> > 
> > Sorry. Removed redundant brackets.
> 
> 
> Thanks.

:)

> It is also a good idea to add quotes around the command key. See the
> example in 25.3 Substituting Key Bindings in Documentation
> (I am honestly not sure how important quoting is, but let's better
> follow the Elisp manual).

Hopefully done.

> Also, please make the commit message more concrete.
> 
> Maybe something like
> 
> org: Mention how to widen in docstrings of the commands that do narrowing

Hopefully done.

> Finally, please follow the commit message format as described in
> https://orgmode.org/worg/org-contribute.html#commit-messages
> In particular, add the changelog entries and TINYCHANGE cookie (I assume
> that you don't have FSF copyright assignment).

Hopefully done.

Please review.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-org.el-Mention-how-to-widen-in-docstrings-of-co.patch --]
[-- Type: text/x-patch; name=0001-lisp-org.el-Mention-how-to-widen-in-docstrings-of-co.patch, Size: 2236 bytes --]

From f53b141bd2057898f2606e884cf1a094876696c2 Mon Sep 17 00:00:00 2001
From: Yuval Langer <yuvallangerontheroad@proton.me>
Date: Fri, 25 Nov 2022 16:40:50 +0200
Subject: [PATCH] lisp/org.el: Mention how to widen in docstrings of commands
 that do narrowing

lisp/org.el: (org-narrow-to-subtree, org-toggle-narrow-to-subtree,
org-narrow-to-block, org-narrow-to-element) Mention how to widen in
docstrings of commands that do narrowing.

TINYCHANGE
---
 lisp/org.el | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 472e87b9b..2a1024c89 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7220,7 +7220,8 @@ If yes, remember the marker and the distance to BEG."
   (setq org-markers-to-move nil))
 
 (defun org-narrow-to-subtree (&optional element)
-  "Narrow buffer to the current subtree."
+  "Narrow buffer to the current subtree.
+Use the command `\\[widen]' to see the whole buffer again."
   (interactive)
   (if (org-element--cache-active-p)
       (let* ((heading (org-element-lineage
@@ -7242,7 +7243,8 @@ If yes, remember the marker and the distance to BEG."
 	         (point))))))))
 
 (defun org-toggle-narrow-to-subtree ()
-  "Narrow to the subtree at point or widen a narrowed buffer."
+  "Narrow to the subtree at point or widen a narrowed buffer.
+Use the command `\\[widen]' to see the whole buffer again."
   (interactive)
   (if (buffer-narrowed-p)
       (progn (widen) (message "Buffer widen"))
@@ -7250,7 +7252,8 @@ If yes, remember the marker and the distance to BEG."
     (message "Buffer narrowed to current subtree")))
 
 (defun org-narrow-to-block ()
-  "Narrow buffer to the current block."
+  "Narrow buffer to the current block.
+Use the command `\\[widen]' to see the whole buffer again."
   (interactive)
   (let* ((case-fold-search t)
 	 (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*"
@@ -21162,7 +21165,8 @@ ones already marked."
 	(goto-char (org-element-property :begin element))))))
 
 (defun org-narrow-to-element ()
-  "Narrow buffer to current element."
+  "Narrow buffer to current element.
+Use the command `\\[widen]' to see the whole buffer again."
   (interactive)
   (let ((elem (org-element-at-point)))
     (cond
-- 
2.30.2

Re: [PATCH] Explain how to end a buffer narrowing.

[Ihor Radchenko]

yuvallangerontheroad <yuvallangerontheroad@proton.me> writes:

> Please review.

Thanks!
Applied onto main with a small amendment to the commit message.
I added ":" after the changelog description term.

https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=c4de06ce1

You are now also listed as Org contributor.
https://git.sr.ht/~bzg/worg/commit/2ea3051b

-- 
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>