Ihor Radchenko <[email protected]> writes:
> "J.D. Smith" <[email protected]> writes:
> I think we can slowly move to the code review.
Before we go full-on there, I forgot one more thing - comparison with
org-appear.
There are few good points missed that org-appear does.
The most important missing features in org-inside are:
1. sub/superscript support
2. org-hidden-keywords support
3. hiding in pre-command hook, so that things like fill-paragraph are
not affected by cursor position
4. (maybe) delayed appearance change
Disclosure: I am not familiar with org-appear, so I tasked LLM with
reviewing the codes. Below is the original full report on the
differences:
What org-appear has that org-inside does not
1. Subscript/superscript marker toggling
=org-appear-autosubmarkers= toggles the curly-brace markers around
subscripts and superscripts (e.g., =_{text}= ↔ rendered
subscript). Controlled by =org-pretty-entities=.
org-inside's =org-inside--hidden-contents-types= only covers emphasis
types (=bold code italic verbatim underline strike-through=) and
links. Sub/superscripts are never added to the list.
2. Entity toggling
=org-appear-autoentities= toggles Org entities like =\alpha=, =\to=,
etc. -- it calls =decompose-region= to show the raw TeX-like source and
=compose-region= to restore the UTF-8 glyph. Controlled by
=org-pretty-entities=.
org-inside has no entity handling at all.
3. Keyword toggling
=org-appear-autokeywords= toggles visibility of keywords listed in
=org-hidden-keywords= (e.g., =#+TITLE:=, =#+AUTHOR:=). It removes/adds
the =invisible= and =org-link= text properties on the keyword region.
org-inside does not handle hidden keywords; its type list in
=org-inside--hidden-contents-types= only includes emphasis and links.
4. LaTeX fragment support
=org-appear-inside-latex= applies toggling inside LaTeX fragments and
environments. When enabled, sub/superscript markers and entities are
toggled within =latex-fragment= and =latex-environment= element types.
org-inside does not handle LaTeX fragments or environments at all.
5. Configurable delay
=org-appear-delay= (default =0.0=) introduces an idle-timer delay before
showing hidden markers. The timer is cancelled if the cursor moves away
before it fires. Useful for reducing visual noise during rapid
navigation.
org-inside uses cursor-sensor-functions, which fire instantaneously on
entry/exit. No delay mechanism exists.
6. Trigger modes
=org-appear-trigger= offers three modes:
- =always= -- toggle on every cursor movement (default)
- =on-change= -- toggle only when the buffer is modified or the element is
clicked
- =manual= -- toggle only when
=org-appear-manual-start=/=org-appear-manual-stop= are called
org-inside has a single, always-on behavior via cursor-sensor. The only
manual control is =org-inside-toggle-hidden= (on =C-c C-c=), which
toggles unhiding for the current entity.
7. =manual-linger= option
=org-appear-manual-linger= controls whether elements stay visible after
=org-appear-manual-stop=. When nil (default), elements are re-hidden
immediately on stop.
No equivalent in org-inside.
8. =just-brackets= link mode
=org-appear-autolinks= can be set to the symbol =just-brackets=, which
reveals only the =[[= and =]]= brackets around descriptive links without
showing the URL portion. This is a third visibility state beyond "fully
hidden" and "fully shown."
org-inside's link handling is binary: the link region is either inside
or outside; there is no partial reveal.
9. Evil-mode integration pattern
org-appear has a documented evil-mode integration pattern using the
=manual= trigger:
#+begin_src emacs-lisp
(setq org-appear-trigger 'manual)
(add-hook 'org-mode-hook
(lambda ()
(add-hook 'evil-insert-state-entry-hook #'org-appear-manual-start nil t)
(add-hook 'evil-insert-state-exit-hook #'org-appear-manual-stop nil t)))
#+end_src
org-inside has no equivalent pattern or documentation for modal editing
integration.
10. Pre-command hook for specific commands
org-appear's =pre-command-hook= hides elements before
=org-fill-paragraph= and =org-ctrl-c-ctrl-c= execute, because these
commands depend on column positions and would misbehave if hidden
markers were temporarily visible.
org-inside has no =pre-command-hook= and does not hide elements before
any commands. It relies on the cursor-sensor firing when point moves,
but commands that modify text at point without moving the cursor could
interact differently.
--
Ihor Radchenko // yantar92,
Org mode maintainer,
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>
