[brailleblaster] Re: Block diagram with clarifications
- From: "John J. Boyer" <john.boyer@xxxxxxxxxxxxxxxxx>
- To: brailleblaster@xxxxxxxxxxxxx
- Date: Fri, 12 Oct 2012 20:36:10 -0500
The configuration files are analogous to MSWord templates. The
semantic-action files enable BrailleBlaster to work with any flavor of
xml. The different flavors all use different markup. BrailleBlaster uses
a different set of configuration and semantic-action files than
liblouisutdml because print is not Braille and BrailleBlaster also does
editing. The algorithms in liblouisutdml have been successful, so it is
worthwhile to consider adapting them for wider application.
The reply does not seem to be well-thought out.
John
On Fri, Oct 12, 2012 at 08:42:58PM +0100, Michael Whapples wrote:
> I guess the main thing which crosses my mind is that there seems to be
> quite a bit of duplication between BrailleBlaster and liblouisutdml,
> particularly configuration files and semantic action files.
>
> If focusing on configuration files and semantic action files, I just
> don't get the difference of those for BrailleBlaster and liblouisutdml.
> OK, its said that the BrailleBlaster ones are for how BrailleBlaster
> displays documents and the liblouisutdml ones are for how Braille is
> produced, but what is the difference, surely the idea of the GUI of
> BrailleBlaster is so that people can see the structure of the document
> and how that might be handled for being put into Braille? Why does
> processing for the specific output have to always go right back to the
> underlying document format?
>
> Let me give some examples: Documents normally contain certain common
> features, headings, paragraphs, lists, emphasised text, etc. All the GUI
> is interested in is whether it has a heading, a list, a paragraph, etc,
> it should not be interested in how XHTML, docbook, epub, etc store these
> elements. Equally, there are two outputs (at current) which the user may
> encounter, the BrailleBlaster GUI and Braille/tactile document.
>
> Requiring a mapping from file format to output system leads to a large
> number of files required. In this case where there are two views
> (BrailleBlaster's GUI and Braille from liblouisutdml) we need twice as
> many as supported document formats. If additional document views were
> added (eg. may be someone wanted to add a way to produce a spoken
> version using TTS, not suggesting it as an actual feature at this point)
> then another whole set of files for all supported formats would need
> producing.
>
> I guess I am thinking down the MVC design pattern, the document is the
> model and implements a common model regardless of where it came from,
> the views being BrailleBlaster's GUI and the Braille document (at the
> moment) and the controller being there simply to introduce the two
> together. If a new document format was supported then neither view needs
> any modification, if a new view were added then none of the support
> formats would be affected. Sounds much more maintainable.
>
> Additionally with what was originally suggested, I get the feeling that
> BrailleBlaster's GUI could show document elements differently depending
> on what file format is being viewed (IE. a heading may look different if
> viewing a epub rather than docbook). OK, one might work to try and not
> let this happen, but the potential is there from what I understand.
>
> Just my views.
>
> Michael Whapples
> On 12/10/2012 18:39, John J. Boyer wrote:
> >Here is the block diagram with some clarifications. I would appreciate
> >comments. It is important to be quite sure that this is the best
> >approach for BrailleBlaster.
> >
> >--------------------
> >
> >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.
> >
> >The file is first parsed to produce a parse tree.
> >
> >The configuration files indicated in the user's settings are then read
> >and used to begin the construction of a semantic table. This table is
> >used to specify how markup in the document is to be rendered on the
> >screen and how styles and actions are to be associated with markup for
> >editing. For more on configuration files see Appendix A.
> >
> >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 or
> >according to an indication in the configuration files. The information
> >in the semantic-action files is used to complete the semantic table. For
> >more on semantic-action files see Appendix B.
> >
> >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.
> >
> >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.
> >
> >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.
> >
> >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.
> >
> >Dince 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.
> >
> >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-actionn 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.
> >
> >Besides saving the file as utd or as an envanced 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: Configuration Files
> >
> >Here is a description of BrailleBlaster configuration files. They
> >specify how BrailleBlaster shall operate. The one which the user has
> >selected is referenced in the userSettings.properties file. Selection,
> >creation and editing are done via a dialogue. Note that BrailleBlaster
> >configuration files are completely separate from liblouisutdml
> >configuration files. They are stored in the configurations directory
> >within the programData directory. Below is a sample file. More lines
> >will be added as development proceeds. Explanations follow the sample.
> >
> >--------------------
> >
> >hyphenate=no
> >pageNumberAt=top
> >topMargin=0.5
> >leftMargin=1
> >rightMargin=0.5
> >bottomMargin=0.5
> >paperHeight=11
> >paperWidth=8.5
> >xmlheader="<?xml=version='1.0'=encoding='UTF-8'=standalone='yes'?>
> >semanticFiles=*
> >internetAccessRequired=no
> >newEntries=yes
> >file:filename include
> >debug=no
> >styles=para,heading1,heading2,list
> >
> >--------------------
> >
> >The first line specifies whether hyphenation should be used when a
> >document is displayed onscreen.
> >
> >The second line specifies where the page number should be placed.
> >
> >Then come six lines specifying margins and paper size. These are used
> >principally for making hard copies.
> >
> >the xmlheader line specifies the header that should be used at the
> >beginning of new files.
> >
> >semanticFiles is a comma-separated list of the semantic files to be
> >used. Here the value is an asterisk, which means to use the file which
> >is named for the root element of the document. This is actually the
> >default, so this line is not strictly necessary.
> >
> >InternetAccessRequired specifies whether the Internet will be needed for
> >processing a document, e.g., for getting a DTD.
> >
> >newEntries specifies whether a record should be kept of the markup in a
> >document which has not been assigned to a semantic action or style. This
> >is useful when processing a new flavor of xml for which a
> >semantic-action file does not exist. It applies to all documents.
> >Semantic-action files can also have a newEntries line. It applies to
> >that type of document only.
> >
> >The include line, with a preceding filename, specifies that another
> >configuration file is to be read at the point where it is encountered.
> >
> >debug specifies whether extra testing should be done, experimental
> >features used, and extra logging done.
> >
> >The styles line gives a comma-separated list of styles that will be used
> >in displaying and editing a document. These styles are in the styles
> >directory.
> >
> >The order of entries in a configuration file is generally not important.
> >However, an include line does cause the referenced file to be read at
> >the point where it is encountered.
> >
> >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. They are
> >stored in the semantics directory in the programData directory. There is
> >a dialogue for creating and editing them.
> >
> >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.
> >
> >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.
> >
> > 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.
> > configfile, Specify a configuration file.
> > configstring, Specify a configuration string.
> > configtweak, Use new configurations while rendering.
> > # 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
> > attrtotext, Transform an attribute value to text.
> > runninghead, Specify a running header.
> > footer, Specify a page footer.
> > boxline, Specify a line of identical characters.
> > italicx, Italicise the text within the markup.
> > boldx, Bold it.
> > underlinex, Underline it.
> > 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.
> >
> >
> >
>
--
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:
