New Braille File Format for DBT Users

Version 2.1 for DBT 12.7 dated 9/04/2023

Introduction

Duxbury Systems has the goal of allowing a user with a braille device to write an academic paper on the braille device in braille with all formatting incorporated in the braille. We envision a user connecting to a computer to copy the file onto the computer. A future version of DBT will import the file, translate to inkprint and export (save as) to MS Word. At this point, quite a bit of this is done in DBT 12.7 and in command line programs you can download to work with your copy of DBT 12.7.

We are devising a new file format for writing braille on your braille device containing format commands for DBT. These formatting commands look like HTML. In many cases, they are HTML. We like to call this "braille html". To work with this material, you need a copy of Duxbury DBT 12.7. DBT 12.7 has some new features to assist with this project.

Eventually, all this work will be built into a future DBT. Temporarily, you need to run "stand-alone" conversion programs at the MS-DOS command line. I know running the conversions from the command line is a pain. The more we rewrite and debug outside of DBT, the easier the final integration into DBT will be. Here is a list of expectation: you need to operate at the command line, and be able to unzip this software. You also need to be aware of your directory structure, file types, file extensions, and other mundane details.

Project Elements

The use case we are looking at is a student writing on a braille notetaker for the preparation of inkprint output using MS Word via Duxbury DBT. Yes, you can do this now, but the results are not as good as they can be. Here are some elements of DBT being worked on.

• We would like to directly import jpg files into DBT to allow DBT to allow a blind pass an image hrough DBT, onto a Word file. You need other tools to create and edit jpg files.
• allow import of a braille file that use pseudo-html commands for format. This is the element under discussion. This would allow a blind person to write in braille on a notetaker and get the file into DBT, totally controlling the format and content. This is not part of 12.7.
• allow export from DBT into this curious pseudo-html braille format. This was written to allow 2-way conversion of this new file format. This is not part of 12.7.
• A further item is that we have a dotx Word template which changes the line spacing, margins, and fonts of a DBT generated Word file to resemble an academic paper or thesis. We will be experimenting with making this Word template attachment happen automatically.

Taken together, these elements suggest that someone could write a PhD thesis on a braille notetaker and pop it out in Word. Two things: back up your braille notetaker if you are going to try this, and e-mail languages@duxsys,com to get involved in this project.

It is not a goal to make the braille html file to look good in a browser. Instead the goal is to allow the html markup be easy to read and write on a braille device. Only a few style names from DBT are changed to avoid making it difficult to learn a whole new system.

Version History

This project started in Dec. 2022.

Version 1.2 handles lists better. The bru to htm conversion now defaults to only showing paragraph markup when it changes. If you want to have all paragraph markup, add "all" as a third parameter (see below).

Version 1.3 focused on making sure that anything in a in a DBT bru file can be reproduced in the html file. With a further conversion back to bru, we want, where possible, to reconstruct the original bru file.

Version 1.4 handles hierarchy properly. The |hl2 is matched with <li 2>, etc. See below for details.

Version 1.45 adds the smooth program (since renamed) to improve the output from Duxbury-generated inkprint html files.

Version 1.5 renames smooth to fix-links; code in DBT changed to improve export to html/Word

Version 2.0 is designed for DBT 12.7, which incorporate smooth/fix-links.

Version 2.1 redoes the commands for language switching.

Downloading the Files

All the files are zipped up. Please unpack them into a folder that is easy to find. Click here to download.

All this is the work of David Holladay at Duxbury Systems. Contact him at david@duxsys.com

Things to Note:

