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