[feature] Consistent fixed indentation of headline data
Hi everybody,
I'm using org-mode for a long time, and I never understood quite well
how headline data were supposed to be indented, however I was happy with
what emerged to me as the default of 2 spaces (with my emacs and
org-mode version at the time). I recently updated my old emacs to
=9.5.3=, and what I thought was a default indentation was removed.
Suddenly, I had no indentation at all for these headline-data and this
bugged me.
I went through documentation, and code, and (re-)discovered
`org-adapt-indentation' that was nil in my case and is intended to stay
this way as far as I am concerned : I'm looking for a fixed indentation
whatever the depth of my outlines.
I'm far from sure it was a default one day, but sure it was at least
suggested/enforced in my workflow with my emacs at some time. And even
if it didn't feel like it was clad in iron, it seems I'm not the only
one who was using that as I can find some examples remaining in the
current 'testing/examples' org files.
This indentation concerns only what is called "headline data" in the
documentation of `org-adapt-indentation'. To be precise: schedules
("SCHEDULE:", "DEADLINE:"...), clock drawer (":LOGBOOK:..."), property
drawer (":PROPERTY:..."). These are "data" appearing after the headline
as I understand them.
If I'm a user of org-mode, I'm fairly new in the emacs lisp and hacking
community and I need to know:
- if my proposal is useful and has any chance to be accepted,
- if there are any pitfalls I delved into in matter of coding,
conventions, ...
- if it make sense for others to include this,
Many thanks !
From 54ee0ce45c4a0c31a8a701047d4d56c1592fb5bb Mon Sep 17 00:00:00 2001
From: Valentin Lab
Date: Fri, 1 Jul 2022 14:03:41 +0200
Subject: [PATCH] org-el: Add fixed indentation of headline data
* lisp/org.el (org-headline-data-fixed-indent-level): Definition of
new customizable variable and doc.
(org-add-planning-info): When creating planning line, force a
`org-indent-line' to indent it correctly.
(org--get-expected-indentation): If variable
`org-headline-data-fixed-indent-level' is set and line is header,
inform `org-indent-line' to indent from specified amount.
(org-adapt-indentation): Update documentation to mention new
`org-headline-data-fixed-indent-level'.
TINYCHANGE
Signed-off-by: Valentin Lab
---
lisp/org.el | 22 ++-
testing/lisp/test-org.el | 139 +++
2 files changed, 159 insertions(+), 2 deletions(-)
diff --git a/lisp/org.el b/lisp/org.el
index 38a50d231..377a54edd 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1428,7 +1428,8 @@ The following issues are influenced by this variable:
indentation is not changed at all.
- Property drawers and planning information is inserted indented
- when this variable is set. When nil, they will not be indented.
+ when this variable is set. When nil, they will be indented
+ following `org-headline-data-fixed-indent-level'.
- TAB indents a line relative to current level. The lines below
a headline will be indented when this variable is set to t.
@@ -1445,6 +1446,19 @@ time in Emacs."
(const :tag "Do not adapt indentation at all" nil))
:safe (lambda (x) (memq x '(t nil headline-data
+(defcustom org-headline-data-fixed-indent-level nil
+ "Indentation level for org property drawer.
+
+`org-adapt-indentation' need to be set to nil for this value
+to be considered.
+
+Note that this is all about true indentation, by adding and
+removing space characters. See also \"org-indent.el\" which does
+level-dependent indentation in a virtual way, i.e. at display
+time in Emacs."
+ :group 'org-edit-structure
+ :type 'integer)
+
(defvaralias 'org-special-ctrl-a 'org-special-ctrl-a/e)
(defcustom org-special-ctrl-a/e nil
@@ -10060,7 +10074,8 @@ WHAT entry will also be removed."
(eq what 'closed)
nil nil (list org-end-time-was-given
(unless (eolp) (insert " "))
- ts))
+ ts))
+(org-indent-line)
(defvar org-log-note-marker (make-marker)
"Marker pointing at the entry where the note is to be inserted.")
@@ -18371,6 +18386,9 @@ ELEMENT."
;; a footnote definition.
(org--get-expected-indentation
(org-element-property :parent previous) t))
+ ((and (not (eq org-headline-data-fixed-indent-level nil))
+ (memq type '(drawer property-drawer planning node-property clock)))
+ org-headline-data-fixed-indent-level)
;; Otherwise, move to the first non-blank line above.
(t
(beginning-of-line)
diff --git a/testing/lisp/test-org.el b/testing/lisp/test-org.el
index fcf2d0b5f..600d647e4 100644
--- a/testing/lisp/test-org.el
+++ b/t
Re: [feature] Consistent fixed indentation of headline data
Many thanks for your warm welcome, kind review and suggestions.
I do not provide a corrective patch in this email, but it'll come soon
depending on possible other remarks or follow-ups of this email.
On 07/07/2022 12:41, Ihor Radchenko wrote:
Valentin Lab writes:
Note that we rarely change the defaults. This particular change came
after extensive discussion:
https://orgmode.org/list/878s4x3bwh@gnu.org
Also, it has been documented in https://orgmode.org/Changes.html
I recommend reviewing the changes every time you update Org to new
version.
These links are very informative and give me much more insight on the
current situation. Sorry if I didn't know how to get this info by
myself. I've read the full thread you've linked.
Note that introducing a new customization should be documented in
etc/ORG-NEWS file and probably also in the manual (17.4.2 Hard
indentation).
Yes, I was aware of that, but didn't want to spend to much time if my
contribution was deemed not pertinent.
Also, I am not sure if we really need a new custom variable. We already
have many. What about simply allowing an integer value of
org-adapt-indentation?
Well, my guess was that the "adapt" word in `org-adapt-indentation' was
referring to adaptive (in other words: "changing") indentation depending
on the depth of the outline. It seemed at first un-natural to force a
fixed behavior here. This is why I went with a sub-behavior of when
`org-adapt-indentation' was set to nil, a way to tell that we didn't
want adaptive indentation. It also had the advantage to separate the
implementation and help writing code that would not break the existing
behaviors.
Of course, I'm completely okay to go with your suggestion. Although, I'm
at a lack of inspiration about what would be the best option here:
wouldn't a simple integer as you suggest hide the fact that this will
target only the headline data ? Could we think of more structured value,
perhaps like a cons =(`headline-data . 2)= ? I'm afraid these additions
could be seen as bringing some unwanted complexity.
Although I'm expressing some doubts, I'm ready to implement it using an
integer on `org-adapt-indentation' as you suggest. Just wanted to make
sure it seem sound to everyone before committing to a change that is not
that trivial (well, compared to actual changes).
TINYCHANGE
Signed-off-by: Valentin Lab
Note that your patch is _not_ a tiny change (not <15 LOC).
See https://orgmode.org/worg/org-contribute.html#first-patch and
https://orgmode.org/worg/org-contribute.html#copyright
Would you consider signing the copyright assignment papers with FSF?
Ok, I was not sure about that (counting the actual functional code
change was still under 15LOC, but I guess test counts also). I'm in the
process of signing the copyright assignment papers.
@@ -18371,6 +18386,9 @@ ELEMENT."
;; a footnote definition.
(org--get-expected-indentation
(org-element-property :parent previous) t))
+ ((and (not (eq org-headline-data-fixed-indent-level nil))
+ (memq type '(drawer property-drawer planning node-property clock)))
+ org-headline-data-fixed-indent-level)
;; Otherwise, move to the first non-blank line above.
Why clock? It does not belong to property drawers.
I probably lack some important knowledge here to understand your point.
Here's what I understand: `clock' type targets the 'CLOCK:' keyword (and
not direct timestamps, I added a test to make sure). AFAIK, these
'CLOCK:' lines are made with 'C-c C-x C-i/o' and usually appears in
between a ':LOGBOOK:' drawer. However older implementation of org-mode
did not include these 'CLOCK: ...' lines in logbook drawers. My
intention here, was to make sure that even these orphaned 'CLOCK: ...'
lines, when appearing before any content, would be considered as
headline data, and as such, be indented by the fixed amount.
I definitively consider the logbook (and clock out of logbooks),
property drawer, and planning info ("SCHEDULED", "DEADLINE") as headline
data and are all targeted for indentation. In my code, if I remove
`clock' in the list of types, the intended test about 'CLOCK:' fails...
@@ -1216,6 +1259,13 @@
(org-test-with-temp-text "* H\n:PROPERTIES:\n:key:\n:END:"
(org-indent-region (point-min) (point-max))
(buffer-string)
+ ;; ;; Indent property drawers according to `org-adapt-indentation'.
+ ;; (let ((org-adapt-indentation 'headline-data))
+ ;; (should
+ ;;(equal "* H\n :PROPERTIES:\n :key:\n :END:\n\ncontent2"
+ ;; (org-test-with-temp-text "
