[brailleblaster] Re: Block diagram with clarifications
- From: "John J. Boyer" <john.boyer@xxxxxxxxxxxxxxxxx>
- To: brailleblaster@xxxxxxxxxxxxx
- Date: Sun, 14 Oct 2012 07:26:37 -0500
I think it is time for others to express their opinions. From early
discussions it was obvious to me that BrailleBlaster needed a word
processor so it could create and alter documents. I wasn't even aware of
a different understanding until Michael said that BrailleBlaster should
not create documents.
John
On Sun, Oct 14, 2012 at 11:43:16AM +0100, Michael Whapples wrote:
> On the word processor, I will just put this down as yet another example of
> the BrailleBlaster project being poorly defined and documented. Obviously
> "basic word processing" was never properly defined, and so as a result
> (predictably) people have concluded very different things.
>
> Word processing in BrailleBlaster beyond what I have been describing to me
> has no obvious contribution to BrailleBlaster meeting its goals of providing
> a user friendly way for people who may not be Braille experts to produce high
> quality tactile documents. Please explain how word processor as you describe
> contributes to the goals. Have I missed a goal of BrailleBlaster`? What was
> that goal?
>
> Doing things which do not contribute to a project's goals is an unnecessary
> use of resources, I just want to ensure this does not happen here. There
> possibly are serious questions to ask regarding resources, originally
> BrailleBlaster was planned to take two years, this has been missed, why? If
> its a lack of resources, then its even more critical to ensure that none are
> wasted.
>
> Michael Whapples
> On 14 Oct 2012, at 11:12, John J. Boyer <john.boyer@xxxxxxxxxxxxxxxxx> wrote:
>
> > 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
> >
> >
>
--
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:
