Re: [PATCH] org-faq.org: Expand "What is the best setup for indenting?"
Hi Greg, Bastien merged that patch just before I was going to modify it in response to your suggestions. I think, 3 commits is too much noise in git history for the single item in FAQ. However I can to prepare one more correction. Maybe you have got a better idea how to avoid confusion with Org versions in the tables. On 21/05/2021 09:45, Greg Minshall wrote: I have no idea how to express it in a better way. The tables are same for Org >= 9.5 and for Org < 9.5 (modulo bugs in indentation fixed in 9.4.6). Only default configuration evolves in time. again, i apologize. my confusion was in not having read the text to understand that the "(Org >= 9.5)" was the default. i assumed it meant, "this is the behavior for Org >= 9.5", even though that meant the tables really didn't make sense. if you wanted to compensate for such a "user feature" :), maybe remove "(Org >= 9.5)", and add that information as a short "NB:" line after each table? ... sorry, i should have caught *both* "relatively". i'd suggest a. "do not indent anything", "always indent relative to the element above", "indent just ~PROPERTIES/LOGBOOK~ drawers relative to the current heading level" which klings better to my ears. (sadly, i can't explain any grammatical reason why, though.)
Re: [PATCH] org-faq.org: Expand "What is the best setup for indenting?"
Hi Maxim, Maxim Nikulin writes: > Intermediate patch is attached. Applied to worg, thanks! -- Bastien
Re: [PATCH] org-faq.org: Expand "What is the best setup for indenting?"
Maxim, > The patch removed this phrase. sorry about that. > I have no idea how to express it in a better way. The tables are same > for Org >= 9.5 and for Org < 9.5 (modulo bugs in indentation fixed in > 9.4.6). Only default configuration evolves in time. again, i apologize. my confusion was in not having read the text to understand that the "(Org >= 9.5)" was the default. i assumed it meant, "this is the behavior for Org >= 9.5", even though that meant the tables really didn't make sense. if you wanted to compensate for such a "user feature" :), maybe remove "(Org >= 9.5)", and add that information as a short "NB:" line after each table? > Not being a native speaker, I would either leave it as is or would change > all 3 phrases attempting to make their style more uniform. > > a. "do not indent anything", >"always indent relatively to the element above", >"indent just ~PROPERTIES/LOGBOOK~ drawers relatively >to the current heading level" > > b. "no special indentation", >"indentation of all elements is relative to the element above", >"only ~PROPERTIES/LOGBOOK~ drawers get indentation relative >to the current heading level" > sorry, i should have caught *both* "relatively". i'd suggest > a. "do not indent anything", >"always indent relative to the element above", >"indent just ~PROPERTIES/LOGBOOK~ drawers relative >to the current heading level" which klings better to my ears. (sadly, i can't explain any grammatical reason why, though.) cheers, Greg
Re: [PATCH] org-faq.org: Expand "What is the best setup for indenting?"
Thank you for your comments, Greg. On 20/05/2021 01:06, Greg Minshall wrote: > > patches to patches... :) i think these are really just typos, rather > than any useful substantial comment. > > - s/is enable (the default) or not:/is enabled (the default) or not:/ The patch removed this phrase. > - i would suggest separate tables for >= 9.5 and < 9.5. just so the > differences between with/without =electric-indent-mode= are easier to > spot. I have no idea how to express it in a better way. The tables are same for Org >= 9.5 and for Org < 9.5 (modulo bugs in indentation fixed in 9.4.6). Only default configuration evolves in time. 1. Before 9.4. (org-adapt-indentation t) electric-indent-mode disabled. Bugs remained unnoticed. Users were unaware that default configuration assumed indented text aligned to headline title. 2. 9.4. (org-adapt-indentation t) electric-indent-mode enabled. Hot discussions and recommendations to disable electric-indent-mode since even with (org-adapt-indentation headline-data) behavior was strange. 3. Recent changes. Bugs fixed, (org-adapt-indentation nil), so as earlier text is not indented by default. Now absence of indentation is consistent with settings. > - s/C-j anywhere/C-j elsewhere/ (and, iiuc, maybe also the "unadorned" > [C-j] table entry should probably be [C-j elsewhere]?) > > - s/lost formatting/lose formatting/ > > - s/and, that is/and,/ Agree. > - s/always indent relatively/always indent relative/ Not being a native speaker, I would either leave it as is or would change all 3 phrases attempting to make their style more uniform. a. "do not indent anything", "always indent relatively to the element above", "indent just ~PROPERTIES/LOGBOOK~ drawers relatively to the current heading level" b. "no special indentation", "indentation of all elements is relative to the element above", "only ~PROPERTIES/LOGBOOK~ drawers get indentation relative to the current heading level" If you think that your variant is better, I can add it to the patch. > - s/the the element/to the element/ Agree. Intermediate patch is attached. >From 1881aacf22fda650408434394a96f3aaea2c6928 Mon Sep 17 00:00:00 2001 From: Max Nikulin Date: Thu, 20 May 2021 22:48:58 +0700 Subject: [PATCH] org-faq.org: Fix typos and style in "setup for indenting" * org-faq.org (What is the best setup for indenting?): Minor corrections suggested by Greg Minshall. --- org-faq.org | 16 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/org-faq.org b/org-faq.org index 0f8934af..54d5e403 100644 --- a/org-faq.org +++ b/org-faq.org @@ -1039,7 +1039,7 @@ In more details, ~org-adapt-indentation~ controls indentation with regards to previous element. Apparent effect is increased indentation for content of deeper nested headings. The variable accepts three values: =nil= (no special indentation), =t= (always indent relatively -the the element above) and =headline-data= (only indent the +to the element above) and =headline-data= (only indent the ~PROPERTIES/LOGBOOK~ drawers relatively to the current level). Value =t= is suitable for short entries especially if you plan to share your documents with someone who does not use Emacs. If you just want to @@ -1059,8 +1059,8 @@ With ~electric-indent-mode~ enabled: |---+++| | RET after a headline | Do not indent | Indent | Do not indent | | C-j after a headline | Do not indent | Do not indent | Do not indent | -| RET anywhere | Indent wrt previous| Indent wrt previous| Indent wrt previous| -| C-j anywhere | Do not indent wrt prev | Do not indent wrt previous | Do not indent wrt previous | +| RET elsewhere | Indent wrt previous| Indent wrt previous| Indent wrt previous| +| C-j elsewhere | Do not indent wrt prev | Do not indent wrt previous | Do not indent wrt previous | | Insert PROPERTIES/LOGBOOK | Do not indent | Indent wrt headline| Indent wrt headline| With ~electric-indent-mode~ disabled: @@ -1069,21 +1069,21 @@ With ~electric-indent-mode~ disabled: |---+-++| | RET after a headline | Do not indent | Do not indent | Do not indent | | C-j after a headline | Do not indent | Indent | Do not indent | -| RET | Do not indent | Do not indent wrt previous | Do not indent wrt previous | -| C-j | Indent wrt previous | Indent wrt previous| Indent wrt previous| +| RET elsewhere | Do not indent | Do not indent wrt previous | Do not
Re: [PATCH] org-faq.org: Expand "What is the best setup for indenting?"
Hi Maxim, applied in Worg, thanks! -- Bastien
Re: [PATCH] org-faq.org: Expand "What is the best setup for indenting?"
Maxim, patches to patches... :) i think these are really just typos, rather than any useful substantial comment. - s/is enable (the default) or not:/is enabled (the default) or not:/ - i would suggest separate tables for >= 9.5 and < 9.5. just so the differences between with/without =electric-indent-mode= are easier to spot. - s/C-j anywhere/C-j elsewhere/ (and, iiuc, maybe also the "unadorned" [C-j] table entry should probably be [C-j elsewhere]?) - s/lost formatting/lose formatting/ - s/and, that is/and,/ - s/always indent relatively/always indent relative/ - s/the the element/to the element/ cheers, Greg
[PATCH] org-faq.org: Expand "What is the best setup for indenting?"
--- org-faq.org | 61 ++--- 1 file changed, 44 insertions(+), 17 deletions(-) diff --git a/org-faq.org b/org-faq.org index 9cc193c4..0f8934af 100644 --- a/org-faq.org +++ b/org-faq.org @@ -1029,21 +1029,33 @@ something like this: :CUSTOM_ID: indentation :END: -Indentation is a matter of personal preferences. General indentation -preferences are controlled in Emacs via ~electric-indent-mode~. Org -indentation behavior changes depending on ~org-adapt-indentation~, which -accepts three values: =nil= (no special indentation), =t= (always indent -relatively the the element above) and =headline-data= (only indent the -~PROPERTIES/LOGBOOK~ drawers relatively to the current level). On top -of these two configuration areas, there the difference between =RET= and -=C-j=. - -Here are two tables summarizing the behavior depending on whether -~electric-indent-mode~ is enable (the default) or not: - -With `electric-indent-mode' enabled: - -| org-adapt-indentation => | nil| t | headline-data | +Indentation, both appearance and behavior, is a matter of personal +preferences. You may try if the following adjustments suits better +for you than the defaults. Set ~org-adapt-indentation~ to have +content aligned to headline titles. Disable ~electric-indent-mode~ to +avoid automatic indentation in response to =RET= key. + +In more details, ~org-adapt-indentation~ controls indentation with +regards to previous element. Apparent effect is increased indentation +for content of deeper nested headings. The variable accepts three +values: =nil= (no special indentation), =t= (always indent relatively +the the element above) and =headline-data= (only indent the +~PROPERTIES/LOGBOOK~ drawers relatively to the current level). Value +=t= is suitable for short entries especially if you plan to share your +documents with someone who does not use Emacs. If you just want to +make heading level more prominent then consider adding visual left +margin using =#+STARTUP: indent= as described in the [[https://orgmode.org/manual/Clean-View.html#Clean-View][Clean View]] +section of the manual. The option works without adding extra spaces +to the document text. + +Configured indentation may be applied in response to =RET= or to +=C-j= depending on the state of ~electric-indent-mode~. The following +tables summarizes the difference. Version number is added to column +header if it describes default settings. + +With ~electric-indent-mode~ enabled: + +| org-adapt-indentation => | nil (Org >= 9.5) | t (Org 9.4) | headline-data | |---+++| | RET after a headline | Do not indent | Indent | Do not indent | | C-j after a headline | Do not indent | Do not indent | Do not indent | @@ -1051,9 +1063,9 @@ With `electric-indent-mode' enabled: | C-j anywhere | Do not indent wrt prev | Do not indent wrt previous | Do not indent wrt previous | | Insert PROPERTIES/LOGBOOK | Do not indent | Indent wrt headline | Indent wrt headline| -With `electric-indent-mode' disabled: +With ~electric-indent-mode~ disabled: -| org-adapt-indentation => | nil | t | headline-data | +| org-adapt-indentation => | nil | t | headline-data (Org < 9.4) | |---+-++| | RET after a headline | Do not indent | Do not indent | Do not indent | | C-j after a headline | Do not indent | Indent | Do not indent | @@ -1061,6 +1073,21 @@ With `electric-indent-mode' disabled: | C-j | Indent wrt previous | Indent wrt previous | Indent wrt previous| | Insert PROPERTIES/LOGBOOK | Do not indent | Indent wrt headline | Indent wrt headline| +Do not try to avoid or to ignore indentation of heading body or +properties drawer determined by current state of +~org-adapt-indentation~ and ~electric-indent-mode~ by pressing =C-j= +instead of =RET= (or vice versa). The result is transient and you will +lost formatting when you refile heading or change its level (promote +or demote it). + +You may have noticed recommendation to disable ~electric-indent-mode~ +to restore behavior prior to Org 9.4. In Org 9.5 +~org-adapt-indentation~ default value changed to =nil= and, that is +more important, a number of bugs related to indentation were fixed. +Using =RET= with enabled ~electric-indent-mode~ should be convenient +now. Just customize ~org-adapt-indentation~ variable
