Re: [PATCH 1] lisp/org-fold.el: Fold header lines in blocks (was: Proposal: folding stacked `#+header:' lines in src blocks)

[Ihor Radchenko]

h...@heagren.com writes:

> Great! I've worked up a patch (well, two patches), attached.
>
> Some details of the implementation:
> - folding blocks now cycles:
>- everything folded (only top header line visible if present,
>  otherwise only `#+begin' line visible).
>- all content visible, (header stack folded, top header visible,
>  `#+begin' and `#+end' lines visible).
>- everything visible
>- (the second and third are treated as equivalent unless there is
>  more than one header line.)

This logic does not really belong to org-fold.el. Rather to
org-cycle.el(org-cycle). Ideally, we need to split `org-cycle' into
smaller functions.

Also, changing default toggle behaviour may break third-party usage.
People now expect flipping between folded/unfolded. Your patch will
change that.

> - renames `org-fold--hide-wrapper-toggle' to
>`org-fold--hide-wrapper-cycle', which seemed more appropriate under
>the circumstances.

Please, no. As I said above, we need to move the cycling logic to
org-cycle. `org-fold--hide-wrapper-toggle' may only be modified to
accept a new value of FORCE other than 'off.

> Some less-than-perfections:
> - I'm not sure what to do about default block folding (as in, how
>blocks are folded when a file is first visited). First, I don't have
>a complete list of things (variables, startup options, etc.) which
>affect it. Secondly, I'm not sure what the behaviour should be now
>that blocks can be in up to three folding states. Advice would be
>appreciated.

We may define default folding state at startup via defcustom.

> - I'm not sure what other documentation I should add. Once this patch
>is stable and people approve of it, I can add a news entry. Should I
>update the manual at all?

Yes. For example, 2.8 Blocks section of the manual. But let's decide
about implementation first. Manual if the last thing to do.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

[PATCH 1] lisp/org-fold.el: Fold header lines in blocks (was: Proposal: folding stacked `#+header:' lines in src blocks)

[hugo]

On 2022-12-07 19:58, Thomas S. Dye wrote:

I would use this feature.  My stack typically includes headers, a
name, and a caption.  It would be nice to fold them all out of sight.


Great! I've worked up a patch (well, two patches), attached.

Some details of the implementation:
- folding blocks now cycles:
  - everything folded (only top header line visible if present,
otherwise only `#+begin' line visible).
  - all content visible, (header stack folded, top header visible,
`#+begin' and `#+end' lines visible).
  - everything visible
  - (the second and third are treated as equivalent unless there is
more than one header line.)
- Folding will happen on pressing  (or whatever you have bound)
  with point:
  - anywhere on the `#+begin' or `#+end' line
  - on any header keyword (`#+name:', `#+header', etc.)
  - anywhere else in the header stack where completion does not
otherwise kick in (not quite sure of the exact mechanics on this
one, might be dependant on one's configuration)? This includes
part-way through header lines.
  - This seemed to me the most comfortable configuration for use.
- Retain the old behaviour of moving point to the beginning of the
  remaining visible lines when point is hidden by folding.
- renames `org-fold--hide-wrapper-toggle' to
  `org-fold--hide-wrapper-cycle', which seemed more appropriate under
  the circumstances.
- All the tests in testing/lisp/test-org-fold.el pass for me.

Some less-than-perfections:
- I'm not sure what to do about default block folding (as in, how
  blocks are folded when a file is first visited). First, I don't have
  a complete list of things (variables, startup options, etc.) which
  affect it. Secondly, I'm not sure what the behaviour should be now
  that blocks can be in up to three folding states. Advice would be
  appreciated.
- I'm not sure what other documentation I should add. Once this patch
  is stable and people approve of it, I can add a news entry. Should I
  update the manual at all?

Hope this is useful!

HugoFrom 04186df871b94d4a961a5193a7cb050f2a4bc2ff Mon Sep 17 00:00:00 2001
From: Hugo Heagren 
Date: Mon, 12 Dec 2022 11:30:10 +
Subject: [PATCH 2/2] lisp/org-fold.el: Rename `org-fold--hide-wrapper-toggle'
 to `org-fold--hide-wrapper-cycle'

* lisp/org-fold.el: rename
(org-fold--hide-wrapper-toggle): Rename to
`org-fold--hide-wrapper-cycle'.
(org-fold-hide-block-toggle, org-fold-hide-drawer-toggle): Replace old
function name with new.
---
 lisp/org-fold.el | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lisp/org-fold.el b/lisp/org-fold.el
index 21cdc6fad..37e6d6450 100644
--- a/lisp/org-fold.el
+++ b/lisp/org-fold.el
@@ -477,7 +477,7 @@ heading to appear."
 
 ; Blocks and drawers visibility
 
-(defun org-fold--hide-wrapper-toggle (element category force no-error)
+(defun org-fold--hide-wrapper-cycle (element category force no-error)
   "Cycle visibility for ELEMENT.
 
 ELEMENT is a block or drawer type parsed element.  CATEGORY is
@@ -579,7 +579,7 @@ ELEMENT is provided, consider it instead of the current block.
 
 Return a non-nil value when toggling is successful."
   (interactive)
-  (org-fold--hide-wrapper-toggle
+  (org-fold--hide-wrapper-cycle
(or element (org-element-at-point)) 'block force no-error))
 
 (defun org-fold-hide-drawer-toggle ( force no-error element)
@@ -592,7 +592,7 @@ ELEMENT is provided, consider it instead of the current drawer.
 
 Return a non-nil value when toggling is successful."
   (interactive)
-  (org-fold--hide-wrapper-toggle
+  (org-fold--hide-wrapper-cycle
(or element (org-element-at-point)) 'drawer force no-error))
 
 (defun org-fold-hide-block-all ()
-- 
2.20.1

From 62ef11504f361d058c5425ad5e1184be6e19bd6f Mon Sep 17 00:00:00 2001
From: Hugo Heagren 
Date: Mon, 12 Dec 2022 11:25:14 +
Subject: [PATCH 1/2] lisp/org-fold.el: Fold header lines in blocks

* lisp/org-fold.el (org-fold--hide-wrapper-toggle): Cycle blocks
between three folding states, potentially including headers in
folding.  Update docstring accordingly.
---
 lisp/org-fold.el | 65 +++-
 1 file changed, 53 insertions(+), 12 deletions(-)

diff --git a/lisp/org-fold.el b/lisp/org-fold.el
index 05ac71ea4..21cdc6fad 100644
--- a/lisp/org-fold.el
+++ b/lisp/org-fold.el
@@ -478,14 +478,27 @@ heading to appear."
 ; Blocks and drawers visibility
 
 (defun org-fold--hide-wrapper-toggle (element category force no-error)
-  "Toggle visibility for ELEMENT.
+  "Cycle visibility for ELEMENT.
 
 ELEMENT is a block or drawer type parsed element.  CATEGORY is
 either `block' or `drawer'.  When FORCE is `off', show the block
 or drawer.  If it is non-nil, hide it unconditionally.  Throw an
 error when not at a block or drawer, unless NO-ERROR is non-nil.
 
-Return a non-nil value when toggling is successful."
+A property drawer will cycle between open and closed states.
+
+A block with not extra header arguments (lines beginning

Re: Proposal: folding stacked `#+header:' lines in src blocks

[Thomas S. Dye]

h...@heagren.com writes:

First question: what do people think of this, do people support 
this as

an idea?


I would use this feature.  My stack typically includes headers, a 
name, and a caption.  It would be nice to fold them all out of 
sight.


All the best,
Tom

--
Thomas S. Dye
https://tsdye.online/tsdye

Proposal: folding stacked `#+header:' lines in src blocks

[hugo]

Sometimes I deal with large blocks (generally src blocks) with a lot of
header arguments. To deal with this, I stack them up in `#+header:'
lines. Real example from a file I have:

,
| #+header: :results (if (org-export-derived-backend-p 
org-export-current-backend 'latex) "latex" "file raw")
| #+header: :file (if (org-export-derived-backend-p 
org-export-current-backend 'latex) nil "foo.png")

| #+header: :packages '((nil "tikz" t))
| #+header: :imagemagick t :fit t
| #+header: :headers '("\\usetikzlibrary{calc,positioning,patterns}")
| #+begin_src latex
|   
| #+end_src
`

This is fine, but the height of the header lines often rather gets in
the way when I'm working (once I've written them out, or expanded them
from a snippet, I don't want to see them again).

Thus, I propose that stacked `#+header:' line on top of blocks be
foldable. I'm thinking of this as roughly analagous to folding property
drawers under headlines. That is:
- the header stack should be foldable independently of the block's
  content. That is, I should be able to fold up my stack of five header
  lines into one line, without folding my block.
- the header lines should be folded by default when the block is folded
- there should be a variable (corresponding to
  `org-cycle-hide-drawer-startup') controlling wether the header stacks
  are shown on startup or not.
- /unlike/ property drawer folding, I think it would be good if hitting
   repeatedly cycled the block through three states:
  - everything unfolded
  - header folded and content open
  - everything folded.

First question: what do people think of this, do people support this as
an idea?

If so, second question: I think this would be implemented by altering
`org-fold--hide-wrapper-toggle' to treat blocks specially with a cyclic
folding system. Is this right?

If other people think this is a good idea, and that's roughly the way to
go, I'll try to make a patch at some point.

Any thoughts welcome!

Hugo