Remaining Questions From Remote Flare Course
Sorry about the delay, folks. Here are the answers to the remaining questions…
How to control the indent of a table – To set a global indent, open the Stylesheet Editor, select the tr style, open the Box properties group, and set the indent by using the margin-left property. To set an indent for one table, or one group of tables, create a new style class under the tr style, such as “table indent style 1” or the like, then select the new style, open the Box properties group, and set the indent by using the margin-left property.
Find Results window not displaying – If you recall, the Find Results window didn’t open when I ran a search in the advanced course. This was due to some undetermined layout setting. To fix this, reset your layout to the default (Window > Layouts > Reset Window Layout…) and try the search again. The Find Results window should display perfectly at the bottom of the screen.
Is there a “Keep With Next” or “Keep With Previous” setting for print out- put to prevent two page elements from splitting across a page break, such as keeping a paragraph and a numbered list together? – Yes, but it’s not labelled as such. In the Stylesheet editor, open the PrintSupport properties group for the style that you’re formatting and select either the always or avoid value, as needed, for either the page-break-before or page-break-after property, as needed.
Monday, July 28, 2008
Tuesday, July 22, 2008
First Issue From the 7/21-7/22 Advanced Flare Course
Re the exercise on page 103 about finding and removing unused style classes from a CSS - I looked in the original dept_styles.css file, in the Files folder, and it does contain the p.temporary class. This means that I probably accidentally deleted p.temporary from the css in the project when I was moving other style classes out from under the Print Medium. So you should have found p.temporary in the dept_styles.css file that you imported into the project and should have been able to delete it per the exercise.
More to come over the next few days.
Re the exercise on page 103 about finding and removing unused style classes from a CSS - I looked in the original dept_styles.css file, in the Files folder, and it does contain the p.temporary class. This means that I probably accidentally deleted p.temporary from the css in the project when I was moving other style classes out from under the Print Medium. So you should have found p.temporary in the dept_styles.css file that you imported into the project and should have been able to delete it per the exercise.
More to come over the next few days.
Sunday, July 20, 2008
A Word and Framemaker File Import Peculiarity in MadCap Flare
If you've ever imported Word or Frame files into Flare, you may have tripped over a peculiarity in Flare's Word Import Editor and Frame Import Editor. It has to do with how two features in these editors can conflict and produce often totally unpredictable results.
The first feature is the New Topic Styles tab. This feature scans the file to import and lists all head styles in that file. You can then tell Flare to split the file by splitting on specific head styles. For example, if Flare finds head 1, 2, and 3 in the incoming file and you specify head 1 and 2 on which to split, Flare creates a new topic every time it finds text in head 1 or 2 style. Text in head 3 style remains a part of the head 2-level-based topic that contains it. So far, so good.
The second feature is the Options tab. This feature scans the file to import, counts the number of characters in it, then lets you split the file at character X. The default length is 10,000 characters, with a default of 1,000 in the split document. For example, if a file contains 10,001 characters, Flare will not split this document because it exceeds the minimum length to be split (10,000 characters) but does not meet the minimum length required for the file to be split out (1,000 characters). If the a file contains 11,001 characters, then it meets both minimums (10,000 characters overall plus 1,000 characters for the split). The result is two topics, one of 10,000 characters and one of 1,001 characters.
The result is actually a bit more complex since there's a risk of the split occurring in the middle of a paragraph. So Flare actually splits the file at the whole paragraph nearest the split point. As you might imagine, it's hard to predict where the file will be split. Ignoring this issue, however, the split-on-number-of-characters feature is pretty straightforward. So what's the problem that I mentioned at the beginning?
The problem is that this split-on-number-of-characters feature is turned on by default. If you look at the Options tab on the Word or Frame Import Editor, you'll see that the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option are all selected. The result is that if you also use the Heading style options on the New Topic Styles tab to split incoming files, you have absolutely no idea how Flare will create the new topics.
So, if you want to use the Heading style options on the New Topic Styles tab to split incoming files, go to the Options tab first and deselect the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option. Then you should be fine.
If you've ever imported Word or Frame files into Flare, you may have tripped over a peculiarity in Flare's Word Import Editor and Frame Import Editor. It has to do with how two features in these editors can conflict and produce often totally unpredictable results.
The first feature is the New Topic Styles tab. This feature scans the file to import and lists all head styles in that file. You can then tell Flare to split the file by splitting on specific head styles. For example, if Flare finds head 1, 2, and 3 in the incoming file and you specify head 1 and 2 on which to split, Flare creates a new topic every time it finds text in head 1 or 2 style. Text in head 3 style remains a part of the head 2-level-based topic that contains it. So far, so good.
The second feature is the Options tab. This feature scans the file to import, counts the number of characters in it, then lets you split the file at character X. The default length is 10,000 characters, with a default of 1,000 in the split document. For example, if a file contains 10,001 characters, Flare will not split this document because it exceeds the minimum length to be split (10,000 characters) but does not meet the minimum length required for the file to be split out (1,000 characters). If the a file contains 11,001 characters, then it meets both minimums (10,000 characters overall plus 1,000 characters for the split). The result is two topics, one of 10,000 characters and one of 1,001 characters.
The result is actually a bit more complex since there's a risk of the split occurring in the middle of a paragraph. So Flare actually splits the file at the whole paragraph nearest the split point. As you might imagine, it's hard to predict where the file will be split. Ignoring this issue, however, the split-on-number-of-characters feature is pretty straightforward. So what's the problem that I mentioned at the beginning?
The problem is that this split-on-number-of-characters feature is turned on by default. If you look at the Options tab on the Word or Frame Import Editor, you'll see that the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option are all selected. The result is that if you also use the Heading style options on the New Topic Styles tab to split incoming files, you have absolutely no idea how Flare will create the new topics.
So, if you want to use the Heading style options on the New Topic Styles tab to split incoming files, go to the Options tab first and deselect the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option. Then you should be fine.
Friday, July 11, 2008
Why Migrating From Word To An XML-Based Document Authoring Tool Won’t Be Easy …
Every once in a while, you run into a situation that supports a position of yours to a tee. Here’s one…
XML-based authoring tool vendors claim their products are getting easier to use with each release. They’re right. Comparing today’s xMetal to the original is like comparing night and day. However, my position is that there are four unfortunate corollaries to this trend that are going to make life tough for many doc groups in the next few years.
1 - As the tools get better, the need for authors to understand the underlying technologies is apparently declining. For example, if a tool lets you define styles by using a dialog box, do you need to know CSS coding, or even what CSS is? Which brings us to…
2 - As the tools get easier to use, there’s a sense in many companies that there's less need for training.
3 - XML-based authoring tool vendors talk about authors using their tools to create content much the way authors do now with Word. The implication is that migration from Word to an XML-based authoring tool is conceptually similar and thus shouldn’t be too difficult.
4 - The XML-based authoring world is very different from the Word world, and those differences are going to create some unfortunate assumptions.
The result of these corollaries is a lot of confusion, which brings up that situation I mentioned. (Before I proceed, let me make clear that what follows is not a slap at xMetal. It’s just that a very basic feature of xMetal illustrates the four corollaries perfectly.)
To create a new document in xMetal, you select File > New.
The first decision point, and problem, is whether to create a document from a template or a blank document. It’s confusing since any new document is “blank.” What this is really asking is whether to create a new document based on a DITA template or a non-DITA template, specifically XML or SGML. If authors understand the difference between DITA, XML, and SGML, it’s an easy decision. But if authors don’t understand the difference, haven’t been trained, and are thinking in Word terms, the very first step in a new project is confusing.
The second decision point, and problem, is when you decide that the General tab options make sense since you want to create an XML document rather than a DITA document. The help even says to choose the DTD, schema, or rules file for the document you want to create. But if you select the Blank Well-Formed XML Document option, there’s no place to choose the DTD, schema, or rules file. You’re just thrown into a new document. But if you select the Blank XML Document option, xMetal asks you to select the DTD, schema, or rules file. So there’s something different between the Blank Well-Formed XML Document and Blank XML Document options, but what? And isn’t a document that’s well-formed, whatever that is, better than a document that’s apparently not well-formed? And why would any tool let you create one? It all makes sense once you understand that the Blank XML Document option is really the Blank ‘Valid’ XML Document option, if you can find someone to explain this. If not, authors coming over from Word will again be lost on their first step.
The solution, of course, is to understand XML’s underlying technologies, ideally through directed training as opposed to floundering through a new technology. This may seem like a lot to read into one menu selection, but there are many assumptions behind that one menu selection that, if unaddressed, will leave new authors lost and frustrated.
Every once in a while, you run into a situation that supports a position of yours to a tee. Here’s one…
XML-based authoring tool vendors claim their products are getting easier to use with each release. They’re right. Comparing today’s xMetal to the original is like comparing night and day. However, my position is that there are four unfortunate corollaries to this trend that are going to make life tough for many doc groups in the next few years.
1 - As the tools get better, the need for authors to understand the underlying technologies is apparently declining. For example, if a tool lets you define styles by using a dialog box, do you need to know CSS coding, or even what CSS is? Which brings us to…
2 - As the tools get easier to use, there’s a sense in many companies that there's less need for training.
3 - XML-based authoring tool vendors talk about authors using their tools to create content much the way authors do now with Word. The implication is that migration from Word to an XML-based authoring tool is conceptually similar and thus shouldn’t be too difficult.
4 - The XML-based authoring world is very different from the Word world, and those differences are going to create some unfortunate assumptions.
The result of these corollaries is a lot of confusion, which brings up that situation I mentioned. (Before I proceed, let me make clear that what follows is not a slap at xMetal. It’s just that a very basic feature of xMetal illustrates the four corollaries perfectly.)
To create a new document in xMetal, you select File > New.
The first decision point, and problem, is whether to create a document from a template or a blank document. It’s confusing since any new document is “blank.” What this is really asking is whether to create a new document based on a DITA template or a non-DITA template, specifically XML or SGML. If authors understand the difference between DITA, XML, and SGML, it’s an easy decision. But if authors don’t understand the difference, haven’t been trained, and are thinking in Word terms, the very first step in a new project is confusing.
The second decision point, and problem, is when you decide that the General tab options make sense since you want to create an XML document rather than a DITA document. The help even says to choose the DTD, schema, or rules file for the document you want to create. But if you select the Blank Well-Formed XML Document option, there’s no place to choose the DTD, schema, or rules file. You’re just thrown into a new document. But if you select the Blank XML Document option, xMetal asks you to select the DTD, schema, or rules file. So there’s something different between the Blank Well-Formed XML Document and Blank XML Document options, but what? And isn’t a document that’s well-formed, whatever that is, better than a document that’s apparently not well-formed? And why would any tool let you create one? It all makes sense once you understand that the Blank XML Document option is really the Blank ‘Valid’ XML Document option, if you can find someone to explain this. If not, authors coming over from Word will again be lost on their first step.
The solution, of course, is to understand XML’s underlying technologies, ideally through directed training as opposed to floundering through a new technology. This may seem like a lot to read into one menu selection, but there are many assumptions behind that one menu selection that, if unaddressed, will leave new authors lost and frustrated.
Saturday, June 21, 2008
Friday, June 20, 2008
Adobe AIR
Since Adobe introduced AIR, there’s been a lot of discussion about what it is and why to use it. I’ve also been asked how it applies to RoboHelp specifically. The Adobe web site describes AIR, but I think the discussion is aimed a bit too much at developers and not enough at RoboHelp authors, so here’s my short initial take on what AIR is in general and for RoboHelp specifically.
In general…
AIR, Adobe Integrated Runtime, is an output format with characteristics of both web-based and desktop applications. It’s web-aware but doesn’t run in a browser. Instead, it runs like a desktop application, which lets it take advantage of desktop features like local file storage. Yet because it’s web-aware, it can search the web for updates if users have an internet connection and update itself as needed. Adobe has stated that it plans to implement AIR across its product line, essentially creating a new output format.
For RoboHelp…
The Microsoft HTML Help output format (CHM) is an old (pre-‘97) and increasingly constrained format that looks increasingly antiquated in an increasingly webby world. It will be around for a long time, just as WinHelp has been around since it was unofficially put to sleep in ‘97, but I consider it a dying format.
However, HTML Help has one great attribute – it’s compiled. No matter whether a project contains one topic or a thousand, they’ll all be encapsulated into one distributable CHM file. IT managers like this because they only have to distribute one file. That one-file model is increasingly out of place in a web-oriented world, but its simplicity is a virtue.
In contrast, WebHelp, created by eHelp (original vendor of RoboHelp) in ‘97/’98, is not compiled. If a project contains a thousand topics, you have to distribute one thousand files – slightly more counting the control files. (This sounds difficult but it’s easy since RoboHelp puts all the files in one WebHelp folder. You just distribute that folder.) This makes WebHelp more efficient for web-based distribution because it acts like a web site. If users call for one topic, they get that one topic rather than all one thousand as they would with the CHM. However, IT managers often don’t like having to upload those thousand-plus files to a server.
The RoboHelp Packager for Adobe AIR tries to get the best of both formats. (To download beta 2, see http://labs.adobe.com/technologies/robohelp/.)
Like HTML Help, the Packager encapsulates all the distributable files in one AIR file. This means IT only has to deal with one file rather than hundreds or thousands as it does with WebHelp. (Even though those files are contained in a single WebHelp folder, they still have to be distributed.) For many IT managers, that’s a big benefit by itself.
Once you output to AIR, you get several other options as well.
You can apply skins, a la WebHelp. However, the skins are more flexible. For example, you can add a Resources button on the toolbar with links to other web pages. If you select one of those links, the target page opens in the AIR window in its own tab. This lets users keep the help file and other web pages open at the same time and access them quickly by just selecting the desired tab.
The output should look consistent on different platforms and operating systems. (I’d want to see a greater base of experience about this before accepting the idea wholeheartedly since different platforms and operating systems often have odd twists. However, since the output is not running in a browser, the browser display differences that we often see shouldn’t be an issue.
You can give users the ability to comment on the output, lending a Web 2.0 air to RoboHelp for the first time.
What do we have to do to make AIR work on users’ PCs? According to the AIR help, users must have the Adobe AIR runtime environment installed on their PCs. This seems like a straightforward download and installation. However, compared to the simple Flash Viewer installation procedure that many users are accustomed to, the AIR runtime installation is going to look more difficult and may slow acceptance of AIR until the runtime installation gets simpler.
I’ll add more as the RoboHelp Packager for Adobe AIR firms up.
Since Adobe introduced AIR, there’s been a lot of discussion about what it is and why to use it. I’ve also been asked how it applies to RoboHelp specifically. The Adobe web site describes AIR, but I think the discussion is aimed a bit too much at developers and not enough at RoboHelp authors, so here’s my short initial take on what AIR is in general and for RoboHelp specifically.
In general…
AIR, Adobe Integrated Runtime, is an output format with characteristics of both web-based and desktop applications. It’s web-aware but doesn’t run in a browser. Instead, it runs like a desktop application, which lets it take advantage of desktop features like local file storage. Yet because it’s web-aware, it can search the web for updates if users have an internet connection and update itself as needed. Adobe has stated that it plans to implement AIR across its product line, essentially creating a new output format.
For RoboHelp…
The Microsoft HTML Help output format (CHM) is an old (pre-‘97) and increasingly constrained format that looks increasingly antiquated in an increasingly webby world. It will be around for a long time, just as WinHelp has been around since it was unofficially put to sleep in ‘97, but I consider it a dying format.
However, HTML Help has one great attribute – it’s compiled. No matter whether a project contains one topic or a thousand, they’ll all be encapsulated into one distributable CHM file. IT managers like this because they only have to distribute one file. That one-file model is increasingly out of place in a web-oriented world, but its simplicity is a virtue.
In contrast, WebHelp, created by eHelp (original vendor of RoboHelp) in ‘97/’98, is not compiled. If a project contains a thousand topics, you have to distribute one thousand files – slightly more counting the control files. (This sounds difficult but it’s easy since RoboHelp puts all the files in one WebHelp folder. You just distribute that folder.) This makes WebHelp more efficient for web-based distribution because it acts like a web site. If users call for one topic, they get that one topic rather than all one thousand as they would with the CHM. However, IT managers often don’t like having to upload those thousand-plus files to a server.
The RoboHelp Packager for Adobe AIR tries to get the best of both formats. (To download beta 2, see http://labs.adobe.com/technologies/robohelp/.)
Like HTML Help, the Packager encapsulates all the distributable files in one AIR file. This means IT only has to deal with one file rather than hundreds or thousands as it does with WebHelp. (Even though those files are contained in a single WebHelp folder, they still have to be distributed.) For many IT managers, that’s a big benefit by itself.
Once you output to AIR, you get several other options as well.
You can apply skins, a la WebHelp. However, the skins are more flexible. For example, you can add a Resources button on the toolbar with links to other web pages. If you select one of those links, the target page opens in the AIR window in its own tab. This lets users keep the help file and other web pages open at the same time and access them quickly by just selecting the desired tab.
The output should look consistent on different platforms and operating systems. (I’d want to see a greater base of experience about this before accepting the idea wholeheartedly since different platforms and operating systems often have odd twists. However, since the output is not running in a browser, the browser display differences that we often see shouldn’t be an issue.
You can give users the ability to comment on the output, lending a Web 2.0 air to RoboHelp for the first time.
What do we have to do to make AIR work on users’ PCs? According to the AIR help, users must have the Adobe AIR runtime environment installed on their PCs. This seems like a straightforward download and installation. However, compared to the simple Flash Viewer installation procedure that many users are accustomed to, the AIR runtime installation is going to look more difficult and may slow acceptance of AIR until the runtime installation gets simpler.
I’ll add more as the RoboHelp Packager for Adobe AIR firms up.
Wednesday, May 21, 2008
Microformats
In April, I gave a workshop for the Boston STC on the issue of doing structured authoring without using DITA or Frame. In the workshop, I happened to mention a technology called microformats which several people asked me to define during and after the workshop. I did but, in retrospect, decided that I wasn't satisfied with the answer that I gave. So, here's a better definition that also has a number of additional ramifications.
Microformats use elements from existing languages or standards, like HTML, to mark up web content in such a way as to add semantic information to that content for use in Web 2.0, without having to adopt new languages or standards. Basically, microformats re-use existing features of current languages and standards.
There are several issues tied up in this definition. Let's take a look at two big ones.
- Existing languages or standards... - Every language or standard has a number of widely-used features and an often much larger number of little-known features. The latter often go unused or unnoticed. For example, the rel attribute of the link tag points to the location of the CSS that we attach to a topic in a help system, but rel often goes unnoticed unless you delve into the code. Yet rel is actually pretty flexible, offering a bunch of pre-defined values *and* the ability to define your own. This can get pretty esoteric, but it does not require you to buy and learn new software, just new ways to work what you already have.
- Semantic... - HTML tags like h1 are presentational rather than semantic. In other words, applying h1 to text tells us how to display that text but not what it is. For example, consider an online book store that uses HTML to mark up its listings. We could create a book listing and use h1 for the book title and h2 for the name of the author. We can then format the display by specifying the style attributes for h1 and h2, but we have no way of knowing that h1 is actually the book title and h2 is the author's name - e.g. the semantics of the information. XML lets us fix this by creating our own, semantically-definitive tags, such as creating and using tags called and rather than h1 and h2. But HTML already has elements that carry semantic information, such as the "cite" element that lets us identify a block of text as a citation. In other words, we may well be able to add semantic information without having to move to XML or DITA.
For a detailed overview of microformats, I recommend Microformats: Empowering Your Markup for Web 2.0 by John Allsopp, published by friendsof. In fact, I recommend reading the book even if you never plan to use microformats because of two other useful aspects of the book.
The first is the author's discussion of structural and semantic HTML in chapter 3. Here, he discusses some of the more rigorous programmatic aspects of HTML, how they're implemented, and why they're important for the long run.
The second is the nuggets sprinkled throughout the book, such as this one on why XML is important for RSS feeds.
"...RSSs are also XML-based languages, meaning that feeds must at least be well-formed..."
(from Microformats: Empowering Your Markup for Web 2.0, page 226.)
Why does this matter for technical communication? Today, most material produced by technical communicators is self-contained - e.g. a help system or user manual produced by one developer. But the web already has features like RSS feeds and aggregators that may be just as useful for technical communication. What the nugget above is saying is that RSS feeds and aggregators will most likely require XML, which will require a move away from HTML and the adoption of authoring tools that produce content that's at least well-formed if not valid. ("well-formed" and "valid" in the programmatic sense of following XML syntax rules.)
The book assumes familiarity with HTML, XML, IETF, and other acronyms and is very dense, but it's a quick read if you just look at a few code samples to get the idea and focus instead on the larger issues of programmatic rigor. Highly recommended.
In April, I gave a workshop for the Boston STC on the issue of doing structured authoring without using DITA or Frame. In the workshop, I happened to mention a technology called microformats which several people asked me to define during and after the workshop. I did but, in retrospect, decided that I wasn't satisfied with the answer that I gave. So, here's a better definition that also has a number of additional ramifications.
Microformats use elements from existing languages or standards, like HTML, to mark up web content in such a way as to add semantic information to that content for use in Web 2.0, without having to adopt new languages or standards. Basically, microformats re-use existing features of current languages and standards.
There are several issues tied up in this definition. Let's take a look at two big ones.
- Existing languages or standards... - Every language or standard has a number of widely-used features and an often much larger number of little-known features. The latter often go unused or unnoticed. For example, the rel attribute of the link tag points to the location of the CSS that we attach to a topic in a help system, but rel often goes unnoticed unless you delve into the code. Yet rel is actually pretty flexible, offering a bunch of pre-defined values *and* the ability to define your own. This can get pretty esoteric, but it does not require you to buy and learn new software, just new ways to work what you already have.
- Semantic... - HTML tags like h1 are presentational rather than semantic. In other words, applying h1 to text tells us how to display that text but not what it is. For example, consider an online book store that uses HTML to mark up its listings. We could create a book listing and use h1 for the book title and h2 for the name of the author. We can then format the display by specifying the style attributes for h1 and h2, but we have no way of knowing that h1 is actually the book title and h2 is the author's name - e.g. the semantics of the information. XML lets us fix this by creating our own, semantically-definitive tags, such as creating and using tags called
For a detailed overview of microformats, I recommend Microformats: Empowering Your Markup for Web 2.0 by John Allsopp, published by friendsof. In fact, I recommend reading the book even if you never plan to use microformats because of two other useful aspects of the book.
The first is the author's discussion of structural and semantic HTML in chapter 3. Here, he discusses some of the more rigorous programmatic aspects of HTML, how they're implemented, and why they're important for the long run.
The second is the nuggets sprinkled throughout the book, such as this one on why XML is important for RSS feeds.
"...RSSs are also XML-based languages, meaning that feeds must at least be well-formed..."
(from Microformats: Empowering Your Markup for Web 2.0, page 226.)
Why does this matter for technical communication? Today, most material produced by technical communicators is self-contained - e.g. a help system or user manual produced by one developer. But the web already has features like RSS feeds and aggregators that may be just as useful for technical communication. What the nugget above is saying is that RSS feeds and aggregators will most likely require XML, which will require a move away from HTML and the adoption of authoring tools that produce content that's at least well-formed if not valid. ("well-formed" and "valid" in the programmatic sense of following XML syntax rules.)
The book assumes familiarity with HTML, XML, IETF, and other acronyms and is very dense, but it's a quick read if you just look at a few code samples to get the idea and focus instead on the larger issues of programmatic rigor. Highly recommended.
Subscribe to:
Posts (Atom)