ITauthor

It looks like I'm going to have to come up with some tedius workarounds for the flaws in the way MadCap Flare outputs to FrameMaker. One example of a flaw is that - as far as I can make out - Flare ignores any styles you may have applied to anchors (i.e. a elements) and so, when they come over into FrameMaker, they are indistinguishable and you loose any differentiation you may have had in your WebHelp between two different kinds of anchors. Another baffling irritation is that text I have defined with a PrintOnly condition come over into FrameMaker with a "link" format applied to it. To workaround a lot of this madness I think I'm going to have to take the FrameMaker files, save them as MIF files (which are text versions of binary FrameMaker files), run a whole batch of search/replaces on these files and then pull the resulting MIF files back into FrameMaker and do the final tidy up, reformatting work prior to outputting to PDF. All of this is extremely depressing when you consider that you should be able to go straight from Flare to FrameMaker, apply a template, and output to PDF, without ever having to do anything more than click a few buttons in Flare. I think that's what's known as a pipe dream. Come on MadCap! Make it happen! Or at least make it possible. Anyhow, MIF seems to be the only way to do this, since the FrameMaker output from Flare isn't a structured document, meaning you can't process it with XSL in FrameMaker. Here's some details on MIF: http://www.stc-siliconvalley.org/newsletter/2002_1... And here's a link to an evaluation download for Mif2Go - an application that allows you to output a whole bookful of files to MIF from within FrameMaker: http://www.omsys.com/dcl/download.htm

---

Update: After writing this post I realised that I was taking the wrong approach to outputting from Flare to FrameMaker. The reason the a elements were indistinguishable was because all of my topics contain the following references: Following the instructions in Flare's help, I was defining styles in Flare's style editor and associating formatting with a "print" media. However, this was all happening in the main memex.css file that is included in each of these referenced files. Basically, the idea is that I set up all my styles in memex.css, then include this in MemexScreen.css and MemexPrint.css and add to these files any alternative formatting that, because it comes after the included file, overrides the main memex.css file. However, the Flare style editor wasn't making it clear that all of my styling, including the "print" media stuff was going in the memex.css file, when the print-only stuff needed to go in the MemexPrint.css file. Once I worked out this, the classes I applied to the a element got transmogrified into FrameMaker character formats, as I'd originally expected.This finally opened my eyes to the fact that I needed to apply this principal to all styling for my printed output. In fact what I did was, as a test, I just copied all of the styles from the main memex.css file into the MemexPrint.css file. When I then built the FrameMaker output, lo and behold it came out looking very like the WebHelp output. This wasn't actually what I wanted, but it proved the principal that the way to get the single sourcing to work from Flare to FrameMaker is to do all your styling in Flare. See: Hold off on the MIF for more on this.

XMetaL have been doing a lot of work on DITA over the last few months. I'm still waiting to hear what Madcap are doing about putting DITA support into Flare. But in the meanwhile, Adobe have surprised a lot of people (me included) by announcing and - more importantly - demonstrating their FrameMaker DITA Application Pack, which adds a DITA menu to FrameMaker 7.2. To date this hasn't yet been released, but it's due for a beta release this month (which I guess means by the end of this month). It consists of two DLLs, an EDD file, a DTD for DITA, read/write rules, structure files and documentation (including online help created using the application pack). The demo of the application pack (by Adobe's FrameMaker evangalist, RJ Jacquez) is a Macromedia Breeze webinar. You can access it at: www.adobe.com/cfusion/event/index.cfm?event=list&loc=en_us&type=ondemand_seminar&product=FrameMaker Unfortunately, the picture and the sound on the webinar get out of sync and it's a little difficult to follow, but the demo is excellent and shows that Adobe are putting a serious effort into making FrameMaker a DITA authoring tool. I assume (and I hope) this is stage 1 in an effort that includes integration with RoboHelp, so that you can open your DITA source in either FrameMaker or RoboHelp, edit it and output it to Help or PDF as required. Once that's done the RoboHelp/FrameMaker combination will serious shore up the churn from RoboHelp to Flare (which I'm part of, being a recent Flare convert). What the demo shows is full working use of DITA (with the exception of the Ant Build menu option, which he admits they haven't got working yet). And the fact that Adobe are eating their own dog food and currently using this to produce their own documentation demonstrates that they're taking FrameMaker seriously again as a live product. I have done so much work in the mxDocBook EDD that I've created (and continue to tweak) that I can see they've done a great deal of work to get to where they are. The thing that amazed me with FrameMaker 7.0 was that Adobe didn't supply a working demo EDD and templates to show you what you could do with Structured FrameMaker - you had to start from scratch and do it all yourself, and let me tell you that involved a large number of man hours to get to a state where you could just write the documents! Now it looks like the Application Pack will provide all of that missing stuff for DITA - making a switch from DocBook to DITA more enticing than ever. More good news is that the Application Pack is promised as a free download for registered FrameMaker 7.2 users. Madcap's Frame-compatible Flare is due out in September. It'll be interesting to see what they come up with to stop Frame/RoboHelp users from sitting tight and waiting for next year's version of RoboHelp. Read the rest of this entry »

