customizing Org for legibility

customizing Org for legibility

[Texas Cyberthal]

I aim to popularize Spacemacs as a personal info manager. Next task is
the Org configuration layer.

As preparation, I wrote a post critiquing Org's out-of-the-box
legibility. I believe a default configuration should cater to
beginners, since they're least likely to know how to customize. On the
other hand, maybe a package should set defaults to the median user and
leave beginner intake to distributions.

Along the way, I discovered mixed-pitch, which fixed most of my
complaint. It's quite obscure. I'd like to include it in Spacemacs'
Org layer.

I'm sharing my thoughts to see whether I'm missing anything else.
https://cyberthal-ghost.nfshost.com/configuring-org-for-readable-prose-is-too-complicated/

Re: customizing Org for legibility

[Fraga, Eric]

On Friday, 31 Jan 2020 at 17:34, Texas Cyberthal wrote:
> Along the way, I discovered mixed-pitch, which fixed most of my
> complaint. 

mixed-pitch-mode is quite nice and does work well generally.  It doesn't
work well with org-indent-mode, unfortunately, as the spacing used by
org to align subsequent text with the heading assumes fixed pitch.  I
imagine this could be fixed if somebody has the time and motivation.

in any case, your efforts in making org more attractive to new users is
welcome.  for us old-timers, the look & feel of org is what we grew up
with so we're comfortable with it...

-- 
Eric S Fraga via Emacs 28.0.50, Org release_9.3.1-94-g0ac6a9

Re: customizing Org for legibility

[Diego Zamboni]

[-- Attachment #1: Type: text/plain, Size: 1718 bytes --]

Hi,

I think it's a noble effort to popularize org-mode and to make it easier to
use. And I learned today about mixed-pitch :)

However, a lot of visual configuration depends on fonts, colors, and other
things which may vary a lot between users. While most of us by now probably
use a graphical version of Emacs, any such default settings should be done
with care for users who still use Emacs on a pure-text interface.

Making some default prettification as part of Spacemacs's org-mode layer
would be nice, since it includes a lot of customization and eye candy
already.

In case it's of use or for reference, I wrote a "Beautifying org-mode" blog
post some time ago: https://zzamboni.org/post/beautifying-org-mode-in-emacs/

(the corresponding section of my config file is here:
https://github.com/zzamboni/dot-emacs/blob/master/init.org#beautifying-org-mode
)

All the best,
--Diego



On Fri, Jan 31, 2020 at 10:35 AM Texas Cyberthal <texas.cyberthal@gmail.com>
wrote:

> I aim to popularize Spacemacs as a personal info manager. Next task is
> the Org configuration layer.
>
> As preparation, I wrote a post critiquing Org's out-of-the-box
> legibility. I believe a default configuration should cater to
> beginners, since they're least likely to know how to customize. On the
> other hand, maybe a package should set defaults to the median user and
> leave beginner intake to distributions.
>
> Along the way, I discovered mixed-pitch, which fixed most of my
> complaint. It's quite obscure. I'd like to include it in Spacemacs'
> Org layer.
>
> I'm sharing my thoughts to see whether I'm missing anything else.
>
> https://cyberthal-ghost.nfshost.com/configuring-org-for-readable-prose-is-too-complicated/
>
>

