[brailleblaster] Re: Attention Developers
- From: Hanxiao Fu <hxfu829@xxxxxxxxx>
- To: <brailleblaster@xxxxxxxxxxxxx>
- Date: Sat, 01 Dec 2012 10:28:41 +0800
Hi John,
My mistake, attached wrong file. I am attaching the architecture.txt as
well as blockdiagram.txt again. I think an easier way might be subclassing
Element to have a private field for bb semantics information.
Thanks,
Hanxiao
On 12/1/12 2:26 AM, "John J. Boyer" <john.boyer@xxxxxxxxxxxxxxxxx> wrote:
>Hi Hanxiao,
>
>Thanks for reading the documentation. I don't see an attachment for
>architecture.txt Please also look at Semantics.java in the wordprocessor
>package. It is the beginning of the implementation of using
>semantic-action files to enable BrailleBlaster to handle any flavor of
>xml. Many of the methods are incomplete, but the documentation comments
>should give you an idea of what is intended.
>
>Style and action information is in the markup placed in the document
>when things are added, so removing the bbsem attribute does not affect
>it. The bbsem attribute is added for processing. It is not part of the
>document. Adding it and then removing it seems cumbersom, but there
>seems to be no other way to add semantic information.
>
>All this is difficult to explain, so questions from you and others are
>very welcome.
>
>John
>
>On Fri, Nov 30, 2012 at 10:26:10PM +0800, Hanxiao Fu wrote:
>> Hi John,
>>
>> I read the documentations. Please find my comments (starting by
>> "--Hanxiao:") in the attached files.
>>
>> Thanks,
>> Hanxiao
>>
>> On 11/16/12 4:39 PM, "John J. Boyer" <john.boyer@xxxxxxxxxxxxxxxxx>
>>wrote:
>>
>> >It would be nice if we could reach a consensus on the new design. Could
>> >you clone the brailleblaster.newdesign repository and look at the files
>> >in the documentation directory. It would be helpful to have your
>> >feedback on architecture.txt
>> >
>> >the command for cloning the repository is
>> >
>> >hg clone https://code.google.com/p/brailleblaster.newdesign
>> >
>> >Thanks,
>> >John
>> >
>> >--
>> >John J. Boyer; President, Chief Software Developer
>> >Abilitiessoft, Inc.
>> >http://www.abilitiessoft.com
>> >Madison, Wisconsin USA
>> >Developing software for people with disabilities
>> >
>> >
>>
>
>> This is a sort of informal block diagram in narrative form. It is
>> intended as a guide for the future development of BrailleBlaster.
>>
>> Input may be in the form of an xml file or it may be a utd working file
>> which has been saved so that work can be resumed later. xml files may
>>be
>> original well-formed files of any flavor, for example, dtbook, docbook,
>> etc. They may also be derived from other formats such as MSWord, rtf,
>> and so on. Another source is file sets, such as NIMAS or epub. In this
>> case the manifest is opened, and the file to be processed is chosen
>>from
>> it. A means is provided to concatenate several files into one. xml
>>files
>> can also be derived from plain-text by calling the translateTextFile
>> method with formatFor utd or from brf files by calling
>>backTrnslateFile,
>> also with formatFor utd.
>>
>> Whatever its source, an xml file is rendered by calling translateFile
>> with formatFor utd. BrailleBlaster then works on the utd file produced.
>> In the case of formerly saved utd files or those produced by importing
>> plain text or brf files, BrailleBlaster works with these directly.
>>
>> Configuration files have been eliminated in this revision because most
>> of the information they would contain belongs in the UserSettings file
>> or in the semantic-action file for the particular xml flavor. Some of
>> the things which may be specified in the UserSettings file are listed
>> in Appendix A.
>>
>> The input file is then parsed to produce a parse tree.
>>
>> Semantic-action files are then read. A file is chosen by looking for a
>> file with the name of the root element and the extension .sem It is
>>used
>> to construct the semantic table, which will be used for determining how
>> information should be displayed on the screen and what markup should be
>> used when new information is added. For more on semantic-action files
>> see Appendix B. Appendix C. gives an example semantic-action file.
>>
>> If the semantic-action files contain XPath expressions as keys these
>>are
>> applied to the parse tree, and the selected nodes are modified by
>>adding
>> an attribute indicating the entry in the semantic table to be used. The
>> value of each key will already have been entered into this table.
>>
>> The keys containing markup in the semantic files are then applied to
>>the
>> parse tree, and a similar attribute is added to the matching nodes,
>> unnless it is already present because it has been added by an XPath
>> expression.
>>
>> --Hanxiao: the process of constructing the range lookup table can take
>>place here. See my comment at line95 in architecture.txt about the table.
>>
>> This forms the DOM of the document.
>>
>> This DOM is then used to display the document on the screen. Both the
>> print and Braille windows are filled in this process. The print window
>> resembles WordPad. The Braille window shows the Braille line-by-line,
>> with blank lines, indentations, etc. Its editor is like a simple text
>> editor, but with features for locking Braille.
>>
>> Editing of the print document can then take place. If the contents of a
>> text node are altered the new contents replace the old. They are also
>> dynamically translated and the translation is shown in the Braille
>> window. If an element node is deleted its entire subtree is deleted. If
>> a new block of characters is created the user is prompted to asign it a
>> style and a node with the appropriate markup (derived from the
>> semantic-action files) is added to the document at the place where the
>> new block was created.
>>
>> --Hanxiao: The sychronization can be done by the following: each time
>>the Print View is changed, the corresponding content in Braille View at
>>lines of modified content in Print View will all be repainted with new
>>translated content.
>>
>> if focus is shifted to the Braille window and the user has checked the
>> Edit Braille box on the advanced menu the window can be edited. Any
>> editing is highlighted in both the Braille and print windows. The print
>> window also changes to show the part of the original text that
>> corresponds to each line of Braille.
>>
>> --Hanxiao: I don't know if this could break the structrue in Dasiy
>>View, because Braille View may not know what elements will be modifed
>>but only the translated text content.
>>
>> Since the user may wish to view the result of editing Braille in the
>> context of the entire document, The translate and back-translate items
>> on the menu are replaced with retranslate and reback-translate.
>>
>> --Hanxiao: weren't the two dynimically synchronized from the very
>>beginning? why retranslations or even the translation items needed?
>>
>> The file can be saved as a utd file so work can be resumed later or it
>> can be saved as the original xml file with enhancements. These consist
>> of edited Braille which has been moved into the print document with
>> proper markup (specified in the semantic-action files). The attributes
>> used to create the DOM are removed during the save process. Editing in
>> the print window is handled automatically as part of the conversion of
>> the parse tree to a file.
>>
>> --Hanxiao: If the attributes will be removed, won't the users have to
>>set the styles again next time the document is opened? for example, the
>>user changed an "a" elment, which by semantic-action files has style of
>>"a_style", to have style "b_style". The information will be lost after
>>removal of bbsem attributes.
>>
>> Besides saving the file as utd or as an enhanced document, it can be
>> saved as a brf file or embossed.
>>
>> The enhanced document can then later be rendered by liblouisutdml with
>> any liblouisutdml configuration and semantic-action files that the user
>> wishes. This can be done either by BrailleBlaster or by another
>> application which uses the loblouis-liblouisutdml transcription engine.
>>
>> Appendix A. User settings
>>
>> The settings below are largely for printed output. Analogous settings
>> for embosser output would be included.
>>
>> hyphenate=no
>> topMargin=0.5
>> leftMargin=1
>> rightMargin=0.5
>> bottomMargin=0.5
>> paperHeight=11
>> paperWidth=8.5
>>
>> Appendix B: Semantic-Action Files
>>
>> Semantic-action files associate the markup in a particular type of xml
>> document with BrailleBlaster styles, methods (actions) and macros.
>> Usually they are named by concatenating the name of the root element of
>> the document flavor with the extension .sem They are not to be confused
>> with liblouisutdml semantic-action files. The latter are concerned with
>> rendering an xml document into Braille and tactile graphics.
>> BrailleBlaster semantic-action files are concerned with displaying the
>> contents of a document on the screen and with editing them. Their
>>format
>> is completely different from the format of liblouisutdml
>>semantic-action
>> files. They are stored in the semantics directory in the programData
>> directory. There is a dialogue for creating and editing them. If an
>> unknown xml flavor is encountered a prototype semantic-action file is
>> created.
>>
>> the key part of a line in a semantic-action file is a reference to
>> markup in the document. This may be literal markup or an XPath
>> expression. There are a few exceptions, which will be discussed later.
>> The value part contains the name of a style or action, or of a macro,
>> which can combine several styles and actions. it may also contain
>> parameters.
>>
>> Literal keys may have one of the following forms: an element name; an
>> element name, a comma, and an attribute name; an element name, a comma,
>> an attribute name, an attribute value. XPath keys begin with the
>> characters &xpath with the XPath expression imediately following and
>> enclosed in parentheses. The key may also be the word newEntries. If
>>the
>> value is yes markup which has not yet been associated with anything is
>> recorded and placed in a prototype semantic-action file. The key may
>> also be the word file, followed by a colon followed by a filename. In
>> this case the value is the word include, and the line specifies that
>> another semantic file should be read at this point. Finally, the key
>>may
>> be internetAccessRequired This is used to specify that internnet access
>> is needed to process this xml flavor.
>>
>> Values start with one of the words action macro style. This is followed
>> by a space. If action is specified, the action is one of those below.
>>If
>> style is specified a style name follows. The extension .properties is
>> added to it and it is looked up in the styles directory. Likewise,
>> macros are looked up in the macro directory. All three may have
>> parameters preceded by a space and separated by comas.
>>
>> The following actions may be specified.
>>
>> internetAccessRequired, This document needs Internet access.
>> no, Do nothing except insert a space.
>> skip, Skip the subtree of which this markup is the root.
>> generic, Apply the parameters.
>> cdata, Special processing for CData sections.
>> htmllink, Insert a link
>> htmltarget, to this target.
>> # reserved styles. These styles are predefined, but may be altered
>> document, Assign to the node that actually contains the content, such
>> as the book node in dtbook.
>> para, A paragraph.
>> heading1,various levels of headings
>> heading2,
>> heading3,
>> heading4,
>> heading5,
>> heading6,
>> heading7,
>> heading8,
>> heading9,
>> heading10,
>> contentsheader, The heading of the table of contents.
>> contents1, Various levels within the contents.
>> contents2,
>> contents3,
>> contents4,
>> contents5,
>> contents6,
>> contents7,
>> contents8,
>> contents9,
>> contents10,
>> # General text
>> notranslate, do not translate the contents of the markup.
>> attrtotext, Transform an attribute value to text.
>> runninghead, Specify a running header.
>> footer, Specify a page footer.
>> boxline, Specify a line of identical characters.
>> italic, Italicise the text within the markup.
>> bold, Bold it.
>> underline, Underline it.
>> compbrl, Show it in computer Braille.
>> linespacing, Number of blank lines between lines of characters.
>> blankline, Leave a blank line.
>> softreturn, Start a new line, but not a new style.
>> newpage, Start a new page.
>> brl, Process the <brl> subtree rooted at this node.
>> music, Display/edit the music notation in this subtree.
>> math, Display/edit the MathML notation in this subtree.
>> chemistry, Display/edit the chemistry notation in this subtree.
>> graphic, Display/edit the graphic pointed to by the markup.
>>
>> Appendix C. Example Semantic-Action File (dtbook.sem)
>>
>> file:filename include
>> newEntries no
>> internetAccesRequired no
>> book style document
>> docauthor style para
>> p style para
>> doctitle style heading1
>> h1 style heading1
>> h2 style heading2
>> h3 style heading3
>> h4 style heading4
>> h5 style heading4
>> h6 style heading4
>> a,href action htmlLink
>> a,name action htmlTarget
>> code style computerCode
>> code,class,inline action compbrl
>> span,class,italic action italic \s,\s
>> b action bold
>> acronym action notranslate
>> li style list
>> pagenum action pagenum
>> th style para
>> tr style para
>> strong action italic \s,\s
>> code,class,display style computerCode
>> em action italic \s,\s
>> note style note
>> blockquote style blockquote
>> samp style para
>> sidebar style para
>> br action softReturn
>> abbr style para
>>
>>
>
>> This is a step-by-step description of how the BrailleBlaster document
>> model is built and used. It explains the block diagram in more detail.
>>
>> It begins with an xml file containing utd and a semantic-action file
>>for
>> that flavor of xml.
>>
>> The file is parsed to produce a parse tree and then closed. The
>>document
>> node is pased to a method in the Semantics class.
>>
>> This method looks for a semantic-action file in the semantics
>> subdirectory of the programData folder. The name of this file is formed
>> by adding .sem to the name of the root element. If such a file does not
>> exist a prototype file containing a line for each distinct markup in
>>the
>> document is created. A dialog box informs the user of this situation.
>> The file can later be edited by a developer and added to
>> BrailleBlaster's repertoire.
>>
>> An example semantic-action file for dtbook DAISY xml files is shown
>> below. Note that this file is not a final version, nor is the Semantics
>> class shown later.
>>
>> --------------------
>> newEntries=no
>> internetAccesRequired=no
>> book=style document
>> p=style para
>> h1=style heading1
>> h2=style heading2
>> h3=style heading3
>> h4=style heading4
>> h5=style heading4
>> h6=style heading4
>> a,href=action htmlLink
>> a,name=action htmlTarget
>> code=style computerCode
>> code,class,inline=action compbrl
>> em=action italic \s,\s
>> b=action bold
>> acronym=action notranslate
>> li=style list
>> pagenum=action pagenum
>> docauthor=style para
>> doctitle=style heading1
>> th=style para
>> tr=style para
>> strong=action italic \s,\s
>> code,class,display=style computerCode
>> note=style note
>> blockquote=style blockquote
>> samp=style para
>> sidebar=style para
>> br=action softReturn
>> abbr=style para
>> --------------------
>>
>> The semantic-action file is read into an array of the inner class
>> SemanticEntry, shown below. This array is called semanticTable If no
>> semantic-action file exists a default semanticTable which will give a
>> bare-bones display in the print window is built. The display in the
>> Braille window is defined by the utd part of the document.
>>
>> --------------------
>> package newclasses;
>>
>> public class Semantics {
>> enum Action {
>> no,
>> skip,
>> generic,
>> cdata,
>> htmlLink,
>> htmlTarget,
>> document,
>> para,
>> heading1,
>> heading2,
>> heading3,
>> heading4,
>> heading5,
>> heading6,
>> heading7,
>> heading8,
>> heading9,
>> heading10,
>> contentsHeader,
>> contents1,
>> contents2,
>> contents3,
>> contents4,
>> conents5,
>> contents6,
>> contents7,
>> contents8,
>> contents9,
>> contents10,
>> noTranslate,
>> attrToText,
>> runningHead,
>> footer,
>> boxLine,
>> italic,
>> bold,
>> underline,
>> compbrl,
>> lineSpacing,
>> blankLine,
>> softReturn,
>> newPage,
>> brl,
>> music,
>> math,
>> chemistry,
>> graphic
>> };
>>
>> class SemanticEntry {
>> String markup;
>> String operation;
>> String operand;
>> String parameters;
>> Action action;
>> StyleType style;
>> String macro;
>> }
>>
>> SemanticEntry[] semanticTable = new SemanticEntry[100];
>>
>> }
>> --------------------
>>
>> A hashtable is then constructed in which the key is the markup field of
>> each SementicEntry and the value is its position in the
>> semanticTable array.
>>
>> The array is searched for XPath expresions. If they are found they are
>> applied to the parse tree. Each node in the nodeset is then augmented
>> with a new attribure, bbsem whose value is the position of the
>> SemanticEntry in semanticTable
>>
>> The parse tree is then traversed. If a node does not contain a bbsem
>> attribute the hash table is used to discover whether it is in the
>> semanticTable array. First the attributes with their values, together
>> with the element name are looked up, then just the element name and the
>> name of each attribute, then just the element name. if any of these
>> lookups is successful, a bbsem atttribute is added. During this
>> traversal information on the document, such as whether it references
>> graphics, is also collected.
>>
>> This completes the construction of the document model.
>>
>> BrailleBlaster then calls another method in the Semantics class to
>> display the document in both the print and Braille windows. In the
>> Braille window each line of Braille is displayed with proper
>>indentation
>> and vertical spacing. Tactile images are also displayed. In the print
>> window the bbsem attribute of each node is used to find the appropriate
>> entry in the semanticTable. the style, action or macro referenced in
>> that table is applied. Actions cause methods to be invoked. For
>>example,
>> such a method might underline a block of characters. Instances of class
>> StyleType are created the first time a particular style is used. Macros
>> are compiled the first time they are invoked.
>>
>> BrailleBlaster then calls a readAndEdit method. If a text node is
>>edited
>> in the print window it is dynamically retranslated at each character
>> keystroke in the Braille window. If a new block of characters is
>>created
>> it is assigned the style para (paragraph), but the user can bring up a
>> list of valid styles. When a style or action is chosen, the block of
>> characters is added to the parse treee with the markup in the
>> corresponding entry in the semanticTable. The entry is found by a
>>linear
>> search for the style or action name. There may be several entries that
>> match. The first one is taken. For example, there are several entries
>>in
>> the dtbok.sem file shown above for the para style. The desired one has
>> been placed before all the others, which are used to display various
>> things.
>>
>> When something in the Braille window is edited the markup to be used
>>for
>> locking
>> it is obtained from the semanticTable, as is the markup to be used to
>> indicate that the corresponding part of the print window is to be
>> skipped during retranslation.
>>
>> At any time the user can chose the save menu item. This has two
>>options:
>> save working (utd) file and save enhanced document. In either case
>> the save process involves removal of the bbsem attributes. If the save
>> working document is chosen the parse tree is used to create a file with
>> the utd extension in the same directory as the original document. If
>>the
>> save enhanced document option is chosen any edited Braille is moved
>>into
>> the print part of the document with its appropriate markup. The <brl>
>> subtrees are deleted and a file with the original document name is
>> written to the original directory.
>>
>> If the user choses the Save As menu item s/he can chose a number of
>> options, among them, save as a brf file and save as pef.
>>
>> The emboss menu item will send the <brl> portions of the document to
>>the
>> appropriate embosser driver.
>>
>> The print menu item will print the document as it is shown in the print
>> window.
>>
>
>
>--
>John J. Boyer; President, Chief Software Developer
>Abilitiessoft, Inc.
>http://www.abilitiessoft.com
>Madison, Wisconsin USA
>Developing software for people with disabilities
>
>
This file describes the packages and classes in BrailleBlaster. It is
recommended reading for anyone writing code for the project.
Packages and classes are described in the order which seems to best
promote understanding, not in alphabetical order. Some clases, which may
not be included in the final design, are not described.
A note on directory structure. The user's brlblst directory, which is in
the platform-specific place for application data, will now contain a
replica of the programData directory. If the user creates or modifies a
file in the programData directory this file is placed in
brlblst/programData in the appropriate subdirectory. brlblst/programData
is initially empty. When a file such as a liblouis table is needed it is
checked before the corresponding place in the built-in programData
directory is checked. Temparary files will be placed in the location
favored by the platform. They will be in subdirectories with an instance
ID. Setting up the necessary paths will be handled by BBIni.
--Hanxiao: This is good because if users accidentally modified or simply want
to rollback some settings to default, they know where to remove, or we can
setup the mechanism for users to reset all settings or any specific single
setting.
package org.brailleblaster
class Main: This class contains the main method, which starts
BrailleBlaster and cleans up when it is finished.
class BBIni: This class handles command-line options beginning with "-"
and almost everything needed to set up BrailleBlaster, including
determining platform-dependent paths and other things and loading
liblouisutdml. Other classes seldom have to be concerned with
differences between platforms.
Class Subcommands: This class handles the subcommands like translate,
emboss, checktable, etc. It is called by the main method after BBIni if
there are subcommands. If something is given on the command line that is
not a subcommand it assumes that it is the name of a file to be
processed by the wordprocessor and passes control to WPManager.
class ParseCommandLine: This class is currently unused. It was written
to process complex command lines. However, Subcommands appears to do an
adequate job. ParseCommandLine may therefore be eliminated.
package org.brailleblaster.wordprocessor
class WPManager: This is the entrance point to the "word processor",
so-called because it is more than a text editor. It is the only public
class in this package except for the class CallOutsideWP. It sets up the
basic word processor environment and also the multi-document interface.
--Hanxiao: just a side note for multi-document interface. I think a more
mordern approach for supporting MDI is through using multiple tabs in a single
window, rather than opening a separated window for everytime. Users can then
drag and drop the tab or simply selecting from menu to detach a tab into a new
window. Most modern editors, MS word is an exception though, and browswers are
doing it in this way. This is not a core feature though, but could be an
enhancement to do after finish implement more important features.
class DocumentManager: This class handles each document. It sets up the
print and braille windows, the menus, the toolbar, etc. It contains
methods for handling the various menu items.
class Semantics: This class augments an xml parse tree with semantic
information which will be used in displaying and editing it. Methods in
this class construct a sort of document model from semantic-action
files.
class Styles: This class handles the styles used to control the display
in the print window. These styles deal with layout. Font changes, such
as italic or bold are dealt with by methods in the Actions class.
class Actions: This class contains methods which supplement styles and
perform additional operations, such as emphasis, introducing blank
lines, soft returns, etc.
class UTD: Handles UTDML. It is called by methods in Semantics to handle
subtrees rooted at a <brl> element.
class StylePanel: The user can create and modify styles. These styles
are stored in the user's programData directory.
class BrailleTemplates: This class does not yet exist. It will enable
advanced users to control how liblouisutdml translates and formats
Braille.
class UserHelp: This class contains methods that implement the help
submenu. They open the documents in programData/helpDocs in the system's
default browser.
class CallOutsideWP: this class makes certain features available inside
the wordprocessor package available to other packages. In particular, it
gives access to the ability to show html through the system's default
browser. It contains two methods, showTutorial and showURL. Other
methods will be added as needed.
class DaisyView: This class actually shows the print document on the
left side of the screen. It uses the StyledText control. However, it is
not clear that StyledText can do what we need, since the program must
move about in the parse tree as the user scrolls and moves the cursor.
--Hanxiao: About managing each element in the parse tree and its corresponding
location in the DasiyView, I created a range class, which each range keeps an
element, its correspoding start/end position in the DasiyView and whether it is
a leaf element. Then during the process of parsing the document, ranges are
created and stored in a lookup table. Then we could keep tracing the location
of every element, and what the element is at every position. So if only
locating elements' positions in the View is concerned, I think StyledText
control provides sufficient interfaces.
class BrailleView: This class shows the Braille translation on the right
side of the screen.
class RecentDocuments: This class maintains a file of paths to recently
opened documents and presents the user with a dialogue box for chosing
one of them.
class NewDocument: This class will be rewritten. It will present the
user with a set of radio buttons for the various xml flavors suported
and then call Semantics.makeDocumentModel with a skeleton file for that
flavor.
class BBMenu: Displays the menus and calls a method in DocumentManager
when a menu item is selected.
class BBToolBar: Displays the toolbar and calls a method in
DocumentManager when an item is selected.
class BBStatusBar: Displays and modifies the status bar at the bottom
olf the screen.
class WP: Contains various constants used by other classes.
package org.brailleblaster.xmleditor
This package does not yet exist. It will provide the capability to view
the xml parse tree as such, change and delete attributes and elements,
add new ones, edit text nodes, etc.
--Hanxiao: It can be done with the range lookup table I mentioned above, to
remove the correspoding element's content in the dasiy view.
package org.brailleblaster.settings
class Welcome: This class displays the welcome message when
BrailleBlaster is started and enables the user to chose not to see it
and/or to see a tutorial.
class SettingsDialog: This class enables the user to change the initial
settings, such as which Braille template that will be used.
package org.brailleblaster.localization
class LocalizationHandler: This class provides the capability to display
messages in the user's language or in another language which s/he may
chose.
class LocalizationBase: This is a helper class for
LocalizationHandler.
package org.brailleblaster.util
class BrailleblasterPath: this class is used by BBIni to find the path
to brailleblaster.jar. This path is then used as the basis for all other
paths.
class CheckLiblouisutdmlLog: This class contains methods that check
whether a call to a method in the bindings for liblouisutdml has
produced error messages. If so, these messages are displayed in a manner
appropriate to the GUI or the command line, whichever is being used.
class Notify: Used to display messages that the user must respond to by
pressing the OK button.
class YesNoChoice: Displays messages for which the user can chose either
yes or no.
class FileUtils: Contains methods for various operations on files, such
as deleting a file, checking whether it exists, deleting a directory,
etc.
class ProgramCaller: Used for calling external programs, such as
MathType.
package org.brailleblaster.importers
Contains various classes for importing various types of files. At the
mement the only class is:
class ImportersManager: Choses import methods.
package org.brailleblaster.exporters
This package contains classes for exporting xml documents to various
other file formats. The only class now is:
class ExportersManager: Choses classes and methods for various types of
file formats.
package org.brailleblaster.embossers
Contains drivers for various types of Braille embossers. The only class
now is:
class EmbossersManager: which choses the classes and methods to emboss
on a particular device and to do any preparatory work.
package org.brailleblaster.printers
This is very similar to org.brailleblaster.embossers, except that it
handles conventional ink prnters.
This is a sort of informal block diagram in narrative form. It is
intended as a guide for the future development of BrailleBlaster.
Input may be in the form of an xml file or it may be a utd working file
which has been saved so that work can be resumed later. xml files may be
original well-formed files of any flavor, for example, dtbook, docbook,
etc. They may also be derived from other formats such as MSWord, rtf,
and so on. Another source is file sets, such as NIMAS or epub. In this
case the manifest is opened, and the file to be processed is chosen from
it. A means is provided to concatenate several files into one. xml files
can also be derived from plain-text by calling the translateTextFile
method with formatFor utd or from brf files by calling backTrnslateFile,
also with formatFor utd.
Whatever its source, an xml file is rendered by calling translateFile
with formatFor utd. BrailleBlaster then works on the utd file produced.
In the case of formerly saved utd files or those produced by importing
plain text or brf files, BrailleBlaster works with these directly.
Configuration files have been eliminated in this revision because most
of the information they would contain belongs in the UserSettings file
or in the semantic-action file for the particular xml flavor. Some of
the things which may be specified in the UserSettings file are listed
in Appendix A.
The input file is then parsed to produce a parse tree.
Semantic-action files are then read. A file is chosen by looking for a
file with the name of the root element and the extension .sem It is used
to construct the semantic table, which will be used for determining how
information should be displayed on the screen and what markup should be
used when new information is added. For more on semantic-action files
see Appendix B. Appendix C. gives an example semantic-action file.
If the semantic-action files contain XPath expressions as keys these are
applied to the parse tree, and the selected nodes are modified by adding
an attribute indicating the entry in the semantic table to be used. The
value of each key will already have been entered into this table.
The keys containing markup in the semantic files are then applied to the
parse tree, and a similar attribute is added to the matching nodes,
unnless it is already present because it has been added by an XPath
expression.
--Hanxiao: the process of constructing the range lookup table can take place
here. See my comment at line95 in architecture.txt about the table.
This forms the DOM of the document.
This DOM is then used to display the document on the screen. Both the
print and Braille windows are filled in this process. The print window
resembles WordPad. The Braille window shows the Braille line-by-line,
with blank lines, indentations, etc. Its editor is like a simple text
editor, but with features for locking Braille.
Editing of the print document can then take place. If the contents of a
text node are altered the new contents replace the old. They are also
dynamically translated and the translation is shown in the Braille
window. If an element node is deleted its entire subtree is deleted. If
a new block of characters is created the user is prompted to asign it a
style and a node with the appropriate markup (derived from the
semantic-action files) is added to the document at the place where the
new block was created.
--Hanxiao: The sychronization can be done by the following: each time the Print
View is changed, the corresponding content in Braille View at lines of modified
content in Print View will all be repainted with new translated content.
if focus is shifted to the Braille window and the user has checked the
Edit Braille box on the advanced menu the window can be edited. Any
editing is highlighted in both the Braille and print windows. The print
window also changes to show the part of the original text that
corresponds to each line of Braille.
--Hanxiao: I don't know if this could break the structrue in Dasiy View,
because Braille View may not know what elements will be modifed but only the
translated text content.
Since the user may wish to view the result of editing Braille in the
context of the entire document, The translate and back-translate items
on the menu are replaced with retranslate and reback-translate.
--Hanxiao: weren't the two dynimically synchronized from the very beginning?
why retranslations or even the translation items needed?
The file can be saved as a utd file so work can be resumed later or it
can be saved as the original xml file with enhancements. These consist
of edited Braille which has been moved into the print document with
proper markup (specified in the semantic-action files). The attributes
used to create the DOM are removed during the save process. Editing in
the print window is handled automatically as part of the conversion of
the parse tree to a file.
--Hanxiao: If the attributes will be removed, won't the users have to set the
styles again next time the document is opened? for example, the user changed an
"a" elment, which by semantic-action files has style of "a_style", to have
style "b_style". The information will be lost after removal of bbsem
attributes.
Besides saving the file as utd or as an enhanced document, it can be
saved as a brf file or embossed.
The enhanced document can then later be rendered by liblouisutdml with
any liblouisutdml configuration and semantic-action files that the user
wishes. This can be done either by BrailleBlaster or by another
application which uses the loblouis-liblouisutdml transcription engine.
Appendix A. User settings
The settings below are largely for printed output. Analogous settings
for embosser output would be included.
hyphenate=no
topMargin=0.5
leftMargin=1
rightMargin=0.5
bottomMargin=0.5
paperHeight=11
paperWidth=8.5
Appendix B: Semantic-Action Files
Semantic-action files associate the markup in a particular type of xml
document with BrailleBlaster styles, methods (actions) and macros.
Usually they are named by concatenating the name of the root element of
the document flavor with the extension .sem They are not to be confused
with liblouisutdml semantic-action files. The latter are concerned with
rendering an xml document into Braille and tactile graphics.
BrailleBlaster semantic-action files are concerned with displaying the
contents of a document on the screen and with editing them. Their format
is completely different from the format of liblouisutdml semantic-action
files. They are stored in the semantics directory in the programData
directory. There is a dialogue for creating and editing them. If an
unknown xml flavor is encountered a prototype semantic-action file is
created.
the key part of a line in a semantic-action file is a reference to
markup in the document. This may be literal markup or an XPath
expression. There are a few exceptions, which will be discussed later.
The value part contains the name of a style or action, or of a macro,
which can combine several styles and actions. it may also contain
parameters.
Literal keys may have one of the following forms: an element name; an
element name, a comma, and an attribute name; an element name, a comma,
an attribute name, an attribute value. XPath keys begin with the
characters &xpath with the XPath expression imediately following and
enclosed in parentheses. The key may also be the word newEntries. If the
value is yes markup which has not yet been associated with anything is
recorded and placed in a prototype semantic-action file. The key may
also be the word file, followed by a colon followed by a filename. In
this case the value is the word include, and the line specifies that
another semantic file should be read at this point. Finally, the key may
be internetAccessRequired This is used to specify that internnet access
is needed to process this xml flavor.
Values start with one of the words action macro style. This is followed
by a space. If action is specified, the action is one of those below. If
style is specified a style name follows. The extension .properties is
added to it and it is looked up in the styles directory. Likewise,
macros are looked up in the macro directory. All three may have
parameters preceded by a space and separated by comas.
The following actions may be specified.
internetAccessRequired, This document needs Internet access.
no, Do nothing except insert a space.
skip, Skip the subtree of which this markup is the root.
generic, Apply the parameters.
cdata, Special processing for CData sections.
htmllink, Insert a link
htmltarget, to this target.
# reserved styles. These styles are predefined, but may be altered
document, Assign to the node that actually contains the content, such
as the book node in dtbook.
para, A paragraph.
heading1,various levels of headings
heading2,
heading3,
heading4,
heading5,
heading6,
heading7,
heading8,
heading9,
heading10,
contentsheader, The heading of the table of contents.
contents1, Various levels within the contents.
contents2,
contents3,
contents4,
contents5,
contents6,
contents7,
contents8,
contents9,
contents10,
# General text
notranslate, do not translate the contents of the markup.
attrtotext, Transform an attribute value to text.
runninghead, Specify a running header.
footer, Specify a page footer.
boxline, Specify a line of identical characters.
italic, Italicise the text within the markup.
bold, Bold it.
underline, Underline it.
compbrl, Show it in computer Braille.
linespacing, Number of blank lines between lines of characters.
blankline, Leave a blank line.
softreturn, Start a new line, but not a new style.
newpage, Start a new page.
brl, Process the <brl> subtree rooted at this node.
music, Display/edit the music notation in this subtree.
math, Display/edit the MathML notation in this subtree.
chemistry, Display/edit the chemistry notation in this subtree.
graphic, Display/edit the graphic pointed to by the markup.
Appendix C. Example Semantic-Action File (dtbook.sem)
file:filename include
newEntries no
internetAccesRequired no
book style document
docauthor style para
p style para
doctitle style heading1
h1 style heading1
h2 style heading2
h3 style heading3
h4 style heading4
h5 style heading4
h6 style heading4
a,href action htmlLink
a,name action htmlTarget
code style computerCode
code,class,inline action compbrl
span,class,italic action italic \s,\s
b action bold
acronym action notranslate
li style list
pagenum action pagenum
th style para
tr style para
strong action italic \s,\s
code,class,display style computerCode
em action italic \s,\s
note style note
blockquote style blockquote
samp style para
sidebar style para
br action softReturn
abbr style para
Other related posts:
