[Orgmode] Re: suggestion: simplify depth stepping of document structure (outline) visibility

[Michael Brand]

Hi all

This is a follow-up to
http://thread.gmane.org/gmane.emacs.orgmode/17581

On 09-10-14 14:24 , I wrote:
> (global-set-key (kbd "C->") 'my-orgstruct-dive)
> (global-set-key (kbd "C-<") 'my-orgstruct-dive-out)
> (defvar my-orgstruct-dive-level 0)

Now I did a rewrite for some improvements, mainly to support dive in
and out of headings also in a variant that leaves the visibility of
siblings. The code is at the end.

Example 1: C-> C-> C-< C-> [...]
This changes only the visibility of of the current heading and leaves
the visibility of siblings, similar to Tab.

Example 2: C-u C-> C-> C-< C-< C-< C-> [...]
This changes the visibility of all headings, similar to S-Tab.

Michael

-----------------------------------------------------------
(global-set-key (kbd "C->") 'my-orgstruct-dive-in)
(global-set-key (kbd "C-<") 'my-orgstruct-dive-out)

(defun my-orgstruct-dive-in (arg)
  "This func is very similar to the func my-orgstruct-dive-out. They are
wrappers to simplify comparison with last-command in my-orgstruct-dive.

Without prefix C-u: Dive in and out the current heading (relative) and leave
the visibility of the siblings, similar to Tab. Having the point before the
first heading in a buffer does not make sense.
Example: `C-> C-> C-< C-> [...]'

With prefix C-u: Dive in and out all headings in the buffer (absolute),
similar to S-Tab. If the point is before the first heading then the behavior
is like if it is on a top level heading.
Example: `C-u C-> C-> C-< C-< C-< C-> [...]'"
  (interactive "P")
  (my-orgstruct-dive arg))

(defun my-orgstruct-dive-out (arg)
  "See the docstring of the very similar func my-orgstruct-dive-in."
  (interactive "P")
  (my-orgstruct-dive arg t))

(defvar my-orgstruct-dive-start-arg nil
  "State variable of func my-orgstruct-dive: The prefix state of the first
invoke of my-orgstruct-dive-in or my-orgstruct-dive-out, see their
docstrings.")

(defvar my-orgstruct-dive-level 1
  "State variable of func my-orgstruct-dive: The reduced level which is the
level of the heading and not necessarily the number of stars if oddeven.
The type of level is relative if my-orgstruct-dive-start-arg is nil, else
absolute. For both types of level the smallest possible value is 1.")

(defun my-orgstruct-dive (arg &optional dive-out)
  "Make visible one heading level more or less.
return value: Undefined.
arg: See the docstring about prefix C-u in func my-orgstruct-dive-in
dive-out: If nil dive in, else dive out."
  ;; determine new level
  (if (or arg  ; let any intermediate `C-u' break the invoke repetition
          (and (not (eq last-command 'my-orgstruct-dive-in))
               (not (eq last-command 'my-orgstruct-dive-out))))
      ;; this is the first invoke of dive
      (progn
        ;; move back to beginning of line with heading:
        ;; - to prepare the point location for possibly hitting some Tabs
        ;;   afterwards
        ;; - to skip list elements, they are not supported do dive in
        ;;   (this alone could also be covered within a save-excursion)
        ;; - for the func org-outline-level that requires beginning of line
        ;;   (this alone could also be covered within a save-excursion)
        (unless (org-before-first-heading-p) (outline-back-to-heading))

        ;; reset start arg and level
        (setq my-orgstruct-dive-start-arg arg)
        (setq my-orgstruct-dive-level
              (if my-orgstruct-dive-start-arg
                  ;; absolute level
                  (if (org-before-first-heading-p)
                      '1
                    (org-reduced-level (org-outline-level)))
                ;; relative level
                '1)))
    ;; this is a repeated invoke of dive: increase/decrease level
    (setq my-orgstruct-dive-level
          (+ my-orgstruct-dive-level (if dive-out '-1 '1)))
    (when (< my-orgstruct-dive-level 1) (setq my-orgstruct-dive-level 1)))

  ;; update heading visibility according to new level
  (if my-orgstruct-dive-start-arg
      ;; absolute level
      (org-shifttab my-orgstruct-dive-level)  ; logs the level itself
    ;; relative level
    (hide-subtree)
    (show-children (* (org-level-increment) (1- my-orgstruct-dive-level)))
    (message "Content view to relative level: %d" my-orgstruct-dive-level))

  ;; move back to beginning of line with heading to prepare
  ;; the point location for possibly hitting some Tabs afterwards
  (unless (org-before-first-heading-p) (outline-back-to-heading)))
-----------------------------------------------------------