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.