From 7a9557b018a4e2d03e3a29429b0ca8c8b4a2a662 Mon Sep 17 00:00:00 2001 From: Lionel Henry Date: Fri, 3 Jul 2026 17:54:53 +0200 Subject: [PATCH] Add session mode section in `ark --help` --- crates/ark/src/main.rs | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/crates/ark/src/main.rs b/crates/ark/src/main.rs index 76d9164384..a7ff93df87 100644 --- a/crates/ark/src/main.rs +++ b/crates/ark/src/main.rs @@ -42,7 +42,9 @@ Available options: -- arg1 arg2 ... Set the argument list to pass to R; defaults to --interactive --startup-file FILE An R file to run on session startup ---session-mode MODE The mode in which the session is running (console, notebook, background) +--session-mode MODE The mode in which the session is running: "console" (the + default), "notebook", or "background". See the + "Session modes" section. --no-capture-streams Do not capture stdout/stderr from R --default-repos Set the default repositories to use, by name: "rstudio" ('cran.rstudio.com', the default), or @@ -72,6 +74,28 @@ Available options: r#" --help Print this help message +Session modes: + +"console" mode (the default) is meant for a rich frontend like Positron, while +"notebook" mode is meant for standard Jupyter frontends. They differ in how +some output is reported to the frontend: + +- Errors. A Jupyter error message carries the error message in "evalue" and the + backtrace in "traceback". In "console" mode these are sent as-is. In + "notebook" mode the error message is also prepended to "traceback", because + frontends such as JupyterLab only display "traceback" when it is present, + discarding "evalue". Without the prepend the error message wouldn't show at + all. + +- Autoprint of intermediate expressions. When a single request contains several + top-level expressions (e.g. `a` and `b` in `a; b; c`), "console" mode streams + each intermediate result to the frontend, matching R behaviour. "notebook" + mode emits only the last expression's result, matching how a notebook cell is + typically evaluated by Jupyter kernels. + +Note that `ark --install` sets the generated kernelspec to run Ark in notebook +mode. + "# ); }