Tuesday, May 30, 2006
Sunday, May 28, 2006
Star Wars Weekends!
When we were invited to go to DisneyWorld with some friends, we didn't realize it would be during two of the Star Wars Weekends at MGM! Here's a cool Sandtrooper that was on patrol on Mickey Avenue...
Categories: Sci-Fi
Friday, May 26, 2006
DocSwag!
Norm Walsh has set up a storefront for DocBook swag! Just t-shirts, buttons and a bumpersticker for now. Since caffeine consumption is a staple of technical writers, I'd like to request coffee mugs be added to the product list! I think mouse pads would also be an essential!
Get your DocSwag now at http://www.cafepress.com/dbswag!
Categories: DocSwag
DocBook XSL 1.70.1 released
OK, now it's official. The latest version of the DocBook XSL (1.70.1) has been released.
You can download the latest stylesheets at: http://sourceforge.net/projects/docbook, and you can view the release notes at: http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html
Now go forth and DocBook with style! :-)
Categories: General
Thursday, May 25, 2006
IPBuddys: a new eComic!
My son, Connor, has created a pretty cool comic series about two computers in the networked world. The computers? Right now, a PC laptop and an iMac. Perhaps at some point he can add our old Pentium II-266 tower and 486 desktop!
Originally, he wanted to call it "Saturday.COM", but that name is currently taken, even though that URL doesn't seem to respond. I tried to help him come up with a new name, and eventually settled on "IPBuddys".
He's publishing on Blogger for now. If you have any suggestions of a better place to publish a comic, send me a comment!
You can view IPBuddys at: http://www.ipbuddys.com. What an amazing time we live in, where even an 8-year-old can share his creativity with the world!
Congratulations, Delta IV team!
Congratulations to the Boeing Delta IV team on the successful launch of the GOES-N mission yesterday! I've been fortunate to work with many of the folks on this team, and understand the amount of work and coordination involved in making this a success. Great job!
I was fortunate to see this rocket on the pad several times over the past year. Very cool stuff! I'm glad the Delta IV made the journey as intended, and that the GOES-N payload will help meteorologists in a big way.
Categories: Space
Tuesday, May 23, 2006
Migrating from Interchange to Import/Export
I was trying to upgrade or convert some old Arbortext Interchange import templates to the new Arbortext Import/Export map templates. I searched high and low for this documentation, to no avail (even with Google Desktop!). Eventually I resorted to a support ticket with PTC. To save everyone else some time and trouble, here's the official response:
Instructions for migrating from Interchange to Import/Export can be found on page 216 of the Customizer's Guide(page 228 in the PDF Reader).
And just to be a little more clear, that doc should be in your docs directory (C:\Program Files\Arbortext\Editor\docs\customizing_guide.pdf)
Wednesday, May 17, 2006
DocBook XSL 1.70 released!
It's been a while since the last release of the DocBook stylesheets, but there have been quite a number of improvements and fixes! Michael Smith has announced the availability of Version 1.70.0 of the DocBook XSL stylesheets.
You can download the latest stylesheets at: http://sourceforge.net/projects/docbook, and you can view the release notes at: http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html
Key improvements include:
- support for FOP 0.9
- support for Xalan 2.7
- support for DocBook v5 docs
- many new parameters for FO, HTML and manpage outputs
- additions of WordML stylesheets
This is the initial experimental release, so please test and send feedback to the docbook-apps list! The final version 1.70.1 will be released following the short review and test period.
Categories: DocBook
Tuesday, May 16, 2006
Updated "DocBook V5.0 The Transition Guide"
Dick Hamilton has added a new section about creating customized versions of DocBook V5 grammar. This doc is a great reference for migrating content from earlier versions of the DocBook standard.
You can find the latest version here: http://www.docbook.org/docs/howto/
Categories: DocBook
Thursday, May 04, 2006
A little inline SVG...
I created this graphic for some training I created, and thought I'd try embedding it directly in a blog entry:
Unfortunately, it looks like something is getting messed up on the Blogger side. A working example of inline SVG can be found here: http://jwatt.org/svg/demos/xhtml-with-inline-svg.xhtml. It looks like Blogger pages are served as text/html, not application/xhtml+xml, even though the post editor enforces that your content is well-formed! Hopefully there will be a way to change the blog settings so I can do inline SVG in the near future.
Categories: XML
Star Wars Lego II trailer!
StarWars.com and LucasArts have released the trailer for the new Star Wars Lego II video game! You can view it at: http://download.lucasarts.com/legoswii_480.mov
The original Star Wars Lego game is a ton of fun, and my kids and I played the game together for hours! The controls are simple enough that kids can actually play, and it's entertaining for both Star Wars and Lego fans.
Check it out!
Monday, May 01, 2006
Generating PDF bookmarks with DocBook and Arbortext Publishing Engine
I've been creating PDFs via a DocBook customization layer and Arbortext Publishing Engine. For some reason, using this method, I couldn't get bookmarks in the PDF.
I tried various combinations of:
<xsl:param name="arbortext.extensions">1</xsl:param> <xsl:param name="fop1.extensions">1</xsl:param> <xsl:param name="fop.extensions">1</xsl:param>
Thanks to Paul Grosso for giving me the solution: If you are using Arbortext, you should use
<xsl:import href="doctypes/axdocbook/axdocbook-fo.xsl"/>not
<xsl:import href="docbook-xsl-1.69.1/fo/docbook.xsl"/>
I need to take a look in axdocbook-fo.xsl to see what's going on, and figure out how to make the arbortext extension to the DocBook stylesheets generate the bookmarks properly.
I also found some interesting info on linking to PDFs:
If you want to display bookmarks when the PDF opens, create your link like:
<a href="mydoc.pdf#pagemode=bookmarks
Other linking parameters are described at: http://ic.ucsc.edu/docs/tutorials/linkingtopdfs/.
Wednesday, April 26, 2006
May The Schwartz Be With You...
I'm sure you've all heard that Scott McNealy has handed over the reigns as CEO of Sun to Jonathan Schwartz. Jonathan has been President of Sun for a while now, so it's not totally unexpected. McNealy on the other hand, is now going to be Sun's Chief Evangelist and Chairman of the Board, which I'm sure he'll continue providing witty soundbites for the press to eat up! Of course, he needs to figure out how to blog -- it worked really well for Schwartz, and has really impressed me there.
What is not so clear, is how the market will react to Schwartz. He's certainly younger, and arguably a very bright person. Wall Street continues to call for massive cuts in the company, and in an effort to make his opening numbers look good, I'm wondering if he'll go ahead and follow their advice.
McNealy and Schwartz have made statements in the past that they will avoid layoffs at all costs. That said, I know of several stealth layoffs that continue to occur almost quarterly now. I fear for the Software and Services folks. Sun never could figure out how to sell software, and has instead, open-sourced most of it. Much of services have been out-sourced to India or otherwise. At heart, Sun is still a hardware company. But like a McClaren racer, who can really afford one? These days, folks continue to look for a Toyota Prius-like hybrid -- low on cost, good performance, and runs all kinds of software. I think Sun is a little management heavy, too. When they make the cuts, though, they tend to cut into the muscle and not enough of the fat.
For my friends still left at Sun, "May The Schwartz Be With You" -- and not against you...
Wednesday, April 19, 2006
Playing the Spock Market
The new G4 network has come out with some interesting new shows. Slightly amusing is Bonzai, but the best is Star Trek 2.0!
I found out about it from an ad on MeeVee (who says internet ads don't work?). The show plays uncut classic Trek episodes, but also provides a ticker for the "Spock Market"
Basically, you sign up for a free account where they start you with 100000 Federation credits to "invest". There are a variety of "stocks" you can buy, and based on the episodes that air and other random news events, the value of those stocks change.
For my starting portfolio, here's what I got for my 100000 credits:
- SPK (Spock): 10
- MDM (Dr. McCoy): 5
- SCT (Scotty): 100 - why not? This is Scotty's Engineering Log after all!
- CKV (Chekov): 25
- DMI (Dilithium Mining and Mineral): 45 - hey, who figured out how to re-crystalize in ST IV?
- PHP (Starship Phaser and Photon): 1
- WRP (Cochrane Warp and Impulse): 5
- RAC (Robot, Android and Clone): 15
- RDS (Red Shirt): 2 - because everyone needs a couple of Red Shirts, just in case...
- TRS (Transporter): 50 - what did Scotty work on besides the engines?
- PHZ (Hand Phaser and Blade): 25
- KRS (Klingons, Romulans and More): 25 - I've always liked the Klingons! Qapla'!
I figured this would give me a pretty balanced portfolio. We'll see how this Enterprise works out...
You can give it a try at: http://www.g4tv.com/startrek20/spockmarket.aspx
UPDATE (4/26): My current net worth is 24,293,485 FDR!
- JTK (Kirk): 1006
- SPK (Spock): 75
- MDM (Dr. McCoy): 167
- SCT (Scotty): 100
- CKV (Chekov): 10
- DMI (Dilithium Mining and Mineral): 200
- PHP (Starship Phaser and Photon): 10
- COM (Communicator): 1
- TSP (Tricorder, Sensor and Probe): 10
- WRP (Cochrane Warp and Impulse): 10
- LOG (Starship Log and Computer): 2
- FED (United Federation of Planets): 200
- RAC (Robot, Android and Clone): 130
- RDS (Red Shirt): 100
- TRS (Transporter): 23
- UPP (Universal Planet and Planetoid): 205
- PHZ (Hand Phaser and Blade): 10245
- KRS (Klingons, Romulans and More): 40
Monday, April 17, 2006
Happy Birthday, Flatirons Solutions!
Today is Flatirons Solutions 5th anniversary/birthday!
During the early years, Flatirons had to deal not only with typical startup pains, but also brutal general economic conditions with virtually no IT spending because of the market crash and 9/11.
Despite these very significant challenges, Flatirons is now a $15M company with 80 employees, and a an impressive list of clients in both the commercial and government sectors!
Flatirons Solutions is a great company to work for, and I'd like to say congratulations to our founders and my colleagues for 5 years of Vision, Experience, and Engineering Excellence.
Categories: General, consulting
Annotating DocBook
Dominik Brettnacher has released Annotate 0.1.6, a free annotation tool for DocBook documents. Based on an extension of the DocBook XSL and a DBMS to store the annotations, it looks to be very useful! There is also an online demo you can try. For more info, check out: http://www.brettnacher.org/annotate/.
Annotation has been added to DocBook v5.0, and is described here: http://docbook.org/tdg5/en/html/annotation.html
Categories: DocBook
Thursday, April 13, 2006
You're going to have to get up pretty early...
If you want to hear me play French Horn! I'm playing for the Easter Sunrise service for Rock Creeek Church this Sunday.Selections will be traditional hymns:
"Christ the Lord is Risen Today", "Christ Arose (Up from the Grave He Arose)", and "A Mighty Fortress".
If you are in the Boulder area and are looking for a place to attend Easter services, you are invited to attend!
Directions are located here.
We will be holding Good Friday service at 7pm, Easter Sunrise at 6am w/breakfast, and our regular service at 10am at Monarch High School. Hope to see you there!
Categories: God, Jesus, Christianity, church
Wednesday, April 12, 2006
DocBook V5.0b5
Norm Walsh has just released beta 5 of DocBook V5.0!
Please give this version a test drive and report any problems.
The DTD/XSD/RNG can be found here: http://docbook.org/xml/5.0b5/
Categories: DocBook
Monday, April 03, 2006
Generating DOCTYPE and ENTITY DECLs in XSLT
I ran into a very interesting challenge lately, and since RoboHelp has been EOL'd, I thought I'd try to benefit the rest of the community that might need to migrate content out of RoboHelp. There is an export handler in RoboHTML that will convert content to DocBook, but unfortunately, it doesn't provide very good or accurate markup, IMO.
Since the default RoboHTML export handler for DocBook wouldn't work for us, we created a new export handler, based on the original. What I wanted, was a book file that contained entity declarations for each topic. The trick was trying to generate the Doctype declaration, with the entity declarations. XSLT provides a way to generate a PUBLIC and SYSTEM identifier in the DOCTYPE declaration for an output document, but does not provide a way to write out the entity declarations as an internal DTD subset in that doctype decl.
Part of the solution is to not use the XML output method, but to use the TEXT method. This was working splendidly, until it came time to write the file entity reference in the content. From what I could tell, the problem is with the msxml parser that RoboHelp uses when exporting content. No matter how I tried to escape the "&", I would get & in the entity reference, which of course would not resolve.
Instead of building it into the export handler, I came up with a stylesheet to process the *_toc.xml file that resulted from the DocBook export.
Here are some snippets from the resulting code. The critical components are generating the DOCTYPE decl, generating the ENTITY decl, and then creating the entity reference.
<xsl:output method="text" indent="yes"/>
<xsl:template match="/">
<xsl:text disable-output-escaping="yes"><!DOCTYPE book PUBLIC "-//COMPANY//DTD DocBook-Based Extension v1.0//EN" "extended-docbook.dtd" [
<!ENTITY glossary SYSTEM "glossary.xml">
</xsl:text>
<xsl:for-each select="//tocentry/ulink[normalize-space(@url)!= '']">
<xsl:call-template name="generate_entity_decl">
<xsl:with-param name="url" select="@url" />
<xsl:with-param name="title" select="@title" />
</xsl:call-template>
</xsl:for-each>
<xsl:text disable-output-escaping="yes">]></xsl:text>
<book>
<title><xsl:value-of select="title"/></title>
<bookinfo>
<xsl:call-template name="generate_publisher_info">
<xsl:with-param name="rootnode" select="." />
</xsl:call-template>
</bookinfo>
<xsl:apply-templates/>
<xsl:text disable-output-escaping="yes">&</xsl:text>glossary;
</book>
</xsl:template>
The above creates the DocType declaration, but relies on generating a valid entity name for the entity declarations:
<!-- =========== generate_file_url template ============= -->
<xsl:template name="entityName">
<xsl:param name="url" />
<xsl:choose>
<xsl:when test="contains($url,'/')">
<xsl:value-of select="substring-before($url,'/')"/>
<xsl:call-template name="entityName">
<xsl:with-param name="url" select="substring-after($url, '/')"/>
</xsl:call-template>
</xsl:when>
<xsl:when test="contains($url,'\')">
<xsl:value-of select="substring-before($url,'\')"/>
<xsl:call-template name="entityName">
<xsl:with-param name="url" select="substring-after($url, '\')"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$url"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- ======== outputs entity references ======== -->
<xsl:template name="generate_file_url">
<xsl:param name="url" select="''" />
<xsl:param name="title" select="''" />
<xsl:variable name="transformedURL">
<xsl:value-of select="translate(string($url), ' ()','_' )" />
</xsl:variable>
<xsl:variable name="entity.file.name">
<xsl:call-template name="entityName">
<xsl:with-param name="url" select="$transformedURL" />
</xsl:call-template>
</xsl:variable>
<xsl:variable name="entity.name">
<xsl:choose>
<xsl:when test="contains($entity.file.name, 'htm')">
<xsl:value-of select="substring-before($entity.file.name, '.htm')" />
</xsl:when>
<xsl:when test="contains($entity.file.name, 'xml')">
<xsl:value-of select="substring-before($entity.file.name, '.xml')" />
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$entity.file.name" />
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<!-- outputs entity reference -->
<xsl:text disable-output-escaping="yes">&</xsl:text>
<xsl:value-of select="$entity.name" />
<xsl:text disable-output-escaping="yes">;
</xsl:text>
</xsl:template>
The above templates create a valid entity name, based on the path to the file. I tried to adjust for both XML, HTML and unknown file names. Following is the template that creates the ENTITY declaration that needs to be a part of the internal subset in the DOCTYPE declaration.
<!-- This generates an entity declaration: <!ENTITY foo SYSTEM "foo.xml"> -->
<xsl:template name="generate_entity_decl">
<xsl:param name="url" select="''" />
<xsl:param name="title" select="''" />
<xsl:variable name="transformedURL">
<xsl:value-of select="translate(string($url), ' ()','_' )" />
</xsl:variable>
<xsl:variable name="entity.file.name">
<xsl:call-template name="entityName">
<xsl:with-param name="url" select="$transformedURL" />
</xsl:call-template>
</xsl:variable>
<xsl:variable name="entity.name">
<xsl:choose>
<xsl:when test="contains($entity.file.name, 'htm')">
<xsl:value-of select="substring-before($entity.file.name, '.htm')" />
</xsl:when>
<xsl:when test="contains($entity.file.name, 'xml')">
<xsl:value-of select="substring-before($entity.file.name, '.xml')" />
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$entity.file.name" />
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<!-- outputs entity declaration -->
<xsl:text disable-output-escaping='yes'><!ENTITY </xsl:text><xsl:value-of select='$entity.name'/><xsl:text> SYSTEM
"</xsl:text><xsl:value-of select='$transformedURL'/><xsl:text>"</xsl:text><xsl:text disable-output-escaping='yes'>>
</xsl:text>
</xsl:template>
As you can see, there are several variables that have been reused, and could probably be declared globally or more efficiently. The remaining task is to create the entity reference in the content. Since the RoboHelp export handler dumped everything as a tocentry/ulink, it's pretty easy to extract and re-write the entity reference we really want:
<xsl:template match="tocpart">
<chapter>
<title>
<xsl:value-of select="tocentry"/>
</title>
<xsl:apply-templates />
</chapter>
</xsl:template>
<xsl:template match="tocchap">
<xsl:choose>
<xsl:when test="tocentry/ulink">
<xsl:call-template name="generate_file_url">
<xsl:with-param name="url">
<xsl:value-of select="tocentry/ulink/@url"/>
</xsl:with-param>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<section>
<title>
<xsl:value-of select="tocentry" />
</title>
<xsl:apply-templates select="toclevel1"/>
</section>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
The finer details will be left as an exercise to the reader, but this was a particularly interesting problem and solution. Hope this helps!
Tuesday, March 28, 2006
DITA 2006 - morning sessions from Day 1
As I mentioned before, I thought day 1 of DITA 2006 was a little "marketing" heavy, meaning most of the sessions dealt with the benefits of DITA and not much technical detail.
Dave’s keynote was a good overview of the benefits of DITA. Key benefits are the same as other structured markup benefits: increased consistency of content, content reuse, multiple outputs from a single source, faster and cheaper globalization and enabling personalization. What I thought was interesting, were the numbers he shared. A typical infocenter at IBM contains about 5,000 topics! He said the content is maintained primarily in their source code control and tied to the software builds. I think if you are planning to author large amounts of topics in DITA, a content management system is essential.
Eliot’s preso was one of the more interesting, and controversial of the conference. I enjoyed it immensely. Eliot commented, “The more interesting question is why would DITA not be the right answer?” Some of these reasons may include: a small writing group that cannot afford some of the tools that help to author DITA effectively, such as an author-friendly XML editor (Arbortext or XMetal) and a content management system (such as Documentum, Ixiasoft, or XyEnterprise).
The most controversial part of Eliot’s preso was the comment that
“In order to use DITA effectively, you have to Specialize!”
Derived types can inherit processing defined for their ancestors. Industries can also create a set of specific types for their needs. DITA Specializations, by design, reduce the risk of creating customizations (where with a DocBook customization you have to be careful about maintaining your customization when the standard changes).
Eliot also discussed some of the hidden traps you can run into with DITA:
- Inefficient processes – automating an inefficient process will fail to deliver the expected benefits and cost savings!
- organizational boundaries – must focus on the enterprise bigger picture if it’s to be done right.
- technology limitations – no OOB DITA solution. info analysis still necessary to determine additional specs, format analysis and stylesheet dev, legacy data conversion, integration with other tools (translation memory, DAM, CMS, etc.)
- resource utilization – SMEs perform time consuming formatting tasks, indexing content, redundant content creation, maintenance of reused content, using expensive resources for copyediting and production functions.
My other favorite quote from Eliot:
“Do not underestimate the level of expertise and effort involved to implement DITA smoothly.”
Tony DiSilva also started the recurring question at the conference:
“How do you know when you should be using DocBook and when you should be using DITA?”
Specialization is essential for larger companies. The decision for smaller enterprises may be fuzzier between DITA and DocBook. With DITA, you will likely need a CMS (increasing the cost). DITA 1.1 is focusing on adding features to enable books. (front and back matter, indexing, etc.). This will make it harder to decide between DITA and DocBook.
How can they play together? Perhaps DocBook could adopt some form of DITA specialization mechanisms for fallback processing of customizations. The two standards could/should align some of the core element types in DITA 2.0/DocBook 6.0. For example, DocBook predates HTML, so those tags weren’t adopted. DITA started with the HTML tags.
IMO, if you already have your content in DocBook, there is no compelling reason to switch or migrate your content to DITA. As Norm Walsh has pointed out previously, with possibly one exception, everything that you can do in DITA can be done with DocBook. We have helped several of our customers do DITA-like implementations using DocBook. If your content is unstructured, and you are moving to a structured markup standard, the decision is on more equal footing. Key considerations are: youth of DITA vs. maturity of DocBook, robustness of markup and toolsets, ease of exchange with other partners or groups (what standard are they using? how portable do you need your content? what is the expected lifespan of the content? what is the current structure of the content, and how much rework will be needed as part of the migration?).
One of the great things about this conference is access to the founding fathers of DITA! I had a chance to chat with Michael Priestley, Don Day and Rob Anderson about several topics:
Is DITA planning to use/provide RelaxNG schemas?
Don Day – not really. RelaxNG doesn’t have default attributes, and DITA relies heavily on attributes.
Do you see any tie between DITAMaps and Topic Maps?
Michael Priestly – they are very different. DITA maps are much more hierarchical and constraining, where XTMs focus on relationships and are non-constraining.
Looks like this post is getting a little long, so I'll split up my posts. Stay tuned for more DITA 2006!
Categories: DITA