Read each paragraph before undertaking the suggested action. You will need to switch back and forth from this page and the WriteR application.
If we refer to a key to press, it will be put between less than and
greater than signs, so <Enter> means to hit the key
called “Enter” on your keyboard. A combination of keys that get pressed
together are joined by a plus sign. For example
<Ctrl+Home> is the common keystroke for sending the
cursor to the top of your document.
The descriptions offered her are intended for Windows users who installed WriteR using the installer. If you obtained WriteR by other means, it is because you are skilled enough to know what aspects of these instructions won’t work for you until you do something smart for yourself. Feel free to read on, but note that not all comments are relevant.
WriteR is a very standard application with pull down menus and occasional dialogue boxes. It is meant to be simple to use, but does have all sorts of things people who write lots of R markdown documents might want.
WriteR was developed for blind people by a blind person. It was designed to be driven using the keyboard. Anyone who can use a mouse may do so, but there are no design features to help make icons bigger or bolder. The application does not have any intentional colours built in, so any colour that might be visible is pure luck. There is absolutely no reliance placed on any visual components.
If you have installed WriteR using the provided installer, you will find WriteR on the start menu. The WriteR folder on the start menu has a Run item and an Uninstall item. Run WriteR now.
When WriteR first opens, it presents a dialogue that asks you to
choose a file. If you had any Rmd files to edit, then you could browse
for those files. If this is the first time you are using WriteR, hit
Escape and the file opened will be called Untitled.Rmd
Our first action is to save this file using a new filename. You can
use the pull down menus: File > Save as using Alt+f,
then the hot key a, or use the single keystroke
<Ctrl+Shift+s> instead. Do this now and give your
file a name of your own choosing. Do not let the extension
Rmd change though. Watch that you know where the file is
being saved. You can change the folder if you like, just like you would
in any other software.
OK, if you’re already starting to poke around, you’ll realise that
the <Alt> key takes you to the menus, allowing you to
move around with the arrow keys, but that almost every action you might
want to take has hot keys. You’ll want to remember some of them because
you’ll use them lots. There are two kinds. If an action can be completed
using a single keystroke then that’s how I will refer to it. A keystroke
will be a combination of Control, Alt, Shift, and something else, or it
will be a function key like <f5>. Don’t play just yet
though. A hot key is an initial letter that is used for items in the
menus. As you gain experience, you’ll recognise them more and more as
well as probably learning how they relate to the keystrokes.
Many hot keys are used across a wide range of Windows applications.
The <Ctrl+a> keystroke will select everything in the
document (just some unimportant text right now) and the
<Del> key deletes it. Feel free to do that now.
We now have a completely blank file that has been given a name of
your choosing. Just to be sure, hit <Ctrl+s> to save
your updated file.
R markdown documents usually have a header or preamble block at the
very top. If you hit <Alt+i> to open the Insert menu,
the first menu item is for inserting the preamble. Hit enter on it, and
then move to the top of the file to see that six lines have just been
added. The first and sixth are just three dashes which enclose the
preamble details. The other four lines are document details that you
should add to. You will see quotes for the title, author, and date
fields. Feel free to type something in there now. Leave the fourth line
alone for now. It just tells WriteR that we’re going to convert our file
to HTML later.
I tend to use headings of level 2 a lot in my documents. So much so
that I made sure I had a hot key to put it in. If you hit
<Alt+2> and start typing something, and then hit
<Enter>, you’ll have written your first piece of
markdown. Look at the line just created. It will start with two hash
signs (number signs) and then the text you wrote.
Feel free to edit that line, but you must leave a space between the last hash sign and the intended heading text.
On a new line, add some text. It doesn’t matter what you type. Then add another heading and another bunch of text.
Check that you have blank lines between your headings and your paragraphs.
Press <Ctrl+s> to save your work again.
Review what you’ve got. The preamble, some headings, and some plain text, separated using some white space.
Even though your file is pretty boring, it’s a good time to see how to do the conversion to HTML. HTML is the default output file type. It can be changed later if that’s what you want to do.
The Build menu has the things we need for the conversion
process. You could ook at the whole menu, but the first item on the list
is the one we want. The conversion process we want to use most is called
“rendering”. Notice that the hot key for rendering our document is
<f5>. You can either hit <Enter>
on the menu item or <f5> while you are editing your
document. When you do, a new window will open with the log that tells
you about the conversion process and outcome. The cursor will be on the
bottom line, but hitting the down arrow will read that bottom line to
you. If the last thing you can read is “Done 0” then we have success,
and an HTML file has just been put in the same folder as your Rmd
file.
To get back to the document from the log window, hit
<f4>. The cursor should be exactly where you left
it.
If there is a problem, the last line of the log window will show “Done 1” and you’ll need to track upwards to see what went wrong.
There are earcons for successful and unsuccessful conversion as well as the text in the log file.
Markdown uses the same methods for writing mathematical expressions
as does LaTeX. For example, if you put
$y=\alpha{}+\beta{} x+\varepsilon{}$ in your document, it
will be converted to an expression with the proper Greek letters
included.
Add the text for the equation, including the dollar signs to your document and render it again. Take a look at what you made.
We use a double dollar when we want to get an expression on its own line.
I hope you copy and pasted the text for the equation. There are a set
of keystrokes that can help generate that from scratch, but the
Math menu has all sorts of things you might want to insert
into an equation. Take a look around that menu now.
When we want to put R commands in our document, we put them inside
what we call an R chunk. The easiest way to show you what an R chunk
looks like is to get you to go to an empty spot in your Rmd file, and
hit <Alt+r>. Do that now.
Three lines got added, which look like the following:
```{r }
<a blank line>
```The first line is called the “opening fence” and it is where the cursor is left, ready for you to add something. Don’t worry about that right now. The third line is called the “closing fence”. R commands go in between the opening and closing fences where there is currently a placeholder in this document to recognise the blank line you will see in your Rmd file.
If you add a simple R command like str(airquality) on
that blank line, and then render your document, you will see the output
from that command added into the HTML document. Do that now.
There are lots of other keystrokes and hot keys that will help WriteR users keep up with people using RStudio.
You could probably now make use of other resources for learning how to use R markdown. Whenever any tutorials on using R markdown mention a keystroke or hot key in RStudio, you will need to see what WriteR uses. There is not perfect alignment between keystrokes and hot keys in RStudio and WriteR. WriteR has many more shortcuts and they are kept as consistent as possible so that they become easier to remember.