Commit 650290c5 authored by Alexander Semke's avatar Alexander Semke
Browse files

Show the information about the available internal help system in Maxima and in R in the help panel.

Right now, when openning the panel the user only sees and empty area and it's not clear what to do.
This confuses user searching for the documentation and they don't realize this panel is for the internal help systems.
So, we show on default the relevant excerpts from R's and Maxima's documentations describing how to use the internal help system.
parent a1f3d222
Pipeline #174809 passed with stage
in 5 minutes and 59 seconds
......@@ -81,6 +81,19 @@ QUrl RBackend::helpUrl() const
"https://cran.r-project.org/manuals.html"));
}
QString RBackend::defaultHelp() const
{
//description of R's help system taken from https://www.r-project.org/help.html
//@tranlators: don't tranlate R's keywords here ("help", etc.) which are put inside <i></i>
return i18n("<h1>R' Help System: <i>help()</i> and <i>?</i>:</h1><br>"
"The <i>help()</i> function and <i>?</i> help operator in R provide access to the documentation pages for R functions, data sets, and other objects, both for packages in the standard R distribution and for contributed packages.<br><br>"
"To access documentation for the standard <i>lm</i> (linear model) function, for example, enter the command <b><i>help(lm)</i></b> or <i>help(\"lm\")</i>, or <i>?lm</i> or <i>?\"lm\"</i> (i.e., the quotes are optional).<br><br>"
"To access help for a function in a package that’s not currently loaded, specify in addition the name of the package: For example, to obtain documentation for the <i>rlm()</i> (robust linear model) function in the MASS package, <i>help(rlm, package=\"MASS\")</i>.<br><br>"
"Standard names in R consist of upper- and lower-case letters, numerals (0-9), underscores (_), and periods (.), and must begin with a letter or a period. To obtain help for an object with a non-standard name (such as the help operator <i>?</i>), the name must be quoted: for example, <i>help('?')</i> or <i>?\"?\"</i>.<br><br>"
"You may also use the <i>help()</i> function to access information about a package in your library — for example, <i>help(package=\"MASS\")</i> — which displays an index of available help pages for the package along with some other information.<br><br>"
"Help pages for functions usually include a section with executable examples illustrating how the functions work. You can execute these examples in the current R session via the <i>example()</i> command: e.g., <i>example(lm)</i>.");
}
QString RBackend::description() const
{
return i18n("<b>R</b> is a language and environment for statistical computing and graphics, similar to the S language and environment. <br/>"\
......
......@@ -17,7 +17,7 @@ class RBackend : public Cantor::Backend
QString id() const override;
QString version() const override;
Cantor::Session *createSession() override;
Cantor::Session* createSession() override;
Cantor::Backend::Capabilities capabilities() const override;
bool requirementsFullfilled(QString* const reason = nullptr) const override;
......@@ -25,6 +25,7 @@ class RBackend : public Cantor::Backend
KConfigSkeleton* config() const override;
QUrl helpUrl() const override;
QString defaultHelp() const override;
QString description() const override;
};
......
......@@ -72,6 +72,30 @@ QUrl MaximaBackend::helpUrl() const
"http://maxima.sourceforge.net/docs/manual/en/maxima.html"));
}
QString MaximaBackend::defaultHelp() const
{
//taken from https://maxima.sourceforge.io/docs/manual/maxima_5.html
//@tranlators: don't tranlate Maxima's keywords here ("describe", "true", "false", etc.) which are put inside of <i></i>
return i18n("<h1>Maxima's Help System</h1>"
"<h2>Function <i>apropos</i></h2>"
"Searches for Maxima names which have name appearing anywhere within them; <i>name</i> must be a string or symbol. Thus, <i>apropos(exp)</i> returns a list of all the flags and functions which have exp as part of their name, such as <i>expand</i>, <i>exp</i>, and <i>exponentialize</i>. So, if you can only remember part of the name of a Maxima command or variable, you can use this command to find the rest of the name. Similarly, you can type <i>apropos(tr_)</i> to find a list of many of the switches relating to the translator, most of which begin with <i>tr_</i>.<br><br>"
"<i>apropos(\"\")</i> returns a list with all Maxima names.<br><br>"
"<i>apropos</i> returns the empty list [], if no name is found.<br><br>"
"<h2>Function <i>describe</i></h2>"
"<i>describe(string)</i> is equivalent to describe(string, exact).<br><br>"
"<i>describe(string, exact)</i> finds an item with title equal (case-insensitive) to string, if there is any such item.<br><br>"
"<i>describe(string, inexact)</i> finds all documented items which contain string in their titles. If there is more than one such item, Maxima asks the user to select an item or items to display.<br><br>"
"<i>? foo</i> (with a space between <i>?</i> and <i>foo</i>) is equivalent to <i>describe(\"foo\", exact)</i>, and <i>?? foo</i> is equivalent to <i>describe(\"foo\", inexact)</i>.<br><br>"
"<i>describe("", inexact)</i> yields a list of all topics documented in the on-line manual.<br><br>"
"<i>describe</i> quotes its argument. <i>describe</i> returns <i>true</i> if some documentation is found, otherwise <i>false</i>.<br>"
"<h2>Function <i>example</i></h2>"
"<i>example(topic)</i> displays some examples of <i>topic</i>, which is a symbol or a string. To get examples for operators like <i>if</i>, <i>do</i>, or <i>lambda</i> the argument must be a string, e.g. <i>example(\"do\")</i>. <i>example</i> is not case sensitive. Most topics are function names.<br><br>"
"<i>example()</i> returns the list of all recognized topics.<br><br>"
"The name of the file containing the examples is given by the global option variable <i>manual_demo</i>, which defaults to <i>\"manual.demo\"</i>.<br><br>"
"<i>example</i> quotes its argument. <i>example</i> returns <i>done</i> unless no examples are found or there is no argument, in which case <i>example</i> returns the list of all recognized topics."
);
}
QWidget* MaximaBackend::settingsWidget(QWidget* parent) const
{
return new MaximaSettingsWidget(parent, id());
......
......@@ -17,16 +17,18 @@ class MaximaBackend : public Cantor::Backend
{
Q_OBJECT
public:
explicit MaximaBackend( QObject* parent = nullptr,const QList<QVariant> args = QList<QVariant>());
explicit MaximaBackend( QObject* parent = nullptr, const QList<QVariant> args = QList<QVariant>());
~MaximaBackend() override;
QString id() const override;
QString version() const override;
Cantor::Session *createSession() override;
Cantor::Session* createSession() override;
Cantor::Backend::Capabilities capabilities() const override;
bool requirementsFullfilled(QString* const reason = nullptr) const override;
QUrl helpUrl() const override;
QString defaultHelp() const override;
QWidget* settingsWidget(QWidget* parent) const override;
KConfigSkeleton* config() const override;
......
......@@ -379,6 +379,9 @@ void CantorShell::addWorksheet(const QString& backendName)
// Force run updateCaption for getting proper backend icon
QMetaObject::invokeMethod(part, "updateCaption");
//show the default help string in the help panel
emit showHelp(backend->defaultHelp());
}
else
{
......
......@@ -68,6 +68,11 @@ QString Backend::url() const
return d->url;
}
QString Backend::defaultHelp() const
{
return QString();
}
bool Backend::isEnabled() const
{
return d->enabled && requirementsFullfilled();
......
......@@ -138,6 +138,13 @@ class CANTOR_EXPORT Backend : public QObject, public KXMLGUIClient
* @return Url of the help
*/
virtual QUrl helpUrl() const = 0;
/**
* Returns the text that should be shown on default in the HelpPanel when it's initially created.
* This text can contain the information for who to use the integrated help available in some backends like Maxima and R.
*/
virtual QString defaultHelp() const;
/**
* Returns if the backend should be enabled (shown in the Backend dialog)
* @return @c true, if the enabled flag is set to true, and the requirements are fulfilled
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment