Towards Developing a DITA Editing Platform on FreeBSD

Having developed a certain sense of interest with regards to writing technical documentation, I've been studying periodically about the Darwin Information Typing Architecture (DITA). There are a number of things that I would like to highlight about DITA, as in a sense of a thesis document – I've tried to collect my notes, as such, with Evernote. Thus far, I have been unable to write any single thesis document about the topic, rather developing only a series of itemized lists of notes, and a small bibliography.

Presently, I think it may be as well to begin writing some narrative text about DITA. Although I may not feel as able to write fluidly, in a digital media – as juxtaposed to a media of graphite and paper, with clipboard, to an older style of desktop writing appliance – but it is surely easier to share a work of writing produced in a legible digital font – here juxtaposed to my own cursive handwriting and ad hoc visual layout approaches, as when writing with pencil on paper.  Sure, I have begun to sketch out an idea for a more fluid style of sketching in a digital media, but it would need some work in regards to ergonomic presentation and editing of vector graphics, and therefore may depend on software not yet developed for the Common Lisp Interface Manager (CLIM). Presently, I am more preoccupied of developing a workflow towards DITA editing with free/open source software (FOSS) tools. Though I have looked at both of the XXE XML editor and OxygenXML for a DITA workflow, I would like to start writing DITA with a platform more familiar to me. Personally, I'm comfortable with Emacs and pSGML.

In regards to any manner of perhaps esoteric features of DITA – such as, DITA linking, DITA content replacement, and any broadly semantic qualities of DITA's  topic element classes – it might not seem that a baseline Emacs + pSGML environment could be completely sufficient, If applied primarily as a DITA editing enviromment. The Emacs + pSGML platform, of course, can be extended with Emacs Lisp. Although Emacs, in turn, may not seem like a very rigorous programming enviromment,  as when juxtaposed to the Eclipse IDE or IntelliJ IDEA platforms – both of which are developed, primarily, in the Java(R) programming language – but I think there is a manner of an incentive in the simple convenience of the interactive, functional command interface of Emacs + pSGML. It may seem to be enough that I might not be excessively distraught about the absence of programmatic rigour in the Emacs Lisp programming language, juxtaposed to Oracle's Java(R).

So, but in that I would not wish to develop an manner of an ivory tower of this concept, and I will be writing with Emacs on a FreeBSD desktop, I think it needs a a sense of a project, in itself. I propose that a FreeBSD port can be developed of each of: The DITA 1.2 Document Type Definition (DTD) files, there integrating with the XML entity resolver's configuration on FreeBSD; the DITA Open Toolit, likewise to be integrated with the host's XML entity resolver, moreover to be applied with the user's own ASF Ant configuration. If anything analogous to the Comprehensive PERL Archive Network (CPAN) may be developed, moreover, as to provide a software distribution service for extensions to the DITA DTDs and DITA Open Toolkit (DITA OT) XML stylesheets, perhaps such a thing may be anyhow designed onto CORBA services, moreover the CORBA Component Model (CCM), if not Java(R) and OSGi services. Of course, from an end user's perspective, that might be secondary to the availability of a FreeBSD port for each of those two existing components, respectively the DITA DTDs and DITA OT.

Fourthly, as towards a concept of applying DITA in an open documentation system, there is a simple concept of a topic repository model that may be developed, in a manner of writing DITA as like for a sort of an – albeit not primarily web-based, and insamuch not web-editable – Wiki-like format. Though it may seem to loose something of a popular incentive, for it not being a web-editable format, but inasmuch as that a DITA editing platform may serve to provide a manner of editing support not easily provided altogether with a web-based interface environment, then perhaps there may be an adequate "up side" to the design decision, as such.

Immediately, I am somewhat distracted of the tedium of making a complete Git clone of the WebKit source code repository – perhaps this is referred to as multi-tasking. It seems that the initial Git fetch must be run incrementally, onto that same source code repository. It's presently at `--depth=20000`, in no small detail. I have referenced only a couple of forum topics [Matthews 2010][midtiby2011], to try to resolve that a complete `git clone` onto that source code repository has consistently has failed. Proceeding to to a `git fetch` at `--depth=60000`, the Git incremental-clone procedure succeeds, so far.

