Re: Concrete suggestions to improve Org mode third-party integration :: an afterthought following Karl Voit's Orgdown proposal

[Dr. Arne Babenhauserheide]

Russell Adams <RLAdams@AdamsInfoServ.Com> writes:

> On Wed, Dec 08, 2021 at 05:16:20PM +0100, Dr. Arne Babenhauserheide wrote:
>>
>> Tim Cross <theophilusx@gmail.com> writes:
>>
>> > Backwards compatibility is important and changes should never be done
>> > lightly. However, that doesn't mean they don't occur (we have already
>> > had breaking changes, so old org files are likely to have issues
>> > already). Backwards compatibility can also become a burden and
>>
>> I already spent several hours fixing old presentations, because of org
>> format changes, so I want to put in a strong vote for backwards
>> compatibility.
>
> I agree completely. Luckily org-lint provides great insights into
> changes. Reading the release notes between major versions is a good
> idea. I have found that anytime I've had a problem it was well
> documented in the release notes, and that I simply neglected to read
> them.
>
>> If you have 1400 slides of lectures, all carefully laid out to convey
>> information as best as possible, and you realize a few days before the
>> lecture when you want to update them that the layout is broken, because
>> of some minor change in interpretation of empty headlines in org-beamer
>> export so you have to go over each slide individually to make sure that
>> nothing is cut off and no layout is broken — and check the compile to
>> latex many times until the layout is working again — that is a huge
>> cost.
>
> I don't see this as much different from the issues encountered with
> compiling code with libraries. During development you have to freeze
> libraries you're working against. After an update, you'll have to
> check again.
>
> I've had this come up in my professional documents on occasion, and
> I've developed habits to help. For instance:
>
>  - Every file gets an export header template and all settings are done
>    there.
>
>  - Exported documents must never depend on variables in my
>    init.el. All variables must be stored as file local variables if
>    they required customization against Org defaults.

I actually have separate .emacs.d folders and autotools setups for most
of my org-mode projects. But that’s to separate it from my emacs setup,
not as protection against a potentially volatile¹ document format.

>  - I run org-lint first if I suspect a problem.
>
>  - I pay latex experts to make my templates so I don't have to.
>
>  - Anything outside of basic Org syntax, tables and source blocks I do
>    directly in latex. Images are a good example. I will use latex code
>    for the image, sizing, orientation, etc instead of relying on Org's
>    extended syntax for image links, caption, and attributes.

> As a result my publishing has been pretty consistent for customer
> documents. I also only update my Org between projects. ;]

If I had needed a stronger argument for more backwards compatibility,
this list of habits is it. That should not be required to keep your
org-mode documents working.

I use org-mode for a lecture I give as small side-job because I like
teaching. It is not my main job.

And I use org-mode for hobby-projects. Yes, the hobby project is a 400
page RPG rulebook, but it is still a hobby project.

And I use org-mode to publish my personal website (also as a Hobby),
with about 150% that size.

And my projects do not end. Some of these documents are already in use
for a decade.

Org-mode is not just a library, it keeps user-data. It should really not
be volatile¹.

If I can’t trust org-mode to keep working but have to check the
documents every time I come back to them — and might have to spend hours
fixing them — then it not suitable for writing, as much as that would
pain me (because it would cast into doubt most of my decisions around
writing of the past decade).

To date, I only had a bigger problem once (and that hurt a lot, because
it was just before giving a lecture, so I had to ditch most of the
improvements I wanted to do and instead spend all the time fixing the
document), but the talk here about “sometimes you have to break
compatibility” goes into a direction I consider as very dangerous.

Please do not make org-mode volatile.¹

Org-Mode and Emacs have mostly been stable the past 15 years. And it is
good to be stable; a strength that is highlighted much too seldomly.

Best wishes,
Arne

¹: https://stevelosh.com/blog/2012/04/volatile-software/
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

signature.asc
Description: PGP signature