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

[Russell Adams <RLAdams@AdamsInfoServ.Com>]

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 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. ;]

------------------------------------------------------------------
Russell Adams                            RLAdams@AdamsInfoServ.com

PGP Key ID:     0x1160DCB3           http://www.adamsinfoserv.com/

Fingerprint:    1723 D8CA 4280 1EC9 557F  66E8 1154 E018 1160 DCB3