BRF to eBRL Converter Quick Start Guide¶

Quick Start Guide¶

This software is released at 1.0 but we're continuing to work on it. It is a complicated process to convert BRFs into eBraille files and user feedback will help us improve the process and the conversions.`

eBraille Converter¶

The eBraille Converter is meant to work with BRF files that have BANA formatting. If you are from a different braille region, the converter may technically convert your file to the new format, but the formatting will be incorrect. This is because the converter works by applying markup to your file based on the cell position and blank lines of the individual items within it. If your file is formatted according to the rules of a braille region that uses formatting rules different than BANA, then you will need to make changes to the software to accommodate that. Instructions on how to make those changes will come in a separate document later.

Basics¶

Run the program by pressing enter while focused on or double-clicking the file Convert2EBRL.exe.

When the program runs, this warning will appear:

This is a reminder that the Converter is still in development. Please convert files and review them but do not use the converter and expect to have perfect eBraille files. Changes are coming in future updates that will make any conversions made using an early version of the eBraille Converter inferior. Use the OK button to acknowledge the warning and proceed to using the program.

Now you will be on the General tab. The General tab is the main tab you will use when doing your conversions. The second tab is Page settings, and you will likely need to visit Page settings first before you start converting files. The third tab is Metadata.

Two buttons that are persistent across tabs are Close and Convert. Convert is will not do anything until you have a valid file to convert and a location to put the converted file. Close will close the program without converting a file.

Page Settings¶

There are several items on this tab. Here is what they are

Has running heads: This checkbox will tell the converter if your file has running heads. If checked, it will assume that you do and any centered heading that appears on line 1 will be made into a running head. If unchecked, it will not do this operation.
Cells per line: This is a textbox where you can type a numeric value to represent the number of cells per line of your transcription. It's important you pick the value that corresponds to the BRF you are trying to convert, or the converter will make incorrect assumptions about your file. Also has up and down arrows so you can adjust with your mouse or keyboard.
Lines per page: Same as cells per line but about lines per page.
Odd Braille page number: Options are None, Top left, Top right, Bottom left, Bottom right. These are the corners of the page that the converter will look for your braille page number on odd numbered pages. Note that whether a page is counted as even or odd is related to the true page count and not the number that appears on the page.
Even Braille page number: Same as Odd Braille page number except about the even braille pages numbers.
Odd print page number: Same as the braille number settings except it is about odd print page numbers.
Even print page numbers: Same as the other page number settings except it is about even print page numbers.

Conversion Profiles¶

Below the toolbar and above the tabs is an item called Conversion Profile. By default, it has two items “APH Interpoint” and “APH Single Sided”. These default profiles conform to how APH generally formats braille that is either meant for interpoint (double-sided) or single-sided production. The two profiles are in a dropdown menu, and you can select between them by activating that dropdown with either your keyboard or mouse.

Changing your profile will change the settings found on the Page Settings tab. The only difference between APH Interpoint and APH Single Sided is that APH interpoint uses the value “None” for the option Even Braille page number.

Creating New Conversion Profiles¶

If the files you are converting do not conform to the settings utilized by the default profiles, you can create your own. To start, change the settings that will align with the files you are converting. When you make changes to any of the settings so that diverges it from the settings of the original profile, the dropdown menu will change to display the word Custom.

To reuse your new profile without having to recreate it each time you use the program, there is a button with an ellipsis on it next to the dropdown. Activate it and it will show the options:

Save profile…- saves the current settings to either a new profile or the current one.
Delete profile…- deletes the currently selected profile. This option is greyed out if the selected profile cannot be deleted.
Reset profile…- removes any custom profiles so that only APH Interpoint and APH Single Sided remain.

When Save profile is selected, a dialog will appear. It has the title Name the profile. The only text on the body of the dialog is Profile name and then buttons for OK and Cancel. Below the text Profile name is a text box. Type the name you would like to use for your custom profile in this text box. Use OK to utilize this profile name or Cancel to exit the dialog.

The profile name cannot be blank. If no text is entered into the textbox and the OK button is used, a warning will appear saying “A profile name cannot be empty, please provide a profile name.”

Metadata tab¶

The Metadata tab is where metadata is added to the file that will be converted. It has several fields.

