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.

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.

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.

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.

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.

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.

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.

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.

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).

Madcap announced Flare 4

Madcap announced Flare 4 yesterday, and we received email that we can download it now (we have a maintenance plan that includes upgrades). I am eagerly anticipating trying the released version, after fiddling around with the beta for a while. But I also realize there is a lot of work ahead if we are to get everything out of it. I am responsible for our formats and templates, and with a new release invariably there are changes.

In addition, Flare 4 includes the capability to go to print from a single source, but the catch is that you have to add a design for your output for print medium, or in our case, re-implement our Framemaker based design. or however close we can get to it.

My first step is going to be to visit the Flare forums to see what the early buzz is.
After that I will download the Flare 4 software and install and register.
Then test drive it for a couple of days.
Then have one of the other writers guinea pig install it on their system.
Then one by one work with the other writers to install on theirs.
Meanwhile I will be testing out how our current CSS performs with Flare 4, and looking to make some minor changes.

One great thing about Flare is that you can have multiple versions existing on your PC at the same time, so there is much less risk that an upgrade will mess up existing projects, or if the upgrade has key defects, make it impossible for you to produce output. I have had other situations with other company's products where you must de-install the previous version to install the update, which then doesn't work right. Then just try to re-install the old version, along with patches you don't remember installing, only to be told that some registry setting prevents the installations, sorry. What a nightmare that can be.

Working with Flare is not all rum-cake and spiced cider in front of a toasty fire, though. There is no doubt that editing XML files in Flare exposes you to more clunkiness and requires more format thinking than writing in Word or Frame. The good news is that you can use the structures to advantage; the bad news is that you have difficulty avoiding some deep delving to understand why things don't look as you wish.

This is especially the case with older project converted. Flare tries hard to cleanup up residual garbage when converting, and does an admirable though not perfect job. But you will still trip over instances where someone did something tricky in a previous revision in a previous HATT that either conflicts with the XML way, or no longer has the same effect. Sometimes these effects are invisible in the XML editor but very visible in the compiled help. Then you just have to open the internal text viewer and look at the code, and hope you don't delete anything crucial.

But that is with 3.1 and prior versions. I am sure that with Flare 4 it will be church bells and the choir invisibule singing Hallelujah all day long.

Meanwhile in the workplace

We are awaiting the release of Flare 4. I tried the beta and it was pretty good, but then my PC got crabbed up and we had to give it a wipe, so bye-bye Flare beta. Did not reload it because by that time we were under the gun to release product, so no play time.

Now the release is just about out, so it would be a good time to do some more preparation. We are ready to upgrade Framemaker and Acrobat to 8 (yes we lag a good bit; but if we upgrade and hit a bug that stops our production, we are hosed so better safe.

Between releases, I am looking at making changes to our Frame templates, and to go back through our Flare help and update the css files (in the rush, they tend to get out of synch). Also looking at aligning the Frame template formats closer to the Flare css formats. The books are Book Antiqua while the Help is Verdana, and we do move info between them so it would help to reduce retagging.

It is nice to dream about single sourcing in Flare (or Frame if it actually worked well, but) and also about moving to DITA, but in our undermanned situation, the conversion would bog us way down. So small steps is the best way we can make progress.

Boy this is boring stuff for anyone reading from the outside. But it is good to record it in frozen electrons, rather than mentally rehash it on a daily basis.