Have you ever wondered how org-mode toggles the visibility of headings?

Now if we evaluate the variable buffer-invisibility-spec, we should get t (the default) in the echo area.

If not, we set this variable to t like this:

(setq buffer-invisibility-spec t)

Now, we make an overlay "on top" of XXXXXX (from point 1 to point 7 in the buffer) that we assign to the variable ov-x using make-overlay:

(setq ov-x (make-overlay 1 7))

and we see the following in the echo area:

#<overlay from 1 to 7 in *invisible*>

Now, by setting the property invisible of the overlay ov-x to t using the function overlay-put like this

(overlay-put ov-x 'invisible t)

we make the characters XXXXXX disappear.

This is due to the value of buffer-invisibility-spec equal to t (the default) which means that text is invisible if it has a non-nil invisible (text or overlay) property.

Now, evaluating the following s-exp sets invisible property of the overlay ov-x to nil

(overlay-put ov-x 'invisible nil)

makes the characters XXXXXX to reappear in the buffer *invisible*.

We also could have removed the overlay ov-x to make the characters XXXXXX to reappear. Let's see how.

First, as previously, we set the invisible property of the overlay ov-x to t to make the characters XXXXXX to disappear:

(overlay-put ov-x 'invisible t)

Then, instead of setting back the invisible overlay property to nil of ov-x we remove it. To do so, we use the function remove-overlays that let you remove all the overlays in a range of the buffer that have a specific property set to some value (in our case the property invisible set to t in the range 1 to 7 of the buffer).

So evaluating the following s-exp:

(remove-overlays 1 7 'invisible t)

removes the overlay ov-x in the buffer *invisible* and make the characters XXXXXX to reappear.

As we removed the overlay ov-x, we redefined it as previously by evaluating the following s-exp:

(setq ov-x (make-overlay 1 7))

Let's set buffer-invisibility-spec to nil:

(setq buffer-invisibility-spec nil)

Then, by evaluating the following s-exp, we expect the characters XXXXXX to disappear:

(overlay-put ov-x 'invisible t)

BUT they don't.

This is normal, as we've just set buffer-invisibility-spec to nil, we've "disabled" the invisibility feature in the buffer *invisible*.

Now, we restore the invisible property of the overlay ov-x so as not to interfere with the next example by evaluating:

(overlay-put ov-x 'invisible nil)

Let's add the characters YYYYYY after the characters XXXXXX with 3 dashes --- in between such that the buffer *invisible* is now:

XXXXXX---YYYYYY

Now, we make an overlay "on top" of YYYYYY (from point 10 to point 16 in the buffer) that we assign to the variable ov-y using make-overlay:

(setq ov-y (make-overlay 10 16))

We set back buffer-invisibility-spec to t (the default):

(setq buffer-invisibility-spec t)

Then we add the list (foo) to the variable buffer-invisibility-spec using the function add-to-invisibility-spec as follow:

(add-to-invisibility-spec '(foo))

Now, the value of buffer-invisibility-spec is ((foo) t).

This implies that, now to make a part of the buffer invisible, the invisible property must be foo or t. Before, it could have been any value that is non-nil.

This way we can toggle the visibility of some parts of the buffer while other parts remain invisible (see org-toggle-link-display for instance).

Let's make XXXXXX disappear "permanently" by setting the invisible property of ov-x to t:

(overlay-put ov-x 'invisible t)

The characters XXXXXX disappear and the buffer *invisible* is now:

---YYYYYY

Now, we set the invisible property of ov-y to be equal to foo:

(overlay-put ov-y 'invisible 'foo)

The characters YYYYYY disappear and the buffer *invisible* is now:

---

Now, what we can do is to make YYYYYY appears again by removing (foo) from the invisibility spec buffer-invisibility-spec while the characters XXXXXX stay invisible:

(remove-from-invisibility-spec '(foo))

Now, the buffer *invisible* is:

---YYYYYY

Note that:

1. the overlay ov-x still has its property invisible equal to t and,

2. the overlay ov-y still has its property invisible equal to foo.

You can verify it by evaluating the following s-exp:

(overlay-get ov-x 'invisible) ; t
(overlay-get ov-y 'invisible) ; foo

If the variable buffer-invisibility-spec as a list contains a cons (foo . t), every continuous part of the buffer with the invisible property set to foo is replaced by ellipsis which are by default ....

The buffer *invisible* still contains the characters XXXXXX---YYYYYY, but maybe not all the characters are visible. So let's put our buffer in an appropriate state for this section.

We removes all the overlays in the buffer (which makes all the content of the buffer visible again). We redifined the ov-x and ov-y as previously (same part of the buffer (1 to 7) and (10 to 16)). And we set buffer-invisibility-spec to be ((foo . t) t). We can do this by evaluating the following expression (in the minibuffer with point in the buffer *invisible*):

(progn
  (remove-overlays)
  (setq ov-x (make-overlay 1 7))
  (setq ov-y (make-overlay 10 16))
  (setq buffer-invisibility-spec t)
  (add-to-invisibility-spec '(foo . t)))

The buffer *invisible* is now:

XXXXXX---YYYYYY

By evaluating the following s-exp, we set the invisible property of the overlay ov-y to foo

(overlay-put ov-y 'invisible 'foo)

and this replaces (visually not the content of the buffer) the characters YYYYYY by the default ellipsis ... and the buffer *invisible* looks like this:

XXXXXX---...

We assume with the buffer *invisible* is in the same state as in the previous section.

Our goal in this section is to modify the default ellipsis ....

To do so we:

1. create a display table with the function make-display-table,

2. we set its special slot 4 (responsible of the display of the ellipsis) which must be a vector of glyph using the function set-display-table-slot,

3. we set the variable buffer-display-table of the buffer *invisible* to be this new display table,

4. we observe the appearance of the buffer *invisible*.

So by evaluating the following s-exp:

(let ((tbl (make-display-table))
      (glyph-vector
       (vector (make-glyph-code ?\ 'font-lock-warning-face)
               (make-glyph-code ?\; 'font-lock-warning-face)
               (make-glyph-code ?- 'font-lock-warning-face)
               (make-glyph-code ?\) 'font-lock-warning-face))))
  (set-display-table-slot tbl 4 glyph-vector)
  (setq buffer-display-table tbl))

the buffer *invisible* should looks like this (if the invisible property of the overlay ov-y is still equal to foo):

XXXXXX--- ;-)

You can read more about character display and display table in the manual (elisp#Character Display).

WE ARE DONE :-)