[MAINTENANCE] On how much we can expose internals into defcustom (was: [BUG] Consider replacing bachload with batch in ob-maxima. [9.6.6 (release_9.6.6 @ /usr/share/emacs/30.0.50/lisp/org/)])

[Ihor Radchenko]

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.

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

This is not necessarily a rigid rule though - we do leave, for example,
`org-latex-engraved-preamble' exposed to the users in ways that can
break LaTeX src block export. The basic condition is that changing
something should be practically useful for users, which is why I asked
you to elaborate on why each of the new customizations need to be
introduced.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>