org-store/insert-link truncating the full subject of mails

org-store/insert-link truncating the full subject of mails

[Garreau, Alexandre]

Why so?

It shouldn’t be this way by default.

I tried to link
“[[gnus:nnml:lists.gnu.emacs-orgmode#87in1rkqlk.fsf@gmail.com][Email
from Tim Cross: Re: {O} Ox-html: Replace <b> with <strong> and <i> with
<em>]]” and after org-store-link in appropriated buffer, org-insert-link
gave me “Email from Tim Cross: Re: {O} Ox-html: Replace <b> w”.

Re: org-store/insert-link truncating the full subject of mails

[Nicolas Goaziou]

Hello,

"Garreau, Alexandre" <galex-713@galex-713.eu> writes:

> Why so?

See `org-email-link-description-format'.

> It shouldn’t be this way by default.

Truncating subject doesn't seem unreasonable to me. In any case, you can
just set the variable above to suit your needs.

Regards,

-- 
Nicolas Goaziou

Re: org-store/insert-link truncating the full subject of mails

[Garreau, Alexandre]

Le 26/10/2018 à 17h35, Nicolas Goaziou a écrit :
> "Garreau, Alexandre" <galex-713@galex-713.eu> writes:
>> Why so?
>
> See `org-email-link-description-format'.

Thank you!

>> It shouldn’t be this way by default.
>
> Truncating subject doesn't seem unreasonable to me. In any case, you can
> just set the variable above to suit your needs.

How’s that? it just feels wrong: if it’s to long, users can truncate
themselves, it’s straightforward, but finding again and adding the end,
or finding the appropriate customization, isn’t.

Also what’s the utility of it?

Re: org-store/insert-link truncating the full subject of mails

[Nicolas Goaziou]

"Garreau, Alexandre" <galex-713@galex-713.eu> writes:

> How’s that?

I think limiting the number of characters in the description is to be on
the safe side. 30 characters are usually enough to understand what the
mail is about.

> it just feels wrong: if it’s to long, users can truncate themselves,
> it’s straightforward, but finding again and adding the end, or finding
> the appropriate customization, isn’t.

> Also what’s the utility of it?

See above.

In any case, if other users feel strongly about changing the default
value, I don't mind. I hope you understand that one data point is not
enough, tho.

Regards,

Re: org-store/insert-link truncating the full subject of mails

[Amin Bandali]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I think limiting the number of characters in the description is to be on
> the safe side. 30 characters are usually enough to understand what the
> mail is about.

Can you please elaborate on what you mean by being on the safe
side in this context?  What problems could potentially arise from
returning the subject in full length?

> In any case, if other users feel strongly about changing the default
> value, I don't mind. I hope you understand that one data point is not
> enough, tho.

Considering my above question and me not knowing why/where this
limit comes from, if there’s a legitimate reason to truncate the
subject then so be it.  But if not, I’d probably be in favour of
changing the default to lift the limit.

Or at the very least mentioning `org-email-link-description-format'
in the docstring for `org-store-link' and potentially other functions
affected by the setting.

just my 2¢.

-amin

Re: org-store/insert-link truncating the full subject of mails

[Nicolas Goaziou]

Hello,

Amin Bandali <bandali@gnu.org> writes:

> Can you please elaborate on what you mean by being on the safe
> side in this context?  What problems could potentially arise from
> returning the subject in full length?

I don't know. This is why I agree it is safer to limit length to an
arbitrary number instead of allowing any size.

> Or at the very least mentioning `org-email-link-description-format'
> in the docstring for `org-store-link' and potentially other functions
> affected by the setting.

