Towards a Definition of a Document System in CORBA

In beginning to develop a concept for a mobile application utilizing the automotive OBD-II/CAN protocol and an OBD-II interface such as the ScanTool 426101 OBDLink MX, the author has begun developing a corresponding concept of an automotive notebook, such that would be accessible via a CORBA service. Though it may be a concept somewhat less stylish than a concept of a networked car with a Bluetooth or WLAN OBD-II/CAN interface, it is the author's opinion that the concept of an automotive notebook is more the appropriate concept to develop, as the first essentially challenging feature of the design of the application.

The author is familiar with some concepts ascertainable of structured markup formats, including the stylish old adage that XML was defined for separating logic of document structure from style of document presentation. Contrasted to a document format such as HTML or LaTeX, those defining -- essentially -- both structure and presentation information, at least that old stylish adage made for a few convenient keynotes for authors assisting in the original popularization of XML. XML itself -- similar to HTML -- is accompanied with a formal Document Object Model (DOM), and is accompanied furthermore by a formal XML to IDL binding definition -- namely the XML Valuetype mapping -- such that would allow for developing an application interface onto an XML like document structure, via CORBA.

In defining an automotive notebook data type in CORBA IDL as a data type subsumed by notebook, and the notebook data type subsumed by document, the software design then may be implemented as it being orthogonal to a design for a CORBA-based document service.  The Document IDL interface, of course, would not be all that there would be to such a thing, though -- in itself -- it presents some particular design concerns, as to its implementation.

Offhand, the author knows of at least a few variably "Mobile-friendly", variably "Editable" document formats, such that masy occur to mind as with regards to how a CORBA-based document service may be defined, viz a viz

• EPUB Book
• ODF Document Package
• DocBook Article

In the author's opinion, the last one of those three presents the most appealing alternative.

Albeit, DocBook does not -- in itself -- define a document container format, such as may be applied for purpose of streams-oriented document storage and streams-oriented document distribution -- namely, in as any single document being stored as a single filesystem object including text, graphics, tables, charts, and so on. In the author's opinion, the appeal of DocBook for this document system design, the appeal is not so much for developing a streams-friendly storage model, but rather for developing a semantically meaningful markup model, separate to any manner of an aesthetically appealing presentation model -- as whether for visual document presentation, or audible document presentation, or for a braille document presentation.

As with regards to developing a visual presentation model for applications in a document service as would implement the XML valuetype mapping for CORBA IDL, a concept of XSL formatting objects (XSL-FO) occurs to the author's consideration. XSL-FO is implemented in Apache FOP. In a sense, XSL-FO is to XML as like DSSSL is to SGML. In another sense: XSL-FO serves to develop a page-oriented rendering for XML, via XSL transformations.

With a further binding for Cascading Sytlesheets (CSS) defined onto the XSL-FO layer in the presentational aspects of the same document service -- thus, with an object model for data structures in a manner of CSS presentational information, then defined with a set of CORBA IDL interfaces -- the presentational aspects of the document service may then be designed with a complete data model, insofar as data structures for presentation of the underlying XML valuetype mapping. To implement a set of human computer interface (HCI) elements for the same document service design,  however, that would be one of the inevitable "Tricky parts."

If in the design of a software model, one may make reference to an item of existing work, in software applications -- even insofar as with regards to designs of human-computer interfaces -- the stylesheet editing components of UX Write then occur to the author's consideration. UX Write is an application available on Apple iOS mobile devices. In the HCI design of UX Write, as the author recalls, UX Write provides a separate interface for each of style editing and for document editing. The features defined to a style in the style editing interface, then, would serve to affect how the markup of a document in UX Write is presented in the document editing interface. The document editing interface may as much be viewed as a markup editing interface, but not in so far as for editing of bare markup -- rather, a sort of stylized markup editing interface. Thus, there is a design concept available, insofar as for how a document editor application may be implemented with a set of separate features for document editing and for presentational style editing. That, in itself, would still not serve to provide a convenient document editing toolkit, though it is towards a design of something like as so,  for an implementation onto CORBA, whether or not with round-trip serialization onto individual files in a filesystem.

Some Thoughts about Source Code, Design Decisions, and Documentation - Markdown, DocBook, and the Igneous-Math Source Tree

Having completed a finals exam for an electronics course I'm enrolled in, I've published the Igneous-Math source code to GitHub, tonight [igneous-math]. The Igenous-Math source tree is currently in the beginnings of its 1.3 edition, focusing on definition of unit conversion formulas. Though, simply, I do look forward to the beginning of the prototyping for the 1.3 edition -- have been bouncing around a few ideas, namely to make reference to the Garnet KR system [garnet] for its formula modeling as applied in KR schema objects and as may be applied in arbitrary Lisp code -- however, I would like to make some more refined documentation for the source tree, also -- now at the end of the end-of-week sprint, in developing that source tree.

In developing the Igenous-Math system, presently, I'm using GNU Emacs as an IDE, together with a system named SLIME, in its Emacs Lisp components -- and in its corresponding Common Lisp components, named SWANK -- focusing mostly on SBCL as the Common Lisp implementation, but  I've made some testing of the source tree using CCL, also. In applying those software components, together with the Git changeset management system, in an installation of KUbuntu within Virtualbox, I think it makes for a fairly comfortable development environment -- it's certainly easy to test the Common Lisp source code, using SLIME+SWANK, and simultaenously so, when running the Linux platform and the Microsoft Windows platform, using Virtualbox. Of course, I would like to make a modicum of effort to ensure that the Igneous-Math system could be a system that other software developers might feel comfortable to use, too, at least once it would be at its first branch-level revision.

