[brailleblaster] Re: Block diagram with clarifications
- From: "John J. Boyer" <john.boyer@xxxxxxxxxxxxxxxxx>
- To: brailleblaster@xxxxxxxxxxxxx
- Date: Sun, 14 Oct 2012 05:12:48 -0500
To put it plainly, I am not at all interested in reducing duplication
between BrailleBlaster and liblouisutdml. In fact, I would consider it a
distraction and unwise. It would further increase the confusion about
the difference between Braille and print, and it would require coding
effort that could be better spent on other things.
This debate has had the merit of making me think more about how
BrailleBlaster works. Most of the things in the configurationn file
really belong in the UserSettings file. newentries and
internetAccessRequired can go in the semantic-action files. The latter
is needed to tell BrailleBlaster that it will need to access the
Internet for information, such as a DTD to be used in validation. APH
wants to do validation. They also want to be able to download files from
the Internet.
A semantic-action file tells BrailleBlaster how to set up the document
model given a parse tree of the document.
Michael, I am surprised that you don't think a decent word processor is
part of BrailleBlaster. It was decided at the beginning that we would
not use an existing word processor. ViewPlus had too much experience
with the difficulties of doing so. The word processor is built into the
specifications. The edit submenu contains all the usual editing items.
I am quite sure that both blind and sighted users will expect a
reasonable, but not fancy word processor. If they do not get it they
will consider BrailleBlaster an inferior product.
I think it would be bestto move on. You can still help with Mercurial
and Java.
John
On Sun, Oct 14, 2012 at 10:39:14AM +0100, Michael Whapples wrote:
> OK, see my responses inline below.
>
> Michael Whapples
> On 14/10/2012 00:50, John J. Boyer wrote:
> >Michael,
> >
> >Your view of BrailleBlaster is more restrictive than mine, and I think
> >than most of the people who are working on it. My understanding of the
> >original specification is that BrailleBlaster is to be a word processor
> >with special Braille facilities.
> MW: Really, I thought BrailleBlaster was an application for producing
> high quality tactile documents. I thought that the word processing
> facility was just part of the application assisting in reaching that
> goal. If making a word processor with Braille facilities, then why not
> take an existing word processor, which probably will be far more
> advanced than we could hope to produce ourselves, and create an add-on.
> MS Word being the most well known, OpenOffice/LibreOffice being probably
> the best known open source alternative, but there are others like lotus
> symphony.
>
> >The print view is simply a standard WYSIWYG eord procesor. The user does
> >not normally see the structure of the xml document any more than the
> >user of MSWord sees the structure of a doc file.
> MW: Yes and no. A sighted user even in WYSIWYG editors do see the
> structure of the document, the problem is that sometimes
> authors/authoring tools don't produce proper structures and fake the
> look of the structure. So My point was that the WYSIWYG editor of
> BrailleBlaster needs to highlight (not screen highlighting, but rather
> just drawing attention to) what is actual structure and what is not.
> Again its a representation of information.
>
> MW: As an example, sometimes authors will fake the look of a heading by
> applying text attributes to a block of text rather than specifying an
> actual heading. In such a case, MS word's WYSIWYG editor will know the
> difference of this to where the author used a heading style, where a
> heading style is used a screen reader will actually announce heading
> information, where as for the case of altered text attributes it won't
> (also Word can use things marked with heading styles to create table of
> contents, etc). However, visually the two ways may look the same, and so
> the structure is less possible to see.
>
> MW: Coming back to BrailleBlaster, the editor needs to draw the user's
> attention to these sorts of deviation from proper structuring.
> Continuing with the heading example, as far as I know font size has no
> bearing on what Braille will be produced, therefore it need not show the
> font size changes, if headings are shown larger (which is a fairly
> normal print convention) then the structure can be seen in quite an
> intuitive way. The user may not believe they are seeing "structure" but
> they are.
>
> MW: Also, I must make it clear, they would not be seeing the XML
> structure, they would be seeing the document structure. The subtlety
> being that they would not be seeing DAISY, ePub, docbook, Word doc, etc
> structure, they would be seeing the abstract document (probably the
> document model) structure, or more accurately a representation of the
> structure.
> >Reducing duplication between BrailleBlaster and liblouisutdml is not a
> >goal. The goal is clarity. That is the reason for separate files. In
> >liblouisutdml there are cases of blocks of code that are similar but
> >that have enough difference that combining them would reuire a lot of
> >extra code and probably a much greater chance for bugs. The same is true
> >to an even greater extent between liblouisutdml and BrailleBlaster.
> MW: Well reducing duplication is normally not stated as a project goal,
> its just a good practice principal. It generally makes things much more
> maintainable, fewer places to fix discovered bugs, fewer places to add
> enhancements, greater chance things will exhibit consistent behaviour,
> etc. Having looked at things, I feel there is even unnecessary
> duplication inside liblouisutdml, configuration files just cover too
> much, I mean cover too many processes, linking stuff which probably
> should never be linked. Just because I desire using a different paper
> size, why do I need to redefine things like XML processing? Surely XML
> processing has nothing to do with my output paper size?
>
> MW: If clarity is what is being sought, may be its time to decide taking
> a different approach. I seem to remember when you first sent information
> about BrailleBlaster configuration and semantic action files there being
> confusion, now I have been confused, this doesn't seem to hold good
> indications for clarity.
>
> MW: I just await those questions like: "I have changed my BrailleBlaster
> configuration yet the Braille output is not changed, why is this so?"
> Will people really grasp the idea that the one piece of software they
> downloaded has two sets of configuration files, will they be aware when
> only one needs changing and when both will?
>
> MW: I just feel its unmaintainable, both technically and from user
> experience/support, therefore for this corner of BrailleBlaster I have
> to say, I have said my view and if you pursue it then I may be best to
> not be involved with this part so I don't have conflicts (how can I
> support something I don't believe in).
> >Sighted users do like to get hard copies of documents. They will expect
> >a reasonable format, though not, of course, all the formatting of
> >MSWord.
> >
> >I would like to see others join in this discussion.
> >
> >John
> >
> >On Sat, Oct 13, 2012 at 08:03:02PM +0100, Michael Whapples wrote:
> >>This is just puzzling me further. I think there must be some fundamental
> >>parts of BrailleBlaster which are not properly defined. While
> >>documentation can seem burdensome, it sometimes is necessary to ensure
> >>people are talking about the same things. May be BrailleBlaster needs
> >>more documentation and may be a glossary for what certain terms mean. In
> >>this spirit, I have quoted certain phrases in the following message and
> >>given definitions for what I understand these terms to mean (see end of
> >>my message for my glossary).
> >>
> >>First thing is, may be semantic action files are doing too much, in this
> >>I mean both liblouisutdml and BrailleBlaster semantic action files. When
> >>one looks at BrailleBlaster and liblouisutdml there are certain things
> >>which are common to both (eg. loading a document into a "document model"
> >>from the "original source"). In trying to minimise duplication then
> >>these common actions should be made common. While the ideal case might
> >>be the code and the rules for how to do this would be shared, it may not
> >>be possible to have common code, but if the rules are defined in
> >>external files then these should be reusable. I would argue that the
> >>code could even be common, while liblouisutdml may not want to become
> >>specific to BrailleBlaster, BrailleBlaster is certainly highly linked to
> >>liblouisutdml, so why couldn't that offer a function to applications for
> >>loading a "document model". Obviously this would need the Java bindings
> >>for liblouisutdml to know how to convert the C "document model" into a
> >>Java "document model" and probably back.
> >>
> >>So what I am saying is, may be semantic action files need to be changed
> >>as to what they work on, rather than working on "original source" they
> >>should work on a "document model". Then the files defining the rules for
> >>mapping from "original source" to "document model" could be common and
> >>so no duplication there.
> >>
> >>Now to the fundamentals which aren't making sense to me. Well I will
> >>only mention one, as its relevant and I don't want to spend too much
> >>time writing this email.
> >>
> >>What is the "print view"? What is the "print view" for? How does the
> >>"print view" add to BrailleBlaster goals? What is the "print view" not?
> >>My answers to these say that the suggested configuration files contain
> >>stuff they should not need to contain, hence why I am asking these
> >>questions in case the definition has moved on.
> >>
> >>Here are some answers from my understanding:
> >>1. The print view is a representation of the document using "print text
> >>characters". The print view will allow the user to easily see the
> >>structure of the document according to the actual structural definition.
> >>2. The print view will be used by the user to identify where the
> >>"original source" did not give specific structural information and so
> >>will allow the user to correct this so that when the document is
> >>translated the Braille will contain the correct layout. An example of
> >>where a document might not contain correct structural information is
> >>where the author specified fonts and other text attributes for a heading
> >>rather than using the correct mark up for a heading.
> >>3. By allowing the user to identify where the document does not contain
> >>sufficient structural information to allow a good quality Braille
> >>translation, it will assist the user in ensuring that the document has
> >>correct structural information and so hopefully lead to better quality
> >>Braille documents being produced.
> >>4. The "print view" is not designed for "pretty print documents". If a
> >>user desires a pretty print document to read there document in print
> >>form then they may be advised to find alternative software designed for
> >>that purpose. Equally the "print view" would not be for creating
> >>perfectly formatted hard copy pretty print documents, again other
> >>software may be better designed for that task. To implement any of this
> >>answer in BrailleBlaster's print view would not contribute to the goals
> >>of BrailleBlaster as I understand them, hence why they are what the
> >>print view is not.
> >>
> >>Taking my answers, particularly to the question of what the "print view"
> >>is not, I have questions over why BrailleBlaster configuration files
> >>need page information. Why would someone be printing the "print view",
> >>if the view is purely on screen then why does it need splitting into
> >>pages? The only case I can see for when a page break needs to be seen in
> >>the "print view" is when the document contains an explicit page break.
> >>On screen need not have paper size, margins, etc, these are all just
> >>unnecessary.
> >>
> >>Again, may be configuration files are covering too much, may be they
> >>need to focus on specific parts of the process. As an example, when
> >>would it ever be needed that BrailleBlaster would need internet access
> >>to load the document but liblouisutdml would not? Surely this
> >>information could be shared? In fact, is there anything in the xml
> >>section of a liblouisutdml configuration file which would not be
> >>relevant to BrailleBlaster? So in seeking maximum reuse, why cannot
> >>BrailleBlaster use a liblouisutdml configuration file? May be correct
> >>uses of sections in the configuration files would be needed, eg. a
> >>[BrailleBlaster] section which liblouisutdml will happily ignore. These
> >>configuration files could be provided by the BrailleBlaster project if
> >>you don't want liblouisutdml to ship with this extra stuff, also correct
> >>uses of include statements could help here in keeping the separation you
> >>want. Also the liblouisutdml specific stuff is actually relevant to
> >>BrailleBlaster here, BrailleBlaster will need to provide a user friendly
> >>way of configuring liblouisutdml, so why not have it that BrailleBlaster
> >>works on one file?
> >>
> >>Glossary:
> >>Document model: An abstract representation of a document. It should be a
> >>common model regardless of where the document came from or what the
> >>"original source" format is. There may be different implementations of a
> >>document model for different programming languages, but it might be
> >>conceivable that there may be ways of passing thenm between programming
> >>languages if such interoperability was desired.
> >>Original source: This is the format of a particular document, examples
> >>might be epub, docbook, daisy, XHTML, and so on.
> >>Pretty print documents: This is a print document as one would desire if
> >>producing it for a sighted audience, IE. how a publisher would intend to
> >>make a book look, making an article presentable for publishing, etc.
> >>Print view: The visual view of the document in BrailleBlaster, where the
> >>text will use print text characters and the view will allow
> >>identification of the document's structure. The print view will allow
> >>editing of the document, this is mainly to allow the user to correct
> >>minor text issues (eg. spelling mistakes) and correct formatting (eg. if
> >>the original source presented a heading by increasing the font, etc
> >>rather than specifying the correct structural element for a heading).
> >>Print text characters: These are the print characters of the alphabet.
> >>Most commonly the characters within the latin character set, but could
> >>also be Chinese characters, etc.
> >>
> >>Michael Whapples
> >>On 13/10/2012 17:03, John J. Boyer wrote:
> >>>well, there is a lot of misunderstanding. I misunderstood your
> >>>presentation in your first message, thinkikng it was not
> >>>well-thought-out. Here is more explanation.
> >>>
> >>>BrailleBlaster semanntic-action files are used to construch a document
> >>>model. This model is then used for displaying and editing both the print
> >>>and Braille views.
> >>>
> >>>Braille rules vary wildly from one country to another. It is less
> >>>confusing to have a fairly standard print display of the document. The
> >>>user can always see how a block of characters is rendered in Braille by
> >>>focusing on the Braille window. This will show the part of the print
> >>>text corresponding to each line of the Braille in the print window.
> >>>
> >>>There is a great deal in liblouisutdml semantic-action files that is
> >>>meaningless to BrailleBlaster. Similarly, the structure of
> >>>semantic-action files that is best for BrailleBlaster would not work in
> >>>liblouisutdml. Trying to combine the two to keep down the number of
> >>>files would lead to a great deal of confusion. There is already a lot of
> >>>confusion between what pertains to print and what pertains to Braille.
> >>>
> >>>liblouisutdml and BrailleBlaster development should remain separate,
> >>>because liblouisutdml and liblouis are intended to form a transcription
> >>>engine that can be used in almost any application. Of course,
> >>>liblouisutdml can be enhanced with functionality that we discover is
> >>>needed while developing BrailleBlaster. An example would be a function
> >>>to report how much of a transcription is finished as a percentage, so
> >>>that it can be used in a progress bar.
> >>>
> >>>John
> >>>
> >>>On Sat, Oct 13, 2012 at 04:11:31PM +0100, Michael Whapples wrote:
> >>>>I did put thought into the reply, to say it wasn't well thought out to
> >>>>me feels insulting.
> >>>>
> >>>>Whether I understood everything fully may be a question, if there are
> >>>>misunderstandings then we would do better in trying to explain it
> >>>>better.
> >>>>
> >>>>I am still unclear to really what the difference of semantic action
> >>>>files for BrailleBlaster and liblouisutdml are. Yes print is not Braille
> >>>>and vice versa, but both are generated from documents. So map from the
> >>>>document model to the view, why have the view go right back to the
> >>>>original XML?
> >>>>
> >>>>Documents may come from many sources, so why not map from the file
> >>>>format to the document model? This surely would reduce duplication of
> >>>>how to process a particular flavour of XML as there would only be one
> >>>>definition of how to process it.
> >>>>
> >>>>With what I have suggested, there would be files to map from file
> >>>>formats into the document model and files to map from the document model
> >>>>to the user's representation of the document (print or Braille). With
> >>>>what I am suggesting, add a new supported document format, you only need
> >>>>to add one file to map from the format to the document model, rather
> >>>>than one for each user's representation (at current that would be two
> >>>>files). Want to add another user's representation, my idea would mean
> >>>>add one mapping, under what has been proposed I understand it to require
> >>>>as many files as formats supported.
> >>>>
> >>>>May be the current design of BraileBlaster and liblouisutdml where they
> >>>>are fairly separated would not allow exactly what I suggest, but still
> >>>>why do they need separate files to use? Isn't there a way to allow them
> >>>>to share semantic action files? This would at least reduce the work in
> >>>>supporting various formats. There may be features of the files not used
> >>>>by both (eg. the files may specify editing information which
> >>>>liblouisutdml does not need), but any uneedede information could be
> >>>>ignored by that tool (liblouisutdml could ignore editing information).
> >>>>
> >>>>Further to the above, I also reject the idea that BrailleBlaster's GUI
> >>>>is producing print documents. This is quite a subtle point, the
> >>>>rejection is that we are not producing software which sighted people
> >>>>would choose to use to print documents because the visual output is so
> >>>>pretty, rather the visual aspect is more to show the document structure
> >>>>so that a sighted person will understand how the document will be
> >>>>translated (IE. a heading need not look like a print heading as in a
> >>>>print book, they just need a way that they can easily distinguish there
> >>>>is a heading which will appear in Braille). My point here is that the
> >>>>visual display needs to represent what should happen in the translation
> >>>>process, so may be the two are fairly linked in what they need to show,
> >>>>IE. they are just different ways of showing the same information.
> >>>>
> >>>>I guess a better phrase to describe what I mean, BrailleBlaster's GUI
> >>>>shows a print representation of BrailleBlaster's document, liblouisutdml
> >>>>will produce a Braille representation of that document. Ideally the
> >>>>Braille representation needs to conform to official Braille rules (I
> >>>>mean more than just the translation, I mean follow the standard for
> >>>>formatting), so may be the BrailleBlaster document model will be swayed
> >>>>towards Braille rules.
> >>>>
> >>>>Notes on what I have used, to show this was thought out:
> >>>>* BrailleBlaster semantic action files are tied to the underlying
> >>>>document format: Appendix B says "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".
> >>>>* Section 4 of the liblouisutdml documentation has the title "Connecting
> >>>>with the XML document - Semantic action files", this sounds very much
> >>>>like it goes right back to the underlying XML as well, also supported by
> >>>>mentions of using xpath expressions to identify nodes, etc.
> >>>>* My statement of documents should go to a intermediate document model,
> >>>>so that the various views need not be concerned with the underlying
> >>>>document format, this is a key part of object orientation. If the
> >>>>document model were represented by a interface, then the view only needs
> >>>>to know that what it has been handed implements that interface, it need
> >>>>not know how it works or even what class type it is. This is why
> >>>>frameworks which use dependency injection, such as the spring framework,
> >>>>can be extended so easily, although it must be noted that I am not
> >>>>suggesting we go as far as using dependency injection or spring
> >>>>framework.
> >>>>* My thought on BrailleBlaster's GUI and the Braille being just
> >>>>different representations of the same information, a similar example
> >>>>might be having data in a table and the same data plotted on a graph, it
> >>>>may look very different but it contains exactly the same information. It
> >>>>must be noted that even for some data there may be a number of different
> >>>>choices of what sort of graph could be used (eg. peoples' responses to a
> >>>>multiple choice question, it could be shown on a bar chart, it possibly
> >>>>could be shown in a PI chart).
> >>>>* Further to that last point, the data may be held in many ways, it
> >>>>might be in an excel spreadsheet, it might be in a database, it might be
> >>>>in a CSV file, may be in XML, etc. It just seems crazy duplication to
> >>>>map straight from the input to the output rather than going to an
> >>>>intermediate model (eg. for responses to a multiple choice question I
> >>>>have identified three outputs and I have named 4 input formats, direct
> >>>>mapping requires 12 mappings, mapping to an intermediate model would
> >>>>only require 7 in total, 4 mappings for input and 3 mappings for
> >>>>outputs. It gets worse as you add more inputs/outputs, add another
> >>>>output you will need 16 direct mappings, but only 8 if going through a
> >>>>common model, increase outputs to 5 and you need 20 direct mappings but
> >>>>only 9 if going through the model, and so on).
> >>>>* How many inputs and outputs do we wish to support in BrailleBlaster?
> >>>>There are certainly a large number of inputs, there are many file
> >>>>formats out there and as I mentioned it is possible to think that other
> >>>>outputs could be conceived (eg. conversion to speech document). I
> >>>>certainly do not wish to support such a level of duplication as my
> >>>>calculations seem to suggest may need supporting in BrailleBlaster.
> >>>>
> >>>>Michael Whapples
> >>>>On 13/10/2012 02:36, John J. Boyer wrote:
> >>>>>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:
