Category: technology
MacDevCenter’s Giles Turnbull has an article up on using RTF (Rich Text Format) as an interchange format. For non-technical users, this is probably the best way to move documents around without having to worry about whether someone can read them. Nearly all word processors that aspire to be “full-featured” provide some support for RTF these days, so it’s a good starting place.
This morning at work, I was asked to provide some information from a quick-start guide for a hand-off to a customer (who wants to write some custom stuff). We’re using FrameMaker for documentation, not Word, and Word users just seem to assume everyone else uses Word. Imagine that. (For those who wonder why I don’t use Word, this profanity-laden rant pretty well sums it up.) FrameMaker’s RTF exporter is less than wonderful, producing sloppy text formatting and losing the graphics, but the customer just wanted the tables so it’s all good.
Way back when, I brought RTF home once and used a text editor on an Amiga to make updates to a manual. We had a deadline and a snowstorm, so I wanted to make sure I could hold up my end of things even if I couldn’t get to the office. It worked, except for one minor detail: those spaces at the end of lines of RTF are significant, and my text editor insisted on removing them... so when I got back to work & opened it in the word processor, there were spacesmissing here and there. Running the spell checker fixed all but one or two of them.
So with all these wonderful real-world examples, what’s lacking in RTF compared to ODF, the virtues of which I’ve been extolling lately?
First, RTF has been one of those formats that is supposed to be well-known, but Microsoft has always had a penchant for omitting things. The newer specifications are better.
Second, there are RTF parsers and conversion tools out there, but they are far less well-known than equivalent XML tools.
Third, even Microsoft is moving to XML for document interchange.
RTF, given its Word-driven ubiquity, will be around for a long time to come and will continue to be a useful interchange format for people interested primarily in exchanging and using documents. Many people will continue to use older versions of Word and Office for a long time to come, and XML interchange won’t be feasible for them. But for those of us who want our computers to extract (and perhaps transform) the important pieces of the documents we get, XML is really the way forward.
Showing posts with label work. Show all posts
Showing posts with label work. Show all posts
Wednesday, October 19, 2005 No comments
Friday, October 14, 2005 2 comments
Laziness and Open Document Format
Categories: technology, work
Current music: Groove Salad
Just before I took off for lunch today, the contractor who picked up the projects I was working on before the reorg motioned me over and asked me, “how did you do it? You put together the whole shell of this project, and I’m just hanging stuff on it. Especially the command-line stuff... how did you get so much of it done with nothing to work with?” Pulling miracles out of my, er, back pocket has been a lot of what I’ve done at the office for the last few years. I got deadlines, limited access (at best) to equipment, a little help from my boss when he’s not swamped with other stuff, very little in the way of specifications, and somehow I managed to maintain documentation for three entire product lines.
My secret is: I’m lazy.
Look, I sit in front of a computer all day. If I can get the computer to do something for me, especially if it’s something that needs to be done more than once, I’ll do it. For example, our original (now “legacy”) product line came with about 4000 pages of documentation scattered over about 20 different manuals. We provided a master index, a 110-page book of its own, as a way to let customers zero in on which manual(s) covered a particular topic. The first time I did the master index, it took two solid weeks of nothing else. This is one of those prime examples for automation: I had to build a book in FrameMaker of all the other books, tag each chapter in each manual, run the index, convert the tags to document references (for example, change “EG” to Engineering Guidelines), remove all but the first reference to any chapter, blah blah blah. To make a long story shorter, I wrote a handful of AppleScripts that eliminated literally 80% of the grunt work: instead of two weeks, I could build the master index in two days. Yesterday, I wrote a script that created index entries from headings (which is OK for a first pass at indexing commands) that saved me a day’s worth of work.
I told you all that to tell you this.
A couple of weeks ago, I wrote about Massachusetts adopting Open Document Format (ODF) for state government documents. Between than and now, OpenOffice 2.0 went into beta test; yesterday, OASIS (Organization for the Advancement of Structured Information Standards) submitted ODF to the International Standards Organization (ISO) for consideration as an international standard for office document interchange.
The neat thing about all this is that the ODF format is easy to pick apart and fiddle with. Internally, content, graphics, and style information are separated and the whole thing is rolled up in a ZIP file. Content and style files use an XML format, which is important for two reasons: XML is plain text, and there are lots of utilities to work with it. So what does that mean? There are several Free programs that support ODF already (OpenOffice and AbiWord run on most computers, while Koffice also runs on Linux systems). But the really fun part is, given a document format both open and relatively easy to parse, you don’t need an office application to do things with ODF files.
In the computing world, when a group like OASIS sets out to nail down a standard, they form a Technical Committee (TC) of interested parties. In the case of the ODF TC, some of the interested parties include companies that make content management systems (or CMS... the alphabet soup is sloshing around quite a bit tonight!) — suffice it to say that a CMS allows you to store, retrieve, and process documents to make something new (kind of like putting basil leaves in a food processor and making pesto). Given the job of a CMS, it usually doesn’t just store a document as-is. In the case of an ODF file, the CMS would probably unzip it and extract just the content and metadata (data about the data) components. The graphics are already stored in the CMS. Let’s say I send a document to the CMS and come back for it a couple of months later. During that time, some of the artwork has been changed. The CMS grabs the original content and metadata, rolls in the updated graphics, and hands me an ODF file. Oh cool, I didn’t have to update the graphics myself!
Another handy utility might be nightly publishing runs. Sometimes, I’m working on a manual that’s getting change requests and bug reports coming in fast & furious. Some of the manuals I deal with have a lot of bitmap graphics, and can take nearly an hour to generate a PDF. Remember, I’m lazy... I don’t want to sit at work an hour overtime just to watch the computer make a PDF. In my theoretical ODF-based system, I simply send in the stuff I worked on during the day, and the CMS builds a new document and emails it (with a summary of what changed) to all the reviewers. The reviewers get fresh hot documentation every morning; I get to go home, sit on the porch, and write haiku before it gets dark.
With the manual finished, I have to send it to the translators. Currently, this involves gathering all the various files together and archiving them (and sending missing pieces or assuring them that the extraneous files aren’t important). In my dream system, I tell the CMS to give me an ODF document of the book. Boom, all the pieces get wrapped together, nothing gets dropped, nothing extra gets added, and I send one file to the translators.
I’m willing to put some effort into making this a reality. After all, I want the computer to do the work for me.
Current music: Groove Salad
Just before I took off for lunch today, the contractor who picked up the projects I was working on before the reorg motioned me over and asked me, “how did you do it? You put together the whole shell of this project, and I’m just hanging stuff on it. Especially the command-line stuff... how did you get so much of it done with nothing to work with?” Pulling miracles out of my, er, back pocket has been a lot of what I’ve done at the office for the last few years. I got deadlines, limited access (at best) to equipment, a little help from my boss when he’s not swamped with other stuff, very little in the way of specifications, and somehow I managed to maintain documentation for three entire product lines.
My secret is: I’m lazy.
Look, I sit in front of a computer all day. If I can get the computer to do something for me, especially if it’s something that needs to be done more than once, I’ll do it. For example, our original (now “legacy”) product line came with about 4000 pages of documentation scattered over about 20 different manuals. We provided a master index, a 110-page book of its own, as a way to let customers zero in on which manual(s) covered a particular topic. The first time I did the master index, it took two solid weeks of nothing else. This is one of those prime examples for automation: I had to build a book in FrameMaker of all the other books, tag each chapter in each manual, run the index, convert the tags to document references (for example, change “EG” to Engineering Guidelines), remove all but the first reference to any chapter, blah blah blah. To make a long story shorter, I wrote a handful of AppleScripts that eliminated literally 80% of the grunt work: instead of two weeks, I could build the master index in two days. Yesterday, I wrote a script that created index entries from headings (which is OK for a first pass at indexing commands) that saved me a day’s worth of work.
I told you all that to tell you this.
A couple of weeks ago, I wrote about Massachusetts adopting Open Document Format (ODF) for state government documents. Between than and now, OpenOffice 2.0 went into beta test; yesterday, OASIS (Organization for the Advancement of Structured Information Standards) submitted ODF to the International Standards Organization (ISO) for consideration as an international standard for office document interchange.
The neat thing about all this is that the ODF format is easy to pick apart and fiddle with. Internally, content, graphics, and style information are separated and the whole thing is rolled up in a ZIP file. Content and style files use an XML format, which is important for two reasons: XML is plain text, and there are lots of utilities to work with it. So what does that mean? There are several Free programs that support ODF already (OpenOffice and AbiWord run on most computers, while Koffice also runs on Linux systems). But the really fun part is, given a document format both open and relatively easy to parse, you don’t need an office application to do things with ODF files.
In the computing world, when a group like OASIS sets out to nail down a standard, they form a Technical Committee (TC) of interested parties. In the case of the ODF TC, some of the interested parties include companies that make content management systems (or CMS... the alphabet soup is sloshing around quite a bit tonight!) — suffice it to say that a CMS allows you to store, retrieve, and process documents to make something new (kind of like putting basil leaves in a food processor and making pesto). Given the job of a CMS, it usually doesn’t just store a document as-is. In the case of an ODF file, the CMS would probably unzip it and extract just the content and metadata (data about the data) components. The graphics are already stored in the CMS. Let’s say I send a document to the CMS and come back for it a couple of months later. During that time, some of the artwork has been changed. The CMS grabs the original content and metadata, rolls in the updated graphics, and hands me an ODF file. Oh cool, I didn’t have to update the graphics myself!
Another handy utility might be nightly publishing runs. Sometimes, I’m working on a manual that’s getting change requests and bug reports coming in fast & furious. Some of the manuals I deal with have a lot of bitmap graphics, and can take nearly an hour to generate a PDF. Remember, I’m lazy... I don’t want to sit at work an hour overtime just to watch the computer make a PDF. In my theoretical ODF-based system, I simply send in the stuff I worked on during the day, and the CMS builds a new document and emails it (with a summary of what changed) to all the reviewers. The reviewers get fresh hot documentation every morning; I get to go home, sit on the porch, and write haiku before it gets dark.
With the manual finished, I have to send it to the translators. Currently, this involves gathering all the various files together and archiving them (and sending missing pieces or assuring them that the extraneous files aren’t important). In my dream system, I tell the CMS to give me an ODF document of the book. Boom, all the pieces get wrapped together, nothing gets dropped, nothing extra gets added, and I send one file to the translators.
I’m willing to put some effort into making this a reality. After all, I want the computer to do the work for me.
Monday, October 10, 2005 No comments
Something you don't see everyday
I was getting my 3 p.m. joe to see me through the rest of the afternoon, and managed to get a whole cup for a change. As I was starting the next pot, the president of our division came in, said hello, then stooped down & picked up a couple of pieces of trash & dumped them in the wastebasket.
I guess that represents why I’ve stayed there for 7 years.
I guess that represents why I’ve stayed there for 7 years.
Tuesday, October 04, 2005 No comments
My ad hoc home office
I thought I’d start the day by describing my work-at-home setup before I get to work.
Last week, I said I work out on the screened-in porch/Florida room with the cats. I set at the windows, looking out over a very rough back yard that needs some serious log removal and weed-eating. The woods takes over about thirty feet away, so it’s a fairly narrow strip of yard I’m talking about.
I sit at an 80s-vintage typing desk, a steel frame with a pretty good composite veneer over who-knows-what for a working surface. I use two phone books to raise the iBook screen up to (almost) eye level... I suppose I ought to get one or two more to get it really right. The Boy’s old iMac “donated” its Apple Pro Keyboard & my MacAlly wheelie mouse (he likes it better than the Pro Mouse and I don’t use it that often) for the day.
The Force is strong with the litter box this morning. Daughter Dearest is supposed to scoop it at least every other day, and we’re lucky if she gets to it twice a week.
Time to start working, after I grab a cup of coffee... and a couple more phone books....
Last week, I said I work out on the screened-in porch/Florida room with the cats. I set at the windows, looking out over a very rough back yard that needs some serious log removal and weed-eating. The woods takes over about thirty feet away, so it’s a fairly narrow strip of yard I’m talking about.
I sit at an 80s-vintage typing desk, a steel frame with a pretty good composite veneer over who-knows-what for a working surface. I use two phone books to raise the iBook screen up to (almost) eye level... I suppose I ought to get one or two more to get it really right. The Boy’s old iMac “donated” its Apple Pro Keyboard & my MacAlly wheelie mouse (he likes it better than the Pro Mouse and I don’t use it that often) for the day.
The Force is strong with the litter box this morning. Daughter Dearest is supposed to scoop it at least every other day, and we’re lucky if she gets to it twice a week.
Time to start working, after I grab a cup of coffee... and a couple more phone books....
Tuesday, September 27, 2005 No comments
Working at home
Current music: Moody Blues - Say It With Love
I’ve sort-of fallen into a routine where I work at home on Tuesdays. Today it worked out even better than usual: Planetary Governor Bok-Bok asked school districts to take a couple of snow days Monday & Tuesday to cushion any Rita-related fuel shortages, so I didn't have to worry about getting the kids up and taking them to school. If that weren't good enough, I turned off the alarm so I could get a reasonable amount of sleep for a change.
Time to get some work done....
I’ve sort-of fallen into a routine where I work at home on Tuesdays. Today it worked out even better than usual: Planetary Governor Bok-Bok asked school districts to take a couple of snow days Monday & Tuesday to cushion any Rita-related fuel shortages, so I didn't have to worry about getting the kids up and taking them to school. If that weren't good enough, I turned off the alarm so I could get a reasonable amount of sleep for a change.
Time to get some work done....
Monday, September 26, 2005 No comments
Yuck
I didn't realize how dirty my keyboard wrist rest was at the office until I dripped a little water on it and tried to rub it off. I had to get some soap on a paper towel to clean it off.
Friday, September 09, 2005 No comments
The stuff I have to document...
One of the products I write about at work has a command-line interface (CLI) used for debugging and troubleshooting. Customers got wind of it, requested documentation, and that’s usually where I get involved.
One particular (or should I say peculiar) troubleshooting command is “ti_ts” — which starts a troubleshooting routine on some TI chips in the box. I tried to get them to change the name, to no avail. So on this development cycle, they added a “codesperms” command (which translates to “active codes per minislot’). I have a pretty good idea what the next oddly-named command will be, but don’t want to give them ideas just in case one of them stumbles across this blog....
One particular (or should I say peculiar) troubleshooting command is “ti_ts” — which starts a troubleshooting routine on some TI chips in the box. I tried to get them to change the name, to no avail. So on this development cycle, they added a “codesperms” command (which translates to “active codes per minislot’). I have a pretty good idea what the next oddly-named command will be, but don’t want to give them ideas just in case one of them stumbles across this blog....
Wednesday, September 07, 2005 No comments
More FrameMaker 7.2 Leakage
A post on the FrameUsers mailing list (thanks Thomas!) suggests doing a Google search on “FrameMaker new multiple undo” and then reading the cached page from Adobe UK (the first link when I tried it). Doing this turns up some more new features:
A sidebar had links for Solaris and Microsoft updates, suggesting that MacOS users are still left out. Figures.
- multiple undo (one of those long-standing malfeatures I griped about yesterday)
- some support for XML Schema (probably conversion to EDD)
- support for native Photoshop (PSD) files
A sidebar had links for Solaris and Microsoft updates, suggesting that MacOS users are still left out. Figures.
Tuesday, September 06, 2005 1 comment
Adobe Leaks FrameMaker 7.2 Info
In which I take a break from chronicling my personal life and talk about work stuff.
Over the Labor Day weekend, various pages on Adobe’s website mentioned the unreleased version 7.2 of FrameMaker, the preferred tool of the trade for most technical writers (who often affectionately call it “Frame”). Adobe (usually one to hold its cards close to the vest) has since revised the pages, although the old ones lived another day in Google’s caches before those too were updated.
But haste often leads to things getting skipped over, and that was the case with a migration guide white paper on Adobe Germany’s site. I grabbed an unrevised copy of the PDF Tuesday afternoon; the good people at Adobe.de have certainly gone home for the day but I expect the white paper to be sanitized first thing tomorrow morning (by about 2 a.m. EDT).
If you download too late, here’s what searching the PDF for “7.2” turned up in the way of new features:
All this is structure-related, which doesn’t do you much good if you aren’t interested in moving to structured Frame. I’m sure that there will be the usual bug replacements (i.e. removing some known bugs and introducing new bugs) as well.
A group of vendors and trainers have been constantly flogging their “FrameMaker Chautauqua” conference on various mailing lists where FrameMaker is either the main or a common topic. The conference includes presentations by Adobe and will be held in early November, so I expect that Adobe will officially announce version 7.2 either at the conference or shortly before. If I’m right, it’s safe to assume that 7.2 is in beta testing right now.
FrameMaker has languished in a near-limbo pretty much since Adobe bought up Frame Technologies some years back. Frame has benefitted from minor updates from time to time, but long-standing bugs and malfeatures have persisted. That, and an abortive foray into porting the Unix version to Linux, have lead many to believe that Adobe is less than enthusiastic about supporting the program. The final straw for some of us was in January 2004, when Adobe dropped support for MacOS citing lack of sales (largely brought on by Adobe’s reluctance to modernize the MacOS version to run natively on MacOS X, leaving FrameMaker one of the last reasons to ever use the “Classic” environment).
Pretty much all summer, the “Chautauqua” people have been hyping Adobe’s presence at their upcoming conference, promising Frame users that they won’t be disappointed by what Adobe has to say about Frame’s life expectancy. Unfortunately, there’s no word on re-introducing MacOS support, preferably for MacOS X. That’s a show-stopper for me and many others: if the rest of the tool chain works well, why change the underlying platform if one tool is no longer supported?
Personally, even if Adobe repents of Windows-centricity, I’m not convinced that page-oriented WYSIWYG tools like Frame are the way forward for technical writing — in a world where our final output is more likely to be PDF and HTML than paper, it doesn’t make much sense to work on the electronic equivalent of a printed page. It makes more sense nowadays to work with markup, either directly (ooo, icky tags, say my less-technical brethren and sistren) or indirectly through an interface that provides formatting hints but no fixed margins or other page-centric details. LyX is a good example of the latter kind of program.
In the end, I expect little or no surprises come November. I’m certainly not going to ask my boss for $695 + hotel to attend a conference for a tool I’m currently planning to abandon, even if the conference is close enough to drive to.
Over the Labor Day weekend, various pages on Adobe’s website mentioned the unreleased version 7.2 of FrameMaker, the preferred tool of the trade for most technical writers (who often affectionately call it “Frame”). Adobe (usually one to hold its cards close to the vest) has since revised the pages, although the old ones lived another day in Google’s caches before those too were updated.
But haste often leads to things getting skipped over, and that was the case with a migration guide white paper on Adobe Germany’s site. I grabbed an unrevised copy of the PDF Tuesday afternoon; the good people at Adobe.de have certainly gone home for the day but I expect the white paper to be sanitized first thing tomorrow morning (by about 2 a.m. EDT).
If you download too late, here’s what searching the PDF for “7.2” turned up in the way of new features:
- XSL processing at XML import and export (alongside existing read/write rules) — this is a feature I’ve wished for, but (see below) probably won’t get.
- Conversion tables, which add structure to unstructured files, can create a “first draft” EDD (a combination of DTD and style sheet).
- Conversion tables also support a “root element” to be applied to the converted document.
All this is structure-related, which doesn’t do you much good if you aren’t interested in moving to structured Frame. I’m sure that there will be the usual bug replacements (i.e. removing some known bugs and introducing new bugs) as well.
A group of vendors and trainers have been constantly flogging their “FrameMaker Chautauqua” conference on various mailing lists where FrameMaker is either the main or a common topic. The conference includes presentations by Adobe and will be held in early November, so I expect that Adobe will officially announce version 7.2 either at the conference or shortly before. If I’m right, it’s safe to assume that 7.2 is in beta testing right now.
FrameMaker has languished in a near-limbo pretty much since Adobe bought up Frame Technologies some years back. Frame has benefitted from minor updates from time to time, but long-standing bugs and malfeatures have persisted. That, and an abortive foray into porting the Unix version to Linux, have lead many to believe that Adobe is less than enthusiastic about supporting the program. The final straw for some of us was in January 2004, when Adobe dropped support for MacOS citing lack of sales (largely brought on by Adobe’s reluctance to modernize the MacOS version to run natively on MacOS X, leaving FrameMaker one of the last reasons to ever use the “Classic” environment).
Pretty much all summer, the “Chautauqua” people have been hyping Adobe’s presence at their upcoming conference, promising Frame users that they won’t be disappointed by what Adobe has to say about Frame’s life expectancy. Unfortunately, there’s no word on re-introducing MacOS support, preferably for MacOS X. That’s a show-stopper for me and many others: if the rest of the tool chain works well, why change the underlying platform if one tool is no longer supported?
Personally, even if Adobe repents of Windows-centricity, I’m not convinced that page-oriented WYSIWYG tools like Frame are the way forward for technical writing — in a world where our final output is more likely to be PDF and HTML than paper, it doesn’t make much sense to work on the electronic equivalent of a printed page. It makes more sense nowadays to work with markup, either directly (ooo, icky tags, say my less-technical brethren and sistren) or indirectly through an interface that provides formatting hints but no fixed margins or other page-centric details. LyX is a good example of the latter kind of program.
In the end, I expect little or no surprises come November. I’m certainly not going to ask my boss for $695 + hotel to attend a conference for a tool I’m currently planning to abandon, even if the conference is close enough to drive to.
Tuesday, July 26, 2005 No comments
Meet the new boss
Current Music: Creation Steppin' Radio
With all the other stuff going on around FAR Manor, I haven't really thought much about impending changes at work. I don't plan to go into deep detail about the workplace, partly because they haven't created a blogging policy. I'll have to talk a bit about the industry, though, for you to make any sense of the following. It's the supply-side of the cable (CATV) business; the company I work for makes cable modems, eMTAs (cable modems with telephone lines built in), and CMTSs (what the cable modems and eMTAs talk to at the other end of the cable). I've been writing the manuals for all but one of the products.
There's a lot of noise from analyst-types about the "triple play" in the cable industry -- that is, data (cable modems), telephony (eMTAs), and digital TV. Lately, I've been devoted full time to the latter. We're building a box that can take a bunch of digital video streams, moosh them around in pre-determined ways, and send them down the cable to your home theater or whatever.
Lately, we've been selling so many eMTAs that the management felt it necessary to divide the company along product lines -- eMTAs on this side, all the headend (cable company) stuff on the other. Just as my former boss hired a contractor to take the eMTA load off me, I got moved to the eMTA side.
I'm not complaining (for a change) -- it looks like I'm going to have an honest-to-God budget and the freedom to roll out web and video editions of documentation. I've been griping for about 7 years that we need to put our documentation online; looks like it might finally happen.
With all the other stuff going on around FAR Manor, I haven't really thought much about impending changes at work. I don't plan to go into deep detail about the workplace, partly because they haven't created a blogging policy. I'll have to talk a bit about the industry, though, for you to make any sense of the following. It's the supply-side of the cable (CATV) business; the company I work for makes cable modems, eMTAs (cable modems with telephone lines built in), and CMTSs (what the cable modems and eMTAs talk to at the other end of the cable). I've been writing the manuals for all but one of the products.
There's a lot of noise from analyst-types about the "triple play" in the cable industry -- that is, data (cable modems), telephony (eMTAs), and digital TV. Lately, I've been devoted full time to the latter. We're building a box that can take a bunch of digital video streams, moosh them around in pre-determined ways, and send them down the cable to your home theater or whatever.
Lately, we've been selling so many eMTAs that the management felt it necessary to divide the company along product lines -- eMTAs on this side, all the headend (cable company) stuff on the other. Just as my former boss hired a contractor to take the eMTA load off me, I got moved to the eMTA side.
I'm not complaining (for a change) -- it looks like I'm going to have an honest-to-God budget and the freedom to roll out web and video editions of documentation. I've been griping for about 7 years that we need to put our documentation online; looks like it might finally happen.
Subscribe to:
Posts (Atom)
LinkWithin
