Only Today Matters! (see Topics and Drivel for yesterday's views).


Monday, December 8, 2008

Bad News From the West Coast

I just saw the news that Adobe is laying off 600 people (Charles Jeter's blog). Details are pretty sketchy here on the east coast, but it sounds like their San Diego facility will be emptied (~50 people there). Seems like Adobe is making a habit of Grinching, as they have in the past turfed people just before Christmas.

It remains to be seen which product groups will be hardest hit, but there is bound to be some effect on the Tech Publishing products. I am interested to see how the US vs global layoff numbers stack up, but I can guess.

It is a shame really, both for the people, and in my opinion, the company and the country. There is so much focus on the short term and the quick buck, and guess what got us to the crisis we find ourselves in?

If companies (and stockholders) were more willing to look more long term, and hunker down and take it if they have losses, maybe we wouldn't go through this kind of crap every 10 years or so.

Then again, if people who want deregulation would realize that deregulation opens the doors to thievery and greed. But those same people act as if a couple who take on a bad mortgage and get foreclosed on are walking away with the money. It is actually the sellers who take away the money and the brokers who take their piece, and the buyers who lose their home. In every one of those bad loans, somebody walked away with a big pile of cash, and while someone who sells a piece of property deserves to be paid for it, I am convinced there were scams going on to drive up the prices, and contrived sales to take profits.

Look at that example in MA where a bank president made a loan to a state senator, and then joined his election campaign, took money as a consultant, but used that money that was supposed to finance the campaign to pay off the home loan for the state senator. That smells like something they wouldn't sell at Legal Seafoods. Do I think that is an isolated case. Simply, no.

Back to the layoffs. Like I said, if companies did it the old way, with temporary shutdowns and pay cuts, and taking a hit to keep their company together, I think we would be better off. But like that company in Chicago, if the bank cuts them off, they literally have to shutter their workplace. But why is an American company cut off that way by the very banks that taxpayers are bailing out? It stretches credibility.

I love how the Auto execs are getting the third degree, but Citibank gets a huge bailout in the dark of night with very little discussion or criticism. Why? Because bank employees have no union, and bankers know where the bodies (figuratively speaking) are buried. Money is the circulatory system and the Fed is the heart. Stop the heart and the body dies. So the big time Fed banks like Citi and BoA call the tune.

Anyway, I am glad that Madcap is doing so well, because lots of their people were on the receiving side of pink slips not that long ago, and it shows that people can rebound and build new success stories out of disasters. But I never hoped that would happen at the cost to Adobe employees, even though I recommended that our group cut its bets on RoboHelp when Macromedia had its CFIT (Controlled flight into terrain). I hope the next innovative and fast growing company arises out of the people that Adobe has given up on.

Tuesday, November 18, 2008

So much for keeping up with the blogsters

We have been buried at work trying to get out a new release on a fast track schedule. Like Agile wasn't fast enough. Me and my com-padre cow-orker have been trying to go it alone on this one rather than split the job amongst the whole group. The problem is that we have two main products, a bevy of small ones, plus just as much hardware and training across 6 writers and a training developer. The writer who concentrates on the hardware teams up with the training developer to split hardware and training, and they are buried plus nagged to pieces by UL compliance, who seem to charge us $250 per comma moved/removed/added.

Two of us work on the 9000 and three on the 800, with one of the three helping out on training, which has to cover every software release plus the new and old hardware.

Bottom line is that we all scramble. So my time for developing Flare and Frame updates and style sheets and anything new comes in small spurts. I had some breathing time when Flare 4 came out but that has disappeared. We have a deadline just before Turkey day, and then another early in December for the SDK and connected program (SDK partner products).

The good news is that have been able to use the Flare global project I built as the basis of a couple of projects and it is working, although the styles are not finished yet and therefore the PDF output looks a tad crude next to our frame books. I still have much to figure out. Some aspects of building a book out of that print TOC still need some thinking. But overall I am pleased and looking forward to the result.

But I am not ready to roll out a global project to the group and tell them to incorporate it into our current Flare Help projects, or convert any books.

So I don't have any juicy new discoveries or exciting stories to tell. I am hoping that by mid december I will be able to point to a beta delivery of web help and a book from the same project, and compiled help and a book from another project. But right now I have to focus on writing a lapfull of readmes and updating a ton of odds and end features across 30 chms and a dozen books. Fun stuff.

Tuesday, October 21, 2008

Adventures in Global Linking

I am putting together a Flare 4 project for use as a department standard template and repository. It will be stored on a network drive in a folder that we use as our main sandbox (or litter box as the case may be) for active projects and other worthwhile junk (those pictures of the Norwegian Majesty gliding through the Bermuda cut). The foremost reason is that the drive is reliably backed up, and it is easier to work from than our source control drives. I would have to say we are pretty good at non-worst practices.

The global linking feature in Flare 4 is going to help us standardize our css, which has tended over the course of several Flare versions and a bunch of product releases to drift significantly toward eccentricity. When you have like 50 projects being worked on by multiple writers, with projects changing hands with some frequency, and our Flare usage evolving (yeah, evolving, that's the ticket), it is pretty hard to synchronize that many stylesheets when a change is needed. So the opportunity to use a global stylesheet beckons.

Beyond that, a number of other elements lend themselves to standardizing. The new page layouts are a prime example, as are variables and table formats. I also think the group will profit by having all the elements that need to be set up for single sourcing pre-defined in a global project.

Something else that we have had a problem with is writers copying elements (such as tables) from one project to another, and even though the tables use the same stylesheet, the table itself still points back to the old project (until you use table properties to convince it that the local stylesheet is friendly), resulting in annoying but ultimately ignorable build errors. My hope is that pointing all the tables back to a central stylesheet will prevent this.

All this sounds good in theory. It is difficult to predict how this will work between six writers and a course developer. So the plan is to develop the global project, apply it to a couple of working projects, and see how it works out.

More later...

Later...
So far so good. I created a project that incorporates almost all of the stuff I have worked on for Frame importing and single sourcing and PDFing. I am not done by any means, but making a global project and having to update it to get results will force me to test out the theory of re-importing and updating with rebuilds and all that stuff.

So I saved the global project, and created a new project from scratch (empty template) and created an import of a Flare project. I added stuff, as Madcap recommends, and when I built a PDF target I started to find things that I had overlooked or just done wrong in the global stylesheet. So I opened up the global project, updated that, and did a re-import. Actually several, iteratively. While there were occasional weirdnesses, such as messages about missing files that were not really missing, and files in use that weren't or should not have been, the updates worked quite well, and I was able to accomplish quite a bit.

One of the best things is that by centralizing the template and layout and style development, I only have to do it once (in the rare cases I get it right the first time, anyway). When I go into work tomorrow, I won't have to look through 50 projects to find my latest fix, or forget where I was and have to start again (less madness, more method). I am exaggerating, of course, but there were times when an interruption or a meeting made me forget something, until I got that vague deja vu that I had redefined that page layout before, and not in a previous lifetime.

This is rambling and generalized and borderline frantic because that is my life as I know it (which reminds me for no good reason of Dennis Hopper in Flashback - "The 90's are going to make the 60's look like the 50's.")

My intention is to blog some of this in more detail so that the mythical reader might get something like a concrete suggestion or tip, rather than "global good; topic good, single-source good, Silverlight ugh."

Wednesday, October 15, 2008

A Book Title PDF Bookmark? In Flare?

I have figured out a minor issue I was having with the PDF target for Flare 4.
Skip the BS and get to the tip (but I do try to make the BS entertaining).

Maybe I am just the dull knife in our Tech Writing drawer, but I was having trouble getting Flare to duplicate the bookmark structure in our Frame books. This after importing a book file from Frame and building the PDF target, and not seeing the bookmarks that I wanted. So I decided to break down the issues and chip away at them one at a time.

In this case, I was trying to find a way to have the PDF target build PDF bookmarks that included the book title at level 1. But if I did so normally (define the BookTitle style as an H1), the book title would show up in the Print TOC, which was kind of silly.

Our books had a first level bookmark for the book title, generated by specifying the BookTitle style in our Frame book as a PDF bookmark. But there is no separate PDF bookmark setup in Flare.

Bookmarks in the Flare PDF target output are controlled by the TOC for your PDF target. That may be a DUH! but the way they work is not all that clear to the dull knives in the drawer.

Warning! Loose talk follows that could be considered criticism of Madcap, but I will explain why it isn't really.
My ex-Boy Scout, due diligence side dutifully searched through the Flare help and pdfs for info on PDF bookmarks. I could not find anything, and looking at their PDFs did not help much, because their bookmark structure is different. In fact, in a few of their own PDFs, the bookmarks don't look so good (like repeated entries and extraneous bookmarks following the Index - look at, with some level of irony, their Printed Output Guide).

I realize Flare 4 was a huge and extraordinarily feature-rich and ambitious release. So like any good customer, the first thing I did was ignore all of their good work and dive in to the nth level details and find little trivial things that work but don't quite work the way I wished, and some other things that don't work right, and pounce on them.

That is my long-winded way of saying that I couldn't have done any better myself on a first edition book, and I harbor zero ill will. There are thousands of things you can do in Frame thousands of ways, and I don't expect Madcap to cover them all in a first release (which is what Flare 4 is, at least of the Blaze component). Flare has handled the bulk of the Frame features very well (IMO). Given the way Madcap has responded previously, I expect these things to be handled just as well in the fullness of time.

How to make a Book Title PDF bookmark that doesn't show up in the Print TOC
Here is the Joe Friday version of how to set up a bookmark structure that has the book parts nestled under a root level book title. It is not the only way, I am sure.

(but see the note at the bottom Postcript Caveat - there is a small gotcha.)
  1. Create a TOC that you will use for your PDF target output.
  2. Open your PDF target, then click the Printed Output tab.
  3. Select Use TOC depth for heading levels.
  4. Select Inject Headings for unlinked books in TOC.
  5. Click the Basic tab and specify the your TOC from Step 1 as the Master TOC.
  6. Open your PDF Target Master TOC.
  7. Make a TOC entry for your cover/title page by clicking the New Item icon.
  8. Move this TOC entry so that it is the first (top) entry in the TOC by clicking the up arrow as often as needed.
  9. Move it to the leftmost level by clicking the left arrow as often as needed. Everything else is now under this TOC entry, at least one level to the right.
  10. In the Stylesheet Editor, change the font color for p.TOC1 to white (invisible), the font size to like 3pts, and margin-top and margin-bottom to zero. (IF your stylesheet does not contain the p.TOC sub-classes, you may need to import those classes from another stylesheet like basic.css. If you created your stylesheet by importing from Framemaker, for example, you may not have these classes.)
  11. Build your PDF target and enjoy the result.
The part that isn't that intuitive if you did a lot of Frame -> PDF books is that there is not a separate GUI for setting up bookmarks in Flare, and no one really comes out and tells you that the master toc for the PDF target handles this. Also, it is inherent in the heading CSS classes that they are automatically created as bookmarks, but you can turn this off in the PDF target. It is also kind of new thinking that not all H1's are created equal in the Flare world, because in this case the heading levels in the bookmarks are controlled by their position in the TOC, rather than strictly their CSS class. However, within the body of the document/project, the CSS still determines how headings are displayed.

Here is a snapshot of the result:



Postscript Caveat
Apparently the 'inject Headings for unlinked books in TOC' does more than it implies - it also 'injects' a heading from the TOC into the main text. Flare help notes this parenthetically. In this case the injected heading showed up at the top of the page layout on the cover page, pushing the book title text that was supposed to be there down a line. Hmm. It is a vanilla H1 because that is where it lives in the bookmark TOC (I added a border to the style and it showed up with the border).

I colored the H1 style white and that solved the problem.

But if you are using the plain H1 in your project, that is not so good a solution. In my case, I use sub-classes of H1 so it should work, but if I import a raw H1 I will never see it in the print medium. I don't like making kludgey stuff stuff a department standard, so the jury remains out on whether this is a solution or an annoyance.

Monday, October 13, 2008

Trouble in Patriot Nation

Reflecting back on yesterday's 30-10 loss by the New England Patriots to the San Diego Chargers, a few things seem clear to me (and probably to every other New Englander who cares about football).
  1. Matt Cassell is not Tom Brady, and he knows it, and so does everyone else on both sides of the ball.
  2. The rest of the offense is dealing poorly with Brady's absence. They are not picking up their play; just the opposite.
  3. The best defense is a good offense. But when you don't have the best offense, your defense has to actually be good. The Patriots defense is being exposed as less than good in many ways.
On the first point, no one should expect Matt Cassell to be as good as Brady. He is actually a rather competent QB. But for a team that relied heavily on Brady's excellence, anything less puts a huge burden on the line, the backs, and the receivers. Time at time in this game, and previous games as well, these players have not stepped up, in my opinion. In fact, it seems that the staff also has resigned themselves to their fate of mediocrity. Case in point, a long pass that Moss caught, then was hit and lost the ball going out of bounds. The announcers expected the Pats to challenge the call, as Moss seemed to have a strong grip on the ball while in bounds. The ball was knocked out by the defensive back, and no one, Moss or coaches, seemed interested enough to challenge the incompletion. On the next possession, the Chargers scored on a long pass. That was a turning point but NE looked like they were just waiting for the roof to collapse, and it did. With Brady and their top two runners out, the team came into the stadium with a fork sticking out of their backs.

Think about how many times on a 3rd down Cassell completed a pass but the gain was too short for a first. Either the pattern or the receiver or Casell's vision or all three combine to make that a bad call and a bad result. The offense was able to do none of the things that past Patriots could do to pressure a defense. Brady's ability to sense almost supernaturally the open man and hit him was so obviously missing from the Patriot's game. As a result, the Chargers could just play the percentages and rely on their scouting to ID the target player and cover him.

Without the offense to either strike and score or hold the ball, the defense was exposed as lacking in many areas. Particularly in the secondary, the players replacing Randall Gaye and Asanti Samuel just do not stack up, talent-wise or height-wise. They are being exploited by opponent's QBs and the front 7 are generating almost no pass rush to speak of. As a result, Rivers was able to pick them apart. When the Pats used 4 down linemen they could stop up Thomlinson fairly well, but if they stayed in the 4-3, The Chargers were killing them with passing. If they went back to the 3-4, they couldn't contain the run, and the pass plays the Pats generated even less pressure than with the 4-3.

On top of that, it seemed like the Chargers were not being called for holding numerous times. On one of the bombs from Rivers, it looked like a New England blitzer was dragged down by two Chargers, but no call (other than touchdown). On their big punt return, the Pats first man looked like he was hit from behind twice, yet the Pats got a 15 yard facemask called on the play instead. The coaching staff seemed to accept both of these with no argument.

If the rest of the schedule is like this, it will be a long long season.

Wednesday, October 1, 2008

Things You Discover Accidently

Timeout from the Template trials to mention a little tidbit I found yesterday.
(Disclaimer - We could have been doing this all wrong for years. I understand CSS about the same way Genghis Khan understood quantum physics, but like him, I trust my instincts. I will ask the Flare crew for an opinion at some point.)

Since back in the RH days, our help topics have had a Product/Company masthead on every page. In RH you set up the style for the topic background and attached a graphic, and you could open the css file and see the code that included the graphic in the html Body element.

The code:
BODY {
font-size: 8pt;
font-family: Verdana, sans-serif;
background-repeat: No-Repeat;
background-attachment: scroll;
background-color: #ffffff;
background-image: url(SHLogo.gif);
}
The look:







When we moved our help to Flare, we duplicated this, but it always looked a little funny in the Flare XML Editor.




It looks fine compiled, and previews fine, but it is annoying in the editor.
What I think is going on here is that the XML Editor (noticed that I did not call it something that begins with W) would not display the margin-top: 30pt setting for the H1, but the compiled help handled this correctly.

Our solution was to fake it by inserting an index keyword on the first line that of course did not show in the compiled version but made the editor look tidier.







Still, all is not right with the world. If you look at the upper right corner of the snapshots, you can see a small gap between the top of the graphic and the top of page. If you look at the bottom left of the graphic, you can see another glitch. What is happening is that the editor is displaying the graphic twice, overlapped. We could never figure that out.

With the advent of Flare 4, the XML editor now correctly displays the margin-top: 30pt setting for the H1, but something still was wrong.

Here is the same topic opened in Flare 4. The offset is even more pronounced. I also showed the structure bar, and that gives a hint of what is going on.





Notice the matching offset in the structure bar between the html bar and the body bar - it matches the graphic. Here is how it looks without the para for the index tag:





Notice that the background graphic looks great nestled up in the left corner aligned with the html structure bar, but why is it repeated at the start of the body bar?

It looks like the XML Editor realizes that it needs to display the graphic in the upper left corner, but then the code that displays the body tag also feels compelled to display the graphic as well.

So I reasoned, "Well I don't need both" and went into the stylesheet editor and added the graphic to the html style class in the css. Trust me, the picture looks exactly the same.

Then I deleted the graphic from the Background properties in the body style class. Now it looks correct in the WYSIWD ('what you see is what we display') editor.




I did not know if it is a good idea to attach the masthead graphic to the html class tag. Looking at the compiled Help, I am thinking 'not':






So I guess I should file a bug report, finally. I have to confess that for the first few years as a Flare user, I kept quiet, searched for answers, and made my own workarounds. I have been the same way with RH and Frame and Word; just not much of a rabble-rouser.

Now I am feeling a little more militant, or maybe just more cranky as get older. Or maybe I feel empowered by Madcap's responsiveness, and deep down I like what they are doing. I like the tool and I want to see it improve, as well as have my colleagues like it just as much.

But for now my index tag workaround will stay in place.

Tuesday, September 30, 2008

Template Tuesday

After being crazed and interrupted for a couple of days with mundane matters, like the projects that keep me employed, I finally got to the point where I had defined enough of a template for importing Framemaker documents that I was ready to test a 'virgin' document to see if the styles I had defined would be applied correctly.

Let me step back to fill in some blanks here, because from the last blog entry, this is like the learn-to-draw lesson that goes from two circles and a square to Abe Lincoln's portrait in one step.

Last episode our hero was lamenting side heads and ditching chapter page numbering. Most of the focus then was on page layouts, and within them trying to duplicate structures in our Frame templates.

After deciding to ditch side heads, the focus was back on the .css, but with an important difference I mentioned in that entry: making sure that the writers in the group would have an easy adjustment to working in Flare with a print (PDF) target.

What I decided was to make the default stylesheet medium = online help so that when a writer imported content from Framemaker, their initial view of the result would look like our help. If it looked different, that would not be a confidence boost.

So in the stylesheet, the default medium and the non-print medium are the same.

The print medium defines different fonts, colors, and spacing for the content, by no small coincidence corresponding to our Framemaker styles.

The names of the styles match our Framemaker styles, not our inherited from RH Help style names. This is primarily to facilitate the potential of exporting back to Framemaker. I don't anticipate that being a frequent usage, but I don't want to make it harder.

This unfortunately means that the existing help will probably need to be retagged and pointed to the new stylesheet, but not immediately (because most of the projects will not suddenly become single sourced in the next iteration; most of the time writers will be importing new content written in Frame to add to or replace existing content in the help).

Setting up the styles was somewhat tedious. I had imported a template document from Frame that had the styles in it, and had the import definition Preserver Framemaker Styles to get the styles into the spreadsheet. But of course that made the print styles the default medium. I unimaginitively used the old brute force method to move the styles to the print medium, and then defined the default medium for help. I could have tried to be tricky with editing the .css as text and copying the styles to the media type in the source, but I did not want to make a mistake and snafu the whole thing. So I chickened out and did it in the Flare Stylesheet editor.

Sidebar: Even though I seem to be ignoring all advice, I did do a lot of the things Sharon Burton recommended in her best practices document, and those recommended in the Flare Transition From FrameMaker Guide and Flare Printed Output Guide. I used those sources to get my feet wet, and I tried so many different imports that I sometimes lost track of which import I was working on when interrupted by persons from Porlock. I found that I could not simply follow these sources to my Xanadu, because I really had several different objectives (setting up single source for a specific project, making an import template that would work for the other writers, come up with Frame template changes that would improve our books, etc.). But I did find answers to many of my questions in these sources and in the Flare Help (time and again; too many search results but almost never lacking an answer, ultimately).

Devil and Details: (Boy that sounds ominous, but...)
So I was at the point where I had mapped it all out, and was ready to try a clean import. So I added the document I wanted to import to the import template. But the button said "Reimport" and I did not want to reimport the document I had alread imported. Hmm. So I deleted it from the definition, but the button still said reimport. So I went to the Help and decided I would save the import template to My Projects and then add it to the Project as if it hadn't been there before and see what happened. So I did that and Project>Import File>etc. Then I did Add Files... and added the document I wanted to import, and checked the style mapping, and unchecked Preserve Framemaker styles, and hit Save. The button still said Reimport, but I clicked it anyway.

It worked. Sorta. It was totally successful, except that when I opened the content topics, none of the styles looked right. They were all Arial 12pt instead of Verdana 8pt!

No different in print medium. Grr. This is the devil part. I tried to re-assign the right stylesheet and found that not only was a missing stylesheet named in properties, but the stylesheet field was unavailable to edit (grayed out). WHAT?!

Back to the Flare help, and an answer. During my flailing, I had at some point assigned a master stylesheet to the project. Not only hadn't I wanted to do that (really, it was an accident, I didn't mean it), but I assigned some stylesheet from who knows where - it was a missing file!

The magic part is that once I cleared that field in Project Properties and assigned the correct style sheet, everything worked "Like Butter."

So Happy Day and all that.

I still have much to do (this didn't have the custom page layouts assigned yet, among other things), but this was a big hurdle to get over. Out of time, more tomorrow, I hope.

Wednesday, September 24, 2008

Another Day, another Template

So today I sat back a little and took stock. Although I have not yet built a perfect clone of our Framemaker format, I have been able to do all of the 'tough' tasks, such as page layouts, sideheads, tables for notes and cautions, headers and footers, title pages with background graphics, mini TOCs, and a few other tidbits.

I still need to build a cloned TOC and Index, and set up chapter headings for the Preface and Appendices and Glossary, but those should be minor.

But now I am giving some thought to practicality. And I think that other writers in the group will have a hard time with two things on the format so far. One is switching between print and non print views, because in the non-print view, the headings that are in the sidehead for printing disappear off the left if you click the Web layout. They are still there and re-appear if you click non print medium, but it is disconcerting. The second thing is the complexity of putting in note and caution tables so that they overlap into the sidehead. It can be done, but it has to be manually applied as best I can tell, because a table stylesheet has no way to set a negative margin, and no place to store a sub-class setting that includes the negative left margin (nor does the Table Properties dialog help). So you have to apply both manually.

Because in Frame we use AutoText to add these tables from a menu, and it does so with one click, it seems that writers will resent doing the extra machinations to achieve this. Sure I can add the table formats to 'My Templates" which I have urged writers to use (but they don't - they copy tables in from other projects and end up with build errors because they drag along a table stylesheet from another project), or I can make snippets and tell the writers to change the snippet to text to enter content, but they ignore that method. That is with the simple tables we use now in our help; they might freak if they had to apply a table style and then a table class. Not sure I'd blame them, when it is one click in Frame.

And what is 'this' really? It is a holdover from books our company published in the 1970s, quite frankly, and in my opinion, a poor use of white space. Our software books that are still printed (just two per product now) are published in a 7.5x9 custom size, and a wide left side head just wastes space, in my view. 1.75 of a 6 inch width is a lot of real estate, and it translates into extra pages printed per book. Even worse, all of our PDFs for software have a matching format, so those PDFs are likewise inflated. And all this just to accommodate Heading1 and Heading2, both of which are larger in Font size, different font family, and different color. Sure they stand out, but so does white socks with an Armani suit (not that I would know one or fit into one). That and the Note and Caution tables, each of which has a large graphic and a background shade to distinguish it. And oversize tables, of which we have many, already stretch into the sidehead, and are more finicky because of it.

All of that is a long-winded rationalization for my plan to propose to the group ditching the sideheads. For the books that will remain in Frame (the hardware books, at least half of our output, are already single sourced, in that they do not ship as help), changing the Frame template will just slide most things to the left a bit, and only the page breaks will change. For the software books and help, I think the look will be better, the books fewer pages by some (as I might increase the vertical spacing for the other headings to open up some white), and the formatting in either Frame and Flare will be easier.

Right now there are two books/help outputs that will gain much by full single sourcing and conditionalizing (4 outputs from 1 source for each). The others will be helped by generating less formatting work for the other authors, who will be able to seamlessly write in Frame (by choice) and import to Flare, because we will be using one combined set of style definitions, rather than two very different ones (one Frame and one inherited from pre-Flare RH). What will happen is that their content transferred to help will automatically show up in Verdana in the non-print view, while it was (and still is) Book Antiqua in the print medium.

At the same time we will be ditching chapter-page numbering for continuous page numbering to match our PDFs, losing another archaic remnant of days gone by. I had no problem implementing 1-5 in Flare, but I have been an advocate of the book matching the PDF for years, and had to bite my tongue and bide my time. Now they are powerless to stop me! (Sorry about the meglomania.)

Seriously, I have not had much trouble convincing the other writers, and showing them some usability articles from this century really helped.

Tuesday, September 23, 2008

Single Source Diary - Day 6

Today (virtual Monday; I am blogging Tuesday about Monday) , I am going to copy into the "new" template project the page layouts I have previously worked on.

Then I will make some modifications to the default medium stylesheet so that the headings positioning match the headings in our Framemaker books.

Here is a tip - if you are building page templates and stylesheets, and thus doing a build every 15 minutes or less, it might make sense to do this in a stub of a project rather than your 1000 topic monster. It is pretty easy to copy your template stuff and some samples into an empty project, do the work, and then copy them back into the real thing. Logical, but I found that it was easy to do the work in place and forget that when you ran a build, you were building everything every time.

The copy-in of Page Layouts worked. Then I made the modifications so that the Headings were positioned in the 'side-head' area of the pages (Using the negative left margin strategy documented [very clearly] in the Flare Help). Because Flare doesn't quite do side-heads quite the same way as Frame, and the format I am 'duping' has side-heads, I had the choice of css-left-margining every style except the headings, or giving the 2 heading styles that extend left into the 2-inch side head a negative left margin.

I chose to make 2 styles funky instead of 25 or so. (Before I can consider this part of the project finished, I have to modify all of the Frame table formats for Notes and Cautions, etc. that extend into the side head, because right now they are all truncated go off the page to the right in the PDF.
Late breaking Arrrgh:
(As Scooby-Do says "Rought-Ro" - that won't work because Table stylesheets don't support a negative left margin. I need to rethink this part some. I don't want to kludge something. I hate side-heads. Did I mention that? If I can, I will liquidate them, or just not do the tables that way.)
Un-Arrrgh: I take it back. I defined a table sub-class in template.css with a -1 inch left margin and it worked perfectly. So I needed a table stylesheet and a table subclass to make it work. See the snapshot below.



This is again, a result of the fact that I did the page layout with all text in the main text frame.) Here is a snap that shows enough of the idea.

I did some tuning of the headers and footers, because I am making one thing different in these templates. We are proposing to go with consecutive page numbering rather than chapter page numbering, so I wanted to make sure I could build it in Flare as well as retrofit it for Frame.

To get the look we wanted, we needed to place 3 elements in the footer at appropriate spacing:
- Page number
- Chapter number
- Book Title
to do this I ended up putting the page number in a text decoration frame flush left (or right on the right-hand page) and a footer frame with a 2 column table for Chapter (left) and Book Title (right) and vice versa on right-hand pages. I could not find any other way to have 3 elements correctly justified. I added a second text deco frame, but nothing showed up in it, nor did a second footer frame do the trick (I posted in the Flare Forum about this).

Here is a snap of the result.


All in all this day went pretty well.

Tomorrow I have to get back to some regular old projects, and I am going to run some comparison tests running Flare on a faster machine to check CPU amd memory utilization. My 512mb machine is getting kinda pegged out running Frame, Flare, and Outlook plus other junk simultaneously.

Friday, September 19, 2008

Single Source Diary - Day 5

Let me start out with the good news before serving some fine whine.
(Yesterday was manic depression Thursday, I guess. My mood is much better, and the fatalism is gone, at least until Monday.)

I went back to basics today (Friday), imported our templates, then went through the styles one by one, leaving the default medium set to the print style definition, and changing the non-print definition of the style to match our current help. As a result I can view a sample file in each medium and layout view and it looks right. It is kind of neat to click and watch the topic flicker back and forth between book and help looks.

What I plan to do next is import a real book and pre-apply this css during the import and see what happens.

Then I can (next week):
- Finish the Page Layouts I already worked a bunch on.
- Set up the Print Medium headings so that they start at the left margin in the side-head of our format
- Take the Frame Table styles I imported and set up the non-print versions of those.
- Import these Table and Page styles into the real book.
- Rework the TOC into a print toc.
- Create a non-print toc.
- Do a book build and a help build to see what the result is.

Dark Cloud, Silver Lining
Yesterday was a tough day. I decided to try to convert an entire book to a Flare project. This ran OK, but I found when it completed that Flare had incorrectly mapped some fonts to the wrong family (New Times Roman 12pt instead of Book Antiqua 10pt). This both very noticeable and distressing because the mismatched style happened to be p.Body, so all plain text was wrong.

So I tried it again, and this time distiller crashed during the conversion (Flare is converting graphics to PDF and back to gif etc) and hung Flare. I ran multiple imports, and when I imported a chapter, it came in fine. When I imported a book (several different books), the formats were messed up. When I imported the template chapter only, it seemed to work.

My guess is that by fixing the font mismatches and then using mapping to that css during the next import, the problem can be avoided. Or by pre-mapping p.body using conversion styles.

I just don't know why it was happening. It is possible that somewhere within our books, somewhere there is body text in Times New Roman. But why Flare would decide to use that instance, I don't know, and I don't have time to figure it out.

Couple this with the annoyment I had with page number variables, which were centered but were not supposed to be centered in our book format, and there seemed to be no obviouss way to right justify them, or change them in any way. You cannot select the text as it is part of the Madcap variable.

You could right-align the entire footer frame, but then if you wanted another variable for say a left justified Chapter name, that too was right justified.

The two alternatives were to make a two column table and manually space it, or set up two footer frames, one on the left and one on the right.
Update (09/22/08): Actually now I am using a footer frame and a text decoration frame. When I used two footer frames, I got an arrow connecting the two frames, and frame #2 seemed to be invisible in the output.

Oh, by the way, have fun trying to format the variables in the font you want them. Try to edit the style class, and they are all Madcap Variable, hence one style fits all. So without extra fooling around, your header variables have to be the same size as your footer variables.
Update (09/22/08): Turns out you can assign a paragraph style to the line the variable is on, and that works. What I cannot seem to do is to assign a span (frame character style, like in our Frame template) to the text in the Variable. Anyway, a paragraph style works fine.

By the way, with a 370 page book, Flare was using 90%+ of CPU and memory usage had grown to 208mb (up to 310 at times) on a 512mb system during a PDF build. And it didn't give the memory back when the build was done. It also seems to at random times peg the CPU to 90-100%, even when you are not editing. My guess is .net is saying hi to Madcap to ferret out license thieves.

So I basically spent a whole day trying to figure this out, and I still do not have what I consider an acceptable solution. At this point I am not sure that I can meet my goal of creating a PDF in Flare that is an acceptable substitute for our Framemaker version.

Woe is me.

Thursday, September 18, 2008

Single Source Diary - Day 4

Short and Sweet:
I took care of a bunch of smaller tasks.
  • Created a TOC for the print version
  • Created a print TOC topic
  • Inserted a Print TOC Proxy that points to the Print TOC (but I left in the default formats).
  • I imported the Preface Framemaker document, and begin tidying it up (but stopped because it cross referenced other chapters that were not yet chapterized).
  • I imported the other two chapters that were not a part of the existing help project, and linked them into the Print TOC
  • I built what I had done into PDF to survey the good and bad news. Lots of things worked just fine, but lots of aspects of our book design still remain to be applied.
Short Shameful Confession:
(Snort if you recognize that.)
I was so intent on adding the chapters that were part of the book to the project that I completely ignored the fact that Flare can import your book file and drag all the .fm files that are part of the book along with it.

In retrospect, I probably still would have done the import individually, because I already had the bulk of the information in Flare. But if you want to turn a book that has never seen Flare into a single source Flare project, importing the whole book might be your best choice.

I did this with a book, changed a couple of settings in the Target Printed Output tab, and did a build, and the result was a decent PDF (not publishable to fool anyone next to the previous PDF, but readable and not ugly). Ten minutes tops. Well, no TOC or Index, and Flare did not quite understand the role of chapter titles in our formats, and reference page graphics were nowhere to be found, but overall it looked pretty decent.

More later.

Wednesday, September 17, 2008

Single Source Diary - Day 3 Postamble

I spent most of this morning struggling with how to put two separate graphics on the same line in a Flare 4 page layout to mimic what we have in our Frame frontmatter template.

One complication is that both graphics are 72dpi reduced in Frame to 15%, and are in separate frames, grouped, one left-justified and one right-justified.

Full size, one of the graphics is 22 inches wide. So I pasted both onto one big hunkin' canvas, positioned them by hand, imported this monster into my Flare decoration frame, and then used the right-click Object selection to size it (I set both the Size and Print Size settings because it seemed like setting just the Print Size settings didn't let the graphic display in the Page Layout Editor.

Now that I think back, I probably could have used separate frames in the Flare layout also. DOH!

I don't like LCD monitors because when you bang your head on them, it doesn't hurt enough.

I just tried using the two frame method and it worked (to the degree I tried it; I did not want to nuke what I already did). I saw enough to know that I had picked the wrong road to travel.

So getting that demon behind me, what I really want to describe is the process of going from defining a page layout to match your Frame template to reviewing the results in a PDF target.

First of all, you need to have some content to apply the page layout to. I created a titlepage.htm file in Flare 4 to hold the title page content. When I open it in the XML editor, by default the first time it looks like a help topic.

If you have used Flare before, you will notice that the XML Editor toolbar in Flare 4 has some new gadgets. There is a Layout button and a Medium button. At first the Layout button defaults to Web. The Medium button defaults to Default (shocking!).

If you change Layout to Print, Medium changes to Print also, and your topic looks more like book than help suddenly.

You also need to create a new target (from the Project menu or the Project Organizer) and pick PDF as the output type.

You should then create a TOC for your PDF target, then associate that TOC with the PDF target (Edit the Target and pick Basic>Master TOC>your print TOC name).

Then add a topic or two to the Print TOC. To experiment with the page layout options, right-click on a toc entry and select Properties, then select Chapter Break>Start a new chapter document. Choose a Page layout from the drop-down for Configure chapter using this Page Layout, then pick a Page Type, and click OK. I love bolding text; it makes me feel like a real tech writer.

Now you are ready to try making a PDF.

You will also see another toolbar called Project (under View>Toolbar>Project) that has a Build Primary button with a drop down. Click the drop-arrow on the Build Primary button and select "Build PrintTarget" or whatever you called your PDF target. The compiler should be off and running, and in a short time a PDF should be viewable.

It might not look pretty at first, but here is the beauty of it. It is so easy in Flare to make a few

changes and kick off a target build that you can make incremental improvements and build every couple of minutes. Of course if you have a project with hundreds of topics, once you add them to the print TOC I imagine the builds will take a bunch longer. I haven't done that yet, to be honest.

Now I need to take a break for lunch and then this afternoon take stock of what I need to do next, because I am doing this on the fly and haven't thought it all out. That's a painful admission, but hey, I'm having fun. But this isn't a best practices course now is it?

Which should have been obvious after reading the first paragraph of this epistle.

Single Source Diary - Day 3 Preamble

This is the third day of my project to convert two books and two help systems about a single product into a single source project using Flare 4.

True Confessions:
So I ignored the sage advice I got about importing from Sharon Burton to "let it rip and then set up the formats you want in Flare. Then throw out the Frame files you imported and use the CSS you did in Flare for all future imports."

Well I had reasons, and Sharon was mainly answering my question about CCS styles, and not a word was said about Page Layouts, which is what I am currently working on.

But I kinda felt guilty about not trying it. So this morning I did an import of the frontmatter document, and as I suspected, and as happened in earlier Flare versions, the result looked good text-wise, but Flare ignored the master page formats, graphics, and text. The book title starts at the very top of page 1, though it is correctly right justified.

Flare documents this on page 23 of their hopefully titled "T r a n s i t i o n F r o m F r a m e M a k e r G u i d e" (it looks better on their cover page) . "Master pages from FrameMaker are not converted in Flare. You need to re-create them as page layouts." For those of us with templates that include text and graphic material, this also means import by hand, and resize by hand.

(As vaguely demonstrated in yesterday's blob, Flare does allow you to include this material in their Page Layouts, so if you have used Frame Master Pages, you do not have to rethink your templates; you can create elements in your Flare Page Layouts that serve much the same functions.)

But overall, the import went well, and it was mightly speedy. Next I added the frontmatter.htm to the TOC that was created by default, and edited its properties to set the page layout to Title, and built the PDF target. I ended up with a valid PDF with decent frontmatter, but to duplicate the look of the Framemaker frontmatter, I will need to go back and design the Title page layout, just like I did the day before. What I will probably do instead is take the best of both projects and combine them - in other words the character format definitions for the symbols, and anything else that looks better in the "let it rip" import.

What I will emphasize on the plus side is that the Flare import of the text within the frontmatter was rather better than my paste in attempt, mostly because it allowed me to map the superscript character style for the trademark and copyright symbols, and those ended up looking perfect. I did it by hand in my version, and the first attempt was ... not perfect. In fact, it was yukky in-line formatting that I intend to throw away today.

So after all that, Sharon was right, but that there is potentially layout work that Flare cannot do for you.

Tuesday, September 16, 2008

Single Source Diary - Day 2

Yesterday I added the default templates for printed output. Today I will work on making them look like our Framemaker books.

Today's disclaimer:
This is the "Innocents Abroad" (a travelogue) version of the process of single-sourcing a project from 4 sources to a single Flare project. If I survive this, I intend to blog a Mapquest version that offers the fastest stepwise route from here to there, probably based on the "Short and Sweet" summaries and looking back. In the meantime, when you run out of patience with these ramblings, you can probably do these tasks in shorter time than I by using the Flare Printed Output Guide PDF as your bible.

Dose of Hope:
This book layout stuff is complicated anywhere, in Frame or Flare or whatever. Flare is trying to provide the same level of flexibility as Frame, and Frame is famous/notorious for being the swiss army knife of technical book design. Realize that if you can get it right, you only need to do it once and you can re-use it for every project.

Short and Sweet:
I was able to build a Title page layout in Flare that echoes (pretty much) what our title page in Frame does, using the default frontmatter template and the Page Layout Editor. I still need to make adjustments to the graphic logos because there were two on one line in Frame and that is hard to duplicate in Flare. I tried using a table but the right-justified graphic is not lining up correctly.

So I still have some issues to solve, but the good news is that by jumping ahead and defining a titlepage.htm, a print target, and a one topic print toc, I was able to output the title page and Copyright page to PDF and they looked dern close to the Frame version.

Groddy Details:
Might as well start with the title page. Ours includes a right-justified product title, release number book title and revision number 2 5/8 inches down from the top (that is where the page frame on the title page starts), and at the bottom a company logo and address. No header, footer or page number. In Frame, this is page one of a two-page document; the second page is copyright and trademark info, plus some publication data. I did not mention that our book format is 9x7.5 but the margins are placed so that printing on an 8.5x11 page looks presentable.

In Frame the the book title stuff is text, while the bottom logo and address is two graphics and text on the master page. I am going to try to build a snippet for this.

But before that, I need to deal with something in the Page Layout file. Our help stylesheet uses a non-repeating graphic of the product name as a page header. This seems to be showing up on the Page Layout template (though a quick test seems to indicate it does not print or PDF there). Still, it looks hideous and distracting. So I want to see if I can modify the css to hide it for the print version.

So far, no luck. It appears in the first line of the body and in the footer, despite my setting all these elenments to have no background image. When I look at the xml for the frontmatter page layout, no sign of the graphic or a call to the stylesheet. It does show up in the output (yes, I can generate a target output even this early on; there just are not any real contents), which is bad. Clearly I need to do some digging to find out where this is coming from.

Okay, what I found out is that the graphic was defined in the default medium stylesheet. (There are three mediums - default, print, and non-print). So it was showing up by inheritance in the print medium stylesheet. So I nuked it in the default medium. That made it disappear everywhere. So I added it back into the non-print medium. Now it shows up when I edit or preview a page (an existing topic) in Layout Mode Web, Medium non-pint. It is hidden in Layout Mode Print, medium print and medium default, but visible in medium non-print. (Layout Mode determines what your XML editor looks like; to over simplify, whether it looks like you are editing a help topic or a print document page.)

But the graphic still showed up on the page layout file, until I edited its property sheet and chose the Print Condition tag under conditional text. Then the graphic disappeared. Curiously when I then deselected Print and Okayed that, the graphic did not re-appear. Hmm. This makes me think that it is an artifact of some buried setting (this project was imported from the old RoboHelp back in the Flare 1 days, so I think there are still gremlins in there, like a liberal sprinkling of links to old pal ehlpdhtm.js, which survived the import process though it seems to serve no purpose. Perhaps a Madcap coder was nostalgic for files from the old ehelp days).

Do I have to tell you that I think this is over-complicated? I am sure I will recognize why it is set up this way someday, maybe even soon. It is flexible, I'll give it that.

Okay, enough of that crap. Let's get back to the basics. The Frontmatter.flgpl file has 5 page layouts defined. The T page must be the title page.

So I am going to attempt to move the top margin down 2 5/8 inches like in the Frame template. First I click on the ruler on the left of the editor and change the measurement from pixels to inches. Then I click on the gray frame and drag it down. Oops, the ruler is in tenths. I refuse to disclose how I figured out that 5/8 = .625 inches. So I drag the border down just below 2 and 6/10, probably to 2.650 given the grid, which I am way to lazy to change. But while I am lazy, I make up for that deficiency by being I am easily distracted. So I go search in Flare help for the new Zoom feature.

Darn. Looks like that works in the XML editor, not the Page Layout Editor. Oh well. .65 is close enough for now (I realize later that I can set it more precisely from a right-click selection that opens up a dialog box).

That should correctly set the top of the page for the Book title. Now I have to think about the logo and address and the snippet thing, and how to position that. I think I could shorten the main frame and add a separate frame for the logo and address. Before I do that I want to look back at the Framemaker version. That sticks the text part in an unanchored text frame that is not part of the flow, and places a grouped graphic of both logos in an anchored frame within that frame. I will try a separate frame in the Flare template and see how that works. I am not sure how I get the snippet in there. back to looking at the Printed output guide.

Back again, and I think I am going to try to add this as a footer frame, to which you can directly add text and graphics. I believe that this will only appear on the title page, as this page of the layout (because it is designated as the Title payout) will be used only for page one of the frontmatter.

Note that this layout has an Empty page, which the book says will immediately follow the title page. For our books, because the title page is actually an inside title page on the right side (the outside cover is spearately printed), the next, left, page is used for the copyright/trademark stuff, and should not be blank like a cardstock type cover, so I think I need to delete the Empty page from the layout. We will see.

So I am moving the bottom of the body frame up one inch and creating a one-inch text frame at the bottom. I am making this a footer frame becuase the bible ominously says that decoration frames are not support in Framemaker output, and while I don't expect to output to frame, I want to play it same and not remove options.

Next I click F2 to edit the frame (opens the Frame Contents Editor). I click the insert a Picture icon, and realize I have to export the picture from Frame, because it is copied into the book, not referenced (long story about master pages skipped). Of course, the picure is in reality two gifs in a grouped frame, with the originals huge in size and displayed at 15% in frame, so I am going to fake it by reducing them size first, just to get a facimile graphic. That done, I pick it and place it, then type in the Address text (I will variable or snippet this later, for now I want immediate gratification and I am itching to click preview somewhere.) Bad news is the lo rez version of the graphi looks so lo rez. But overall the page is correct. I will try other stuff later, like re-sizing using a new Flare Object feature, and a table to allow two grapics on one line.

I have to finick around with it to make it fit yet loook like frame. But I did it after some heartburn. Then I created some styles (print medium only) to handle the book title, part number, product, etc. I typed those into titlepage.htm (that I also created). Then I created a Toc for the print version, and a print target to PDF, clicked build, and I got a 2 page PDF with a title page that looked surprisingly like my frame book.

I will go over those steps tomorrow when I do them for real.

Monday, September 15, 2008

Single Source Diary - Day 1.5

I left off with: I next need to figure out the best way to add the Print Layout files to the project and define them.

Short and Sweet:
I can simply add these elements from existing Flare 4 templates to an existing (help-only) project, refine their design, and apply them (in a Print-Output target that I also have to create, later).

For Tech Writing Masochistics, the Excruciating Details:
In this project, almost all of the content is already in Flare. But there is no print target defined, and no definition of how printed pages should look.

Additionally, there is a chapter about hardware in the books that is not currently in the Flare project, because it was not part of the online Help. So that chapter needs to be imported.

Also, there are elements in the book, such as the print TOC, the title page and copyrights, and the preface, that are not in the Flare project yet. And another thing - the project Index is formatted for help, not print.

(I think I will set up the page formats first before I import these files.)

I think it makes the most sense to build the 'containers' for these objects in the project, and then either import them or recreate them. I think trying to import them to create the 'containers' would bring along baggage and would cause extra work in molding them to fit into Flare. But I will experiment with both approaches to make sure.

However, I also think that I can save some time by starting with the sample Print Output templates that Flare 4 includes. So if I create a new project, I should be able to put together a book template and then import it into the existing project. I hope. Back to reading about Page Layouts.

Well BZZZT! in a good way. It looks like it is just as easy to add the sample Page Layouts one by one to an existing Flare project, so there is no need to create a new one and copy stuff over.

I can add the following templates I need from the Project menu Add Page Layouts selection:
ChapterLetter.flpgl, FrontMatterResizable.flpgl, IndexResizable.flpgl, GlossaryResizable.flpgl. (.flpgl is the extension for Page Layout XML files.)

Next Steps:
I will need to figure out is how to use variables in the running headers and footers, but I am not worried as I saw steps on such things while skimming the Flare Printed Output Guide.

Discouraging Words:
I suppose this is my futile attempt to not appear to be a total Flare 4 suck-up.
But I did notice -
One thing that gives me slight pause - in the Flare PDFs available for download, the bookmarks are not perfect. There are some strays and repeats and out-of-orders, and a case or two where the subordinate levels don't exist. I don't know if this is a result of gremlins in their straight-to-PDF output or end of release frenzy by their Tech Pubs folks. Either way, it will be something to look out for. Given that we have similar problems with our Framemaker output to Acrobat sometimes (mostly unnested index entries and TOC entries in the Preface), I am neither shocked or chagrined.

Single Source Diary - Day 1

(After proposing a project to merge projects so that two books and two help systems can be produced using a single Flare 4 project, this is the morning of the first day. One other note: I am not posing as a Flare expert. Quite the opposite. I am intentionally stumbling through this the first time. It is up to the reader to decide if any foibles are mine or Madcap's.)

The introductory post of this series (Pilot Project with Flare 4) proposed some of the tasks that need to be defined and completed to create a single source project out of four (now separate) targets.

The next step I am going to take is to break down some of the objectives into tasks that need to be done.

What I am going to look at first is how the book templates we have in Framemaker should be implemented in Flare.

Short and Sweet:
I need to define Page Layouts in Flare 4 for each of the book components that are part of our Framemaker template.

Result:
I need four Page Layouts to implement the same structure as our seven Framemaker templates (I think). I don't need the Frame Book File because the Flare Project file acts in that capacity. It sounds like I can have one page layout that contains all the frontmatter (book title page, copyright/trademark page, TOC (a proxy - more about that in a later diary, I'll bet), and the Preface. I next need to figure out the best way to add these files to the project and define them.

Clarification (9/23/08):
to be more specific, the four Page Layouts are: frontmatter, chapter, glossary, index. Our glossary looks different than the chapter, while chapter and appendix are almost identical. Preface can either be inside the frontmatter or a separate document using the chapter page layout.

Long-winded and Painful:
Right now we have seven template documents in Framemaker for Fontmatter, TOC, Preface, Chapter, Appendix, Index, and Glossary. One thing that seems evident to me is that in a Flare single source project, the structure will be similar, but I think I can combine the frontmatter, mostly because the TOC does not have to be a standalone generated file.

For example, instead of an independent file in the Framemaker book for the Frontmatter that is used as part boilerplate and part fill-in-the-blanks, there will be a frontmatter topic in the Flare project template that will serve the same role, but it will be a self-contained in the template. Well, I suppose it is still a file, but it is more tightly integrated into the project, as are all individual files in a Flare project. It will probably use snippets and variables in place of the master page boilerplate of the Frame frontmatter file.

That file can also contain the TOC and Preface, and use Roman numbering, if we decide to preserve that archaic convention. At least Michael Hughes considers it fairly useless in an online document, except to tell the reader "... if the page number is a Roman numeral, there is no useful content on that page."

The Chapter and Appendix have an almost identical template, except that the Chapter numbering differs. I will need to determine how number versus letter titles work in Flare (has not been an issue for Help) to determine if I need two topic templates or one.

The Answer: just one format I think because I can setup a chapter break that resets to 1 and changes numbering scheme to uppercase Alpha. (But I am not sure how that affects the page footers - so I may have to backpedal later.)

I do know that you can set up a first page that is always a right-side page for print output, but I do not know how you set up the topic that follows. I think that between chapter breaks (settings in your print TOC that signal a new chapter), the rest of the topics in the chapter just flow in, starting either as a new page or continuing an old one, depending upon their topic heading type.

This also bring up the hierarchy discrepancy we have between our help and books. In a book, we have a chapter title, and then Heading1,2,3 etc. In Help we have H1, H2, H3, but no concept of a chapter title.

Typically in our books the chapter title is in a larger font than the Heading1. This probably means that we will need to have a Chapter Title template topic that uses one tag for book and a different tag for help, conditionally, or perhaps that the Chapter Title template is used only in the book TOC. Typically our Chapter Title page has a small intro and a mini-toc for the chapter. Then often the first Heading1 is an overview, starting on the next page. In the Help we tend to just have the overview, without the short blurb and mini toc. We do often have a list of topic hyperlinks, but later in the topic. This may be worth re-examining.

I think at this point I am going to go off to look at the Flare 4 help and pdfs to understand how to do a mini toc in Flare, and to see if they have other advice on importing and setting up chapters and headings.

Back again...I skimmed through the section on mini toc that explains how proxies are used. So now I know what to use to create one. When I create a chapter title topic I will follow the steps to build in the mini toc proxy.

There is a section in the Flare Printed Output Guide that explains "Using TOC Depth For Heading Levels" in a printed TOC. This section explains how to use the outlin in your Print toc to build the toc in the target output. So essentially any topics that I identify in the print TOC as the Chapter Title topics will show up in the TOC that way, and in the correct order in the PDF.

There is also a section in the Flare book called "Specifying Chapter Breaks And Page Layouts" that explains how you let Flare know where chapters begin and end in the Print version.

Another important concept that comes up here is the difference between Page Layouts and Master Pages in Flare. In Flare, the newer concept of Page Layouts is best for print documents, while Master Pages are best for adding page-like elements to online content. For example, if you want to put a footer in your help with a 'breadcrumbs' trail to show how the topic links to higher level topics, you would put that in a master page. For now I think this project will be using Page Layouts, unless I can't make them work.

Even more Blather
One thing I have to add (writer compulsion is a terrible affliction) is that the objective of this exercise is not to find a way to consign Framemaker to the dustbin. It is more of a proof of concept for instances where there would be a potential benefit for single sourcing, and there is need of a help target. We have lots of hardware books and training books that do not have a help target, so any gain in single sourcing would be dissipated by the work needed to convert them.

Actually the training is potentially a third target for this project, but that would be excerpts, not single source. The training developers could use source from the project as a starting point for their training materials, but that would end up in Powerpoint and in Framemaker.

One other thing to mention is that my goal is not just to convert this particular project to single source, but to define a Flare project template that could be used to convert other projects. So I will build a project template, then test it out with this project, rather than build single sourcing into this project, then try to extract portions of it into a template.

Politically Shrinking (and I don't mean egos)

This blogsite's title ominously threatens to discuss politics, and I prefer not to make empty threats, so let me just say that Presidential Politics in the USA just plain sucks. The parties have devolved to the degree that the campaign is like two kids in a substitute teacher's class having a spitball fight, while trying between shots to pretend that they are doing no such thing. When liitle Johnny misses his shot, wiseguy Jimmy yells out that Johnny hit him with a spitball. Hopefully Americans, who consider themselves smarter than the average substitute teacher, can see through this flimsy pretense that both parties are juvenile and venial and could not insult our intelligence more if they tried.

But unfortunately, the outward signs that the politico's consultants swear by seem to show that it works, and denial works just as well. So the strategy is to claim you are running a clean campaign, smear at every opportunity, and cry foul every time your opponent waves vaguely in your direction.

The radio pundits call us a nation of whiners, and there certainly is some truth to that, though much much less than they imply. Most Americans, I believe, wince when they hear about the political thin-skins who attempt to make every political statement into a racist or sexist issue. Most Americans are sick of this but with both parties doing it and blaming the other, most Americans have no real outlet to express their disgust.

What is not clear yet is whether that strategy really works. For example, was the Swift boat stuff a deciding issue in the Kerry vs Bush race, or was Kerry's personality, or Edward's for that matter, versus plain old George, the leader who brought us back from 9/11, and declared Mission Accomplished in Iraq, better enough?

This political season, will the attempts to 'elitize' Obama, combined with just plain folks hockey mom Sarah, be enough to give John McCain, who does not look quite as old as the Mummy, a ticket to the White House, despite blunder after blunder by the incumbent party?

Economically, today we have seen a 300 point drop in the Dow Jones (leveling back to 180), and deep losses globally over the latest financial crisis at Lehman Brothers and Merril Lynch, plus AIG on the ropes. Will the GOP spinners be able to say that all was fine until Pelosi and company took away Congress? Will the Obama campaign be able to make their "more of the same" slogan stick to McCain/Palin?

All of which has nothing to do with fixing the economy. Sixteen years ago, Bill Clinton hit the boom/bust cycle just right with "It's the economy, Stupid!" Bill got lucky because the cycle was heading up anyway. This election season, it does not look like the cycle is heading upward. But the neglect of the current administration needs to be a big issue on the table, given that they have watered down the economy with the spending in Iraq. Can anyone ward off a crash? In my opinion, only by cutting off the Iraq funds, stop printing extra money, and moving a fraction of that spending into the domestic economy to alternative energy and border management. Right now, I would rather have the Marines stationed on the Texas/Arizone/New Mexico border than in the Middle East.

The other worrisome story is the border tensions with Pakistan over Al Qaida. Rather than getting the dander up in an unsettled Muslim country that has nuclear weapons over some irregular stragglers taking potshots at our forces, why not set up a tripwire type of exclusion zone, and let everyone know that anything that crosses it is liable to be blown to bits? But it seems that we are so determined to prove our toughness that we will do any stupid thing that some neocon in Washington thinks of. That strategy did not work in Southeast Asia in the 70's, and it is unlikely to work in Southwest Asia now. It is just crazy to contemplate drawing in Pakistan or saber rattling against Iran when we are in dire straits economically.

Saturday, September 13, 2008

Conditional Text Zombies

Funny little story about a bullet in the last post. I worked for a company a while back that was a spin-off of a spin-off, where some tech pubs department members migrated from the mother ship to a seedling, then to another seedling when the options dried up at the first. Being loathe to throw anything out or to re-invent the wheel, these intrepid explorers loaded the first company's Framemaker files onto the covered wagon and brought them to the first spin-off, making enough cosmetic changes so it didn't look like a rip-off, but preserving the basic structure of the book. When some of the pilgrims moved on to the next colony, they loaded up the new files, brought them to the new promised land, and jimmied them up a little to look different. In both cases, this consisted mostly of changing the font and colors of the headings and table/figure captions, using a different look on the cover page, and substituting new graphics for the company imprints.

Well, by the time I got to the third company, as a wage slave rather than a stakeholder, they had published a release or two of most books. It was a hectic environment, and on one document, they had a publishing mistake - a book went out with what looked like some extraneous pages in a couple of places, almost like the old days when you picked up a job at a printer and found someone else's email interleaved with your manual's chapters. People thought it was a fluke because the Frame source looked just fine. Then it happened again, fortunately on a review draft.

Everyone was mystified. So they asked me to look at the document. Honestly I am less of a Frame guru than I should be, but I am a decent detective. It turns out there was conditional text buried in the document, not from the current company, but from both previous companies! One chunk was a fairly extensive two page blurb about the original company, including graphics and logos and all sorts of incriminating stuff. But mixed throughout was sniglets of stuff just waiting to be accidentally exposed.

Essentially, the writers who spread this disease had taken a book from the first company, used it as the basis of multiple books for the second company, and then taken one of those books to the third company to use as a basis for other books. So what we really had was a book masquerading as a set of templates, where only the text had been cleaned out, but the reference pages, master pages, and wells of conditional content still remained, at least in part, from two prior companies, each of whom, by the by, were competitors of the current place.

The current writer had tried to conditionalize some text for our current company, and in doing so had called back from the nether regions a bunch of this stuff from beyond the grave. It was like the tech pubs version of a zombie movie.

If I remember correctly, much of the conditional text from company 1 was all blue, and that from company 2 was all red, so that when you exposed both, there were globs of color clumped into various places in a given chapter. And because text copying and movement had inadvertently carried conditional stuff along with it, there were multiple instances in some cases.

So the department manager sent me on a stealthy search and destroy mission to find and terminate any instances of undead conditional text in the templates and in the books created from them. I was Van Helsing for a week (yes, I know, he hunted vampires, not zombies; perfect analogies are just so prissy; I prefer a touch of dissonance, some grating and grinding). When I finished, needless to say this was not a widely discussed success story.

I am sure the passage of years has inflated and distorted some aspects of this, but it kind of sums up my feelings about conditional text. I will end with another tortured analogy, quoting one of my favorite movie lines, to sum up my past feelings about conditional text. In Snatch, when cousin Avi (Dennis Farina) returns from England, US Customs asks him "Do you have anything to declare?" He replies "Yeah. Don't go to England."

Pilot Project with Flare 4

After going over some of the tutorial 'movies' on single sourcing and other topics, I have decided that I am going to use an upcoming project as a pilot for single sourcing with Flare 4.

Since I have this blog space, I am going to use it as an excuse to keep somewhat of a record of how the single-source project proceeds, airing the successes, false starts, stumbling blocks, and eurekas as I muddle through the process of learning how to use Flare to tame this project, and also to provide a test case for single sourcing other projects of mine and of the writing group.

Trying to put on a positive spin, I will describe my working process as spontaneous. What that really means, though, is that I typically leave a minimum footprint for a project record. Great for ecology but not so good for repeatable processes. So by logging what I am doing here, I hope to be able to better assess, analyze, and standardize what I have done, if I can successfully complete the project as intended. If I cannot, I will be better able to determine where I messed up and how to correct it.

Here is a description of the task as I see it. We have a product that allows customers to create badge layouts for access cards they issue to employees and visitors and contractors. The access cards are typically proximity or magnetic (swipe) cards that unlock building doors or provide other access (elevators, parking lots, etc). This product has two versions. One on our legacy access control system, the other on our new .net platform. Both products use the same base code, but differ slightly in features and in the way they work with the platform (the new platform stores stuff in SQL, the old one in separate files).

So while there are differences, it is fundamentally the same product. The next release of both versions continues the process plan by Engineering to merge the feature set so that both platforms support the same version, and a more dynamic interchange between them is offered to customers who have both our platforms.

Presently each product has its own help system and book. These have very similar content, as my authoring has been topic-based, with topics lumped to make book chapters. But essentially there are 4 project sources. Using Flare, I want to attempt to reduce this to one source set.
I do expect that I will still need to produce 4 outputs as before.

Here is an outline of the basic tasks I think I need to perform to do this. I am not numbering these yet, though I do have an inkling of the order they will require.
  • The help for both is already in Flare 3.1, but in separate projects.
  • We do not yet have a print media definition in Flare, so we need one.
  • Both books are in Framemaker using our well-defined book templates.
  • Those templates and their features need to be built into the print media definition.
  • The help systems are almost identical in look and feel, with the exception of product logo banners. A previous blog entry covers my solution to that issue. (Flare CSS...)
  • The books currently have a hardware related chapter that is not part of the help.
  • The version for the newer platform does not yet support a major feature that is in the legacy product.
  • The help/chapter for that feature is written and will need to be conditionalized for the newer platform. It is an 80-page honker.
  • It is possible that some aspects of the feature will be implemented differently, and will support different card technologies, readers, and printers than the older platform.
  • I want the books produced by Flare output to be virtually indistinguishable (by me at least) from the Framemaker version. Reasonable compromises will be made I am sure. but if it looks that close, no one else outside of the writer's colony will have a clue.
  • I have little experience with conditional text, except for the experience of cleaning up after a bad implementation at a previous job. So setting up conditions for both print vs help and for feature inclusion/exclusion will be challenging (at least to do it right so that it is sustainable and not a confusing mess.
  • Right now, the project time lines for either project are not set except as vague fiscal quarters, so I am not sure which version comes first.
  • I have to create 4 TOCs for this; 2 book, 2 help. Contents will be fairly close, but the books have a preface that is not in the help, and a copyright/trademarks page.
  • Typically we put far fewer screen shots in our help, assuming the customer is staring at the screen we are talking about. But I have to say that looking at Flare's own help, they tend to throw in quite a few screen shots and they have no compulsion against making them enormous. So I am going to think about balancing the help real estate vs the degree of difficulty incorporating the book's screenshots into the help (all those captions and cross references are gunky).
  • After I have set up the book template aspects of this, I need to import the hardware chapter and put it in the book side TOC.
This list hopefully covers most of the big ticket items that need to be done to plan the project. When I get back to the salt mine on Monday I will probably try to refine this list and put it in some semblance of order, and reflect on what I have forgotten to include.

Thursday, September 11, 2008

Day 1 with Flare 4

I installed Flare 4 today and started playing around.

Things that I liked right away (disclaimer - these are in no way important, just stuff I liked):
  • File> Zip - you can make a zip file of your project right from the file menu. Very handy.
  • Footer in the help listing all the PDFs you can download from Madcap. Some very useful titles. If you are going to have a 7 line corporate address in the footer, you might as well do something useful at the left margin.
  • Select table cells, right click and viola! Cell Content Style menu selection - you can assign a style to multiple table cells. Good Glory!
  • The new printed output tools (Blaze inside) look good, and the interface is modern and clean. What Frame could be if Adobe hadn't neglected it for years (still love ya Frame, but I loved my 82 Chevy Nova too).
  • Review toolbar and X-Edit built-in. Not sure how Engineering will take to it. Maybe if I say XML repeatedly they will be interested.
  • Layout Dropdown - you can edit in a web layout or a print layout. Maybe some of my compadres will author more Flare First (rest of the group is book first help later; I am the opposite. If I wanted to write chapters, I'd be channeling Normal Mailer rather than [insert rich and famous web author here].
  • Font Properties button - Ok, it was there before. I am such a dedicated CSS-er that I never ever opened it to inline font properties, and saw that the example text was "The cute red cat in the hat"
  • Global Project Linking - This is one thing I am itching to try. We have the same stylesheet copied into over 40 projects, but god knows what has happened to them over the past several releases. They have probably been tinkered (I know I have changed things in one and not the others).
  • Video Tutorial on single sourcing in Flare. I will be watching this one in the morning.
  • Widow and Orphan Control - I just had to say that this always reminds me of some horror movie where single moms and abandoned children are turned into zombie slaves by a publisher.
  • Basic Madcap Analyzer inside - because my guess is that I could never get my boss to spring for the full product, at least I get some reports with V4.
The bad news is I have not found anything to complain about, so I guess I will have to go home and mock the cat to bleed off some aggression. He doesn't like it when I imitate him, but he puts up with it because I am the one who wields the food scoop.

There are scads of things that I haven't even looked at yet. This is obviously an incomplete and seriously quirky list, and not in anyway an attempt to review the product.

But I hope it was interesting anyway.

Wednesday, September 10, 2008

Reviving Oblivion

This blog has so far suffered from all work no play. That is hardly reflective of my real life. So let's talk about about Oblivion. This game is Bethesda Softworks to a T - monumental, beautiful, engaging, virtually limitless in depth, and a crash king. It is so Bethesda that even the console versions crash with regularity. The last official patch was ages ago (well, 4/30/07, ancient history for a PC game).

Fortunately some dedicated folks (Quarn & Kivan) have put together the UOP - the Unofficial Oblivion Patch. If you have played Oblivion on the PC, you will be more than amazed at the way crashes are minimized. I have now played days without crashing during the game. Admittedly, the game crashes to desktop on exit on my PC almost every time, but it never freezes the whole system like it used to. What amazes me most is that you can open and play games that were saved on pre-UOP versions of Oblivion - lots of times big patches are not backward compatible.

If you have played Oblivion before and took it out of your rotation because of the crashes, you should download this patch and give it another try. You can get the patch at (among other places) PlanetElderScrolls.

Have fun. Meanwhile, I'm heading back to my house on the waterfront to soultrap conjured creatures and recharge my Shadowhunt bow.

Flare CSS Management (and a neat little trick)

We have two main products, each with a main help system and one or more smaller surrogate help systems. One main help system is a master with around 30 merged .chms. The other is one big chmglob with just as much info, but linked to a legacy product that would not know how to point to merged chms, so say the Engineers.

If you know help, you can infer from this why I have a concern about managing CSS formats.

The legacy help system was converted from RH, and brought along untold amounts of format baggage in the guise of inline formatting and residual crap. We cleaned all that up, gave it a clean and fresh look (clean white vs unbrushed teeth yellow background).

We then started fresh in Flare on the new help system for the newer system. The newer product is .net, C#, VS2005 look-and-feel, which is ultra modern compared to the older. But the customer base is very much the same, so we adapted a very similar look and feel for both help systems.

So we used the same CSS formats for both help systems. Only difference was the banner on every topic.

Topic Banner for the new product



Topic Banner for the older product



Over the course of like 4 releases of each product, with around 40 .chms, and with us adjusting to the Flare way rather than the RH way, variances have crept into the many copies of the CSS in use.
Typically, when a new format was needed to handle a quirk or something we had overlooked (for example, text in tables that looked OK in RH seemed to be rubbing shoulders with table borders in Flare), the change got made by a writer and did not get propagated to every project. I am sure you can see where this got us.

So now that the hubbub from the latest releases has subsided, and we are about to load up Flare 4, I am spending some time looking at these CSS issues to both repair the CSS and plan ahead.

What Flare 4 appears to give us is a way to globally manage our CSS - Global Project Linking. If I read correctly what has been announced, we can put our 'master' CSS file out on our shared network drive and have all the Flare projects link to it. My guess is that we can lock it and thereby centralize changes, so that we don't end up with 40 different variants.

Of course, to do that, we need to have one CSS file to rule them all.

That brings me to The Neat Little Trick Part in the title.

By using the Stylesheet Medium setting in Flare's CSS Editor, I can set up, in one CSS file, two versions of the topic background, each of which uses a product-specific banner. Medium is most commonly used to distinguish between print and non-print formatting in a Flare target, but in this case I am using it to distinguish between two variants of online help.

Stylesheets Mediums are described well in the Flare Help (topics = Creating Medium Types and Associating a Medium Type with a Target), but the focus is on print vs non-print. This is another way to take advantage of this feature.

One other note - projects for help system A will have only the target for A, and projects for Help system B will have only the target for B, to avoid unfortunate results (product A has help banner for product B).