org-adapt-indentation default should be nil [legibility 3/6]

org-adapt-indentation default should be nil [legibility 3/6]

[Texas Cyberthal]

#+begin_src elisp
(org-adapt-indentation nil)
#+end_src

Adaptive indentation makes sense when using Org as a plain-text
database. It does not make sense when using Org for longform prose.

In the former case, outline depth is important to reflect properties
such as inheritance. The code elements are primary and the prose
secondary.

In the latter case, the primary payload is the prose. Gratuitously
indenting it wastes screen space and requires the user to make layout
adjustments for legibility. The extra information value of indentation
reflecting outline depth is negligible; the heading already conveys
it.

Beginners are bad at making adjustments to keep heavily-indented prose
legible. Thus the default should be nil.

Re: org-adapt-indentation default should be nil [legibility 3/6]

[Adam Porter]

Texas Cyberthal <texas.cyberthal@gmail.com> writes:

> #+begin_src elisp
> (org-adapt-indentation nil)
> #+end_src
>
> Adaptive indentation makes sense when using Org as a plain-text
> database. It does not make sense when using Org for longform prose.
>
> In the former case, outline depth is important to reflect properties
> such as inheritance. The code elements are primary and the prose
> secondary.
>
> In the latter case, the primary payload is the prose. Gratuitously
> indenting it wastes screen space and requires the user to make layout
> adjustments for legibility. The extra information value of indentation
> reflecting outline depth is negligible; the heading already conveys
> it.
>
> Beginners are bad at making adjustments to keep heavily-indented prose
> legible. Thus the default should be nil.

I think you have a better case for changing this setting.  However, I
think there is another consideration: the default settings do not put
blank lines between headings and their entry text, and without any
indentation, headings and entry text on varying levels tends to blend
together, making for very poor readability.  Disabling this setting
would make this problem worse.

Generally, I don't think "beginners are bad at" is a good argument for
changing defaults.  No one is "good at" Emacs and Org when they first
come to it.  There's probably room for improving the defaults, but we
should not necessarily make changes based on guessing what brand-new
users are most likely to want.  Emacs and Org are, thankfully, generally
free from the trend of aiming software at those who have never used it
before.  Instead, it tends to call users to learn more and aspire to
mastery, which is more useful and empowering in the long run.

Re: org-adapt-indentation default should be nil [legibility 3/6]

[Bastien]

Hi Texas and Adam,

Adam Porter <adam@alphapapa.net> writes:

>> Beginners are bad at making adjustments to keep heavily-indented
>> prose legible. Thus the default should be nil.
>
> I think you have a better case for changing this setting.

The default `org-adapt-indentation' can indeed be problematic.

One problem is that you typically want planning information and
property/logbook drawer of a headline to be indented, while you
don't want the subtree *text* to be indented.

From master, you can test

  (setq org-adapt-indentation 'headline-data)

To get this behavior.  I think it should be the default, but
(1) it should be heavily tested first via a major release and
(2) other users may think otherwise, this needs to be carefully
discussed first.

Thanks,

-- 
 Bastien

Re: org-adapt-indentation default should be nil [legibility 3/6]

[Samuel Wales]

[this is addressed to bastien]

hi,

if you are thinking of changing the default to indenting meta lines
and asking for opinions on that:

fwiw, if org /were starting out/, i would propose that meta stuff not
be indented at all either.  then the regexps everywhere could be
reliable.  and it reduces number of things to think about.  keyboard
macros, grep, third party tools in and outside of emacs.

the idea being keep to the basics so there will be no surprises.

i have a case i won't go into where a tool cannot reliably parse such
lines, because it has to distinguish semantic indentation and physical
aesthetic indentation.  this can't be done without ai in its context.
so the tool /outlaws/ physical indentation for a feature.

it doesn't actually shoot you or post wanted signs if you physically
indent, but the feature will not work.

imo there are more arguments too.

for example, state change lines and notes can be wide.  for
accessibility, i always want the default to be the one that does not
affect whose who need it, who already have too much to deal with.
this is my opinion.

obviously, as a default not indenting text as you seem to propose is
good for newcomers.

as for org as it is now, with a mixture of at least 3 indentation
styles in the wild, idk.

fwiw.

Re: org-adapt-indentation default should be nil [legibility 3/6]

[Bastien]

Hi Samuel,

thanks for your feedback.

Samuel Wales <samologist@gmail.com> writes:

> obviously, as a default not indenting text as you seem to propose is
> good for newcomers.

Perhaps, we will see!

> as for org as it is now, with a mixture of at least 3 indentation
> styles in the wild, idk.

What I observed is that some users will turn M-x org-indent RET just
to have planning lines displayed correctly (i.e. visually indented),
while still willing to let the subtree text not indented at all.

You can now have this without running org-indent, which I think is an
improvement - we'll see.

Best,

-- 
 Bastien

Re: org-adapt-indentation default should be nil [legibility 3/6]

[Samuel Wales]

On 2/10/20, Bastien <bzg@gnu.org> wrote:
> Hi Samuel,
>
> thanks for your feedback.
>
> Samuel Wales <samologist@gmail.com> writes:
>
>> obviously, as a default not indenting text as you seem to propose is
>> good for newcomers.

that statement was in the context of accessibility.

>
> Perhaps, we will see!

indeed we will get opinions.

Re: org-adapt-indentation default should be nil [legibility 3/6]

[Texas Cyberthal]

> the default settings do not put blank lines between headings and their entry text,

I don't know what this means. Plain Emacs behaves the same way
Spacemacs does in this regard. Insertion of a blank line after a
heading is voluntary but standrd. Insertion of a blank line between
the current non-empty line and a new heading is automatic. The fact
that the latter looks nice tends to make users do the former.

> without any indentation, headings and entry text on varying levels tends to blend together, making for very poor readability.

If the goal is to read the body text of headings, then deeply
indenting it is contrary to the goal. If the goal is to see the depth
of headings, then the bodies should be folded. If folded mode doesn't
convey sufficient information, the solution is to rewrite the heading
titles to better summarize the body text.

I never use org-adapt-indentation and have no readability issues. Out
of curiosity, I tried to turn it on just now. There's no toggle for
it, even though it's a buffer-local variable. This suggests it's not
useful, since apparently nobody who's turned it off cares to turn it
on again.

> No one is "good at" Emacs and Org when they first come to it.

UI difficulty is exponential, not linear. The more initially difficult
the Emacs UI is acknowledged to be, the more important it is to reduce
that difficulty with noob-friendly defaults, so that they can
eventually reach the point of elitist unconcern for noobs.

The problem with aiming software at noobs is ruining the expert
experience. Changing defaults doesn't ruin expert experience because
experts have configuration management. Noob friendly defaults
increases the likelihood there is a long term for them. Emacs' biggest
barrier to adoption is acclimatization. I just read a GTD thread in
which they all agreed Org was too hard to be worth learning, including
the guy advocating it:

https://forum.gettingthingsdone.com/threads/emacs-org-mode-is-the-perfect-tool-for-gtd.15028/page-2

To be clear, this is the biggest GTD forum, which Org is the best
implementation of, and it seems most of them are using digital GTD
tools.

Re: org-adapt-indentation default should be nil [legibility 3/6]

[Adam Porter]

Texas Cyberthal <texas.cyberthal@gmail.com> writes:

>> the default settings do not put blank lines between headings and
>> their entry text,
>
> I don't know what this means. Plain Emacs behaves the same way
> Spacemacs does in this regard. Insertion of a blank line after a
> heading is voluntary but standrd.

I don't know what you mean, either, but you keep mentioning Spacemacs,
which isn't very relevant.

>> without any indentation, headings and entry text on varying levels
>> tends to blend together, making for very poor readability.
>
> If the goal is to read the body text of headings, then deeply
> indenting it is contrary to the goal. If the goal is to see the depth
> of headings, then the bodies should be folded. If folded mode doesn't
> convey sufficient information, the solution is to rewrite the heading
> titles to better summarize the body text.

It is not for you to decide what others should do.  Your preferences are
not mine.  It sounds like you should develop your own "Texas Cyberthal
Emacs starter kit" that has all the settings you think are best.

>> No one is "good at" Emacs and Org when they first come to it.
>
> UI difficulty is exponential, not linear.

Come on, we all know that the Emacs learning curve is a spiral.

> The more initially difficult the Emacs UI is acknowledged to be, the
> more important it is to reduce that difficulty with noob-friendly
> defaults, so that they can eventually reach the point of elitist
> unconcern for noobs.

The issue here is not whether Emacs can generally be improved, but
whether your specific proposals are good ideas.

It's unfriendly of you--and incorrect--to imply that we are elitists
without concern for new users.  Much effort is put into improving
documentation, answering questions, writing explanatory articles, giving
demonstrations, etc.  Some of us even publish code to help others
improve their configs, e.g. https://github.com/alphapapa/alpha-org.  I
suggest that you give those avenues a try, rather than insisting that
your preferences are best for others.

> The problem with aiming software at noobs is ruining the expert
> experience.

That is one problem with software that overemphasizes the experience of
new users.  Another, perhaps more serious, problem is that it inhibits
the development of such expertise.  I feel like some of ESR's writings
are relevant here.

> Changing defaults doesn't ruin expert experience because experts have
> configuration management.

A VCS does not obviate the need to compensate for changes in default
behavior.

> Noob friendly defaults increases the likelihood there is a long term
> for them.  Emacs' biggest barrier to adoption is acclimatization.

You're not quite wrong, but you're missing the point about long-term
users.  What makes software attractive in the long-term is not what
makes it appeal to new users.  Emacs is not called "the editor of a
lifetime" for nothing--nor is notepad.exe called that, even though it is
very easy for new users to use.  Emacs is attractive in the long-term
because of its power, flexibility, and potential for mastery.  There is
a balance to be struck between appealing to new users and empowering the
development of expertise; to an extent, the two goals do conflict.

> I just read a GTD thread in which they all agreed Org was too hard to
> be worth learning, including the guy advocating it:
>
> https://forum.gettingthingsdone.com/threads/emacs-org-mode-is-the-perfect-tool-for-gtd.15028/page-2
>
> To be clear, this is the biggest GTD forum, which Org is the best
> implementation of, and it seems most of them are using digital GTD
> tools.

So what?  Emacs and Org do not need to adapt themselves to users who do
not like them.  They are successful because of what they are.

You seem very concerned about new users, thinking that, unless we make
Emacs/Org very easy for new users to understand, there will be no new
users.  This is obviously not the case.  Emacs is one of the oldest
pieces of software still widely used.  It and Org are gaining new users
every day; the community is more vibrant than ever.  Probably more
people use Emacs and Org today than ever before.

Consider an analogy: Years ago, Mozilla Firefox was the fastest, most
powerful, most popular browser that wasn't imposed on its users.  It was
the obvious victor in the "browser wars," having led the way in
unseating IE and freeing the Web from Microsoft's hegemony.  Then Google
Chrome arose as a challenger, with certain inherent advantages due to
Google's position.  Mozilla then chose to stop leading and start
following.  Every new Firefox release became more like Chrome, with
Mozilla thinking that it could win back users.  But why would a user who
was happy with Chrome want to switch to a poor imitation of it?  Mozilla
thought it could succeed by abandoning what had made it successful--it
thought Firefox would be more popular if it stopped being Firefox.  The
result was continued decline in Firefox's market share and, eventually,
Mozilla's recent layoffs.

Time and again, concerned people say that Emacs needs to be made simpler
for new users.  In a way, these people are right.  In a way, they are
missing the point.  Emacs is successful because it is Emacs.