I've published a transcription of the part of my most recent podcast where I described my day at a FrameMaker event organised by Mekon: www.itauthor.com/authtools/framemaker/frameday

In FrameMaker 7.1, when you save documents to DocBook XML, the scaling on images gets lost, without the following workaround.

For example, this afternoon I was in the middle of writing a document and I added a mediaobject element, whose imagedata element referenced an EPS image file I'd created in Illustrator. I sized and positioned the image like I wanted it, within an anchored frame. Here's a screenshot of how it looked (note - the image you get in FrameMaker when you insert an EPS is a low definition TIFF that allows you to size/place the image):

However, when I saved and close the FrameMaker file and then reopened it, this is what I got:

The sizing details are lost. Here's what was in the XML:

<para><mediaobject><imageobject>
<imagedata width = "5.281in" depth = "1.533in" align = "left"
    entityref = "imagedata2" angle = "0.000"
    cropped = "1" float = "0" nsoffset = "0.000in" position = "below"
    xoffset = "0.674in" yoffset = "0.000in"/></imageobject></mediaobject></para>

It looks like the width and depth of the image are recorded, but actually these are the dimensions of the anchored frame.

Thanks to Steve Whitlach for providing the remedy:
www.getnet.com/~swhitlat/DocBook/Frame_Project_Readme.html

The trick is to map FrameMaker's "import size" property to a DocBook element. As usual the handy role element is the obvious choice. So, we need to add the following to the read-write rule for the imagedata element:

attribute "role" is fm property import size;

The "imagedata" section of my read-write rules file looks like this:

element "imagedata"
{
  is fm graphic element "ImageData";
  writer anchored frame 
  {
    specify size in cm;
    export to file "$(docname).eps" as "EPS";
  }
  attribute "fileref" is fm property file;
  attribute "entityref" 
  {
    is fm property entity;
    is fm attribute;
  }
  attribute "align" 
  {
    is fm property alignment;
    value "left" is fm property value align left;
    value "center" is fm property value align center;
    value "right" is fm property value align right;
    value "inside" is fm property value align inside;
    value "outside" is fm property value align outside;
  }
  attribute "angle" is fm property angle;
  attribute "bloffset" is fm property baseline offset;
  attribute "cropped" is fm property cropped;
  attribute "float" is fm property floating;
  attribute "depth" is fm property height;
  attribute "nsoffset" is fm property near-side offset;
  attribute "position" is fm property position;
  attribute "width" is fm property width;  
  attribute "dpi" is fm property dpi;
  attribute "xoffset" is fm property horizontal offset;
  attribute "yoffset" is fm property vertical offset;
  attribute "role" is fm property import size;
}

This gives us the following XML:

<para><mediaobject><imageobject>
<imagedata width = "5.281in" depth = "1.533in" align = "left"
    entityref = "imagedata2" role = "3.933in 1.392in" angle = "0.000"
    cropped = "1" float = "0" nsoffset = "0.000in" position = "below"
    xoffset = "0.674in" yoffset = "0.000in"/></imageobject></mediaobject></para>

Now the image dimensions are recorded as:

role = "3.933in 1.392in"

It's useful to add "live" email addresses to the PDF documents you create in FrameMaker. For example, let's suppose you want to make "support@yourdomain.com" a link that, when clicked in the PDF will open up a new email in the default email client. Here's how it's done:

1. Insert "support@yourdomain.com" in the text.
2. Select it.
3. Wrap it in the email element.
4. Click inside this element and do Esc-h-S to select the contents of the element.
5. Choose Hypertext.
6. In the text box, enter:

   message URL mailto:support@yourdomain.com

   or:

   message URL mailto:support@yourdomain.com?Subject=Some%20appropriate%20subject%20line

   if you want to specify a particular Subject in the email.

   Note: you can do everything with the final part of the command (after "URL") that you could do by entering the command directly into the address bar of a browser.

   For example, try pasting the following into your browser's address bar and hitting Return:

   mailto:support@yourdomain.com?subject=Support%20email%20(TEST)&cc=documentation@yourdomain.com&From=him&Body=%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A----------------------------------------%0D%0AThis%20email%20was%20%22auto-generated%22%20by:%0D%0AAlistair%20Christie

7. Click New Hypertext Marker.
8. Close the Hypertext dialog box.
9. Test the link by Ctrl-Alt-clicking it.