branch: externals/org-modern
commit a462be576ced8405a70116863bbca7c05dc19957
Author: JD Smith <[email protected]>
Commit: JD Smith <[email protected]>
Merge org-modern-indent README and ChangeLog into org-modern's
---
CHANGELOG.org | 31 +++++++++++++++++++++++++++++
README.org | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----
2 files changed, 91 insertions(+), 4 deletions(-)
diff --git a/CHANGELOG.org b/CHANGELOG.org
index 3cf6b87f3e..359dede5ef 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -69,3 +69,34 @@
* Version 0.8 (2023-02-15)
- Start of changelog.
+
+* org-modern-indent change history
+
+~org-modern-indent~ was incorporated as an extension to ~org-modern~ in v2.0.
The prior change history for ~org-modern-indent~ is as follows, based on its
release versions as a separate package:
+
+- **v0.6**: Merged as an ~org-modern~ extension.
+- **v0.5.1**: Small simplifications for block drawing.
+- **v0.5**: Another complete rewrite which substantially improves
+ performance and accuracy. Now block detection uses ~org-element~
+ and the block styling is implemented in
+ ~before/after-change-functions~. Benefits include:
+ 1. Higher performance and more reliable fontification.
+ 2. Ability to detect and correctly treat _damaged_ blocks
+ (header/footer line altered or removed) as well as _merged_ blocks.
+ 2. Caches all prefix strings for lower memory usage/GC churn.
+ 3. No more "runaway" formatting when partial blocks are created:
+ only _real_ blocks (according to ~org-element~) are
+
+ Note that v0.5 implements indented block styling using display
+ properties on the indentation text, so navigation will "skip over"
+ it.
+- **v0.1**: features a complete re-write to use font-lock directly. This
+ has a few benefits:
+ 1. No longer relies on org-mode face names for recognizing
+ blocks, so ~org-src-block-faces~ can have arbitrary faces
+ applied, e.g. for different ~src~ languages, as in the screenshot.
+ 2. Eliminates the "race" between font-locking and applying the prefix text
properties.
+ 3. Enables in-text bracket decorations for "bulk-indented" blocks, for
example blocks situated
+ in an arbitrarily-nested plain list item.
+
+
diff --git a/README.org b/README.org
index e450926b55..fadd3652ae 100644
--- a/README.org
+++ b/README.org
@@ -22,9 +22,7 @@ syntax element individually via the =org-modern=
customization group.
[[https://github.com/minad/org-modern/blob/screenshots/example.gif?raw=true]]
The screenshots shows [[file:example.org][example.org]] with =org-modern-mode=
turned on and off. The
-elegant theme featured in the screenshot is
[[https://protesilaos.com/emacs/modus-themes][modus-operandi]]. Since version
2.0,
-this package incorporates ~org-modern-indent~; see [[./README-indent.md][its
README]] for more information
-and a screenshot.
+elegant theme featured in the screenshot is
[[https://protesilaos.com/emacs/modus-themes][modus-operandi]].
Since this package adjusts text styling, it depends on your font settings. You
should ensure that your =variable-pitch= and =fixed-pitch= fonts combine
@@ -122,12 +120,70 @@ An alternative setup, using ~use-package~:
(org-agenda-finalize . org-modern-agenda))
#+end_src
+
+* Indent
+
+Since version 2.0, this package incorporates ~org-modern-indent~, which
provides block bracket styling when ~org-indent~ is enabled, including support
for "bulk-indented" blocks nested within plain lists:
+
+https://github.com/user-attachments/assets/7ca42ce7-dcfb-4c66-b5f4-1798a4fd4df5
+
+*Note*: non-nil ~line-spacing~ is not recommended with ~org-modern-indent~, as
it leads to gaps in the vertical bars drawn to indicate blocks.
+
* Incompatibilities
- =org-num-mode= interferes with the =org-modern= prettification of TODO
keywords.
- =visual-wrap-prefix-mode= relies on the =wrap-prefix= text property which is
also
used by =org-modern=.
+* Indentation Hints
+
+A few hints for managing indented blocks.
+
+** Bulk-indented blocks (e.g. within plain lists):
+
+Bulk-indented blocks have "real" (space/tab) indentation applied and managed
by org. This extra indentation is applied by org on _top_ of the (fake,
prefix-based) indentation used by org-indent. To nest blocks properly within
such indented content, e.g. in plain list items, you only have to begin the
~#+begin~ at the same level as the list element's text.
+
+As an important principle, ~org-modern-indent~ does not alter the contents of
the text in your org documents, not even indentation. It just styles what is
there. To help achieve proper block bulk-indented alignment, here are a few
ways to alter blocks indentation using org and other commands:
+
+- **Start things right**: Hit return after your last line of text (e.g in a
list item), then immediately hit =C-c C,= to create the desired block. It will
be indented at the right level:
+
+ #+begin_src org
+ - This list item contains a:
+ - sublist, which holds a block:
+ [C-c C-,] here
+ #+end_src
+
+- **Move flush left**: Note: =M-{= will get you to the start of a block
quickly. =M-\= at block start will move the block's first header line to
column 0. Then =M-S-left= (or =right=) will indent the full block.
+- **Indent rigidly**: =M-h= selects the entire block. Then =C-x TAB= enters
"rigid indent" mode, after which left/right moves the entire block.
+- **Re-indent a block**: If you have a block that is partially aligned,
perhaps with a "hanging end", like so:
+
+ #+begin_src org
+
+ - List 1
+ - List 2
+ ,#+begin_src lang
+ foo_lang(x)
+ ,#+end_src
+ #+end_src
+
+ you can simply use =M-S-left/right= at block start (or in fact anywhere on
the block header/footer) to ~org-indent-block~. Note that
~org-src-preserve-indentation=nil~ is an important setting, to allow org to
(re-)indent blocks to respect the local indentation inside list and other
elements. Also note that (from ~org-indent-region~):
+
+ #+begin_quote
+ The function will not indent contents of example blocks, verse blocks and
export blocks as leading white spaces are assumed to be significant there.
+ #+end_quote
+
+** Font spacing and faces
+
+The default ~fixed-pitch~ font (from which ~org-meta-line~ inherits) has line
spacing >1.0 on some systems. This will introduce gaps _even if your default
font is changed_, and ~line-space~ is nil. To correct it, add:
+
+#+begin_src emacs-lisp
+(set-face-attribute 'fixed-pitch nil :family "Hack" :height 1.0) ; or whatever
font family
+#+end_src
+
+### The bracket style
+
+If you'd like a different face than ~org-meta-line~ for the "bracket",
configure the ~org-modern-indent-bracket-line~ face.
+
* Alternatives
The tag style of =org-modern= is inspired by Nicholas Rougier's
[[https://github.com/rougier/svg-tag-mode][svg-tag-mode]]. In
@@ -143,7 +199,7 @@ table and block styling from =org-modern=. If you are
interested in further
tweaks, Emacs comes with the builtin =prettify-symbols-mode= which can be used
for
individual styling of custom keywords.
-Alternatives are the older =org-superstar= and =org-bullets= packages, which
are
+Alternatives are the older
[[https://github.com/integral-dw/org-superstar-mode][=org-superstar=]] and
[[https://github.com/sabof/org-bullets][=org-bullets=]] packages, which are
more limited and mainly adjust headlines and lists. =org-superstar= relies on
character composition, while =org-modern= uses text properties, which are
considered more future-proof. Note that =org-modern= is a full replacement for