[-- Attachment #2: Type: text/html, Size: 2692 bytes --]

Re: customizing Org for legibility

[Texas Cyberthal]

Thanks for the insight on why things are the way they are. Sounds like
the Spacemacs layer is the correct place to address legibility.
Knowing this will help me argue my case at Spacemacs.

I planned to mine the Zamboni post already. mixed-mode must be obscure
indeed if he didn't know about it until today either!

One thing I don't understand: It seems that GUI and terminal modes are
completely different. Rather than constrain GUI defaults to terminal
limitations, it makes sense to gracefully degrade them when a terminal
is detected. I assume that terminal users don't care about variable
pitch. They're likely doing sysadmin, with little or no prose
interaction.

On Fri, Jan 31, 2020 at 9:20 PM Diego Zamboni <diego@zzamboni.org> wrote:
>
> Hi,
>
> I think it's a noble effort to popularize org-mode and to make it easier to use. And I learned today about mixed-pitch :)
>
> However, a lot of visual configuration depends on fonts, colors, and other things which may vary a lot between users. While most of us by now probably use a graphical version of Emacs, any such default settings should be done with care for users who still use Emacs on a pure-text interface.
>
> Making some default prettification as part of Spacemacs's org-mode layer would be nice, since it includes a lot of customization and eye candy already.
>
> In case it's of use or for reference, I wrote a "Beautifying org-mode" blog post some time ago: https://zzamboni.org/post/beautifying-org-mode-in-emacs/
>
> (the corresponding section of my config file is here: https://github.com/zzamboni/dot-emacs/blob/master/init.org#beautifying-org-mode)
>
> All the best,
> --Diego
>
>
>
> On Fri, Jan 31, 2020 at 10:35 AM Texas Cyberthal <texas.cyberthal@gmail.com> wrote:
>>
>> I aim to popularize Spacemacs as a personal info manager. Next task is
>> the Org configuration layer.
>>
>> As preparation, I wrote a post critiquing Org's out-of-the-box
>> legibility. I believe a default configuration should cater to
>> beginners, since they're least likely to know how to customize. On the
>> other hand, maybe a package should set defaults to the median user and
>> leave beginner intake to distributions.
>>
>> Along the way, I discovered mixed-pitch, which fixed most of my
>> complaint. It's quite obscure. I'd like to include it in Spacemacs'
>> Org layer.
>>
>> I'm sharing my thoughts to see whether I'm missing anything else.
>> https://cyberthal-ghost.nfshost.com/configuring-org-for-readable-prose-is-too-complicated/
>>

Re: customizing Org for legibility

[Jack Kamm]

> One thing I don't understand: It seems that GUI and terminal modes are
> completely different. Rather than constrain GUI defaults to terminal
> limitations, it makes sense to gracefully degrade them when a terminal
> is detected. I assume that terminal users don't care about variable
> pitch. They're likely doing sysadmin, with little or no prose
> interaction.

Personally, I run emacs in daemon mode, and often have both GUI and
terminal emacsclients connected to the same session. So I like to have
settings that work well in both.

I agree terminal users typically won't want variable pitch, but disagree
that they are generally doing sysadmin -- I know users who use org-mode
for their notes, but prefer to use emacs in the terminal.

Speaking to my own preferences -- I prefer fixed-width for editing text,
whether it's prose or code. For example, if I execute a command to move
the cursor down 10 lines, I like to know where my cursor is going to end
up. Fixed-width also works better for certain editing commands, such as
rectangle commands.

I am not sure what the majority preference is here, but it would be
interesting to know, and also how it distributes across old-timers and
newcomers. Ideally, it should be easy to accommodate all preferences,
with a small amount of configuration and easily discoverable
documentation.

Re: customizing Org for legibility

[Bob Newell]

Aloha everyone,

> I agree terminal users typically won't want variable pitch, but disagree
> that they are generally doing sysadmin -- I know users who use org-mode
> for their notes, but prefer to use emacs in the terminal.

I have a Very Big Use Case here: on my Android devices I run
Termux, which runs nearly everything perfectly but only in
terminal mode. I run Emacs/org-mode this way on my Android
tablet all the time when out of the house or traveling.

The mixed pitch idea has great merit, don't get me wrong, and
would be a very nice thing indeed on my native Linux
devices. But I'd hope there would be no "unintended
consequences" for terminal users.

-- 
Bob Newell
Honolulu, Hawai`i
- Via Gnus/BBDB/Org/Emacs/Linux

Re: customizing Org for legibility

[Diego Zamboni]

[-- Attachment #1: Type: text/plain, Size: 972 bytes --]

HI Bob,

In my testing, all font-related settings get ignored when running in
terminal mode, except for the colors.

--Diego


On Sat, Feb 1, 2020 at 9:12 PM Bob Newell <bobnewell@bobnewell.net> wrote:

> Aloha everyone,
>
> > I agree terminal users typically won't want variable pitch, but disagree
> > that they are generally doing sysadmin -- I know users who use org-mode
> > for their notes, but prefer to use emacs in the terminal.
>
> I have a Very Big Use Case here: on my Android devices I run
> Termux, which runs nearly everything perfectly but only in
> terminal mode. I run Emacs/org-mode this way on my Android
> tablet all the time when out of the house or traveling.
>
> The mixed pitch idea has great merit, don't get me wrong, and
> would be a very nice thing indeed on my native Linux
> devices. But I'd hope there would be no "unintended
> consequences" for terminal users.
>
> --
> Bob Newell
> Honolulu, Hawai`i
> - Via Gnus/BBDB/Org/Emacs/Linux
>
>

[-- Attachment #2: Type: text/html, Size: 1415 bytes --]

Re: customizing Org for legibility

[Tim Cross]

Good points Jack - I was going to post something similar.

There are many who use terminal mode for all sorts of reasons which may
not be obvious and which is not just sys admin work. For example, people
who like to use tmux or do pair programming (or paired writing, such as
for co-authoring of papers, presentations etc). Spacemacs has been
growing in popularity for this as well.

My concern here is that we are very much moving into aesthetics and
personal taste. I'm largely with Jack in that I prefer fixed width
fonts. While I agree that variable pitch can make some text look better,
I find the additional complication this brings wrt formatting and
consistent presentation outweighs the small visual improvements. For
similar reasons, I never use visual-line-mode.

I'm not saying we should not have 'mixed' fonts. However, we do need to
ensure this is optional and that it is thoroughly tested - for example,
many people have customised Agenda views. There has been discussion
around how variable pitch can work, but these tend to focus on the
'default' agenda. It is important to be mindful of such assumptions in
order to recognise where changes will need to be implemented as options
you can select rather than defaults you must disable.

It has been some years since I have done anything with Emacs' customize
interface and in particular, custom-face settings, but from memory, it
allowed you to set defaults for both GUI and text based consoles, so it
should be possible to do things in a way which work for both
environments. 

Jack Kamm <jackkamm@gmail.com> writes:

>> One thing I don't understand: It seems that GUI and terminal modes are
>> completely different. Rather than constrain GUI defaults to terminal
>> limitations, it makes sense to gracefully degrade them when a terminal
>> is detected. I assume that terminal users don't care about variable
>> pitch. They're likely doing sysadmin, with little or no prose
>> interaction.
>
> Personally, I run emacs in daemon mode, and often have both GUI and
> terminal emacsclients connected to the same session. So I like to have
> settings that work well in both.
>
> I agree terminal users typically won't want variable pitch, but disagree
> that they are generally doing sysadmin -- I know users who use org-mode
> for their notes, but prefer to use emacs in the terminal.
>
> Speaking to my own preferences -- I prefer fixed-width for editing text,
> whether it's prose or code. For example, if I execute a command to move
> the cursor down 10 lines, I like to know where my cursor is going to end
> up. Fixed-width also works better for certain editing commands, such as
> rectangle commands.
>
> I am not sure what the majority preference is here, but it would be
> interesting to know, and also how it distributes across old-timers and
> newcomers. Ideally, it should be easy to accommodate all preferences,
> with a small amount of configuration and easily discoverable
> documentation.


-- 
Tim Cross

Re: customizing Org for legibility

[Samuel Wales]

i get the sense spacemacs has brought a lot of new users to emacs.  i
don't use it but i have comments on your interesting and welcome
beauty tips.

i wasn't clear on the difference between beautifying list markers and
using org bullets.

this is really impressive.  does it have a fill column?  "... wrap
around nicely in the window according to their proportional-font size,
instead of at a fixed character count...".

i would be over the moon if you could make headers in the agenda
variable pitch.  not only would it look better and be consistent with
the outline, but it would conserve space.

also, i would remove the second column, which seems not to do anything.

also, i removed colons from some columns in the agenda and think it
looks better.  also i aligned all items.  also, i made bare active
tses use a leader.  also i made everything more compact except
categories which i widened.  also, i removed [xd.] in leaders.

curious what the brackets mean in
   ("PROPOSAL"     . "orange")
   ("[PROPOSAL]"   . "orange")

what does reformatting a buffer change?

could tags be fixed to stay at a column by counting pixels?

thank you for the tips.


On 1/31/20, Texas Cyberthal <texas.cyberthal@gmail.com> wrote:
> I aim to popularize Spacemacs as a personal info manager. Next task is
> the Org configuration layer.
>
> As preparation, I wrote a post critiquing Org's out-of-the-box
> legibility. I believe a default configuration should cater to
> beginners, since they're least likely to know how to customize. On the
> other hand, maybe a package should set defaults to the median user and
> leave beginner intake to distributions.
>
> Along the way, I discovered mixed-pitch, which fixed most of my
> complaint. It's quite obscure. I'd like to include it in Spacemacs'
> Org layer.
>
> I'm sharing my thoughts to see whether I'm missing anything else.
> https://cyberthal-ghost.nfshost.com/configuring-org-for-readable-prose-is-too-complicated/
>
>


-- 
The Kafka Pandemic

What is misopathy?
https://thekafkapandemic.blogspot.com/2013/10/why-some-diseases-are-wronged.html

The disease DOES progress. MANY people have died from it. And ANYBODY
can get it at any time.

Re: customizing Org for legibility

[Texas Cyberthal]

> this is really impressive.  does it have a fill column?

That seems to be a quote from Zamboni's page. AFAIK, visual line mode
is the opposite of using a fill column.

#+begin_quote
i would be over the moon if you could make headers in the agenda variable pitch.
not only would it look better and be consistent with the outline, but it would
conserve space.
#+end_quote

I think headers in the agenda should remain fixed pitch, so that its
table aspects align correctly. Headers should be kept concise for
agenda compatibility. That's why I use non-standard syntax for
headings. E.g., I'd title this email chain thus:

tech | org-mode@ mail list | prose legibility | 2020-01

I don't recognize the other questions you're asking and suspect
they're for Zamboni.

Also, in my last email I miswrote: it's mixed-pitch not mixed-mode.

On Sat, Feb 1, 2020 at 4:13 AM Samuel Wales <samologist@gmail.com> wrote:
>
> i get the sense spacemacs has brought a lot of new users to emacs.  i
> don't use it but i have comments on your interesting and welcome
> beauty tips.
>
> i wasn't clear on the difference between beautifying list markers and
> using org bullets.
>
> this is really impressive.  does it have a fill column?  "... wrap
> around nicely in the window according to their proportional-font size,
> instead of at a fixed character count...".
>
> i would be over the moon if you could make headers in the agenda
> variable pitch.  not only would it look better and be consistent with
> the outline, but it would conserve space.
>
> also, i would remove the second column, which seems not to do anything.
>
> also, i removed colons from some columns in the agenda and think it
> looks better.  also i aligned all items.  also, i made bare active
> tses use a leader.  also i made everything more compact except
> categories which i widened.  also, i removed [xd.] in leaders.
>
> curious what the brackets mean in
>    ("PROPOSAL"     . "orange")
>    ("[PROPOSAL]"   . "orange")
>
> what does reformatting a buffer change?
>
> could tags be fixed to stay at a column by counting pixels?
>
> thank you for the tips.
>
>
> On 1/31/20, Texas Cyberthal <texas.cyberthal@gmail.com> wrote:
> > I aim to popularize Spacemacs as a personal info manager. Next task is
> > the Org configuration layer.
> >
> > As preparation, I wrote a post critiquing Org's out-of-the-box
> > legibility. I believe a default configuration should cater to
> > beginners, since they're least likely to know how to customize. On the
> > other hand, maybe a package should set defaults to the median user and
> > leave beginner intake to distributions.
> >
> > Along the way, I discovered mixed-pitch, which fixed most of my
> > complaint. It's quite obscure. I'd like to include it in Spacemacs'
> > Org layer.
> >
> > I'm sharing my thoughts to see whether I'm missing anything else.
> > https://cyberthal-ghost.nfshost.com/configuring-org-for-readable-prose-is-too-complicated/
> >
> >
>
>
> --
> The Kafka Pandemic
>
> What is misopathy?
> https://thekafkapandemic.blogspot.com/2013/10/why-some-diseases-are-wronged.html
>
> The disease DOES progress. MANY people have died from it. And ANYBODY
> can get it at any time.

Re: customizing Org for legibility

[Samuel Wales]

hi texas,

apologies for any attribution errors.

headers in the agenda are on the right.  so there is nothing to line
up except tags, which are also not lined up in the outline.  so they
can be variable pitch ...

... unless you make headers line up with /one another/?

* like         this
* and         this

[i am writing this in variable pitch gmail so i probably misaligned
but you get the point.]

?  in which case you need fixed pitch.

didn't know anybody did that!

Re: customizing Org for legibility

[Texas Cyberthal]

Ok, I see what you're saying. You're proposing to have TODO states and
other tags on the left of the heading title in fixed pitch, and the
heading title in variable pitch. In my current setup the whole heading
is fixed in Agenda and variable in normal buffers. I agree it would be
good to have mixed-pitch headings.

On Sat, Feb 1, 2020 at 9:34 AM Samuel Wales <samologist@gmail.com> wrote:
>
> hi texas,
>
> apologies for any attribution errors.
>
> headers in the agenda are on the right.  so there is nothing to line
> up except tags, which are also not lined up in the outline.  so they
> can be variable pitch ...
>
> ... unless you make headers line up with /one another/?
>
> * like         this
> * and         this
>
> [i am writing this in variable pitch gmail so i probably misaligned
> but you get the point.]
>
> ?  in which case you need fixed pitch.
>
> didn't know anybody did that!

Re: customizing Org for legibility

[Diego Zamboni]

[-- Attachment #1: Type: text/plain, Size: 618 bytes --]

> Ok, I see what you're saying. You're proposing to have TODO states and
> other tags on the left of the heading title in fixed pitch, and the
> heading title in variable pitch. In my current setup the whole heading
> is fixed in Agenda and variable in normal buffers. I agree it would be
> good to have mixed-pitch headings.
>

This is doable for the TODO states already using the org-todo-keyword-faces
variable, which can contain full font attribute lists, like this:

    (org-todo-keyword-faces
     '(("TODO"         . (:foreground "DarkOrchid1" :inherit fixed-pitch))
       ("INBOX"        . "cyan"))

--Diego

[-- Attachment #2: Type: text/html, Size: 1068 bytes --]

Re: customizing Org for legibility

[Diego Zamboni]

[-- Attachment #1: Type: text/plain, Size: 3201 bytes --]

Hi Samuel,


> i get the sense spacemacs has brought a lot of new users to emacs.  i
> don't use it but i have comments on your interesting and welcome
> beauty tips.
>

This is definitely the case. I also don't use Spacemacs, but know a few
people who got started thanks to it. I even have a friend who was a
devoted vim user, and now swears by Spacemacs, particularly thanks to
org-mode and magit :)

this is really impressive.  does it have a fill column?
>

Yes, there is (I don't use it):
https://github.com/joostkremers/visual-fill-column

i would be over the moon if you could make headers in the agenda
> variable pitch.  not only would it look better and be consistent with
> the outline, but it would conserve space.
>

I think you can configure most faces as you wish. For this, I have found
the key "C-u C-x =" (which run what-cursor-position with the DETAILED
argument enabled) very useful - among other things, it shows the face which
is applied at the point under the cursor. Based on that, you can know which
face you need to customize. For example, when running it on an agenda
header line, I see the following:

There are text properties here:
  day                  737456
  face                 org-agenda-date-today

By customizing this face to inherit from "variable-pitch", I was able to
make those lines display in variable pitch font.

also, i would remove the second column, which seems not to do anything.
>
> also, i removed colons from some columns in the agenda and think it
> looks better.  also i aligned all items.  also, i made bare active
> tses use a leader.  also i made everything more compact except
> categories which i widened.  also, i removed [xd.] in leaders.
>

I would be interested to learn how to make these customizations. I have
only recently been getting into agenda mode, so I have not customized much
yet,

curious what the brackets mean in
>    ("PROPOSAL"     . "orange")
>    ("[PROPOSAL]"   . "orange")
>

Nothing special - only that I sometimes use TAG in my headers, and others I
use [TAG], depending on how I think it looks better at the time :) This way
it gets colorized correctly no matter what.

what does reformatting a buffer change?
>

I guess you are referring to the zz/org-reformat-buffer in my config? I got
this from the mailing list, although I can't remember who posted it (sorry
to the author! there goes my intention to always attribute things). It
basically redoes all the spacing and indentation in the buffer. I run it
every once in a while to uniformize things.

could tags be fixed to stay at a column by counting pixels?
>

I have not found a way to make that happen. The misalignment was bothering
me, so in the end this is what I do:

- In =variable-pitch= mode, the default right-alignment for headline tags
doesn't work, and results in the tags being misaligned (as it uses
character positions to do the alignment). This setting positions the tags
right after the last character of the headline, so at least they are more
consistent.

  #+begin_src emacs-lisp :tangle no :noweb-ref org-mode-custom-vars
    (org-tags-column 0)
  #+end_src


> thank you for the tips.
>

Glad you found them useful!

Cheers,
--Diego

[-- Attachment #2: Type: text/html, Size: 5156 bytes --]

Re: customizing Org for legibility

[Bastien]

Hi Texas,

> I aim to popularize Spacemacs as a personal info manager. Next task is
> the Org configuration layer.

thanks for doing so.

> As preparation, I wrote a post critiquing Org's out-of-the-box
> legibility.

some ideas might be useful - thanks again.

Can you take ideas one by one and send an email to the list for each
improvement you sugggest?  That will make it easier for everyone to
contribute to what feature or new default is discussed, based on the
subject line of your emails.

Thanks in advance,

-- 
 Bastien