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

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
|   <tikz stuff here>
| #+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
   <tab> 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

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

[Thomas S. Dye]

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

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

[hugo]

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

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 <tab> (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!

Hugo

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-lisp-org-fold.el-Rename-org-fold-hide-wrapper-toggle.patch --]
[-- Type: text/x-diff; name=0002-lisp-org-fold.el-Rename-org-fold-hide-wrapper-toggle.patch, Size: 1692 bytes --]

From 04186df871b94d4a961a5193a7cb050f2a4bc2ff Mon Sep 17 00:00:00 2001
From: Hugo Heagren <hugo@heagren.com>
Date: Mon, 12 Dec 2022 11:30:10 +0000
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 (&optional 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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0001-lisp-org-fold.el-Fold-header-lines-in-blocks.patch --]
[-- Type: text/x-diff; name=0001-lisp-org-fold.el-Fold-header-lines-in-blocks.patch, Size: 5403 bytes --]

From 62ef11504f361d058c5425ad5e1184be6e19bd6f Mon Sep 17 00:00:00 2001
From: Hugo Heagren <hugo@heagren.com>
Date: Mon, 12 Dec 2022 11:25:14 +0000
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
+`#+header:', `#+name:' etc. directly above it) will cycle between
+open and closed states.  A block with such headers will cycle:
+- everything closed (with only the top header visible)
+- header stack folded (top header visible, other headers hidden, body
+  and content of block visible)
+- everything open
+
+When there is only one header argument, no distinction is made
+between the the second and third states.
+
+Return a non-nil value when cycling is successful."
   (let ((type (org-element-type element)))
     (cond
      ((memq type
@@ -495,28 +508,56 @@ Return a non-nil value when toggling is successful."
                         comment-block dynamic-block example-block export-block
                         quote-block special-block src-block verse-block))
               (_ (error "Unknown category: %S" category))))
-      (let* ((post (org-element-property :post-affiliated element))
+      (let* ((post (org-element-property :post-affiliated element)) ; bol of begin_x
+             (begin (org-element-property :begin element))          ; bol of first header
+             (content-begin                                         ; bol of block content
+              (1+ (save-excursion (goto-char post) (line-end-position))))
+             (state
+              (cond
+               ;; Everything is folded
+               ((org-fold-folded-p content-begin 'block) 'all)
+               ;; Everything is open
+               (t 'nothing)))
              (start (save-excursion
-                      (goto-char post)
+                      (goto-char
+                       (if (equal category 'block)
+                           (pcase state
+                             ;; If there are no headers, start unfolding
+                             ;; from the char before the char at bol
+                             ;; of `begin_x', so that `begin_x' is
+                             ;; displayed after unfolding. Otherwise
+                             ;; begin unfolding from bol of that line.
+                             ('all (if (= post begin) post (1- post)))
+                             ('nothing begin))
+                         post))
                       (line-end-position)))
              (end (save-excursion
-                    (goto-char (org-element-property :end element))
+                    (goto-char
+                     (if (equal category 'block)
+                         (pcase state
+                           ('all (org-element-property :end element))
+                           ('nothing (org-element-property :end element)))
+                       (org-element-property :end element)))
                     (skip-chars-backward " \t\n")
                     (line-end-position))))
         ;; Do nothing when not before or at the block opening line or
         ;; at the block closing line.
         (unless (let ((eol (line-end-position)))
-                  (and (> eol start) (/= eol end)))
+                  (and (> eol content-begin) (/= eol end)))
           (org-fold-region start end
-                   (cond ((eq force 'off) nil)
-                         (force t)
-                         ((org-fold-folded-p start category) nil)
-                         (t t))
-                   category)
+                           (cond ((eq force 'off) nil)
+                                 (force t)
+                                 ((org-fold-folded-p start category) nil)
+                                 (t t))
+                           category)
           ;; When the block is hidden away, make sure point is left in
           ;; a visible part of the buffer.
           (when (invisible-p (max (1- (point)) (point-min)))
-            (goto-char post))
+            ;; The only state transition which hides point is from
+            ;; everything open to everything folded. In this case, the
+            ;; best place to leave point is at bol of first visible
+            ;; line, which is `begin'.
+            (goto-char begin))
           ;; Signal success.
           t)))
      (no-error nil)
-- 
2.20.1

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

[Ihor Radchenko]

hugo@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 <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>