Re: Changed list indentation behavior: how to revert?

[T.F. Torrey]

Hello all,

I apologize in advance that this is so long.

I've been following this thread closely, because I've been using Org
mode daily for well over a decade, and this behavior affects me in
several important ways.  I think this summary might be helpful.

Forever, it has been possible to start a heading in Org by typing a
return one or more times, then typing an asterisk and a space and the
heading text.  To add a series of headings, just keep hitting return at
the end of the current one, type an asterisk and a space and the next
one, then repeat.  If you want subheadings, it is as simple as typing
more asterisks.  Easy.

This worked because electric-indent-mode defaulted to off, and although
org-adapt-indentation defaulted to t, it didn't affect this situation.

The default behavior here matters because Org is a killer feature of
Emacs, enticing many people to give it a try, including my nine-year-old
daughter.  For them, it should behave by default the way it looks like
it should.  That means, typing asterisks and text for headings, followed
by returns, and text, and more asterisks, should just work by default.

#+NAME: Old Defaults: electric-indent-mode OFF and org-adapt-indent t
#+begin_example org
,* Testing out Org, type <RET> here once or twice

I get it!  I'll type <RET> once or twice again and start a subheading.

,** Headings are easy!  Now another <RET> or two for subhead content

This is awesome!  It works just as I expect, and I don't have to
memorize a bunch of key chords just to get started.  And folding is
awesome!  I love Org!  I will stick with it and learn it all!
#+end_example

I have probably typed close to a million headings like this all by
myself, and collectively we have probably typed billions or more.

The last release, as everyone knows, turned on electric-indent-mode by
default.  So, right now, typing an Org document with default settings
does not work like it looks like it should.  This is the new experience
for people used to the old defaults, and beginners like my daughter:

#+NAME: New Defaults: electric-indent-mode ON and org-adapt-indent t
#+begin_example org
,* I typed an asterisk for this heading, how about <RET> here once or twice

  Okay.  This is indented.  Since I'm new, I don't realize it isn't
  useful yet, or that it makes a difference at all.  How about a
  subheading?  I'll hit <RET> a couple times, they type two asterisks.

  ,** Is this a subheading? It looks like one.  <RET> again here ...

  Okay, the indentation isn't the same, but maybe it's okay?  I
  probably didn't even notice.

  ,*** I think I'm organizing my document with *'s and <RET>'s

  I'm going to try folding my stuff, becaue I saw that and it looks
  awesome.

  Wait!  The instructions say <TAB> will cycle the folding, but it
  only works on the top level.  What?

  Okay, some searching said I have to modify init, or something, or
  type some weird key combinations.  What?  This looked like it was
  going to be easy.  Nerds are liars.

  I can't figure this out, and I don't have time to mess with this.
  I'm going back to Word.  Maybe I'll try Markdown tomorrow.
#+end_example

For new users, step one is either to start changing default settings,
start learning key chords and/or arcane (to beginners) commands---or go
back to Word or Markdown.

Turning on electric-indent-mode, all by itself, shouldn't break the
useful or customary indentation that the users of Org expect, but it
has.  Instead of starting a new heading by typing <RET> one or more
times, then typing an asterisk and a space and a new heading, a user
has to either hit some control characters with returns, or backspace to
column zero, or something else.

The manual shows heading and body formatting as this:

#+NAME: Org Manual Sample: electric-indent-mode on, org-adapt-indent t
#+begin_example org
,* Top level headline
,** Second level
,*** Third level
    some text
,*** Third level
    more text
,* Another top level headline
#+end_example

I don't recall ever seeing an Org document in real life with the body
indented at the level of each heading, and I haven't seen anyone argue
for that behavior on this thread.  I've tried it, and the text body
width rapidly becomes too narrow to be useful.  As several people have
noted, even the Org repositories turn this off, which suggests even
the developers don't find it useful.  Why this is set as the default,
I have no idea, but it didn't really matter until now.

An Org document looks like you can create it by typing asterisks,
text, and returns, but you can't, not by default, anyway.

That's the root of the problem: the longstanding default *behavior*
has been changed.  The only people unaffected are people who already
had compensatory settings in their init files.

As far as I can tell, turning on electric-indent-mode by default was
done for no reason other than other Emacs modes have it as a default.

The proper fix for this is one of two choices:

1. If keeping electric-indent-mode on is really important, the easiest
   way to restore intuitive behavior is to change the default of
   org-adapt-indentation to nil.  Yes, this changes a longstanding
   default, but it is necessitated because of the change of another
   longstanding default: electric-indent-mode.  Before, anyone who
   wanted text indented by default needed to specify that in their init
   file, so this should not inconvenience anyone who wasn't
   inconvenienced before.

or

2. More involved would be to change the default behavior of Org's
   electric indentation so that typing <RET> at the end of a heading
   takes you back to column 0 by default.  In many contexts, the
   indentation provided by org-auto-indent is useful, but not this
   one.

The Emacs manual says that "Electric Indent mode is a global minor mode
that automatically indents the line after every <RET> you type", but
that's not exactly true.  What it does do is indent a line to what is
useful or customary based on the context, which is often not at all.  In
the context of hitting <RET> at the end of a heading in Org, what is
useful may be debatable, but it seems customary for all serious Org
users to return to column 0, and that seems what new and casual users
expect.

Finally, I can point out that, for myself, adding another line to my
init file (actually a literate Org doc) is not a big deal.  I've been
using Org and Emacs long enough that changing defaults doesn't bother me
much.

For new and casual users, including my nine-year-old daughter, however,
I hope we can change the defaults so that it works the way it looks like
it should.  It's not easy to get her to try Emacs and Org, and this
makes it harder.

Side note: the manual frequently refers to headings as "headlines", but
that is not the right use of that word.  To whit: there is no such thing
as a "subheadline", but there is a "subheading", because that construct
is a "heading", and a "headline" is something else.

All the best,
Terry