Ed. Note: There's also something to write about `git gc`

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]

Workspaces, Source Trees, and Working Sets - Towards an Abstract View Of Baseline Project Resource Container Models (Draft 7)

Brief Exposition

Earlier this year, I'd purchased a Chromebook. I'd made an extensive effort of detailing my "First boot," albeit as something of a "Chromebook Fanboy" then -- that, before I began to try to comprehend the ChromiumOS source code repository, a task that remains "Incomplete," to this day.

A couple of months after that "fist boot," my Chromebook became my primary development platform. That was around when my old/newest Toshiba laptop became unbootable from its internal hard drive -- as was certainly due to the hard shutdowns that that PC was so apt at making, when running MS Windows, and the corresponding filesystem corruption during the hard shutdowns, corruption apparently not only on the NTFS partition but also on the boot sector.  That laptop, with that internal hard drive, now cannot boot from the internal hard drive. I've certainly tried to recover that other laptop's internal hard drive, using SystemRescueCD, but to no avail. I can use SystemRescueCD on a DVD-ROM drive, to boot the PC and to chroot to the existing Linux partition on that PC, and from that chroot, I can even 'mount' the primary NTFS partition on the hard drive, and any of the two NTFS-format rescue partitions. I've tried to use TestDisk to recover the MBR and make the internal hard drive bootable again, but to no avail. At some future time, I might endeavor to install an SSD drive into the laptop, and to image the old hard drive onto that SSD, across the "swap."

When I was using my Chromebook as my primary development platform -- granted, absent some features such as SBCL, Virtualbox, and QEMU, it being a Samsung Chromebook, and therefore an ARM Chromebook -- first, I'd installed a KDE chroot using Crouton. Using that chroot environment, I'd begun to make use of an SD card that I had around, a little 16GB media card, to store the files of the chroot desktop workspaces.

An ad hoc Workspace Model

In regards to how I had developed workspaces on that SD card, it was essentially similar to how the Eclipse IDE manages workspaces  in the Eclipse IDE. Sure, though, the approach I had developed was distinctly ad hoc. In a personal regards, I was using only Emacs as an IDE -- Eclipse Kepler not being available via the Ubuntu ARM ports, at that time. In the approach I'd developed for ad hoc workspace development on that SD card, I basically had made one workspace per each specific task area such as I could endeavor to collect and to develop source code resources within.  For instance, I'd made an a workspace for working with McCLIM, on that platform -- ultimately, porting McCLIM to ECL and CCL,  The last workspace that I'd made, on that platform, it was essentially for building an Eclipse Kepler edition for ARM, using the Ubuntu Eclipse source package. I'd left that aside, however, when I discovered that as well as I would also to backport Jetty for that, I'd also have to backport Apache Tomcat 7. I wasn't certain of how much further the backport list would expand from there, so I left that backport project aside, in its workspace.

Presently, I have a great, new, remarkably well featured and furthermore remarkably student budget friendly HP Pavilion 15" TouchSmart PC. In the process of making it "My PC," I've since made a TAR archive of my workspaces set on the Chromebook, transferred it to the Pavilion PC using SSH, then configured the Cygwin environment on the Pavilion PC to create native MS Windows Shortcuts in lieu of Symbolic Links, and then unpacked the archive as transferred. 

Presently, before finishing that workspace migration, I would like to take some time to reconsider how I've organized the workspaces of the same -- considering that in the Eclipse IDE, I could use project groups, alternate to filesystem directories, for creating something like my Chroebook's ad hoc workspaces, namely for organizing source trees into task groups, insofar as in metadata created and applied by the Eclipse IDE.

The tangential idea that -- in regards to this article -- that I am "looking for," I think, is to create a portability layer for working with Eclipse IDE workspaces in a development environment in Common Lisp.

There is a pragmatic concern, also. As a case in point, there's my CCL workspace from my Chromebook, in which I've cloned a source tree for each of:

• CCL Linux ARM, release 1.9
• CCL Linux ARM Trunk
• CLX, as in portable CLX
• FFIGEN4, as forked by CCL

Presently, I'll need to add a CCL Windows Trunk source tree to that short list. I would like to be able to keep that short list consistent, of course, for synch back to the Chromebook -- and that, in developing not any sort of hack in tools development, around this task.

Migrating the SCCM Repositories

When I was migrating the Chromebook's workspaces onto my Windows 8 laptop, I observed that I might have to update the Git config for each Git repository now on the latter, to ensure that each Git repository is using a desired semantics for text file line endings on the Microsoft platform, as well as with  specify settings with regards to symlink handling, file permissions, pathnames, and for using SourceGear DiffMerge as a tool for the diff and merge commands in Git. 

Sure, I've used git config to specify some site-specific default settings for those configuration items, however I'm concerned that I should have to ensure that all of those configuration items will override any current repository-specific configuration settings as such, for those configuration items, and onto those source tree items that I've now migrated from an Ext4 filesystem.

Of course, there are also some SVN and CVS managed source trees in that set of workspaces. I think, it calls for a development of an abstract model for SCCM tools and interfaces

Workspace as Concept

Presently, I would like to begin a tangent about ISO topic maps and/or SKOS and/or CORBA. Briefly:

• A workspace -- in a sense of a container of digital file source trees and changesets -- can be modeled as a SKOS Concept
• ...regardless of the SCCM tool used for each respective soucre tree and changesets
• ...and in such a manner a that the SKOS Model thusly defined may be applied by developer tools within an integrated desktop environment, as for a purpose of "checking out" a sort of broader "thing" than a Git repository with submodules  -- namely and rather, for "checking out" or "cloning" such a workspace as would be defined in such a SKOS model
• SKOS 2 is implemented in OWL
• OWL is supported with the ODM metamodel published by the OMG
• MOF2I, published by the OMG, provides a means for transforming an MOF metamodel into a set of IDL interface definitions, though of course the practical details of the transformation may seem however obscure in all of the the rhetorical statements in the MOF2I specification
• A CORBA-backed distributable service could be developed for checking out workspaces, in using a model derived of the SKOS model -- possibly, integrating persistent CORBA IOR URI into the OWL+SKOS metamodel, furtermore
• Such a network service could be userfully implemented on a thin client platform, or on a PC

Workspace as Filesystem Resource

An Eclipse IDE workspace may contain an indefinite number of source trees -- literally, filesystem resources -- each, loaded as an Eclipse project, with corresponding Eclipse IDE project metadata.

Each source tree may be categorized, within the Eclipse IDE, within zero or more working set items. Those working set items would, in each, be local to the Eclipse IDE workspace that is being visited in the Eclipse IDE. (An Eclipse IDE working set would be similar to the concept of ad hoc filesystem workspace, as I'd made when developing on my Chromebook)

The set of working set items in a single Eclipse IDE workspace is listed in the workspace metadata created by the Eclipse IDE, in each specific Eclipse IDE workspace. However, rather than editing the metadata external to the metadata controller application -- in this situation, the Eclipse IDE -- it would be more advantageous to use an interface within the Eclipse IDE -- such an interfaces as may be available, hypothetically, for a sort of provisioning of project resources in the Eclipse IDE.

Workspace as CORBA IDL Interface

Hypothetically, it is possible to share working sets between individual desktop platforms -- ostensibly, in an extension to the Eclipse IDE, as well as in extensions to other desktop applications such as Emacs SLIME, and mobile applications such as Textastic. A CORBA architecture may be developed, for such an extension -- implementing sort of a peer to peer CORBA architecture for authorized workspace sharing between individual desktop PCs and thin client platform applications, or alternately, for sharing workspaces and project information in synchronization with a central project management server, the later also using CORBA .

In CORBA IDL, the interface definitions for the source-tree/working-set association model would be essentially trivial -- such as to define an IDL interface SourceTree (container, contained), and an interface, WorkingSet (container), with a few simple operations in each respective IDL interface definition for managing a doubly-linked list associating zero or more SourceTree items with each WorkingSet.

Of course, the WorkingSet interface would, in itself, need a convenient, additional interface available -- such as may be defined with a name, WorkspaceManager -- for listing a set of WorkingSet instances registered within a CORBA ORB. The WorkspaceManager and Workspace interfaces could then be defined as to contain similar operations for operating on a doubly-linked-list associating zero or more WorkingSet objects with a single WorkspaceManager

Applications for a CORBA Workspace Manager

• Central management of user/team workspaces, working sets, and working-set/project associations
• Towards an abstract concept similar to Git submodules and SVN externals
• May be defined in such a manner as to be applicable not exclusively onto a single SCCM service, but rather, as to be portable onto multiple SCCM services (Git, SVN, Hg, Darcs, CVS, ...) 
• May be designed as to allow for team synchronization of workspaces, across a heterogeneous SCCM service mix
• Might provide some features such as may be functionally analogous to some features provided in the Eclipse IDE, primarily in the Eclipse Team extensions
• May be applied as effectively a component for a team SCCM application framework, for LAN-local developer teams and for distributed developer teams
• May be utilized within centalized workflows for distribution management and reporting for projects
• May be utilized within mobile development applications, essentially as a sort of distributed project model

Commensurate Dependency: Multi-User Model in CORBA

To define a multi-user WorkspaceManager as an application of CORBA network service technologies, it would require a definition of a set of CORBA IDL interface definitions, for defining a user model in CORBA IDL.

• Goals:
• to support user authentication in CORBA interface implementations
• to provide interfaces for user identity management, for application within user authorization procedures, in extensional implementations of CORBA interfaces
• for application in the Project WorkspaceManager design and its implementation
• for application within other CORBA application designs entailing multi-user access and authorization models and corresponding procedures applied onto digital resources, within a CORBA services network
• References for a central user model interface library, in free/open standards and free/open source software models, may include:
• Liferay. Security and Permissions, in manual: Liferay Portal 6.2 Developer's Guide
• The Liferay Portal Permissions DRAC model extends on the JSR 286 Portal Resource model, and JSR 286 Principal Security model
• Refer to the following sections of JSR 286 (PDF):
• Section PLT.21, User Information -- referencing JSR 286 user attributes
• Section PLT.24, Security -- noting section PLT.24.2, Roles, and the corresponding section SRV.12.4 of the Servlet Specification as referenced in JSR 286, namely JSR 154, Java Servlet^tm 2.4
• Picketlink IDM -- as used in GateIn and the eXo Platform
• OpenLDAP
• Note that the Liferay, GateIn and eXo Platform portal frameworks, when installed, can each be configured to use an LDAP service for principal authentication and principal metadata within the web portal
• Furthermore, a Linux host can be configured to use an LDAP service for host-level principal authentication
• Therefore, LDAP might be preferred as a a central principal information service for networked applications
• Observe the features of OpenLDAP's functional model -- as detailed in the OpenLDAP Administrator Guide 2.4  (alternate editions)-- including:
• Central, selective LDAP directory replication, using OpenLDAP slurpd
• OpenLDAP backend service interfaces
• BerkeleyDB
• SQL
• Others
• Alternatives: On the Java platform, Apache DS provides a Java-based LDAP server implementation. On Microsoft Windows host networks, consult documentation about Microsoft Active Directory.
• PAM, NSS on Linux
• Note configurations for using an LDAP service as a principal authentication service on a Linux host, using PAM and NSS
• Kerberos
• Note, specifically, the concept of a domain in Kerberos
• X.509 (PKI/PMI) -- referencing:
• X.509 article at Wikipedia, the Free Encyclopedia
• Note, specifically, the concept of certificate revocation lists
• strongSwan -- free/open source VPN service application
• EJBCA -- Java-based X.509 Certificate Authority (CA) service
• OpenSSL -- free/open source X.509/SSL toolkit
• CORBA 3.3, module CSI

Implementation Proposal

CORBA ORB Implementations

• JacORB, 
• Contexts
• Eclipse IDE plugins
• Liferay 'ext' plugins
• JacORB CORBA service for Liferay 
• Observe that a "new" JacORB service installation would collide with the CORBA services provided by some enterprise application containers such as Glassfish, but would provide necessary functionality lacking from a "Bare bones" Liferay installation onto Tomcat 7
• Implementation of CORBA user model onto Liferay
• Implementation of additional IDL interfaces onto JSR 286 (comprehensive)
• Liferay 'portlet' plugins
• Workspace view (project resource list)
• WorkspaceManager porlet (workspace list)
• configuration dashboard component for WorkspaceManager
• Observe that JacORB supports authentication with Kerberos (LAN, etc)
• CLORB, in the Common Lisp components