[brailleblaster] Re: Attention Developers
- From: "John J. Boyer" <john.boyer@xxxxxxxxxxxxxxxxx>
- To: brailleblaster@xxxxxxxxxxxxx
- Date: Sat, 1 Dec 2012 23:22:33 -0600
Hi Hanxiao,
Thanks for the files. I'll get back to you. I'm considering using an
ArrayList to get away from the need of a bbsem attribute. I've thought
of subclassing element, but I don't see how that would work, since XOM
generates ElementWhat do you have in mind?
Thanks,
John
On Sat, Dec 01, 2012 at 10:28:41AM +0800, Hanxiao Fu wrote:
> 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
>
>
--
John J. Boyer; President, Chief Software Developer
Abilitiessoft, Inc.
http://www.abilitiessoft.com
Madison, Wisconsin USA
Developing software for people with disabilities
Other related posts:
