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

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