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