Identifier: Already filled out with an automatically generated (UUID). It is not recommended to edit this field.
Title: Type in the complete title of the work being converted.
Creator: Type in the name of the primary author, editor, or creator of the work that was transcribed.
Producer: Type in the name of the organization or individual that produced the braille publication.
Language: This field is automatically populated with the value “en-Brai”, which uses “en” for English and “-Brai” to indicate that the text of the file is displayed using braille. If you are converting a file that is in a language besides English, you can change the en value to reflect that language. For example, for Spanish is es, so for a converted file that is in Spanish, this field would read “es-Brai”.
Braille system: This field is automatically populated with the initialism UEB for Unified English Braille. If you are converting a file using another braille code, you can edit this field to reflect the name of that code.
Cell type: This field is automatically populated with the number 6, representing 6-dot braille. If you are converting a file with a different cell type, such as 8-dot braille, you can edit this field to reflect that.
Complete transcription: This field is automatically set with the value True, meaning the file being converted is the complete transcription. A file is considered complete if no further changes are expected for it. If you are converting a file that is still being developed, you can change this value to False by activating the field and using the dropdown menu.
Copyrighted: Input the copyright date of the work being transcribed. Use the format YYYY-MM-DD, YYYY-MM, or YYYY depending on how much information is available to you. Y is year, M is month, and D is date.
Transcribed: Input the date the work was transcribed. If the date is unknown, use the best approximation. Use the format YYYY-MM-DD, YYYY-MM, or YYYY depending on how much information is available to you. Y is year, M is month, and D is date.

Adding Additional Metadata¶

Below the fields for inputting the minimum required Metadata, there is a section for Additional metadata. It has two buttons, Add and Remove. Add, when activated by mouse click or keyboard, displays all of the required metadata values. Select one to add that value. Additional custom metadata types will be available in a future update.

To remove an added metadata value, use the Remove button. It will remove whichever metadata value is currently selected. If no metadata values are selected, it will remove the last value added.

General tab¶

You will primarily work using the General tab as it is assumed that you will rarely need to change your page settings.

The first item on the general tab is Input type. Here you will select either List of BRF or Directory of BRF. These items change how Input BRF works when you use the Browse button.

List of BRF will have you point the converter to individual BRF files, most likely just one file. Directory of BRF will have you point the converter to a folder containing BRFs.

Once you have selected your input type, next you will interact with the Input BRF item. This item has a textbox where you can type the directory of either the folder or individual BRF that you want to convert or a Browse button, which will open the File Explorer and allow you to point to the folder or individual BRF you are wanting to convert.

The next item is a checkbox labeled as Include Images. Unchecked by default, if your BRF file has tactile graphic files that you would like included in your final conversion, this is where you would indicate that. The Image directory item is greyed out unless this checkbox is checked.

If the Include images checkbox is checked, then Image directory will become available. Just like the Input BRF item, you can either type the location of your images or use the Browse button to point the converter to the location. The primary difference between Input BRF and Image directory is that Image directory will always point to a folder and never to an individual graphic file.

Finally, there is the option for Output eBraille. This option works like Input BRF and Image directory, in that you can either type the location or use the browse button to point the converter to where you want your converted eBRL file to be saved. The main difference here is that you will also need to tell the converter what to name the file.

As we are still in beta, the converter will save your file as a zip. It does this because only a limited amount of program can read eBRL files. We will utilize the browser to review your created eBraille files.

Reading eBraille files¶

While the Monarch can read eBraille files, you can also read them using your browser. This isn't a perfect process since browsers are made for web pages and not documents, so the formatting won't visually appear accurate and some of the braille characters will have a larger font size. This doesn't affect the actual braille if it is read using a Monarch or via browser with a screen reader and braille display but it is important to remember that this is happening. It's just the browser applying irrelevant formatting and that formatting isn't applied in other contexts.

Here are the instructions for how to read eBraille files without a Monarch.

Created eBraille files will first need to be unzipped. You can do this by changing the file extension from .EBRL to .ZIP. Once the file extension is .ZIP, you can extract it using your normal process.

Once unzipped, you can open and review the items freely. Note that ordinarily, a reader would just open a .EBRL file on their Monarch or eBraille reader of their choosing. For testing purposes, we’re going to see “inside” the eBraille file.

First open the unzipped folder from your conversion. You’ll find two folders and three files. One folder is called ebraille and the other is called META-INF. The three files are index.html, mimetype, and package.opf. These files are used by software when reading eBraille files and are ordinarily never seen by a person. Mimetype and package.opf can be ignored during the field test.

To start reading your eBraille files, open index.html in your browser. By default, Windows will open HTML files in your browser, so activate it by either double-clicking or pressing enter on it to open the file in your browser and begin your review. When reading outside of a Monarch or other eBraille-supporting braille display or tablet, the index.html is the best way to open your eBraille because it contains the table of contents, generated by the converter using the headings in your file, and it's a great way to access your entire file at once.