The biggest failing we run into time and time again around content / digital publishing projects is the misunderstanding of where the complexity lies.
When someone buys an RDBMS, they don't assume that simply installing such a system and some trivial configuration will solve their data problems for them or produce their data-driven software application. They understand that this is just a tool which they will use to do the large amount of work of analyzing their data needs, designing a schema, and implementing it in their RDBMS along with application code to use it.
However when they buy a content management system, or some other content tool, they have a tendency to expect that it WILL fill all their content needs, and that the analogous work of analyzing, designing and implementing are minor. While people understand that "data" is hard, complex, a lot of work etc., they seem to assume content is relatively easy.
This is not unlike the scenario with a lot of other software projects where some out-of-the-box middle-ware is expected to provide a solution and the task of analyzing and defining their needs and of designing a solution (even in terms of the "parts" the middle-ware supplies) is vastly under-estimated.
A content management / publishing system (and by this I mean not specifically a CMS, but the whole system and process by which a company manages and publishes its content, including whatever software systems and tools are used to facilitate this, and the human processes around that) can be enormously complex. It's not the same as everyone else's, and there's not some off-the-shelf system that simply does it all automatically. The commonality of "everyone has content" is about as significant as the commonalty of "everyone has data". It's the details around "what kind of" and "how used" that drastically overshadow the commonalities.
The software tools, wherever they fall on the out-of-box / highly customized / home-rolled spectrum provide pieces of the solution, not the big picture, and that big picture, that overall design, is needed to even know how to put those pieces together. In fact, if you haven't figured out your overall design in detail, then you don't really even know what the pieces are that you need.
This big picture is a domain model. You have a business domain around your content, and the different sorts of content, the roles they play, and the processes that go into producing, maintaining, publishing (by which we include making available through some specialized web application) are all parts of this domain model. These software systems and tools you've bought do not provide that domain model or those elements of it. They may provide you with means of modeling them or implementing your model. But if you don't start with that model...well, good luck.
This is the understandable human failing of wishful thinking. Analyzing your needs and designing that model is HARD. It's not the sort of thing that business people, or content production people are good at or know how to do. Software people, on the other hand, who do (the competent ones) know how to do that, typically don't understand the content production and publishing domain, and communicating a deep understanding of those needs from one group to the other is also very hard. Unfortunately content-oriented software specialists are both rare, not commonly recognized as a specialty, and (largely because of the misconception outlined above) undervalued.
Wednesday, January 6, 2010
Friday, May 29, 2009
NAVSEA: Wrycan and Altova Project Case Study
Thousands of technical processes. CAD drawings. Schematics. Wiring diagrams. Safety and Training requirements. Piddle packs.
What do all of those items have in common? They are all parts of a complex Navy system that were documented in an antiquated format.
Wrycan was chosen by NAVSEA to assist in converting tens of thousands of pages of existing documentation into XML to comply with the Navy document model. Wrycan used Altova's XML editor as a key component in the editioral process. Modules from the Wrycan XMS were used to facilitate workflow and document assembly while Wrycan's XSL Consultants developed the high-end PDF output.
The result is an end-to-end process that allows NAVSEA to author, edit, review, approve, publish and distribute large volumes of technical and process information to those who need it.
Wrycan and Altova have just published a case study outlining the project. Read it to find out how Wrycan and Altova worked together to ensure the project was a success.
Interested in talking about your content with us? Get in touch.
~
What do all of those items have in common? They are all parts of a complex Navy system that were documented in an antiquated format.
Wrycan was chosen by NAVSEA to assist in converting tens of thousands of pages of existing documentation into XML to comply with the Navy document model. Wrycan used Altova's XML editor as a key component in the editioral process. Modules from the Wrycan XMS were used to facilitate workflow and document assembly while Wrycan's XSL Consultants developed the high-end PDF output.
The result is an end-to-end process that allows NAVSEA to author, edit, review, approve, publish and distribute large volumes of technical and process information to those who need it.
Wrycan and Altova have just published a case study outlining the project. Read it to find out how Wrycan and Altova worked together to ensure the project was a success.
Interested in talking about your content with us? Get in touch.
~
Monday, April 20, 2009
Product Announcement: XMS Correlation Tool
Cambridge MA - Say goodbye to managing textbook correlations in Microsoft Excel and Microsoft Word. Wrycan is happy to announce the release of a new product, the XMS Correlation Tool.
An innovative product for educational content publishers, the XMS Correlation Tool is built to solve one of the most common challenges facing educational publishers today, creating and managing educational standards correlation data.
The XMS Correlation Tool is a web-based system built on top of Wrycan XMS that allows you to create, manage and utilize correlation data for all your education content, regardless of format.
The XMS Correlation Tool supports various correlation scenarios including:
figure 1. correlation web interface
Sound interesting? Want to see more? Contact us to get more information and to set up a demo.
About Wrycan
Wrycan, Inc., a privately held company, was founded in 2002 to provide content-centric products and services to companies looking for innovative approaches to content creation, management, publishing and delivery. Our primary product, Wrycan XMS, is a content management platform built on years of experience solving "the hard content problems" for our clients. Wrycan XMS includes robust content repository, workflow and publishing facilities that together provide a solution for the most complex content management/utilization needs.
Your content is innovative, your content tools should be innovative too.
For more information about Wrycan's products and services, please visit our website, www.wrycan.com or contact John Corkery, Director of Business Development (john.corkery (at) wrycan.com)
~
An innovative product for educational content publishers, the XMS Correlation Tool is built to solve one of the most common challenges facing educational publishers today, creating and managing educational standards correlation data.
The XMS Correlation Tool is a web-based system built on top of Wrycan XMS that allows you to create, manage and utilize correlation data for all your education content, regardless of format.
The XMS Correlation Tool supports various correlation scenarios including:
- correlating content to state and national standards
- correlating content to custom intermediary standards
- correlating custom intermediary standards to state and national standards
figure 1. correlation web interface
Sound interesting? Want to see more? Contact us to get more information and to set up a demo.
About Wrycan
Wrycan, Inc., a privately held company, was founded in 2002 to provide content-centric products and services to companies looking for innovative approaches to content creation, management, publishing and delivery. Our primary product, Wrycan XMS, is a content management platform built on years of experience solving "the hard content problems" for our clients. Wrycan XMS includes robust content repository, workflow and publishing facilities that together provide a solution for the most complex content management/utilization needs.
Your content is innovative, your content tools should be innovative too.
For more information about Wrycan's products and services, please visit our website, www.wrycan.com or contact John Corkery, Director of Business Development (john.corkery (at) wrycan.com)
~
Monday, February 23, 2009
How to Customize Attributes in the DITA Open Toolkit PDF Plugin
This tutorial uses the DITA Open Toolkit 1.4.2.1 and the corresponding PDF plugin release, and Wrycan's demo text. This assumes you have a working DITA environment and can run the default formatting with PDF plugin. If you don't know how to do this, contact us and we can post an example! We will be working in the demo/fo/Customization directory of the open toolkit as shown in the image below.
1. In this example, we are going to customize the <codeblock> element by increasing the font size, changing the font color and weight, and modifying the background color. Our default code block looks like the following before any changes:
and the dita xml content looks like:
<codeblock>/* I should have green text and a red background */
<xsl:template match="dita">
<output>DITA IS COOL</output>
</xsl:template>
</codeblock>
2. In order to modify the <codeblock>, we first need to figure out which attributes to change. The method I find most useful is to run a full-text search the demo/fo directory. Searching for the term "codeblock" yields a few results, one of which is demo/fo/xsl/pr-domain.xsl and the template is found on line 46: <xsl:template match="*[contains(@class,' pr-d/codeblock ')]">. Examining this template shows us that we want to modify the "codeblock" attribute set as shown on line 48: <fo:block xsl:use-attribute-sets="codeblock" id="{@id}">. Looking at the text search again, we can see that the "codeblock" attribute set is found in demo/fo/cfg/fo/attrs/pr-domain-attr.xsl on line 41: <xsl:attribute-set name="codeblock">. The next step is to customize this attribute set.
3. In order to customize this attribute set, copy demo/fo/Customization/fo/attrs/custom.xsl.orig to custom.xsl and copy the codeblock attribute set into the new XSL. We are going to modify the background color, font color, font size, and make the font bold. In order to do this, we only need to specify the attributes that we are going to change, so the resulting block of code to add looks like:
<xsl:attribute-set name="codeblock">
<xsl:attribute name="background-color">#dc7f72</xsl:attribute>
<xsl:attribute name="font-size">12pt</xsl:attribute>
<xsl:attribute name="color">#005511</xsl:attribute>
<xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>
Note, that we could also copy over the entire codeblock attribute set and modify that, which would results in the code below. Both of these should produce the same output.
<xsl:attribute-set name="codeblock">
<xsl:attribute name="space-before">0.4em</xsl:attribute>
<xsl:attribute name="space-after">0.8em</xsl:attribute>
<xsl:attribute name="white-space-treatment">preserve</xsl:attribute>
<xsl:attribute name="white-space-collapse">false</xsl:attribute>
<xsl:attribute name="linefeed-treatment">preserve</xsl:attribute>
<xsl:attribute name="wrap-option">wrap</xsl:attribute>
<xsl:attribute name="background-color">#dc7f72</xsl:attribute>
<xsl:attribute name="font-family">Monospaced</xsl:attribute>
<xsl:attribute name="line-height">106%</xsl:attribute>
<xsl:attribute name="font-size">12pt</xsl:attribute>
<xsl:attribute name="keep-with-previous.within-page">always</xsl:attribute>
<!-- <xsl:attribute name="keep-together.within-page">always</xsl:attribute>-->
<!-- Additional attributes -->
<xsl:attribute name="color">#005511</xsl:attribute>
<xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>
4. The last step is to tell the plugin that we have made customizations. In order to do this, copy demo/fo/Customization/catalog.xml.orig to catalog.xml and then open the copied file and edit the 6th row to uncomment the code from:
<!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/-->
to:
<uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl">
and save the file.
5. This should create the output below for the <codeblock> element. There are many different ways the attributes can be customized and this is just one small example. If you have some ideas for other examples you would like to see, contact us!
Monday, February 16, 2009
Create SVG-based charts "on the fly" using XML and XMS
In order to really take advantage of XML-based content you need more than just an XML-aware database or repository. We built the XMS Content Management System to provide the right tools and facilities to unlock and make use of all the inherent value in well-designed XML content/data.
A cool yet practical example is to take a simple data set and create charts using XML and SVG. In a recent client project we needed to create reports that indicated how assets were distributed across geographies. Aside from just showing a table of the data (See figure 1), we wanted to produce a world map that would show exactly how the assets were allocated across each region. In this how-to I will explain how this was done using the XMS but most of the steps are general enough you should be able to replicate most of them with other system. If you have questions about how to do something like this using a different system feel free to contact us.
figure 1: table of geographic asset distribution
The first step to adding a map visual for this data was to find a good SVG map. We found some good options released by the CIA for public use on Wikipedia.
The map was very well defined and each country had it's own separate structure. The map was black and white but we wanted to add color to each region to make it easy to differentiate. Since we were using Morningstar's regional data we had to modify the SVG map to group the countries into the correct regions and give them a specific color. This was easy since the CIA used the proper two character country code for each SVG object. A few CSS changes yielded the following in the SVG:
figure 2: SVG with Morningstar region mappings
You can download a copy of the modified SVG here (~2MB).
Next, we loaded the SVG map into the XMS along with some sample data sets containing examples of asset allocation over geographic regions. To create the publication that would produce the report containing both the table and the map, two XSL transforms were written; one to produce the HTML report with the table (report.xsl) and one that would produce the correct SVG (map.xsl). Together these XSL transforms would create the report by generating the table of results and the PNG version of the map.
The XMS has a powerful publishing module which allowed us to process the SVG map and embed the result into the report. In this example the report.xsl would do most of the work while the map.xsl would simply assign the correct percentages to the regions of the map in the SVG. A sample of the XSL used to assign the precentages in the SVG map is shown in figure 3.
figure 3: sample of the map.xsl showing the regional percentages being added (shown in XMLSpy from Altova)
The resulting SVG is then rasterized to a GIF, JPG or PNG and the URL to the new image would be "handed back" to the report.xsl and added to the resulting report HTML. The XMS uses XEP from RenderX to convert vector graphics into raster formats. You could use other tools like Batik to get the same result. The result report combining both the table and the map looks something like the following:
figure 4: resulting regional report
Pretty slick. Of course we did the same for other charts (i.e. pie charts) but the map example was the most interesting. Another advantage of using SVG is the fact that it is vector-based, meaning that PDFs generated with the native SVG (not rasterized) will look very polished.
A cool yet practical example is to take a simple data set and create charts using XML and SVG. In a recent client project we needed to create reports that indicated how assets were distributed across geographies. Aside from just showing a table of the data (See figure 1), we wanted to produce a world map that would show exactly how the assets were allocated across each region. In this how-to I will explain how this was done using the XMS but most of the steps are general enough you should be able to replicate most of them with other system. If you have questions about how to do something like this using a different system feel free to contact us.
figure 1: table of geographic asset distribution
The first step to adding a map visual for this data was to find a good SVG map. We found some good options released by the CIA for public use on Wikipedia.
The map was very well defined and each country had it's own separate structure. The map was black and white but we wanted to add color to each region to make it easy to differentiate. Since we were using Morningstar's regional data we had to modify the SVG map to group the countries into the correct regions and give them a specific color. This was easy since the CIA used the proper two character country code for each SVG object. A few CSS changes yielded the following in the SVG:
figure 2: SVG with Morningstar region mappings
You can download a copy of the modified SVG here (~2MB).
Next, we loaded the SVG map into the XMS along with some sample data sets containing examples of asset allocation over geographic regions. To create the publication that would produce the report containing both the table and the map, two XSL transforms were written; one to produce the HTML report with the table (report.xsl) and one that would produce the correct SVG (map.xsl). Together these XSL transforms would create the report by generating the table of results and the PNG version of the map.
The XMS has a powerful publishing module which allowed us to process the SVG map and embed the result into the report. In this example the report.xsl would do most of the work while the map.xsl would simply assign the correct percentages to the regions of the map in the SVG. A sample of the XSL used to assign the precentages in the SVG map is shown in figure 3.
figure 3: sample of the map.xsl showing the regional percentages being added (shown in XMLSpy from Altova)
The resulting SVG is then rasterized to a GIF, JPG or PNG and the URL to the new image would be "handed back" to the report.xsl and added to the resulting report HTML. The XMS uses XEP from RenderX to convert vector graphics into raster formats. You could use other tools like Batik to get the same result. The result report combining both the table and the map looks something like the following:
figure 4: resulting regional report
Pretty slick. Of course we did the same for other charts (i.e. pie charts) but the map example was the most interesting. Another advantage of using SVG is the fact that it is vector-based, meaning that PDFs generated with the native SVG (not rasterized) will look very polished.
Wednesday, February 11, 2009
How to Modify the Cover Page in the DITA Open Toolkit PDF Plugin
This tutorial uses the DITA Open Toolkit 1.4.2.1 and the corresponding PDF plugin release, and Wrycan's demo text. This assumes you have a working DITA environment and can run the default formatting with PDF plugin. If you don't know how to do this, contact us and we can post an example of how to do this! We will be working in the demo/fo/Customization directory of the open toolkit as shown in the image below.
1. With our sample content, the cover page of the document contains plain title text slightly above the center of an empty page:Wrycan® Lorem Ipsum Test
We are going to modify this so that our company logo appears below the title text.
2. In order to modify the cover page, we first need to figure out which stylesheet creates the cover sheet. The method I find most useful is to run a full-text search the demo/fo directory. Searching for terms like "cover" and "cover sheet" yield no results in this case, so the next thing to do is look at the xsl files themselves. Starting with demo/fo/xsl/fo/root-processing.xsl we can see there is a template called createFrontMatter. Searching in the XSLs for this template reveals that it is in demo/fo/xsl/front-matter.xsl.
3. The next step is to modify the template. In order to do this, copy demo/fo/Customization/fo/xsl/custom.xsl.orig to custom.xsl and copy the createFrontMatter template into the copied XSL. The logo image is going to be added below the subtitle, so below the template call with the "set the subtitle" code comment. Add the code below underneath the subtitle template:
<fo:block text-align="center" width="100%">
<fo:external-graphic src="url({concat($artworkPrefix, '/Customization/OpenTopic/common/artwork/logo.png')})"/>
fo:block>
<fo:block text-align="center" width="100%">
<fo:external-graphic src="url({concat($artworkPrefix, '/Customization/OpenTopic/common/artwork/logo.png')})"/>
fo:block>
The parameter $artworkPrefix is passed in during the build process and the string "/Customization/OpenTopic/common/artwork/" is created for where our logo image is going to end up during processing.
4. Now that the code has been added, we need to actually add the logo. To do this just copy an image file of the name logo.png into demo/fo/Customization/common/artwork folder or use ours as shown at the end of this post.
5. The last step is to tell the plugin that we have made customizations. In order to do this, copy demo/fo/Customization/catalog.xml.orig to catalog.xml and then open the copied file and edit the 10th row to uncomment the code from:
<!--uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/-->
to: <uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/> and save the file.
6. This should create the output below on the cover sheet of the pdf. There are many different ways the cover sheet can be customized and this is just one small example. If you have some ideas for other examples you would like to see, contact us!
Wrycan® Lorem Ipsum Test
Saturday, February 7, 2009
How to Customize the DITA Open Toolkit PDF Plugin Output to Remove "on page xx" Text for Cross References
This tutorial uses the DITA Open Toolkit 1.4.2.1 and the corresponding PDF plugin release, and Wrycan's demo text. This assumes you have a working DITA environment and can run the default formatting with PDF plugin. If you don't know how to do this, contact us and we can post an example of how to do this! We will be working in the demo/fo/Customization directory of the of the open toolkit as shown in the image below.
1. We will customize the cross references so that there will be no "on page xx" displayed. The DITA markup that we are customizing looks like the following in XML:
<p><b>This xref link to <xref href="PellentesqueConsectetuer.xml#pellCon/sampleXREFtarget" scope="local"/> is a sample link to an element within this topic.<b><p>
And the default output looks like the following in the PDF output:
This xref link to Table 3: Sample XREF Target on page 11 is a sample link to an element within this topic.
This xref link to Table 3: Sample XREF Target on page 11 is a sample link to an element within this topic.
2. Next, we need to find the code in the XSL where this occurs, and then create the customization layer to override this code. To do this, a full text search of the demo folder can be done for the text "on page." One tool that can do this quickly is Edit Plus which reveals that in demo/fo/cfg/common/vars/en_us.xml, on line 258, there is a variable that is set with the name "On the page" as shown below:
<variable id="On the page"> on page <param ref-name="pagenum"/></variable>
3. Another search can now be done for the text "On the page," which shows that demo/fo/xsl/fo/links.xsl on line 371 is where this variable is being called, in the template <xsl:template name="insertPageNumberCitation">. The next step is to integrate this template into the customization layer.
4. A quick and easy way to do this is to copy the file demo/fo/Customization/fo/xsl/custom.xsl.orig to custom.xsl. Then open it and copy/paste the original insertPageNumberCitation template from links.xsl. This template has an <xsl:otherwise> containing the "On the page" variable, so in order to remove the "on page xx" text, this otherwise case should be removed by deleting everything from and including <xsl:otherwise> to <xsl:otherwise> and save the file. Note: If you are going to be making a lot of customizations to the fo plugin, then it might be a good idea to utilize the <xsl:import>
function to better organize your customizations. If you have any questions about this method, feel free to ask and we'll do a post on it!
5. Finally, the fo plugin needs to be told that customizations have been added. In order to do this, copy demo/fo/Customization/catalog.xml.orig to catalog.xml and uncomment line 10 from:
<!--uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/-->
to
<uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/> and save the file.
<!--uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/-->
to
<uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/> and save the file.
The creation of the customization layer is now complete! Re-run the pdf and see the results. In our case the output now looks like the following:
This xref link to Table 3: Sample XREF Target is a sample link to an element within this topic.
This xref link to Table 3: Sample XREF Target is a sample link to an element within this topic.
If you would like to see any other ways to customize the DITA Open Toolkit, contact us and we can provide one!
Subscribe to:
Posts (Atom)