I updated the manual instead. It now mentions
`org-email-link-description-format'.

Regards,

-- 
Nicolas Goaziou

Re: org-store/insert-link truncating the full subject of mails

[Garreau, Alexandre]

Le 27/10/2018 à 11h27, Nicolas Goaziou a écrit :
> Hello,
>
> Amin Bandali <bandali@gnu.org> writes:
>
>> Can you please elaborate on what you mean by being on the safe
>> side in this context?  What problems could potentially arise from
>> returning the subject in full length?
>
> I don't know. This is why I agree it is safer to limit length to an
> arbitrary number instead of allowing any size.

Without justification, that’d look like “argument from ignorance”, so
unless a real reason is found, I believe it would be better to remove a
truncation that will very certainly in fact bother at least some users
(while there’s still 0 data point on how non-truncation might be
bothering, and that’s what being asked).

Re: org-store/insert-link truncating the full subject of mails

[Nicolas Goaziou]

"Garreau, Alexandre" <galex-713@galex-713.eu> writes:

> Without justification, that’d look like “argument from ignorance”,

I'm not arguing for truncating subjects.

However, I'm arguing against changing a 10 years old default value
without a strong reason. Default value annoys some users. Point taken.
But changing it might also annoy some users, possibly, at least, the
person that chose it in the first place, or users that do not like
arbitrary long links.

> so unless a real reason is found, I believe it would be better to
> remove a truncation that will very certainly in fact bother at least
> some users (while there’s still 0 data point on how non-truncation
> might be bothering, and that’s what being asked).

Truncation, an its related variable, are now documented in the manual.
The bothering is somewhat very limited.

Re: org-store/insert-link truncating the full subject of mails

[Garreau, Alexandre]

Le 27/10/2018 à 13h55, Nicolas Goaziou a écrit :
> "Garreau, Alexandre" <galex-713@galex-713.eu> writes:
>
>> Without justification, that’d look like “argument from ignorance”,
>
> I'm not arguing for truncating subjects.
>
> However, I'm arguing against changing a 10 years old default value
> without a strong reason. Default value annoys some users. Point taken.
> But changing it might also annoy some users, possibly, at least, the
> person that chose it in the first place, or users that do not like
> arbitrary long links.

This is an argument in favor of immobility.  The reason could also be
ridden in old capabilities, bugs or slowyness not relevant nowadays.  If
anything, we should find back who introduced this default, and ask them.

Especially, this is a end-user thing.  Not a programming-language API.
This can be seen by the user.  So it’s not a problem.

What could be done, if you want, is to rely on external software: for
instance, sometimes, when answering, Gnus takes away the “Was: ...”
subject line ending, if too long: that might be used to shorten it, if
believed useful.  That would be acceptable, as it would stay semantic,
and wouldn’t break in the middle of a sentence.

>> so unless a real reason is found, I believe it would be better to
>> remove a truncation that will very certainly in fact bother at least
>> some users (while there’s still 0 data point on how non-truncation
>> might be bothering, and that’s what being asked).
>
> Truncation, an its related variable, are now documented in the manual.
> The bothering is somewhat very limited.

Yes, if only each user of each piece of software took the time to read
the integrality of documentation each time they used something: I don’t
and only did partially for org, yet… but for instance I did for Gnus, a
long time ago, and never did it again: as example, did you?.

Default are an important thing, they should fit what the most common,
unspecific, and ignorant about the software in question, person.
Documentation should be there only to adapt to more specific, and less
common, cases (and, when possible, software should be made so that to
conditionally do the right thing depending of the context so that
changing the default behavior is less and less needed).  Not the other
way around.

Re: org-store/insert-link truncating the full subject of mails

[Garreau, Alexandre]

Le 27/10/2018 à 13h55, Nicolas Goaziou a écrit :
> "Garreau, Alexandre" <galex-713@galex-713.eu> writes:
>
>> Without justification, that’d look like “argument from ignorance”,
>
> I'm not arguing for truncating subjects.
>
> However, I'm arguing against changing a 10 years old default value
> without a strong reason. Default value annoys some users. Point taken.
> But changing it might also annoy some users, possibly, at least, the
> person that chose it in the first place, or users that do not like
> arbitrary long links.

This is an argument in favor of immobility.  The reason could also be
ridden in old capabilities, bugs or slowyness not relevant nowadays.  If
anything, we should find back who introduced this default, and ask them.

Especially, this is a end-user thing.  Not a programming-language API.
This can be seen by the user.  So it’s not a problem.

What could be done, if you want, is to rely on external software: for
instance, sometimes, when answering, Gnus takes away the “Was: ...”
subject line ending, if too long: that might be used to shorten it, if
believed useful.  That would be acceptable, as it would stay semantic,
and wouldn’t break in the middle of a sentence.

>> so unless a real reason is found, I believe it would be better to
>> remove a truncation that will very certainly in fact bother at least
>> some users (while there’s still 0 data point on how non-truncation
>> might be bothering, and that’s what being asked).
>
> Truncation, an its related variable, are now documented in the manual.
> The bothering is somewhat very limited.

Yes, if only each user of each piece of software took the time to read
the integrality of documentation each time they used something: I don’t
and only did partially for org, yet… but for instance I did for Gnus, a
long time ago, and never did it again: as example, did you?.

Default are an important thing, they should fit what the most common,
unspecific, and ignorant about the software in question, person.
Documentation should be there only to adapt to more specific, and less
common, cases (and, when possible, software should be made so that to
conditionally do the right thing depending of the context so that
changing the default behavior is less and less needed).  Not the other
way around.

Re: org-store/insert-link truncating the full subject of mails

[Amin Bandali]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I don't know. This is why I agree it is safer to limit length to an
> arbitrary number instead of allowing any size.

Hoping to find an actual answer, I did a =git blame lisp/org.el=
and found the commit that introduced it,
2c16f092e64915a7e3d0b2dda82f3978a0f42dea, by Carsten Dominik,
the creator of Org mode himself.

I emailed Carsten yesterday and asked if he recalls why he
introduced that variable and that behvaiour.  He said that he
doesn’t recall exactly, but that either it was aesthetic (he
didn’t find extremely long link descriptions pretty), or that
long lines slowed down some regular expressions that ran in the
buffer.  He said it was most likely the first one (aesthetic),
and that he wouldn’t object to lifting the restriction.

On a side note, I’d like to point out that I use C-h k, C-h f,
and C-h v many times a day, especially when encountering new
functions or variables.  But I don’t know if I’m the minority, or
if most other Emacs users check the docs frequently as well.

That said, I still find the default a bit obtuse and frankly
unexpected.  I don’t know, maybe a nice middle ground between the
current behaviour and completely removing the limit would be to
increase the limit from 30 to 78 characters, the recommended
maximum number of characters in a line according to RFC 2822 [0].
That somehow feels less arbitrary, and would cover a larger
portion of subjects.

[0]: https://tools.ietf.org/html/rfc2822#section-2.1.1

> I updated the manual instead. It now mentions
> `org-email-link-description-format'.

