-
Notifications
You must be signed in to change notification settings - Fork 0
Home
I will be posting zipped snapshots of my operating code until I can work out a folder system that accommodates developer tools and documentation as well. As soon as the main branch of expeDITA framework core is ready to contribute, I may transition the wiki to an expeDITA server (to eat one's own dogfood, as it were). For now I'll post key information for developers here.
any2dita.com is a snapshot of the current production code running on http://any2dita.com. This zip includes the plugin; to install, unzip into a test folder (I used http://localhost/any2dita.com/ to test the application in my laptop's WAMP stack, for example) and follow the #CONFIG: flags in the comments in index.php.
plugin_any2dita is the standalone plugin folder. For now, in this form, the plugin is fairly simple to unzip and study. These files are probably ready to put into a branch now.
Enough of the expeDITA framework is present to support use of the plugin subsystem, making it effectively a dedicated any2dita application. Additional modules will include router, CRUD services, UI features, DITA content preprocessing for conditionality, alternate renditions, API access, and more.
The theme services in expeDITA are based on easy integration of freely available "css templates" that can be decomposed into a standard structure that fully supports all orginal widget types. It is agnostic about whether the content flows into fixed or responsive themes. It is flexible to the design point that themes can be switched on the fly while retaining the visitor's state. On the public demo site, look for a selector widget by which you can change themes to suit your preference, or to compare the same content in other rendering contexts.
The Markdown converter relies on the PHP libraries provided by Michel Fortin. They are used as is and the only binding is the dynamic include as needed.
The Rich Text converter will initially make use of the whizzywing.js lightweight editor from whizzywing.com.
Having built several PHP-based conversion interfaces and tools, I was struck by the common elements across them:
- Input interfaces are largely alike, and pass nearly all the same parameters to the conversion tool.
- For the formats chosen, HTML code, pasted HTML, Markdown, and Mediawiki, there is a common normalization into HTML for a very aggressive pipeline that does both code-based DOM manipulations (chunking the apparent hierarchies for example) and conversion into a rich intermediate form that goes through a final XSLT-based transform for the to-DITA result. This is the beating heart of any2dita.
- Obviously, after the conversion to DITA, all the user interface features are the same: save, view, clean up. So all outputs end up in the common report.
HTML on the Web is depraved and behaves pathologically in conversion. But I believe that if each depraved instance can be handled by a custom hook in the pipeline, we'll eventually build a robust tool for much of the conventional documentation scraped from the Web.
I have higher hopes for Markdown because when it gets converted into HTML, most of the bad practices just can't happen. This stuff is a joy to transform. You will get the most reliable conversions for content prepared as conventional Markdown documents. The main dependency is that it follow the practices of the daringfireball site the Fortin converters are written to.
expeDITA plugins are simply dropped into the expedita/plugins/ folder in the framework distribution. Plugins use action and filter hooks to insert themselves into expeDITA program logic. Plugin files are read at the plugin root level and one folder down. This means that single file plugins can fulfill simple-to-modest enhancements, and a folder can support applications that require multiple files. For example, the main XSL transforms are in a child folder of a single dita-doc plugin folder that keeps together that particular renderer.