Skip to main content
Tools

Don’t type, drag to the cmd window

I spend a good deal of time with a Windows cmd.exe window open on my desktop. If I’m not running the DITA OT, I’m testing some Perl script, or Ant, or Python, or who knows.

A few years ago (in the Windows 98 days), I discovered a nifty cmd window trick. People are consistently amazed when I demonstrate it to them. Now I’m going to share it with you.

Say you need to change directory to some long and gnarly path name. You could type the whole thing in. Or, if you have Windows Explorer open on your desktop, you can:

  1. Type “cd ” in the cmd window (the space is important).
  2. Go to Windows Explorer and find the folder you want to navigate to.
  3. Drag and drop the folder from Windows Explorer to the cmd window.

Hey presto! The path name is copied to the cmd window. What’s more, if there are spaces in the path, the path is automatically quoted.

Now you can click in the cmd window and press Enter to perform the command.

Cool! No more typing long path names for this ToolSmith.

This works for filenames too. If I’m running a Perl script that needs to work on a file way down my directory tree, I type “perl myScriptName.pl “, then drag and drop the file name from Windows Explorer into my cmd window.

I’ll keep adding more ToolSmith’s Tricks as I use them. What’s your favorite trick?

Simon Bate
February 20, 2009
Read More
Tools

WMF…that’ll shut ’em up

Which graphics formats should you use in your documentation? For print, the traditional advice is EPS for line drawings and TIFF for screen captures and photographs. That’s still good advice. These days, you might choose PDF and PNG for the same purposes. There are caveats for each of these formats, but in general, these are excellent choices.

Of course, everybody knows to stay away from WMF, the Windows Metafile Format. WMF doesn’t handle gradients, can’t have more than 256 colors, and refuses to play nice with anything other than Windows.

Think you’re too good to hang out with WMF? For your print and online documentation, perhaps. But it may be a great choice to give to your company’s PowerPoint users.

Are you familiar with this scenario? PowerPoint User saw some graphics in your documentation and thought they would work for some sales presentations. The screen captures are easy; you just give PowerPoint User PNGs or BMPs or whatever. It’s the line drawings that are the problem. PowerPoint User doesn’t have Illustrator and has never heard of EPS. PowerPoint User says, “Can you give me a copy of those pictures in a format that I can use in PowerPoint? Oh, and can make that box purple and change that font for me first? And move that line just a little bit? And make that line thicker? And remove that entire right side of the picture and split it into two pictures?”

You want PowerPoint User to reuse the graphics; you’re all about reuse. But you have dealt with PowerPoint User before, and you know you will never get your real job done if you get pulled into the sucking vortex of PowerPoint User’s endless requests.

The secret is to give PowerPoint User the graphics in a format that can be edited from within PowerPoint (or Word): WMF. Here’s the drill that will make you a hero:

  1. Save your graphics as WMF.
  2. Place each WMF on a separate page in a PowerPoint or Word file.
  3. Tell PowerPoint User to double-click on a graphic to make it editable.(If you think your PowerPoint User is really dumb, you can double-click the graphic and respond to the dialog box asking if you want to make the drawing editable yourself before saving the file, but nobody is that dumb.)

WMF. It will make PowerPoint User go away…happy!

Sarah O'Keefe
February 20, 2009
Read More
Conferences

Looking Fear Straight in the Eye

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.

Simon Bate
November 3, 2008
Read More
Opinion

Why XML and structured authoring is a tough transition

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.

Sarah O'Keefe
May 4, 2007
Read More
News

Friends in new places

We’re pleased to announce that we have joined XMetaL’s Partner Program as a Certified Service Provider.

We will not be reselling XMetaL software, but we will begin offering XMetaL classes this summer.

This is really a customer-driven decision — we have clients asking us to develop XML and DITA implementations with XMetaL as the core authoring tool.

Sarah O'Keefe
April 2, 2007
Read More
Conferences

WritersUA: My sessions

I delivered a session on Coping with the XML Paradigm Shift, in which I introduced my Taxonomy of Problem Writers for the first time. The slides are available in PDF format, and I welcome any and all comments. You probably won’t be surprised that the presentation is slightly over the top. It has, however, already served as a great conversation starter —
I heard people talking about Technosaurs and One-Trick Ponies.

On Tuesday afternoon, I did a double-length, hands-on Introduction to DITA session. (Many thanks to XMetaL for providing attendees with evaluation copies to use during the session.)

I arrived in the room about half an hour before the session and found a few people already moved in. (Always a good sign.) Trying to install and configure software just minutes before a session like this is a truly terrifying undertaking. And as we got closer to the session time, more
and more (and MORE) people kept coming. By my count, we had at least 35 people with laptops and five more without. (That’s about triple the number I’d normally allow in a hands-on training session.)