Thanks for that.

Best,
amin

Re: org-store/insert-link truncating the full subject of mails

[Garreau, Alexandre]

Le 28/10/2018 à 10h05, Amin Bandali a écrit :
> Hi,
>
> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> I don't know. This is why I agree it is safer to limit length to an
>> arbitrary number instead of allowing any size.
>
> Hoping to find an actual answer, I did a =git blame lisp/org.el=
> and found the commit that introduced it,
> 2c16f092e64915a7e3d0b2dda82f3978a0f42dea, by Carsten Dominik,
> the creator of Org mode himself.
>
> I emailed Carsten yesterday and asked if he recalls why he
> introduced that variable and that behvaiour.  He said that he
> doesn’t recall exactly, but that either it was aesthetic (he
> didn’t find extremely long link descriptions pretty), or that
> long lines slowed down some regular expressions that ran in the
> buffer.  He said it was most likely the first one (aesthetic),
> and that he wouldn’t object to lifting the restriction.

Thank you so much!  That was the Right Thing to do imho.  I really have
to learn git.  I wish a knew it here.

> On a side note, I’d like to point out that I use C-h k, C-h f,
> and C-h v many times a day, especially when encountering new
> functions or variables.  But I don’t know if I’m the minority, or
> if most other Emacs users check the docs frequently as well.

I’m an heavy user of them as well, and find them way easier and more
friendly than the manual, as they usually, don’t require me to read more
than a paragraph of a few lines (or it’s me doing it repetedly then),
while a manual requires to prepare to read a text of an indefinite
length (before to have found) which is way less predictable and hence
more tiring.

