Suggestions for new configuration option to open documentation in CLI vs. GUI

Since 5.2, the doc command always tries to open documentation in a Qt browser. This is absolutely fine when the GUI is running. However, if running the CLI (with Qt library available for plotting) the documentation still opens in a Qt browser. Many users who run the CLI want to remain in the CLI and would prefer that this documentation be shown in the terminal window (or associated program such as emacs). A bug report about this is here GNU Octave - Bugs: bug #62855, "doc" command opens gui... [Savannah].

An easy solution would be to have a configuration variable that is consulted when in CLI mode about whether to open documentation in the CLI or in the GUI Qt browser.

The question I’m asking of maintainers is what the name of this configuration variable should be.

EDIT (8/13/22): For reference, the code in doc.m that is relevant is

  ## Give event manager the first shot.

  status = ! __event_manager_show_documentation__ (function_name);

  if (status)

Octave always tries to display using the Qt browser first. My change would be along these lines

status = true;
if (doc_display_in_gui)
    status = ! __event_manager_show_documentation__ (function_name);

if (status)

How about --doc-display-mode={text,gui,default}?

We have “info_program” . Can we make it so info_program(“gui”) would run gui and
info_program(“info”) would run info?

And allegedly we already have ‘–info-program NAME’, but it does not seem to be doing anything
at the moment.

Maybe we could do this. I was thinking not of a command-line option to Octave, but of a boolean configuration variable within Octave. Example code might be where there is a file static variable

  // TRUE means we should try to enter the debugger on SIGINT.
  bool Vdebug_on_interrupt = false;

and then a function to set/unset the variable

DEFUN (debug_on_interrupt, args, nargout,
       doc: /* -*- texinfo -*-
@deftypefn  {} {@var{val} =} debug_on_interrupt ()
@deftypefnx {} {@var{old_val} =} debug_on_interrupt (@var{new_val})
@deftypefnx {} {@var{old_val} =} debug_on_interrupt (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will try
to enter debugging mode when it receives an interrupt signal (typically
generated with @kbd{C-c}).

If a second interrupt signal is received before reaching the debugging mode,
a normal interrupt will occur.

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.
The original variable value is restored when exiting the function.
@seealso{debug_on_error, debug_on_warning}
@end deftypefn */)
  return set_internal_variable (Vdebug_on_interrupt, args, nargout,

Maybe something like doc_display_in_gui.

Is it possible to DTRT without a configuration option? Just based on whether octave-cli or the full Qt app is running.

Or if you want to add an option, its default unset behaviour is to DTRT (i.e., its a tri-state: always Qt thingy, always text, or DTRT)

Afaict, octave-cli doesn’t link with Qt. I’d guess that it won’t open the documentation in a GUI window already (because it probably can’t).

@rik’s suggestion sounds good to me. Setting it to the GUI option should still fall back to the CLI if octave-cli is used.

No, we do need a configuration option. octave-cli is not linked with Qt and will always show doc output in CLI. The regular octave executable is linked to Qt. When you start the GUI with octave --gui this will display doc output in a Qt browser widget. The intermediate case is that you start octave without the --gui option which will start a CLI interface. However, this version defaults to also showing doc output in a Qt browser despite the user’s preference for the CLI as noted by not starting the GUI.

In previous versions of Octave (<= 5.2) we tested for isguirunning before deciding whether to display output in Qt widget. We could always go back to that, or we could implement this option so that user’s have the choice.

1 Like