Using environment files for customization

[AKielhorn]

Are you aware of environmental files in ConTeXt?

https://wiki.contextgarden.net/Project_structure

With environment files you can put most of the customization into a ConTeXt file. No need to add hundreds of defcustoms in the lisp code.

This is a first draft of my thoughts:

You supply an environment template file with ox-context. When exporting, you copy the file to the target directory and rename it to <org-filename>_env.tex.

The user can now configure the file needing only ConTeXt knowledge.

If there is already a file, you don't copy the template, just use it.

There should probably some kind of versioning: When you add new commands to the export that are not in the user supplied file you can show an error. Maybe an exporter command to just copy the template file using the original name?

There should be a way to use one template file for different org files. Maybe a #+OPTION: environment: common_env.tex?

Instead of

#+CONTEXT_HEADER: \setuppapersize[A4]

The following code will create a "Snippet" for a4 paper size:

(add-to-list
'org-context-snippets-alist
'("paper-a4" . "\\setuppapersize[A4]") t)

You can then add the setup command to a document with the following:

#+CONTEXT_SNIPPETS: paper-a4

You will have lines like

% \setuppapersize[A4]
% \setuppapersize[A5][A4]
% \setuppapersize[letter]
% \setuppapersize[legal]

and the user can uncomment the desired paper size.

Disadvantages:

• You now have two files for every exported file.
• Users may accidentally mess with the environment file.
• The environment file gets stale. This always happens when I use Pandoc with an old document :-(

What do you think about this approach?

[Jason-S-Ross]

With environment files you can put most of the customization into a ConTeXt file. No need to add hundreds of defcustoms in the lisp code.

The html and LaTeX exporters make heavy use of defcustom for similar features so I assume that many users expect the functionality. If no one is using the feature, I'd be open to removing them in favor of what you're suggesting. (I use DOOM Emacs which discourages using customize-group, so I'm not taking advantage of defcustom personally.)

From a maintenance standpoint, the downside I see to what you're suggesting is that it moves two things that are tightly coupled (the command name and the command definition) that currently live in a single cons cell into two separate files that are two different types.

There should be a way to use one template file for different org files. Maybe a #+OPTION: environment: common_env.tex?

I would be open to this. It might make sense to define a new keyword like #+ENVIRONMENT for this purpose. It might also make sense to define a custom list of directories that ox-context would search for a file with the name specified by the #+ENVIRONMENT keyword.

Note: there's nothing stopping users from using their own environment files with the current implementation:

#+CONTEXT_HEADER_EXTRA: \environment /home/jason/context-environments/my-env

---

As a side note, just in case it's not 100% clear, the following line in your org file is all that's needed to set the paper size:

#+CONTEXT_HEADER: \setuppapersize[A4]

The other code I've mentioned would be used to update template settings globally.

[AKielhorn]

Having the whole configuration in defcustom has a disadvantage when using multiple files with different layout.

You have to change the defcustoms before processing the file.

This can be done via a setupfile (This is how I do it in LaTeX right now.)

I hope some org and ConTeXt join this discussion.

Do you want to announce this exporter on the ConTeXt mailing list or should I do it?

[Jason-S-Ross]

Having the whole configuration in defcustom has a disadvantage when using multiple files with different layout.

You have to change the defcustoms before processing the file.

This can be done via a setupfile (This is how I do it in LaTeX right now.)

I don't understand this objection yet. One way to customize files on export is through the defcustoms. Another way is to add an environment file to #+CONTEXT_HEADER_EXTRA. Yet another way is to define a preset or include a snippet. These different configuration methods all work right now - you don't have to change any defcustoms if you don't want to.

Maybe I would understand what the problem is if you could include an example of what you would like to do and how you would have to do it?

I hope some org and ConTeXt join this discussion.

Do you want to announce this exporter on the ConTeXt mailing list or should I do it?

~I will post an announcement to the mailing list today. However, I've been unable to post messages to the ConTeXt mailing list in the past, so if you find that there is no announcement tomorrow I would appreciate it if you could.~ I made the post. Thanks for reminding me!

[Jason-S-Ross]

@AKielhorn I have added a readme file with some additional explanation on what I was thinking with regards to environment files. Can you let me know if this would work for what you're doing?

https://github.com/Jason-S-Ross/ox-context-examples/commit/cc422450ec7934d77858168d1734364b34f2ff47

[AKielhorn]

With the readme and the examples it is much easier to customize the exporter.

I will use the ConTeXt backend for my next project and write back if something is missing.