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 08:22:31PM +0100, Dr. Arne Babenhauserheide wrote:
> >  - 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 think this may be a problem regarding expectations.

I expect Org to be great at handling it's own format, and to give me
the editing experience within Emacs that I have come to expect.

That Org can also be used to export to other formats is both a
blessing and a curse. Org can only do high level constructs in the
languages it exports to, and really should only be expected to do just
that. It's a paper thin macro or template over a much more complicated
document language.

Org's lightweight markup has had things bolted onto it repeatedly for
years. Typically issues have resulted in changes in the export engine
defaults (ie: html moving to using css), and not Org itself changing
the editing experience in Emacs.

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

Org's format isn't volatile. You could view those anytime in Org and
see what you expect to see. The issue you are having is that an old
document may not export perfectly over time.

What if Org didn't diverge, the underlying format did?

> 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).

You can absolutely trust Org to open, view, and edit it's own files
even decades old. It's plain text, so there's no risk in experiencing
a permanent loss of data.

The exporting is the difference in expectations. Org's lightweight
markup is quite simple, and the documents it produces should be as
well. This is much like the original HTML specification. Look how
complicated it is to write HTML now with CSS and Javascript emulating
mundane functions after decades of bolt on "standards".

If I had a document which had a highly sensitive output format which
had to remain perfect over decades, I would argue that perhaps Org
wasn't the correct markup to write it in.

Much like plain text vs original simple HTML, vs Latex. Text was plain
and simple, with little formatting. Durable and ugly at times, but
always legible. The original HTML had more markup required, but it was
hyperlinks and some simple fonts and formats. Prettier, variable
fonts, colors, pictures. Latex can make pixel perfect PDFs with
multiple medias and professional results, however it has a very
specific format and this may be poor for writing in dynamically. HTML
required decades of tweaks to become "pixel perfect", and HTML a
decade old rarely renders properly in a "modern" browser.

At some point with each of these languages, the formatting became more
important than the content.

I write all my customer documentation in Org, with custom Latex
templates. I've only had to make major changes once, I think between
v8 and v9. Yes, my old documents won't export identically without the
changes. The likelihood they still export is high, and 100% that I can
view and edit them correctly in Org. It's only the polished result
which could degrade. I may have to tweak them to make them export the
same way again, but I expect they can without too much effort. I'm OK
with that.

> Please do not make org-mode volatile.¹

I think our maintainers have done an excellent job of minimizing the
impact of any changes. However when changes are needed, I trust their
judgement to have good reason to make a change and document it
thoroughly.

However I only export Org to be backwardly compatible with itself, not
the languages it makes exports to.

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

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

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