Re: [MAINTENANCE] On how much we can expose internals into defcustom

[Leo Butler]

On Tue, Sep 05 2023, Ihor Radchenko <yantar92@posteo.net> wrote:

> CCing Bastien, as he might want to intervene.
>
> Leo Butler <Leo.Butler@umanitoba.ca> writes:
>
>    >> +(defcustom org-babel-maxima-command-arguments
>    >> +  "--very-quiet"
>    >
>    >> +(defcustom org-babel-maxima-batch/load
>    >> +  "batchload"
>    >> +
>    >> +(defcustom org-babel-maxima-graphic-file-format-string
>    >> +  "(set_plot_option ('[gnuplot_term, png]), set_plot_option 
> ('[gnuplot_out_file, %S]))$"
>    >> +
>    >> +(defcustom org-babel-maxima-default-epilogue
>    >> +  "gnuplot_close ()$"
>
>>> IMHO, in their current state, if a user mindlessly customizes these
>>> options without knowing how ob-maxima internals work, ob-maxima may
>>> simply be broken.
>>
>> I think there is a fine line between being too rigid but working within
>> a limited scope (as ob-maxima is now), or providing enough customizable
>> options to let users do what they want. I would prefer the latter,
>> if the defaults provide a working configuration.
>>
>> Note that I do attempt to suggest other working options in the defcustom
>> definitions.
>
>>> As a general rule, we do not expose internal details that are _required_
>>> for things to work to users.
>>
>> I understand this principle, but, why not provide enough options for
>> users to configure a package to do what they want? Yes, that may mean
>> they break the package--but only temporarily, because returning to the
>> default options will return the package to a working state.
>
> That's a bit more tricky.
> Imagine, for example, that we commit
>
> +(defcustom org-babel-maxima-command-arguments
> +  "--very-quiet"
>
> and some users will later customize the default value to
>
> "--very-quite --my-personal-switch-I-want"
>
> Then, in future, due to changes in Org or maxima, we might need to
> change "--very-quite" to something else in order to keep ob-maxima in
> working condition: "--very-quite=yes 
> --another-useful-flag-we-absolutely-need-in-org"
>
> In order to make such a switch, we will have to force all the users
> change their customization - something we do not want to annoy users
> with.

I understand your general argument, but I doubt it is relevant to this
particular case.

In this specific case, that command-line option `--very-quiet' was
introduced in 17 years ago
(https://sourceforge.net/p/maxima/mailman/message/11796355/). The syntax
has not changed since it was introduced.

>
> So, leaving essential settings customizeable is not necessarily a good idea.

I understand your hesitation about full-blown customization using
`defcustom'. However, I would still like to have more dials to turn.

Perhaps we could add header arguments to get the desired customization?
E.g.

- :batch :: Control how the Maxima source is evaluated by Maxima.
  1. Default. If nil or no, then use batchload with the --very-quiet
     command-line flag.
  2. If t or yes, then use batch with the --quiet command-line flag;

- :plot-engine :: Set the plotting package.
  1. Default. If nil or no, the use `plot';
  2. If `draw', then use `draw'.

- Similarly, we could do something like ob-R.el does, and construct the
  graphics instructions using some additional header arguments and
  grovelling the terminal from the filename (see
  org-babel-R-construct-graphics-device-call).

My sense is that this would be more in keeping with how other ob-*.el
packages do things.

Best,
Leo