In BrailleR: Improved Access for Blind Users

First notes about WriteR --- an R markdown editor

last updated by Jonathan Godfrey on 6 January 2016

Version: 0.160105.3

Credits: Original concept by Jonathan Godfrey, coding by James Curtis.

Feedback: Bugs and enhancement suggestions should be sent to Jonathan Godfrey [e-mail]

## What is WriteR?

This editor was created because blind R users cannot use the excellent RStudio integrated development environment (IDE) with their screen reader software. The first task that the WriteR application makes possible for blind users is the processing of markdown with embedded R code. This could prove invaluable for blind students completing assignment work.

What do I need?

In addition to the files in the current download, you need to have three other applications installed on your computer to make the editor fully functional:

1. you must have R installed on your computer. If you do not edit the settings file, the first time you run the WriteR editor, it will search for the latest version of R that you have installed. This is necessary because some users will have multiple versions of R on their system.
2. the WriteR editor is currently written in Python so needs it to be installed on your computer. This will change once we've slowed down the pace of development. At that time, the download will be an executable file for each operating system or similar solution instead of source code that must be interpreted. Our hope is to re-release the application using C++ instead of Python.
3. to convert the markdown document you create into a fully accessible HTML document, you will also need pandoc. If you have pandoc installed on your computer it is already listed in your path as part of its default installation.

Getting started with WriteR outside R

The following is a set of instructions that is Windows-centric. If you are a Linux or Mac user and you know what you are doing given what you read for the Windows users, please do share your experiences with the developers. We'd love to pass your knowledge on to others and we will give you credit for your efforts.

If you downloaded WriteR as a zip file then it has one program file and several test files, including the file you are now reading. Put the downloaded file into a folder where you want to do your working. Unzip it here.

When you first open WriteR, by hittin Enter on the WriteR.pyw file, the application will create an options file called "WriteROptions" in the working directory alongside WriteR.pyw. You will need to open this file using your favourite text editor to review its contents. We are primarily concerned that WriteR has maanged to find your R installation when it created the WriteROptions file.

The first thing you will need to do when WriteR opens is to choose a file to edit. If you do not want to edit an existing file, hit the "Escape" key or the "Cancel" button. If you have used the application before, the last file you edited will be opened automatically.

A second option for opening WriteR does exist if you are comfortable using hte command line in Windows. If you navigate to the working directory where you can see the WriteR.pyw file, then you should be able to open the application by typing WriteR.pyw at the prompt. If you like this way of working, then you can look forward to expanding the use of the command line approach to add the name of the file you wish to edit as the argument to the command.

If you did not understand the second option just presented, stick to using the first option given above.

Linux users: do what?

Mac users: do what?

Go to the section which continues with help on basic editing of your first document.

Getting started with WriteR from inside R

WriteR is bundled in the BrailleR ppackage for R. Convenience functions have been written to get you started as easily as we can manage.

Basic editing of your first document.

Start editing your file once you can see WriteR has opened up a window properly. If you did not choose a file, some default text was put in the window for you.

When you have typed enough and want to see how it is represented in HTML, you will "build" the HTML document. A menu item does exist for this but the hot key is set to f5. You must save your work immediately prior to the build process using the ctrl+s hot key.

The newly updated HTML file is in the same folder as the Rmd file you are editing. If all has gone to plan, that will be the Working folder. You will need to browse to that folder manually to find the new file and open it in the browser of your choice. You can keep this file open. After you update the Rmd file in the editor and re-build the HTML, you will need to refresh the HTML file being viewed by hitting f5 in the browser. We'll try to make this a smoother exercise in future releases.

So, the steps to update your html file after some editing of your Rmd file is: save, build, switch, refresh. In terms of hot keys, that is ctrl+s, f5, alt+tab, and f5. N.B. you might need to alt+tab a few times to work through the windows that are open at present.

To find out how to create R markdown content, take a look at the file "Basics.Rmd" bundled with the application. Once you open it in WriteR, try to build it to see how the R content appears. There is plenty of documentation out there for writing R markdown documents so we don't need to include it here.

Removing the WriteR editor

The installation process is about as clean as it can be. To remove WriteR you only need to delete the folder where you put the files for the application. There is no uninstallation process to work through.

Known bugs and suggestions

Minor

• the word editor appears when the file is first opened and needs to be deleted. This "starting text" can be tailored to whatever you like in the settings menu item.
• the save as points to the wrong folder initially. Change this in the settings menu item.
• the About dialogue needs the version number put in it. I'm using the date (in yymmdd format) as the minor version number at present. The major version number will remain at zero until we have a satisfactory level of development for a public release.
• standard highlighting and hot keys for modification. e.g. highlight a word and bold it with ctrl+b.

Major

• a settings file and menu would definitely help. This was introduced in v0.150227 although it has a quirk about the labelling of the dialogue boxes when using Jaws as the screen reader.
• perhaps we can allow other file types down the track. This could be useful for Rnw files for example.
• spell checking would be nice.
• as well as Build, can we have a Build and View hot key?
• can we update the browser on build and view?

Resolved:

BrailleR documentation built on July 26, 2023, 5:46 p.m.