There were a few kinks, but we managed to get everyone up and running*, and I think the session was valuable. At the end, I polled the room on whether they were more or less likely to implement DITA and got an even split. Perfect!

We will be extending this three-hour session into a two-day Introduction to DITA class, which we expect to begin offering in mid-summer. Watch this space for more details.

* One person had a Mac, which I hadn’t anticipated. Sorry! The two people running Vista also had some issues. There were a few installation errors, but their software seemed to run OK.

Sarah O'Keefe
March 28, 2007
Read More
Conferences

Fun in Long Beach (?)

Registration has opened for WritersUA. Now in its fifteenth year, the 2007 conference will be in Long Beach, California from March 25-28.

The schedule and session descriptions are available, and they look great.

I will be doing two sessions:

  • Coping with the XML Paradigm Shift (my original title was Paradigm Shifts are Never Pretty, so you can see where that one is going)
  • Introduction to DITA (a double-length, hands-on session). A few years ago, XML was the buzzword. Now it’s DITA. This session will provide the information you need to make an informed decision about DITA.

In addition, I see presentations from a lot of the Usual Suspects — Char James-Tanny, Neil Perlin, Alan Houser, Jared Spool, Dave Gash, and many, many others.

Don’t miss it.

Sarah O'Keefe
December 4, 2006
Read More
Opinion

Play nicely, and share your code

[updated to fix broken link]

Quadralay’s new ePublisher Pro was released with, shall we say, minimal documentation. The user guide describes how to manipulate the basic interface, but details on how to go under the covers and customize the XSL transformations that make up the core of the product are absent.

It appears that the company is trying to address this shortcoming with a wiki. There are some concerns about this approach, though. Char James-Tanny points out that “no one seems to have the rights to any of the material that’s posted.” And Bill Swallow writes this in waxing techcomm: “If the intent is to supply users with a means of online support/reference, I think it would be best to triage the contributed content, have it validated by a company representative, and then published.”

I think the wiki approach raises a larger question–how much documentation should a product creator be responsible for? A product like ePublisher Pro provides a configuration platform–the customization possibilities are endless. For advanced customization, ePublisher Pro is more comparable to a software development environment than a menu-driven application. Documenting a “development platform” is very, very tricky.

Nonetheless, there are some things that Quadralay should have provided and hasn’t. These include:

  • An inventory of the XSL transformation files provided with the product and an overview of what each file does.
  • Examples of how to perform common customizations that cannot be accomplished inside the user interface.
  • Documentation of the Quadralay-provided XSLT extension functions.

Posting these inside the wiki would be a nice start.

Quadralay has tried before to put the expert user community to work (anyone remember the WebWorks Publisher forums on their web site?). But speaking as a consultant, I’m not likely to post into the wiki when the ownership of that code is so unclear. Furthermore, we already have the wwp-users mailing list, which has over 3,000 members. Why bother with the wiki?

Finally, there is a massive disclaimer as part of the wiki:

All projects, code snippets, suggestions presented in this medium are colloborative [sic] materials expressed by both Quadralay personnel and WebWorks power users. Material taken from this medium and implemented into your existing production workflow or testing environments should be carefully considered and is done at your own risk. Although our product support consultants can and will place material on this medium to faciliate collaboration between Quadralay and its customers, Support Incidents submitted through webworks.com regarding issues with implementation of this material will not be accepted. Support for the implementations expressed here will only be supported through this medium.

In other words, if you use information posted on the wiki by Quadralay to customize your project, and it doesn’t work, Quadralay support will not help you.

Boo.

I understand the concerns surrounding wikis and the ability of anyone to edit a page, but it seems this could actually be resolved quite easily. The wiki can be set up with Official and Unofficial pages. Official pages are built by Quadralay employees, are editable only by Quadralay employees, and Quadralay support will provide support for those pages. Unofficial pages are those created by ePublisher Pro users; they are the “use at your own risk” section of the wiki.

Sarah O'Keefe
November 27, 2006
Read More
Opinion

Source, please?

The DITA hype continues.

The announcement for Arbortext 5.3 is almost completely focused on DITA, and in places reads more like a description of DITA than a press release about a new product. And in the middle, we find this item:

“PTC believes that by the end of 2008, up to 80% of all new XML publishing installations will be based on DITA.” (press release at ptc.com)

Is there research to back this up?

I find it very hard to believe that DITA is appropriate for 80 percent of all XML publishing implementations. Just consider the textbook and magazine publishing industries. Aerospace and pharmaceuticals both have non-DITA standard requirements.

(h/t Gilbane Report News)

Sarah O'Keefe
November 13, 2006
Read More