Site FeedPalimpsest has moved. Please visit our blog in its new location for the most recent posts from Scriptorium.
Palimpsest
The long and winding roads from DITA XML to PDF output
Thursday, August 20, 2009 — posted by Sheila Loring
DITA XML is of little use to readers unless it's converted to some kind of output. The DITA Open Toolkit (DITA OT) provides transforms and scripts that convert DITA to PDF output and a long list of other formats.Producing PDF output from DITA content can be challenging. DITA XML is converted to an XSL-FO file, a combination of content and formatting instructions. You must know XSL-FO to customize the PDF, even just to add simple content such as headers and footers, logos, and so on.
To forgo the programming, you can choose a page layout or help authoring tool, but these tools also have pitfalls. Page layout programs have varying degrees of DITA support. Help authoring tools let you style the PDF through CSS, but you can't fine-tune page layout as you can in page layout programs.
These are just a few examples we discuss in our white paper "Creating PDF files from DITA content." Read the white paper online (in HTML or PDF).
Labels: Arbortext, DITA Open Toolkit, ePublisher, flare, FOP, FrameMaker, PDF, quark, robohelp, white papers, XEP, xmetal, XPP, XSL Formatter, xsl-fo
10:00 AM Permalink | |
Top five reasons to like XMetal and oXygen
Thursday, June 11, 2009 — posted by Sheila Loring
Full disclosure: We're an XMetaL Services Provider and have no particular affiliation with oXygen.I'm in the fortunate situation of having access to both XMetaL 5.5 and oXygen 9.3. Both are excellent XML editors for different reasons. I'd hate for Scriptorium to make me choose one over the other.
From the viewpoint of authoring XML and XSLT, here are my top five features of both editors:
oXygen
- Apply XSLT on the fly: You can associate an XML file with an XSLT and transform the XML within oXygen. Goodbye, command line! XMetaL will convert the document to a selected output format. You don't choose the XSLT--it hasn't been a big concern for me.
- Indented code: The pretty-print option makes working with code so easy. You can set oXygen to do this automatically when you open a file or on demand. The result is code indented according to the structure. XMetaL doesn't have pretty print.
- Autocompleting tags:
As you type an element, oXygen pops up a list of elements beginning with the typed string. You press Enter when you find the right tag, and the end tag is inserted for you. The valid attributes at any particular point are also shown in a drop-down list. XMetaL doesn't have autocompleting tags. - Find/replace in one or more documents: I've often needed to search and replace strings in an entire directory. In XMetaL, you can only find and replace in the current document.
- Comparing two documents or directories: Compare files by content or timestamp. In a directory, you can even filter by type so only XML files, for example, are compared. XMetaL doesn't offer this feature.
- Auto-tagging content: You can copy and paste content from an unstructured document (a web page, for example), and XMetaL automatically wraps the content in elements. Even tables and lists are wrapped correctly. This can be handy if you have a few documents to convert. In oXygen, the content is pasted as plain text.
- Auto-assignment of ID attributes: Never worry about coming up with unique IDs. XMetaL will assign them to the types of elements you select. Warning: The strings are quite long, as in "topic_BBEC2A36C97A4CADB130784380036FD6." oXygen only inserts IDs on the top-level element but full support will be added in version 10.3.
- Auto-insertion of basic elements: When you create a document, XMetaL inserts placeholders for elements such as title, shordesc, body, and p. It's a small convenience. oXygen will also insert elements if you have Content Completion selected in the Preferences.
- WYSIWYG view of tables: The table is displayed as you'd see it in a Word or FrameMaker document. In oXygen, all you see are the table element tags.
- Reader-friendly tag view: The tags are a bit easier to read in XMetaL than oXygen. In XMetaL, the opening and closing tags are displayed on one line when possible.
This feature saves space on the page and makes the document easier to read in tag view. For example, you might have a short sentence wrapped in p tags. In XMetal, the p tags are displayed on the same line. In oXygen, the p tags are always on separate lines. This is another convenience that doesn't sound like a big deal, but it really makes a difference while you're authoring.
What I'd like to see in XMetaL: The ability to indent code, the ability to drag and drop topics in the map editor.
What's I'd like to see in oXygen: The ability to view a table--lines and all--in the WYSIWYG view instead of just the element tags.
So how do I choose which editor to use at a particular moment? When I'm casually authoring in XML, I choose XMetaL for all of reasons you read above. The WYSIWYG view is more user-friendly to me. But when I'm writing XSLT or just want to get at the code of an XML document, oXygen is my choice.
Get the scoop on oXygen from http://oxygenxml.com. Read more about XMetaL at http://na.justsystems.com/index.php.
Update 6/15/09:
I'm thrilled to report that two deficiencies I reported in oXygen 9 are now supported in the latest version of oXygen -- 10.2.
- In Author view, tables are now displayed in WYSIWYG format. Just like in your favorite word processor, you can drag and drop column rulings to resize columns. After you resize columns, the colwidth attribute in the colspec element is updated automatically. This is much easier than manually editing the colwidth.
- In Author view, the tags are now displayed on one line when possible. Before, the tags were always on separate lines from the content.
Labels: analysis, oxygen, reviews, xmetal, xml, XSLT
1:54 PM Permalink | |
Presentations on features squeezed into FrameMaker 8
Thursday, November 20, 2008 — posted by Terry Smith
Just two weeks ago I was in an elementary school gymnasium working as an election official. Fourteen straight hours with no breaks for meals because officials aren't allowed to leave the polling area (which is why your ballot may have crumbs on it, sorry about that). In my precinct one candidate received only one vote more than the opponent; in another race, the difference was six votes. A very long and exciting day.Bleary-eyed but pleased to have served my precinct, I spent the next two days attending the DITA/TechComm conference. Perhaps not the heady stuff of this year's election, but definitely worthwhile. This conference had two themes: DITA and the tools in the Adobe Technical Communication Suite (although Madcap Flare was definitely represented, too). The place where those two topics meet is FrameMaker.
I was scheduled to speak on two FrameMaker topics for the conference. FrameMaker 8 now has built-in DITA authoring capabilities, which I demonstrated. I had a few slides to keep the demonstration on track. The slides, which I have included here, are brief.
Burying the lede: We have just released our FrameMaker 8 and DITA Technical Reference. This 55-page document provides detailed documentation of FrameMaker's DITA capabilities (5MB PDF download, $10).
FrameMaker 8 also includes new capabilities for filtering conditional content. For my second presentation, I prepared to show things to consider when single-sourcing in either regular or structured FrameMaker.
FrameMaker 8 also includes new capabilities for filtering conditional content. For my second presentation, I prepared to show things to consider when single-sourcing in either regular or structured FrameMaker.
Labels: adobe, conferences, dita, FrameMaker, PDF, presentations, xmetal
11:49 AM Permalink | |
Looking Fear Straight in the Eye
Monday, November 03, 2008 — posted by Simon Bate
Have you ever been really scared? I don't mean just the Halloween kinda scared, but really scared. That's how I felt at the Burlington Marriott when the hotel employee delivered the box containing the workbooks for my Introduction to XMetaL and DITA workshop. He stood in the doorway, smiled, and handed me a very beat up, bent, folded, spindled, and mutilated FedEx box.The box looked like the driver had had a flat on Route 128 and used it to prevent the truck from rolling back while jacking up the front end. It was nice and damp too. With much trepidation, I opened the box and -- to my relief -- found that the materials were undamaged. Whew.
Following that, Wednesday's all-day workshop on XMetaL and DITA was smooth sailing. OK, we had a bit of a problem with powerstrips, but the helpful DocTrain folks got that taken care of. In retrospect, many of the questions I fielded in the workshop weren't so much about DITA or XMetaL itself. Instead many of the questions were about generating output. The fact is that unless you're willing to spend some quality time with CSS and the DITA Open Toolkit, your output from DITA will look very generic. XMetaL has a number of hooks that ease some of the pain in generating XHTML output. But even those hooks won't save you from FO issues if you want to generate PDF output.
In my presentation on Thursday comparing XMetaL and FrameMaker support in DITA, the questions returned once again to output. Of course, this time the focus was on using FrameMaker 8.0 as a PDF engine. In workflows where content is created and maintained in XML, but then has to be delivered in PDF (or print), FrameMaker 8.0 looks like an attractive possibility. There are a few flaws in this solution (such as translating xref elements for intra-document links into live links in PDF), but users are closer to a solution than they were six months ago.
We've posted PDFs of the slides from both sessions on SlideShare.
You can find the Introduction to XMetaL and DITA workshop slides at:
http://www.slideshare.net/Scriptorium/xmetal-dita-workshop-presentation
The slides for the session on DITA Support in FrameMaker and XMetaL are at:
http://www.slideshare.net/Scriptorium/dita-support-in-framemaker-and-xmetal-presentation
When you're done browsing the slides, take a look on our site for information about how we can help you with your FrameMaker, XMetaL, OT, PDF problems.
It's not that scary.
Labels: dita, doctraineast08, FrameMaker, xmetal
4:41 PM Permalink | |
Learning the DITA Open Toolkit
Thursday, September 04, 2008 — posted by Sarah
(Scriptorium Publishing is a JustSystems Services Partner.)Simon Bate's webinar, An Overview of the DITA Open Toolkit, is now available. This event was jointly sponsored by Scriptorium Publishing and JustSystems. The recorded version is available here (registration required).
During the presentation, we did some audience polling.
Are you currently...? (choose one)
- 31%, Using XML
- 32%, Transitioning to XML
- 16%, Planning to transition
- 17%, Considering a transition
- 3%, Not considering it at all
- 59%, DITA
- 0%, DocBook
- 1%, Other publicly available
- 10%, Developed in-house
- 3%, Not considering it at all
I liked the last poll:
What formats do you currently or plan to publish to?
- 50%, print
- 92%, PDF for download
- 49%, web site
- 79%, online help
- 18%, other
The problem, from our customers' point of view, is that producing nice PDF from DITA content is really quite challenging. (From our point of view as consultants, this is not necessarily a bad thing.) What makes PDF so challenging? Basically, you are reverse engineering your layout engine (think FrameMaker or InDesign) in the XSL-FO programming language.
Simon's presentation provides an excellent introduction to the Open Toolkit, which many find quite intimidating. This was apparent from some of the questions and comments that Simon got:
Is there a GUI for OT that could be used by documentation production staff rather than command line?It's worth noting that running the Open Toolkit is vastly less difficult than configuring the Open Toolkit. The person doing the configuration work will need to understand Ant, type DOS commands (!), and rework the default transformation templates to produce the desired output. The person generating output with the configured OT will need to type in one command or just double-click a batch file to start processing.
I haven't typed a command into DOS in twenty years.
What's the difficulty level of using OT to get HTML output that is more professional-looking, like a WebWorks HTML generation?
Can you please define the purpose of ANT files?
Many of our customers have turned to us for the Scary Configuration Bits. If you're looking for help, keep us in mind.
This session was the second in a series of three webinars we are doing jointly with JustSystems. The last session, on September 23, will provide more details on customizing the DITA Open Toolkit. The webinar is free, but advance registration is required here. Hope to see you there.
Labels: dita, presentations, xmetal, xml
3:41 PM Permalink | |
Surprise! It's about quality.
Tuesday, August 19, 2008 — posted by Sarah
(Scriptorium Publishing is a JustSystems Services Partner.)On Monday, August 18, I delivered a webinar on making the transition from desktop publishing to structured authoring. This event was jointly sponsored by Scriptorium Publishing and JustSystems. The recorded version is available here (registration required).
During the presentation, we did some audience polling. And here, there were some surprises for me. We asked:
How are you authoring content today? (choose any)
- 31%, Word
- 14%, HTML authoring tool (i.e. Dreamweaver)
- 69%, Desktop publishing tool (i.e. unstructured FrameMaker, PageMaker, InDesign)
- 20%, Help authoring tool (i.e. RoboHelp, Flare, AuthorIT)
- 37%, XML authoring tool (i.e. XMetaL or structured FrameMaker)
In poll 2, things got very interesting:
What is the level of authoring at your organization? (choose one)
9%, #1. Chaos. No consistency
4%, #2. Documents match on paper
16%, #2.5 We have a template and sometimes follow it.
60%, #3. Template-based authoring. Repeatable process for creating consistently formatted documents
10%, #4. Structured authoring. Programmatic enforcement of required organization
When I ask this question a roomful of people, it's rare to get an admission of level 1. I've never seen anything like 10 percent of a live audience choose number 1. Perhaps the relative anonymity of a webinar is a contributor?
We asked some questions about skillsets with nothing of particular interest to report. Finally, we inquired about the business driver for structure implementation:
What is your critical business driver behind looking to improve how you manage content?
(choose one main driver)
10%, Speed up time-to-market
30%, Improve satisfaction with customer-facing documentation
3%, Comply with regulatory requirements
12%, Reduce localization cost
27%, Improve staff productivity
13%, Reduce production cost
4%, Other
The surprise here was that, at least in this group, the most single common response was a quality answer ("improve satisfaction") rather than a cost-reduction answer.
My session was the first in a series of three webinars we are doing jointly with JustSystems. The next two sessions will focus on the DITA Open Toolkit. Simon Bate, Senior Technical Consultant with Scriptorium, will deliver an overview of the Open Toolkit on August 26 and a session on troubleshooting and customizing the Open Toolkit on September 23. The webinars are free, but advance registration is required here. Hope to see you there.
Labels: change management, presentations, xmetal, xml
11:27 PM Permalink | |
Why XML and structured authoring is a tough transition
Friday, May 04, 2007 — posted by Sarah
Found on technicalwriter's blog:There are several applications that incorporate features for DITA use, such as XMetal and Altova Authentic, but how much value do they provide? (Looking over the online documentation for XMetal, you will see some pretty shaky formatting and copyfitting.)There may well be formatting and copyfitting issues. Wouldn't surprise me at all. But talk about missing the forest for the trees!
DITA/XML/structured authoring are important because they improve how information is stored. To question their value because somebody produced documentation using them that doesn't look so great...let's try an analogy:
Last week, I went to a restaurant and the food was terrible. I looked in the kitchen and saw Calphalon pots and pans. I conclude that you should not buy Calphalon because the food they produce is terrible.The quality of your food is determined by things such as the quality of the ingredients and the skill of the chef. The pan you choose does contribute -- it helps to use the right size and a high-quality pan, but to dismiss DITA because one example doesn't look quite right is pretty much like dismissing Calphalon because somebody once cooked something that didn't taste very good in it.
PS I like Calphalon. And I have produced my share of problematic entrees.
PPS DITA is not right for everybody.
10:43 AM Permalink | |