Git commit dafafe96c8c96275b65f7988c67027a08102dc51 by Thomas Friedrichsmeier. Committed on 08/06/2024 at 22:10. Pushed by tfry into branch 'master'.
Documentation improvements M +2 -1 doc/rkward/man-rkward.1.docbook M +19 -3 rkward/pages/rkward_trouble_shooting.rkh M +1 -0 rkward/rbackend/rksessionvars.cpp M +11 -1 rkward/rkward.cpp M +0 -1 rkward/settings/rksettings.cpp https://invent.kde.org/education/rkward/-/commit/dafafe96c8c96275b65f7988c67027a08102dc51 diff --git a/doc/rkward/man-rkward.1.docbook b/doc/rkward/man-rkward.1.docbook index 03a2bf739..efe5deb8e 100644 --- a/doc/rkward/man-rkward.1.docbook +++ b/doc/rkward/man-rkward.1.docbook @@ -86,7 +86,8 @@ SPDX-License-Identifier: GFDL-1.2-no-invariants-or-later OR GPL-2.0-or-later </varlistentry> <varlistentry> <term><option>--r-executable</option> <replaceable>command</replaceable></term> -<listitem><para>In the case of several R installations, specify the installation to use, ⪚ <filename>/usr/bin/R</filename>. You can also use the string <replaceable>"auto"</replaceable>, in which case RKWard will try to find R at one of the known standard installation paths. <emphasis>NOTE</emphasis> that while RKWard will <emphasis>often</emphasis> work with newer versions of R, it will <emphasis>sometimes</emphasis> need to be re-compiled for that version, or it may be incompatible altogether.</para></listitem> +<listitem><para>In the case of several R installations, specify the installation to use, ⪚ <filename>/usr/bin/R</filename>. You can also use the string <replaceable>"auto"</replaceable>, in which case RKWard will try to find R at one of the known standard installation paths. <emphasis>NOTE</emphasis> that while RKWard will <emphasis>often</emphasis> work with newer versions of R, it will <emphasis>sometimes</emphasis> need to be re-compiled for that version, or it may be incompatible altogether.</para> +<para>This option changes the R installation only for the current session, not persistently.</para></listitem> </varlistentry> <varlistentry> <term><option>--reuse</option></term> diff --git a/rkward/pages/rkward_trouble_shooting.rkh b/rkward/pages/rkward_trouble_shooting.rkh index 395b9ace6..cd8ac5970 100644 --- a/rkward/pages/rkward_trouble_shooting.rkh +++ b/rkward/pages/rkward_trouble_shooting.rkh @@ -7,15 +7,28 @@ SPDX-License-Identifier: GPL-2.0-or-later <document> <title>Trouble Shooting / FAQ</title> <summary> - RKWard is far from complete and certainly there are many issues that need to be fixed. However, some of the things you notice are not due to the nature of RKWard but R or something else. This section will try to cover some common issues. See also <link href="https://rkward.kde.org/faq";>the online FAQ</link>. + This page will try to cover some common issues you may encounter when using RKWard. See also <link href="https://rkward.kde.org/faq";>the online FAQ</link>. </summary> <section title="The "Analysis" menu is missing, or shows up as "(no label)"" shorttitle="Missing menu items" id="missing_menu_items"> This problem will often occur, when moving an RKWard installation to a different path, esp. on Windows and Mac. You may have to visit Settings->Configure RKWard->Plugins and re-add the relevant ".pluginmap"-files. Starting with version 0.6.3, RKWard should detect a changed installation path, and adjust paths, automatically. </section> - <section title="People tend to ask me what RKWard means. What should I answer?" shorttitle="What does "RKWard" mean?" id="the_name_problems"> - Yes, it's a very odd name. ;) However, R comes obviously from the <link href="http://www.r-project.org/";>R-language</link>, which is the statistical basis of RKWard. K is derived from <link href="http://kde.org/";>KDE</link>, which delivered the basic GUI technologies for RKWard. And <link href="http://en.wikipedia.org/wiki/Ward";>Ward</link>? That's another story. + <section title="The R backend crashed or failed to start" shorttitle="Crashed backend" id="crashed_backend"> + A times the R backend will fail to start due to a configuration or installation problem. Common causes are changed paths, or an update to R. Usually, + in these cases, the setup dialog is shown when starting RKWard, and this allows to select a different installation of R. (Note: You will be offered + a selection of installations found a common paths, but you can also specify a non-detected installation, manually.) + + In many cases, it will "just work" to select a version of R other than what has been used at compile time. Should you run into trouble, it is advised to + use the same, or a similar version of R to what was available during compilation, however. + + You can manually change the R backend at any time, using Settings->Check installation. Be sure to save your data, before changing the backend! You can + also use the command-line option --r-executable in order to start a session using a specific installation of R. + </section> + <section title="Why shouldn't I use R bundled inside the RKWard AppImage" shorttitle="AppImage" id="appimage"> + The AppImage includes an installation of R for convenience, but this installation is not, and cannot technically be made fully functional. Importantly, + you will not generally be able to install R packages (other than ones implemented purely in R). Also, you may run into conflicts between the R installation + inside the AppImage, and R packages that are installed system-wide. This may cause subtle and surprising bugs. </section> <section title="Sometimes I enter a command short after the start of RKWard but it is not processed. What's wrong?" shorttitle="Commands not processing" id="not_yet_ready_problems"> This happens because RKWard starts first and subsequent R is started in the background. Depending on the speed of your machine it can take some time to start R. In any case you can check the state of R within RKWard. Just look at the little box on the right bottom corner of RKWard. If it is green you can go ahead. @@ -32,6 +45,9 @@ SPDX-License-Identifier: GPL-2.0-or-later <section title="RKWard claims to take care of seamless integration with an office-suite. Why is there no native option to save it as an office file?" shorttitle="RKWard integration with an office-suite" id="integration_in_office_suite"> We agree that RKWard is still very lacking when it comes to office integration, and "seamless" integration is still far away. Refer to <link href="rkward://page/rkward_output"/> for information on how to accomplish the most important things right now. In the meantime, it is possible to carry out analyses in RMarkdown documents. These can be saved as PDF, TeX document or Office document, among others. Current RKWard versions support this in principle in the export menu. </section> + <section title="People tend to ask me what RKWard means. What should I answer?" shorttitle="What does "RKWard" mean?" id="the_name_problems"> + Yes, it's a very odd name. ;) However, R comes obviously from the <link href="http://www.r-project.org/";>R-language</link>, which is the statistical basis of RKWard. K is derived from <link href="http://kde.org/";>KDE</link>, which delivered the basic GUI technologies for RKWard. And <link href="http://en.wikipedia.org/wiki/Ward";>Ward</link>? That's another story. + </section> <section title="RKWard is running since ages. Has it hung up?" shorttitle="RKWard seems to hang" id="hung_up_problems"> This depends. Some test and plots just need some time if you have huge amounts of data or sophisticated calculations. Therefore patience is sometimes needed. In any case you can check the state of R within RKWard. Just look at the little box on the right bottom corner of RKWard. Red means there is still something to calculate or plot. If it turns green, R is done calculating. diff --git a/rkward/rbackend/rksessionvars.cpp b/rkward/rbackend/rksessionvars.cpp index 6fa776680..e31779ecc 100644 --- a/rkward/rbackend/rksessionvars.cpp +++ b/rkward/rbackend/rksessionvars.cpp @@ -91,6 +91,7 @@ int RKSessionVars::compareRVersion (const QString& version) { } QStringList RKSessionVars::frontendSessionInfo () { + // NOTE: No translation on purpose. This is mostly meant for pasting to the bug tracker QStringList lines; lines.append ("RKWard version: " RKWARD_VERSION); lines.append ("KDE Frameworks version (runtime): " + QString (KCoreAddons::versionString ())); diff --git a/rkward/rkward.cpp b/rkward/rkward.cpp index e54951fe8..f18f549af 100644 --- a/rkward/rkward.cpp +++ b/rkward/rkward.cpp @@ -38,6 +38,7 @@ SPDX-License-Identifier: GPL-2.0-or-later #include <KConfigGroup> #include <KColorScheme> #include <kwidgetsaddons_version.h> +#include <KMessageWidget> // application specific includes #include "core/rkmodificationtracker.h" @@ -363,6 +364,7 @@ void RKWardMainWindow::initPlugins (const QStringList &automatically_added) { void RKWardMainWindow::startR () { RK_TRACE (APP); + setRStatus(RInterface::Starting); // make sure our general purpose files directory exists QString packages_path = RKSettingsModuleGeneral::filesPath() + "/.rkward_packages"; bool ok = QDir ().mkpath (packages_path); @@ -800,7 +802,6 @@ void RKWardMainWindow::initStatusBar () { boxl->addWidget(dummy); realbar->addPermanentWidget(box, 0); - setRStatus(RInterface::Starting); } void RKWardMainWindow::saveOptions () { @@ -947,6 +948,7 @@ void setIndictatorColor(QWidget *widget, KColorScheme::ForegroundRole fg, KColor void RKWardMainWindow::setRStatus (int status) { RK_TRACE (APP); + static KMessageWidget* rstatus_message = nullptr; if (status == RInterface::Busy) { setIndictatorColor(statusbar_r_status, KColorScheme::NegativeText, KColorScheme::NegativeBackground); @@ -957,6 +959,7 @@ void RKWardMainWindow::setRStatus (int status) { statusbar_r_status->setToolTip(i18n("The <b>R</b> engine is idle.")); interrupt_all_commands->setEnabled(false); } else if (status == RInterface::Starting) { + if (rstatus_message) rstatus_message->hide(); setIndictatorColor(statusbar_r_status, KColorScheme::NeutralText, KColorScheme::NeutralBackground); statusbar_r_status->setToolTip(i18n("The <b>R</b> engine is being initialized.")); } else { @@ -966,6 +969,13 @@ void RKWardMainWindow::setRStatus (int status) { if (RInterface::instance()->backendFailedToStart()) { RKSetupWizard::doAutoCheck(); // The wizard itself will prevent recursion, if alread active } + if (!rstatus_message) { + rstatus_message = new KMessageWidget(i18n("R engine unavailable. See <a href=\"rkward://page/rkward_trouble_shooting\">troubleshooting</a> for possible solutions.")); + rstatus_message->setMessageType(KMessageWidget::Error); + rstatus_message->setCloseButtonVisible(false); + connect(rstatus_message, &KMessageWidget::linkActivated, this, [](const QString& url) { RKWorkplace::mainWorkplace()->openAnyUrl(QUrl(url)); }); + RKWorkplace::mainWorkplace()->addMessageWidget(rstatus_message); + } } } diff --git a/rkward/settings/rksettings.cpp b/rkward/settings/rksettings.cpp index 5993b25c0..3c106b933 100644 --- a/rkward/settings/rksettings.cpp +++ b/rkward/settings/rksettings.cpp @@ -261,7 +261,6 @@ void RKSettings::saveSettings (KConfig *config) { FOREACH_SETTINGS_MODULE(syncConfig(config, RKConfigBase::SaveConfig)); } -#include <KAssistantDialog> QList<RKSetupWizardItem*> RKSettings::validateSettingsInteractive () { RK_TRACE (SETTINGS);
