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

[Ihor Radchenko]

yuvallangerontheroad  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 .
Support Org development at ,
or support my work at 

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

[yuvallangerontheroad]

On Saturday, November 26th, 2022 at 04:26, Ihor Radchenko  
wrote:


> yuvallangerontheroad yuvallangeronther...@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.From f53b141bd2057898f2606e884cf1a094876696c2 Mon Sep 17 00:00:00 2001
From: Yuval Langer 
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  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 .
Support Org development at ,
or support my work at 

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

[yuvallangerontheroad]

On Friday, November 25th, 2022 at 16:52, Ihor Radchenko  
wrote:


> yuvallangerontheroad yuvallangeronther...@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.From 2c5a5fa3cdb06390d3c20a47c97720074a1af507 Mon Sep 17 00:00:00 2001
From: Yuval Langer 
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  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 .
Support Org development at ,
or support my work at 

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

[yuvallangerontheroad]

On Friday, November 25th, 2022 at 16:32, Ihor Radchenko  
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.From 5e0bef6c7e288191d9b7d2517fda29718e47baad Mon Sep 17 00:00:00 2001
From: Yuval Langer 
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  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  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 .
Support Org development at ,
or support my work at 

[PATCH] Explain how to end a buffer narrowing.

[yuvallangerontheroad]

I have added information on how to exit a narrowing. I could have used this 
information when I started using org-narrow-to-subtree.From 680fbfc0a91552c5d73e853effadeaa683266ec9 Mon Sep 17 00:00:00 2001
From: Yuval Langer 
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  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  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  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  to see the whole buffer again."
   (interactive)
   (let ((elem (org-element-at-point)))
 (cond
-- 
2.30.2