• Write a file on your braille device. Use a carriage return for each logical paragraph (body text, heading, list item, etc.
• It is similar to HTML, using < and > to enclose the format
• If a format marker is missing at the beginning of a line, the system copies the markup from the previous paragraph.
• A fixed header is required at the top of the file. This material is in a file called header.txt
• The paragraph style needs to be right after a CR.
• The end paragraph style marker is optional.
• Some pure HTML markup is acceptable and will be converted into DBT markup on the fly, such as <p> <li> (see table below)
• I have included a master's thesis m-thesis.htm as a sample file. It is a real thesis to assist in working on real formatting problems. We are also including it in bru and dxp file format so you can understand the conversions. Image files are not included. Extra credit if you locate the source file on ther web as a pdf.

Table of Markup

Writing Formatting Commands from Braille

• DBT divides markup into three groups: paragraph, inside paragraphs and miscellaneous codes. In this context, a paragraph is a format that starts a new line, such as a table row or a list item. Inside paragraph markup means things like italics and bold that start and end within a paragraph. Miscellaneous codes are other items that not have a start and end.
• Start a new line on your braille device for paragraph markup. You do not need to write paragraph markup if it is the same as the previous paragraph. In DBT, paragraph markup is indicated with a period. The period is not needed in braille html, write <para> not <para.> You do not need the markup at the end of paragraphs. For example, you do not need to use </p> or </li>.
• You do not need most character level, such as italics and boldface, since that is built into the braille. Use <brlinline> to turn off the translator. The <compinline> is not used with English UEB; it is useful in other languages, such as French.
• Some "paragraph styles" are really larger structures, where new lines are indicated by markup like |l |hl1 (which becomes <li>) or |l |hl2 (which becomes <li 2>).

Switching Languages

DBT has two ways of switching languages: switching styles and switching translation tables. Switching styles depends on your template. Switching DBT translation tables can give unexpected results if used improperly. In the table below, entries marked styles uses switching styles the rest use switching translation tables. For French and German, you can use your choice of methods.

Commands for Switching Languages

Mathematics

DBT has a nice feature to import a braille file as containing Nemeth code. This does not work with bru files (yet). Use the format tags <math> and </math> to enclose braille mathematics. How that is handled depends on your DBT template.

Conversion Steps

1. Bring your braille file to your computer (from your braille device), put the file into the directory with your downloaded files. Assume the file is named house.
2. Add the required header at the top.
3. Perform (at the DOS Prompt): new2bru house.htm house.bru<Enter>
4. Open DBT and open the new file
5. Specify the file type Duxbury Formatted Braille
6. If it does not work, contact david@duxsys.com

Running Thing Backwards

If you want to, you can start with a braille file in DBT and read it on your braille device with the new formatting markup.

1. Start with a file in DBT. If it is inkprint, translate to braille.
2. Choose Save As from the DBT file menu.
3. Choose Duxbury Coded Braille (*.bru) as the file type.
4. For convenience, save the file in the same directory as you unpacked this software. Assume the file is named farm
5. Perform (at DOS Prompt): bru2new farm.bru farm.htm<Enter>
6. Copy the new file onto your braille device.
7. Alternative command (for no deletion of duplicated markup): bru2new farm.bru farm.htm all<Enter>
8. If there is a formatting command that got garbled, contact david@duxsys.com

Applying a Template to a Word File

We have a Word Template to enhance Word files called trial-michigan.dotx. It is freely distributed by the University of Michigan.

Apply a Word Template to an existing Word document

1. Open the Word document you will apply template to, and click File > Options to open the Word Options dialog box.
2. In the Word Options dialog box, please (1) click Add-ins in the left bar, (2) select Templates from the Manage drop down list, and (3) click the Go button.
3. In the new opening Templates and Add-ins dialog box, please check the Automatically update document styles option, and click the Attach button.
4. In the Attach Template dialog box, please (1) open the folder containing the personal template you will apply, (2) select the specified personal template, and (3) click the Open button.
5. Click the OK button when it returns to the Templates and Add-ins dialog box.

Required Header

This text is in the file header.txt

<brlhtm>
<no-par> <spacing> <compress>

David's Debugging

David has a batchfile do.bat, which takes a bru file from DBT, converts to the new format, and then converts back to bru (with an x added to the file name). By comparing these files, and by testing how the new bru file loads into DBT, David debugs this material.