Throughout this week's short sprint in the development of the Igenous-Math source tree, I've been making some copious notes in the source-tree -- something to remind oneself of a bit of a sense of context, in relation to any source code approximate to the comments, in the source tree. Of course, that can seem convenient enough, from one's own perspective in developing the source tree. As far as the availability of the source tree, I understand that it might seem to leave something lacking, though, under the heading, "Documentation."

So far as what may be accomplished in developing the documentation of a source tree, I think:

1. An item of documentation may serve as to explain one's design decisions, to oneself, as well as towards the respective audience or user base
• That rather than developing an axiomatic mode, with regards to documentation, alternately one may seek to explain one's rationale, to the reader, as with regards to any specific design decisions made in the development of a software system -- that not only may the documentation serve to explain so many design decisions, but it might alsoserve to place those design decisions within a discrete sense of context, conceptually.
• Inasmuch, candidly, an item of documentation may serve as to explain one's rationale to oneself , at a later time -- thus, perhaps serving to ensure something of a degree of design consistency, with regards to one's rationale, in the design of a software system.
2. An item of documentation may serve as to describe any set of things presently developed within a source tree -- thus, making a sort of simple inventory of results.
3. Furthermore, an item of documentation may serve as to describe any number of things planned for further development, within a source tree and within any related software components
4. That an item of documentation may serve a necessary role in ensuring that the software code one has developed can be reused, as by others and by oneself, extensionally.

Although the Igenous-Math system is published under a license as free/open source software, but candidly, I would not wish to have to ask the reader to peruse the source tree, immediately, if the reader may simply wish to understand the natures of any set of software components published of the source tree. 

So, perhaps that's towards a philosophical regard about documentation. Corresponding to a philosophy about documentation, there would also be a set of tools  one would apply, as in developing a  set of documentation items as -- altogether -- the documentation of a project serving as a sort of content resource, within a project.

Though I have given some consideration towards applying a set of complex editing tools and structured formats for documentation -- had made a note, towards such an affect, in the MetaCommunity.info Work Journal, at a time when I was considering whether I'd wish to use the DocBook format and the DocBook toolchain for documenting another software system I've developed, namely AFFTA -- however, tonight I'm more of a mind that it would be just as well to use the simple Markdown format, in canonical Markdown, or in the more structured MultiMarkdown format. Markdown may serve as a relatively accessible document format, for simple notes and documentation within a software source tree.

DocBook, in its own regards, would be a more syntactically heterogenous format to integrate within a software source tree. In a sense, DocBook doesn't look a whole lot like text/plain, though XML is a plain text format.

A DocBook XML document, in particular, can be written with any existing text editor, such as Emacs, or with a specialized XML editor, such as XXE, the XMLmind XML Editor. In Emacs, specifically, the nXML Emacs Lisp extensions can be of particular utility, when writing XML documents [JClark][NMT].  Together with a complete DocBook toolchain [Sagehill], the DocBook schema [TDG5], and DocBook editing platform, the documentation author would be able to create a well structured and comprehensively descriptive reference document for a project.

As something of a rosetta stone for document formats, there's also Pandoc. 

Presently, MultiMarkdown is the format that I prefer for developing so much as the README file for the Igenous-Math codebase.  There's even a nice, succinct guide page available about MultiMarkdown [ByWord] explaining the additional features provided with MultiMarkdown, as it extending on the original Markdown format.  For a purpose of delineating the simple "To Do" items of the Igneous-Math codebase, and for providing anything of an external, "High level" overview of the codebase -- such as one would encounter of the README file for the source tree, as when viewing the source tree, in its web-based GitHub presentation --  MultiMarkdown may be sufficient, in such application. Candidly, to make such a simple presentation about the source tree, using DocBook -- for one thing, the DocBook format does not so readily allow for the author to control the formatting of the documentation. With DocBook, perhaps there's something of a tradeoff for semantic expressiveness, in lieu of any easy visual design for documentation. By contrast, Markdown allows for an easy control of the visual layout of the documentation, though the Markdown syntax offers only a relatively small set of markup features.

Secondly, the toolchain automation that would be required to simply publish a README file, in Markown format, if from a source document in DocBook format -- such a tranformation model would certainly be less than ideal. It would allow for a transformation of only a limited set of elements from the DocBook schema, and though it may serve to produce some relatively accessible documentation -- accessible to the sighted web visitor, at least -- but one may find it difficult to explain to oneself: Why one would transform a source document from DocBook format, into a source document in Markdown format. Candidly, the GitHub presentation for Markdown is a feature extending of Github's own support for the Markdown format. One might think it's unsurprising, if there's no such specific support for all of XML. in the GitHub web interface -- XML is a very broad markup format, in all of its structural extensibility and its text/plain format

So, if it's possible to effectively produce a snapshot of one's point of view, at a point in time, then here's my view about the Markdown and DocBook formats, considered in relation to development of the Igneous-Math source tree.

It might bear a footnote, also, that the MultiMarkdown format is supported on Ubuntu platforms, in the libtext-multimarkdown-perl package. For integrating MultiMarkdown with Emacs MarkdownMode, there's some advice by David from Austin, TX [ddloeffler]