The problem is, ideally identifiers should be easily named so that you
easily find them with correct prefixes and autocompletion, but you don’t
always know/think to the right keywords, and the words are not always in
the most practical order.  Most of time it works, so it stays awesome
and extremely useful, but it stays imperfect, and henc is not a
substitute for better defaults.

> That said, I still find the default a bit obtuse and frankly
> unexpected.  I don’t know, maybe a nice middle ground between the
> current behaviour and completely removing the limit would be to
> increase the limit from 30 to 78 characters, the recommended
> maximum number of characters in a line according to RFC 2822 [0].
> That somehow feels less arbitrary, and would cover a larger
> portion of subjects.

Rather cutting it, I’d rather try to find the gnus function that cut
subject lines so it does more semantically (like, removing the entire
Was: part if it doesn’t fit, rather than cutting it in the middle), but
78 seems totally more reasonable, at worse, indeed: but maybe that
aforementioned gnus function does something related to it (maybe it does
cut when it exceed 78 chars?)?

However I was unable to find it by el-searching for "was:?", so I’ll ask
them directly, hoping they know and answer.

org-email-link-description-format (Was: Re: org-store/insert-link truncating the full subject of mails)

[Garreau, Alexandre]

On 2018-10-28 at 10:05, Amin Bandali wrote:
> That said, I still find the default a bit obtuse and frankly
> unexpected.  I don’t know, maybe a nice middle ground between the
> current behaviour and completely removing the limit would be to
> increase the limit from 30 to 78 characters, the recommended
> maximum number of characters in a line according to RFC 2822 [0].
> That somehow feels less arbitrary, and would cover a larger
> portion of subjects.
>
> [0]: https://tools.ietf.org/html/rfc2822#section-2.1.1

Okay, so I did not read carefully enough: this is a per line limit,
however Gnus already include this limitation in fill-column so that to
fold subject line in several lines that will be no more than 78
characters, there’s no need to limit to 78 characters, and indeed I
sometimes end with subject lines of more than one line, and wouldn’t
like to see my normal subject line truncated.  The same way, org-mode
will naturally see its paragraphs filled if wanted by the user (otherise
there are no problems in long lines, except, afaik, by default, it
disable truncating lines).

On 2018-10-28 at 18:01, Garreau, Alexandre wrote:
> Rather cutting it, I’d rather try to find the gnus function that cut
> subject lines so it does more semantically (like, removing the entire
> Was: part if it doesn’t fit, rather than cutting it in the middle), but
> 78 seems totally more reasonable, at worse, indeed: but maybe that
> aforementioned gnus function does something related to it (maybe it does
> cut when it exceed 78 chars?)?
>
> However I was unable to find it by el-searching for "was:?", so I’ll ask
> them directly, hoping they know and answer.

So the function I was searching is `message-strip-subject-trailing-was',
and only strip the was part, it doesn’t conditionally strip “Was” if
there were several, or if the subject line was too long.  Yet it can be
used for org-mode as the “Was:” trailing part is likely not to be
interesting at all for refering to a particular message, as anyway it
will be found again when visiting the said article.

What’s more interesting is it’s used in a function
`message-simplify-subject', calling a customizable list of functions
(`message-simplify-subject-functions'), that will simplify deeply the
subject, removing also the “Re:”, the mailing-list part, encoded parts,
etc.  Yet, as it currently only used for replying, it seems to, wrongly
imo, add a “Re:” to the subject line (while this should be its scope,
imo).  So this one is not usable as is.

But `message-strip-subject-re' might be used per se itself, otherwise,
as it seems to me the “Re:” might not be interesting as well, though
mailing-list part may be useful, as in
`org-email-link-description-format' there is nothing to refer to the
group (either the group name in gnus, or either content of “Newsgroups”
header or mailing-list (content of “List-id” or “List-post”, either
address or human-readable part)), but not all mailing-list embed one, so
it might bring inconsistency, and adding a said new format-specifier to
`org-email-link-description-format' seems to me preferable (why not “%g”
for “group”?).

