[rkward-cvs] [rkward] rkward/pages: Some updates to the application help pages.
Thomas Friedrichsmeier
thomas.friedrichsmeier at ruhr-uni-bochum.de
Wed Dec 3 19:29:58 UTC 2014
Git commit 599ac8547d13dc4a6bed9cf1e0d7023fb0ead435 by Thomas Friedrichsmeier.
Committed on 03/12/2014 at 19:26.
Pushed by tfry into branch 'master'.
Some updates to the application help pages.
Also replace some bits that get outdated too quickly (function lists, shortcut lists) with more generic information.
M +1 -1 rkward/pages/rkward_console.rkh
M +2 -2 rkward/pages/rkward_for_new_users.rkh
M +8 -10 rkward/pages/rkward_for_r_users.rkh
D +0 -30 rkward/pages/rkward_for_rkward_devs.rkh
M +1 -1 rkward/pages/rkward_output.rkh
D +0 -27 rkward/pages/rkward_public_functions.rkh
M +8 -52 rkward/pages/rkward_shortcuts.rkh
M +1 -5 rkward/pages/rkward_welcome.rkh
http://commits.kde.org/rkward/599ac8547d13dc4a6bed9cf1e0d7023fb0ead435
diff --git a/rkward/pages/rkward_console.rkh b/rkward/pages/rkward_console.rkh
index 8ef7420..92d7ce2 100644
--- a/rkward/pages/rkward_console.rkh
+++ b/rkward/pages/rkward_console.rkh
@@ -20,7 +20,7 @@ To interrupt a running command, press Ctrl+C, or chose "Interrupt running comman
</section>
<section id="running_selection" title="Re-running selected commands">
-To re-run (a sequence of) selected commands, select them using the mouse. Then chose "Run selection" from the context menu (default shortcut is F8). Leading "> " and "+ " on the selected lines will be removed automatically.
+To re-run (a sequence of) selected commands, select them using the mouse. Then chose "Run selection" from the context menu (default shortcut is Ctrl+Return). Leading "> " and "+ " on the selected lines will be removed automatically.
</section>
<section id="copy" title="Copying commands / output">
diff --git a/rkward/pages/rkward_for_new_users.rkh b/rkward/pages/rkward_for_new_users.rkh
index 8c53258..8342573 100644
--- a/rkward/pages/rkward_for_new_users.rkh
+++ b/rkward/pages/rkward_for_new_users.rkh
@@ -13,7 +13,7 @@ R - and hence RKWard - can deal with a large number of different types of data:
At the same time, R is not confined to working with just one piece of data at a time, but rather you have a "Workspace", where all your different variables, tables, etc. are accessible. You can have many data.frames at once, and additional data of other types. At the left side of the application window, there should be an icon labelled "Workspace". You can click on this to see all the objects present in your workspace. All the objects you create or modify will be visible inside the ".GlobalEnv". Most other objects are predefined in libraries, such as "package:base". See <link href="rkward://page/rkward_workspace_browser"/> for details.
-You do not need to worry about all these details. To create a new spreadsheet (data.frame), chose File->New->Dataset from the menu. All you need to do is to assign a name to this table, then you can start editing. To work with pre-existing data, chose File->Import->Load data, to load data in CSV (comma separated value) format.
+You do not need to worry about all these details. To create a new spreadsheet (data.frame), chose File->New->Dataset from the menu. All you need to do is to assign a name to this table, then you can start editing. To work with pre-existing data, pick the appropriate option from the File->Import menu.
</section>
<section id="use_output_external" title="How can I make use of my results in an external application?">
In this section you will learn about some basic methods how to make use of your results in external applications.
@@ -25,7 +25,7 @@ See <link href="rkward://page/rkward_output"/> for details on working with the o
<section id="basic_stats" title="Basic Analyses">
In order to familiarize yourself with RKWard (or with your data), one of the first things to do might be to chose Analysis->Descriptive Statistics from the Menu. You will be presented with a dialog that allows you to select one or more variables to analyse. This looks similar to the workspace browser introduced above. On the additional tabs you can choose which types of descriptive statistics should be calculated.
-At the lower right of the dialog, there is a button labelled "Code". Using this, you can show/hide a text area. If you look at the contents of this text area (you may have to resize the window to view it more comfortably), you can see the text changing according to the settings you chose in the dialog. This text is actually R syntax. It is the code that is needed to perform these calculations in R. Most of RKWard is based on generating this code for you, and then running it inside R. Later, when you feel more comfortable, have specific needs not covered by RKWard, or you want to automate repetitive tasks, you can use this syntax to literally program your analyses.
+At the lower right of the dialog, there is a button labelled "Code". Using this, you can show/hide a text area. If you look at the contents of this text area (you may have to resize the window to view it more comfortably), you can see the text changing according to the settings you chose in the dialog. This text is actually R syntax. It is the code that is needed to perform these calculations in R. Most of RKWard is based on generating this code for you, and then running it inside R. Later, when you feel more comfortable, have specific needs not covered by RKWard, or you want to automate repetitive tasks, you can use this syntax to literally program your analyses. Note that the code is divided into up to three sections: "Preprocess" for loading required libraries or defining helper functions, "Calculate" to perform the actual calculations, and "Printout" to generate output in RKWard's output window.
For now, just click submit, once you've made your choices, and watch the results show up in a new window.
</section>
diff --git a/rkward/pages/rkward_for_r_users.rkh b/rkward/pages/rkward_for_r_users.rkh
index e5cdbf1..4b07603 100644
--- a/rkward/pages/rkward_for_r_users.rkh
+++ b/rkward/pages/rkward_for_r_users.rkh
@@ -11,9 +11,9 @@
<ul>
<li>Syntax highlighting</li>
- <li>Pressing the Tab key will not complete local file paths (at the moment), but the names of R symbols and functions</li>
<li>While typing function calls, a list of arguments to that function is shown in a box (argument hinting)</li>
<li>While the cursor is on an R symbol or function, pressing F2 will search the R help for that symbol. Also available from the Help menu, or the right mouse button menu</li>
+ <li>You can easily create a transcript of the commands you run in the console using Run->CC commands to output...</li>
</ul>
See <link href="rkward://page/rkward_console"/> for more details.
@@ -21,12 +21,12 @@
<section title="Script Editors" id="script_editor">
Often it is more convenient to write scripts in a separate file, instead of typing them directly in the console. To open a new script editor (with syntax highlighting, and many more features), chose File->New->Script File, or open an already existing Script file using File->Open R Script File.
- You will note that the editor opens in a new window in the main workplace (the area of the window, that you are most likely reading this text, in). You can open any number of Script editor windows at the same time.
+ You will note that the editor opens in a new window in the main workplace (the area of the window, that you are most likely reading this text, in). You can open any number of script editor windows at the same time.
To run the code in a script editor window, either copy and paste it to the console, or chose one of the actions in the Run menu. such as Run All or Run Selection. Note: The contents of the menus may change according to the type of active window. Hence, if you look at the Run menu while reading this, there will be no entries.
</section>
<section title="Workspace View" id="workspace_browser">
- RKWard comes with a "workspace view" or "object browser". By default this is available by clicking on "Workspace" on the left side of the application window. This allows you to examine and manipulate all objects in the R workspace. In case you are not familiar with this aspect of R (usually not directly visible): All the symbols you create are children of the so-called ".GlobalEnv" environment (see <link href="rkward://rhelp/.GlobalEnv"/>). Symbols defined in loaded libraries are located in their own environments.
+ RKWard comes with a "workspace view" or "object browser". By default this is available by clicking on "Workspace" on the left side of the application window. This allows you to examine and manipulate all objects in the R workspace. By default, only the ".GlobalEnv" environment is shown (where you'll typically do your work; see <link href="rkward://rhelp/.GlobalEnv"/>). But, checking "Show All Environments", you can easily explore data and functions in loaded R libraries (and even in package namespaces).
The object browser provides function to select with types of object are shown (on the top). Hovering the mouse over an item will show some additional information on the symbol. Right-clicking on an item will show available actions. See <link href="rkward://page/rkward_workspace_browser"/> for details.
</section>
@@ -34,17 +34,17 @@
By default R help pages are shown as HTML, inside RKWard. You can invoke the help in the usual way by running e.g. "?print" or "help (print)" or "help.start ()" in the console. Additionally, there is a tool window to search your installed R help pages. This is accessible using a button located at the bottom of the window (next to the console button). To view a help page found using this tool, double click on it.
</section>
<section title="Managing installed and loaded Libraries" id="library_management">
- RKWard provides an advanced dialog to have installation, updating, and loading of packages. This is available from Workspace->Configure Packages.
+ RKWard provides an advanced dialog to have installation, updating, and loading of packages. This is available from Settings->Manage R Packages.
</section>
<section title="Window management" id="window_management">
All windows shown in the main view area can be detached to a separate top level window using Windows->Detach. Similarly, detached windows can be attached to the main workplace using Window->Attach.
- Windows can be closed using Windows->Close (Ctrl+W by default).
+ Windows can be closed using Windows->Close (Ctrl+W by default). Ctrl+Tab and Ctrl+Shift+Tab cycle through all active document / tool windows in your session.
Tool windows (e.g. the R Console) can be detached and re-attached using the arrow-icon in their window border.
</section>
<section title="Editing data" id="editing_data">
- RKWard provides a buit-in editor for data.frames. In fact, you can edit many data.frames at the same time, and even while running lengthy calculations. Still the data is stored as a regular data.frame in R. To explore the data editor, either chose File->New->Dataset, or right click a data.frame in the Workspace browser, and chose Edit from the menu.
+ RKWard provides a built-in editor for data.frames. In fact, you can edit many data.frames at the same time, and even while running lengthy calculations. Still the data is stored as a regular data.frame in R. To explore the data editor, either chose File->New->Dataset, or right click a data.frame in the Workspace browser, and chose Edit from the menu.
Support for adding other types of data, esp. single vectors is planned, but not currently supported.
</section>
@@ -52,10 +52,10 @@
R has a few immensely powerful graphics systems (although not interactive) provided by various packages such as <b>graphics</b> and <b>lattice</b>. RKWard wraps around the standard platform-dependent screen device to provide a uniform experience. In additional to the standard functionality of these packages, RKWard provides a screen device history mechanism to store and browse your plots. See <link href="rkward://page/rkward_plot_history"/> for details.
</section>
<section title="Utility functions" id="utility_functions">
- RKWard provides various utility functions which are described here: <link href="rkward://page/rkward_public_functions"/>
+ RKWard provides various utility functions which are listed in the index of the <link href="rkward://rhelp/rkward-package">rkward package overview</link>.
</section>
<section title="Everything else" id="more">
- You will notice that RKWard provides a lot of further menu options. These provide access to functionality in R. In fact, they do so by generating R syntax from settings made in a graphical dialog. For instance, select Analysis->Descriptive Statistics. You will notice a small window at the bottom (can be toggled on or off using the "Code" button) that contains the R code needed to generate these statistics. This way, even if you prefer to script your code by hand, you can use dialogs to gain snippets of code for functions you are less familiar with in R.
+ You will notice that RKWard provides a lot of further menu options. These provide access to functionality in R. In fact, they do so by generating R syntax from settings made in a graphical dialog. For instance, select Analysis->Descriptive Statistics. You will notice a small window at the bottom (can be toggled on or off using the "Code" button) that contains the R code needed to generate these statistics. This way, even if you prefer to script your code by hand, you can use dialogs to gain usage examples or snippets of code for functions you are less familiar with in R.
Also, all commands that are executed get shown in the Command Log, available as a tool window next to the R Console.
</section>
@@ -67,7 +67,5 @@
<li><link href="rkward://page/rkward_for_new_users"/> For an introduction to some more basic concepts</li>
<li><link href="rkward://page/rkward_shortcuts"/></li>
</ul>
-
-TODO: Each of the above sections should eventually get a dedicated page of its own with more detailed information
</related>
</document>
diff --git a/rkward/pages/rkward_for_rkward_devs.rkh b/rkward/pages/rkward_for_rkward_devs.rkh
deleted file mode 100644
index 6ac7ca3..0000000
--- a/rkward/pages/rkward_for_rkward_devs.rkh
+++ /dev/null
@@ -1,30 +0,0 @@
-<!DOCTYPE rkhelp>
-<document>
- <title>For RKWard Developers</title>
- <summary>
- List of various "internal" functions which are generally not of interest to regular users but may be to those who are interested in writing (or extending) plugins or contributing to other areas of RKWard. Make sure to read the warnings and special comments wherever noted.
- </summary>
-
- <section title="Plugins" id="plugins">
- <ul>
- <li>Call or list available plugins: For automated testing of plugins see <link href="rkward://rhelp/rk.call.plugin"/>.</li>
- </ul>
- </section>
-
- <section title="Objects" id="objects">
- <ul>
- <li>Various labels and names related functions are documented here: <link href="rkward://rhelp/rk.get.label"/>.</li>
- <li>Sync: these functions are useful in automated testing: <link href="rkward://rhelp/rk.sync"/></li>
- </ul>
- </section>
-
- <related>
-<ul>
- <li>For more functions of interest see: <link href="rkward://page/rkward_public_functions"/></li>
- <li>Do read the online <link href="http://rkward.sf.net/wiki/Developer_Information">wiki</link> as well.</li>
- <li>To write and share your own GUI dialogs, see the <link href="help:rkwardplugins/">Introduction to Writing Plugins for RKWard</link>.</li>
-</ul>
- </related>
-
-TODO: Make this more developer centric with as many links as possible (doc writing, plugin pages, etc)
-</document>
diff --git a/rkward/pages/rkward_output.rkh b/rkward/pages/rkward_output.rkh
index ade9b04..41f566b 100644
--- a/rkward/pages/rkward_output.rkh
+++ b/rkward/pages/rkward_output.rkh
@@ -8,7 +8,7 @@ TODO: This page is incomplete.
</summary>
<section title="Using the output in an office suite" id="integration_in_office_suite">
-One of the many goals of RKWard is to have a seamless integration with an office-suite. Future plans of RKWard include the usage of the "OASIS Open Document Format for Office Applications (ODF)". But right now there is only support for HTML output (including images as png) of your results. HTML can be read and worked on with any modern office suite.
+One of the many goals of RKWard is to have easy integration with an office-suite. Right now output is simply stored in HTML format (including images as png) of your results. HTML can be read and worked on with any modern office suite.
The easiest way to get output into your office suite, is to first select the relevant portions, copy them (Edit->Copy), then paste them. This works well, at least in OpenOffice. You can also drag and drop images from the output to an OpenOffice document.
diff --git a/rkward/pages/rkward_public_functions.rkh b/rkward/pages/rkward_public_functions.rkh
deleted file mode 100644
index f05465c..0000000
--- a/rkward/pages/rkward_public_functions.rkh
+++ /dev/null
@@ -1,27 +0,0 @@
-<!DOCTYPE rkhelp>
-<document>
- <title>Utility functions in RKWard</title>
-
- <summary>
- This help page links to the man pages of various utility functions available in RKWard which are accessible to the user.
- </summary>
-
- <section title="Graphics related functions" id="public_g_fns">
- <ul>
- <li>See <link href="rkward://rhelp/rk.graph.on"/> or <link href="rkward://rhelp/rk.graph.off"/>.</li>
- <li>See <link href="rkward://rhelp/rk.record.plot"/></li>
- <li>See <link href="rkward://rhelp/rk.duplicate.device"/></li>
- </ul>
- </section>
-
- <section title="Other functions" id="public_fns">
- <ul>
- <li>Various editing (object and files) related functions are documented here: <link href="rkward://rhelp/rk.edit"/>.</li>
- <li>Various output and results related functions are documented here: <link href="rkward://rhelp/rk.results"/>.</li>
- <li>Various file name related functions are documented here: <link href="rkward://rhelp/rk.get.tempfile.name"/>.</li>
- <li>Message boxes and selection lists: see <link href="rkward://rhelp/rk.show.message"/>.</li>
- <li>Misc functions: <link href="rkward://rhelp/rk.misc"/>.</li>
- </ul>
- </section>
-
-</document>
diff --git a/rkward/pages/rkward_shortcuts.rkh b/rkward/pages/rkward_shortcuts.rkh
index 62e3991..52d3b4d 100644
--- a/rkward/pages/rkward_shortcuts.rkh
+++ b/rkward/pages/rkward_shortcuts.rkh
@@ -2,63 +2,19 @@
<document>
<title>RKWard Shortcut keys</title>
<summary>
- You can control RKWard in many situations without using a mouse device, using only the keyboard.
+ You can control RKWard in many situations without using a mouse device, using only the keyboard. The easiest way to find out about shortcuts of interest is to browse the menu. Shortcuts are listed next to their action in the menu.
- Most shortcuts are configurable, using Settings->Configure Shortcuts. For technical reasons, only the shortcuts of those components will be listed that are active
- at that time. Hence, for example, if you want to edit the shortcuts for the data editor, first open a data editor, then select Settings->Configure Shortcuts.
+ Most shortcuts are configurable, using Settings->Configure Shortcuts. For technical reasons, only the shortcuts of those components will be listed that are active at that time. Hence, for example, if you want to edit the shortcuts for the data editor, first open a data editor, then select Settings->Configure Shortcuts.
Most shortcuts for the script editor are managed separately using Settings->Configure Editor->Shortcuts.
On most systems, you can also configure shortcuts by right-clicking on the respective menu item.
</summary>
<section title="RKWard Default Shortcut keys" id="default_shortcut_keys">
- <table>
- <tr colspan="2"><td><b>File Menu</b></td></tr>
- <tr><td>Create new script</td><td>Ctrl + N</td></tr>
- <tr><td>Print</td><td>Ctrl + P</td></tr>
- <tr><td>Quit RKWard</td><td>Shift + Q</td></tr>
- <tr><td>Open existing Script</td><td>Ctrl + O</td></tr>
-
- <tr colspan="2"><td><b>Edit Menu</b></td></tr>
- <tr><td>Copy</td><td>Ctrl + C</td></tr>
- <tr><td>Find</td><td>Ctrl + F</td></tr>
- <tr><td>Find Previous</td><td>Shift + F3</td></tr>
- <tr><td>Find Next</td><td>F3</td></tr>
- <tr><td>Select All</td><td>Ctrl + A</td></tr>
-
- <tr colspan="2"><td><b>View Menu</b></td></tr>
- <tr><td>Decrease font size</td><td>Ctrl + -</td></tr>
- <tr><td>Increase font size</td><td>Ctrl + +</td></tr>
- <tr><td>Show Document Information</td><td>Ctrl + I</td></tr>
- <tr><td>View Source</td><td>Ctrl + U</td></tr>
-
- <tr colspan="2"><td><b>Workspace Menu</b></td></tr>
- <tr><td>Open Workspace</td><td>Ctrl + O</td></tr>
- <tr><td>Save Workspace</td><td>Ctrl + S</td></tr>
-
- <tr colspan="2"><td><b>Run Menu</b></td></tr>
- <tr><td>Run the current line</td><td>Shift + F7</td></tr>
- <tr><td>Add a line break and run the line</td><td>Ctrl + Enter</td></tr>
- <tr><td>Run the current selection</td><td>Shift + F8</td></tr>
- <tr><td>Run the current script</td><td>Shift + F9</td></tr>
- <tr><td>Interrupt all running commands</td><td>Shift + Esc</td></tr>
-
- <tr colspan="2"><td><b>Windows Menu</b></td></tr>
- <tr><td>Close Window</td><td>Ctrl + W</td></tr>
- <tr><td>Previous Window</td><td>Alt + < or Alt + ,</td></tr>
- <tr><td>Next Window</td><td>Alt + > or Alt + .</td></tr>
- <tr><td>Left Window</td><td>Ctrl + < or Ctrl + ,</td></tr>
- <tr><td>Right Window</td><td>Ctrl + > or Ctrl + .</td></tr>
- <tr><td>Activate Document view</td><td>Alt + 0</td></tr>
- <tr><td>Show/Hide Workspace Browser</td><td>Alt + 1</td></tr>
- <tr><td>Show/Hide Command Log</td><td>Alt + 2</td></tr>
- <tr><td>Show/Hide Pending Jobs</td><td>Alt + 3</td></tr>
- <tr><td>Show/Hide Console</td><td>Alt + 4</td></tr>
- <tr><td>Show/Hide R Help Search</td><td>Alt + 5</td></tr>
- <tr><td>Switch between Windows</td><td>Ctrl+Tab</td></tr>
-
- <tr colspan="2"><td><b>Help Menu</b></td></tr>
- <tr><td>Start Help</td><td>F1</td></tr>
- <tr><td>What's this</td><td>Shift + F1</td></tr>
- </table>
+ To point out some of the less discoverable or more important shortcuts:
+ <ul>
+ <li>To cycle between document / tool windows inside RKWard, use Ctrl+Tab and Ctrl+Shift+Tab</li>
+ <li>To run code from scripts / help pages / the console, select it, and use Ctrl+Enter</li>
+ <li>F2 to search the R help for the symbol under the cursor in scripts and the console</li>
+ </ul>
</section>
</document>
diff --git a/rkward/pages/rkward_welcome.rkh b/rkward/pages/rkward_welcome.rkh
index b16ec40..170e355 100644
--- a/rkward/pages/rkward_welcome.rkh
+++ b/rkward/pages/rkward_welcome.rkh
@@ -22,15 +22,11 @@
For more general information on RKWard, who writes it, how to help, further questions, etc. refer to <link href="http://rkward.sourceforge.net/">the project homepage</link>.
</section>
- <section title="For Developers" id="rkward_devs">
- For more information on RKWard, mainly of interest to developers see <link href="rkward://page/rkward_for_rkward_devs">page for developers</link>.
- </section>
-
<section title="Trouble Shooting" id="Trouble Shooting">
If you encounter problems please feel free to search in <link href="rkward://page/rkward_trouble_shooting">Trouble Shooting</link> first.
</section>
<section title="Missing something?" id="missing_something">
- Are you missing a particular GUI dialog in the current menu? Check out the <link href="help:rkwardplugins">Introduction to Writing Plugins for RKWard</link> to learn how easy it is to enhance RKWard with your custom dialogs. And if you like, how to share your work with the community of RKWard users.
+ Are you missing a particular GUI dialog in the current menu? Check out the <link href="help:rkwardplugins">Introduction to Writing Plugins for RKWard</link> to learn how easy it is to enhance RKWard with your custom dialogs. And if you like, how to share your work with the community of RKWard users. See the <link href="rkward://rhelp/rkward-package">rkward package overview</link> for RKWard specific function for development and scripting.
</section>
</document>
More information about the rkward-tracker
mailing list