So may I suggest to change `org-email-link-description' and update
`org-email-link-description-format', so that to support a "%g"
specifier, to refer to the content of :group (or should we add something
to refer List-ID/List-Post?), and a %S that’d return the subject,
simplified by `message-strip-subject-trailing-was',
`message-strip-subject-trailing-re', or, maybe rather, by all the
functions inside `message-simplify-subject-functions' (waiting for
`message-simplify-subject' to be corrected).

Re: org-store/insert-link truncating the full subject of mails

[Eric S Fraga]

On Friday, 26 Oct 2018 at 21:54, Nicolas Goaziou wrote:

[...]

> In any case, if other users feel strongly about changing the default
> value, I don't mind. I hope you understand that one data point is not
> enough, tho.

Just to add a data point: I've been annoyed by the default behaviour for
years.  However, not enough to go about finding out if it was possible
to change this behaviour!  Knowing, *now*, that there is a variable
which controls the format solves my annoyance.

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.1.13-783-g97fac4

Re: org-store/insert-link truncating the full subject of mails

[Nick Dokos]

Eric S Fraga <esflists@gmail.com> writes:

> On Friday, 26 Oct 2018 at 21:54, Nicolas Goaziou wrote:
>
> [...]
>
>> In any case, if other users feel strongly about changing the default
>> value, I don't mind. I hope you understand that one data point is not
>> enough, tho.
>
> Just to add a data point: I've been annoyed by the default behaviour for
> years.  However, not enough to go about finding out if it was possible
> to change this behaviour!  Knowing, *now*, that there is a variable
> which controls the format solves my annoyance.

I don't really care one way or the other: most of the time, I just
want to save the email for some information that it contains which may
or may not be related to the subject line. So I have a capture
template that saves the link, but I add my description of *why* I'm
saving the email (and add tags too), so I have a chance of finding the
information again. I don't worry about the link description.

BTW, if one wants to fit the whole thing on an 80-char line, one might
need to make it much shorter than 78 chars, in order to fit dates,
link description etc., that a capture would add (assuming that you use
a capture). In fact, with indentation the current default makes the
line longer than 80 chars in my setup. Here's what an example looks
like:

,----
| ** Example 
|   [2018-10-30 Tue 11:31] [[gnus:gmane.emacs.orgmode#87pnvttdku.fsf@gmail.com][Email from Eric S. Fraga: Re: org-store/insert-link trun]]
`----

and the RH end of that line (after the link is prettified) is on
column 81 (granted, it depends on the length of the name).

Chances are that if the default is changed to unlimited, I would set
it back to 30, just to keep my notes file neater, or maybe use
truncate-long-lines to truncate at the boundary.

-- 
Nick

"There are only two hard problems in computer science: cache
invalidation, naming things, and off-by-one errors." -Martin Fowler

Re: org-store/insert-link truncating the full subject of mails

[Nicolas Goaziou]

Hello,

"Garreau, Alexandre" <galex-713@galex-713.eu> writes:

> This is an argument in favor of immobility.

True. Immobility is sometimes good, too.

> Yes, if only each user of each piece of software took the time to read
> the integrality of documentation each time they used something: I don’t
> and only did partially for org, yet… but for instance I did for Gnus, a
> long time ago, and never did it again: as example, did you?.

I don't see the point of reading the whole manual when you are looking
for some specific information. You can use, e.g., indices for that.

> Default are an important thing, they should fit what the most common,
> unspecific, and ignorant about the software in question, person.
> Documentation should be there only to adapt to more specific, and less
> common, cases (and, when possible, software should be made so that to
> conditionally do the right thing depending of the context so that
> changing the default behavior is less and less needed).  Not the other
> way around.

These are good rules of thumb when you are defining a default value.
When the default value was set ages ago, and some users may have grown
habits on it, you have to strike a balance between usage and theory. To
put it differently, changing default values annoys some users, and
a better default value may not be worth it.

It seems that no one is firmly attached to the current default value, so
I removed the truncation in "next" branch, i.e., Org 9.3.

Regards,

-- 
Nicolas Goaziou