The example Microsoft gives is a document with three sections in it but the PDF that you generate ends up containing Section 1 followed by Section 3.

You might have encountered this problem if you’re a FrameMaker user and assumed it was an Adobe issue. It wasn’t, it was a Windows issue.

Here's the hotfix:
http://support.microsoft.com/?id=952909

As it happened, the only thing that used Times New Roman in the template I was using was page number in the index. These came out with hash marks followed by numbers that were completely different from the numbers in the original index:

I went into Control Panel > Fonts and deleted the Times New Roman fonts, then downloaded new versions from typedfont.com.

Note: If you’re using typedfont.com you might not, at first sight, notice the download link. It’s a little link halfway down the page, just above the font table:

However, after installing the new fonts (in Vista: right-click the font file and choose Install), the problem remained.

The problem is that when there’s a font problem the printer’s Font Substitution Table gets modified, telling the driver to use another font instead of the font that has a problem. You can repair the font, but the Font Substitution Table doesn’t get modified back to remove the substitution. You’ve got to do that yourself.

To remove the font substitution for a printer (in my case the Adobe PDF “printer”):

1. Go to Control Panel > Printers.
2. Right-click the affected printer and choose Properties.
3. In the Properties dialog box, go to the Device Settings tab.
4. Expand the section headed Font Substitution Table:

     

5. Find the affected font.
6. Click the substituted font and change the setting back to <Don’t Substitute>:

   

7. Click OK.
8. While you’re about it – for good measure – go to the General tab.
9. Click Printing Preferences.
10. In the Printing Preferences dialog box, go to the Paper/Quality tab.
11. Click Advanced:

    

12. In the Advance Options dialog box, change the TrueType Font setting to Download as Softfont:

    

13. Change the PostScript Output Option to Optimize for Portability.
14. Change the TrueType Font Download Option to Outline.
15. Click OK on all the open dialog boxes.

If you were having the same problem I was having, it will now be fixed.

http://www.pcpro.co.uk/reviews/137286/adobe-framemaker-8.html

For the most part it sounds like users of 7.2 (like myself) wouldn't notice much of a difference. However, the thing that intrigues me is the ability to incorporate Flash movies into documents. When I'd heard of this, months ago, I'd thought: okay but what's the point in that? However, Tom Arah's description suddenly reveals how great that might be:

... this hardly seems like rich media, since the 3D models and vector movies are represented in the FrameMaker document as static bitmaps. Everything changes, though, when you export your document to PDF. Suddenly, when viewed within Adobe Reader, the embedded Flash movie and 3D model spring into interactive life.

Now, suddenly, I can imagine how useful it might be to have a PDF that was designed purely for online viewing and was, perhaps, quite a small document but with a series of inbuilt Flash demos. Anything that's show rather than tell has huge appeal, and this could really transform how we think of PDFs.
 
Screenshot taken from PC Pro website.  © Copyright Dennis Publishing Limited

The trouble is that the application pack makes DITA possible, but it doesn't make it a realistic option for most folk because you still need to do a lot of work before you can actually get to the stage where you can hope to produce professional quality documentation with it. If you're like me you just don't have the time to dedicate to this. However, there are efforts to bring this to you and reduce the amount of setup work you need to do before you can start using DITA to produce documentation in FrameMaker.

One such effort  is DITA-FMx. I haven't  tried it out yet, but you can download it for free from here:    

http://www.leximation.com/dita-fmx/

Check out the  online help here:

http://docs.leximation.com/dita-fmx/0.01/  

It's probably worth a look, but I'm still kind of hanging on for Madcap to get their act together on DITA. Flare seems like an obvious tool to use with DITA, but it wasn't in the recently released DITA 3.0 and I haven't heard any firm plans for when it's going to get added. Adobe have stolen a march on Madcap here, but I suspect Madcap's DITA effort will be worth waiting for - so I'm holding back spending time doing DITA in FrameMaker until I see what Madcap come up with, or until I get fed up waiting.

Paragraphs should never be hyphenated unless they are justified. Hyphenating text that's aligned left looks daft. So the result is that you have to sort out this problem in the FrameMaker files produced by Flare before you can output to PDF. A tedious process, but here's the best way to do it. The same tip applies to any change you want to make to each and every format in a FrameMaker file:

1. Open the FrameMaker file.
2. Choose Format > Paragraph > Designer.
3. In the Paragraph Designer dialog box, click the Commands button.
4. Choose Set Window to As Is.
5. Now make the format change you want to make. In our case, click the Advanced tab and clear the Hyphenate check box.
6. Click the Commands button again.
7. This time choose Global Update Options.
8. In the Global Update Options dialog box, choose whether you want to apply changes from multiple tabs in the Paragraph Designer dialog box, or just the currently displayed tab. In our case, we've only made one change so it doesn't matter which of these options you choose.
9. In the Update Paragraph Formats section, choose All Paragraphs and Catalog Entries.
10. Click Update.
11. Save the document.

That's it. Hyphenation is removed from all formats in the document.

You can now use this document as a template for the other document. To do this:

1. In the book window, select all chapter documents.
2. Choose File > Import > Formats.
3. In the Import from Document field, choose the document you just modified.
4. Select all of the check boxes in the Import Formats dialog box.
5. Click Import.

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

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:

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.

Screenshots

1. The Application Pack DLLs add a "DITA" menu to FrameMaker:

2. There is an Options dialog box for the DITA structure applications:

3. Here a topic reference has been added to the ditamap and the map file is now being updated. In screenshot 4 you'll see that the topic title has been updated in the ditamap:

4. A new topic is being added. The file that's created will be called GettingStarted.dita and a reference to this file will be automatically placed in the ditamap at the point shown by the Structure View on the right side of the screenshot:

5. This is the online help currently being written for the Application Pack (aka the DITA+FM Plugin). At the bottom of the ditamap you'll see a reftable that creates topic references from several topics to a reference page:

6. One of the best things about DITA is that it's built for reuse of small sections of text as well as whole topics. To reuse a section it must have a unique ID. The FrameMaker DITA Application gives you a menu option that will automatically assign an ID that is guaranteed to be unique for this project to currently selected section. The DITA options allow you to specify an ID prefix (see screenshot 2) which means you can give each project a unique prefix, ensuring uniqueness of IDs across projects:

7. Now you're in another topic. You've given the section you want to reuse an ID, so you can now insert it into the selected point in the current topic (provided it's valid here - and, in this case, you can see from the Elements catalogue, bottom right, that it is valid to add a section element here):

8. In the Reference Manager you choose a source file and select "section" as the element you want to link by reference. The right pane shows all section elements in the chosen file that have IDs:

9. If you want, you can display all elements and assign an ID here, so that you can add a reference. Clicking insert adds the reference to the section in the other file. The section is displayed in the current file but is only here by reference. The actual text remains in the original file:

www.itauthor.com/authtools/framemaker/frameday

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"

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.

The trouble is that I often work from home and work using Windows Remote Desktop, which doesn't export the display for the remote second monitor to my second monitor at home. Most windows behave sensibly. If they appear in the remote second monitor they're displayed on the main local monitor. The exception is FrameMaker's Structure View window, which stays put, so if I've forgotten to move it onto the main monitor before I leave work, I can't see it when I'm working from home.

The solution is to use keyboard shortcuts.

1. In FrameMaker, press the following sequence of keys: Esc-F-i-v. This passes the focus to the Structure View window.

2. Press Alt+spacebar to access the window control functions.

3. Press m to move the window.

4. Hold down the appropriate cursor arrow key until the window comes into view. For example, my second monitor is to the left of my main monitor, so I hold down the right arrow until I see the window.

5. Press Enter.

Note: Alt+spacebar is a Windows shortcut that works throughout Windows.

On the title verso of my manuals I have a code that tells you the last time the document was modified. I don't want to type this in automatically. Before I started using XML source files this was easy - just use a variable. In an XML-based system it's not so easy because, by default, if you add a variable like Current Date (Long) the date gets written out as text in the XML file - e.g. February 25, 2005. When you open the document up again in FrameMaker, the date is now hard-coded and you need to change it manually.

What you need to do is use a read/write rule to tell FrameMaker that the FrameMaker "Date" element should be a system variable and when it's written to XML it should be called "date". To do this, add this to your rules:

element "date"
{
  is fm system variable element "Date";
}

You then need to edit your EDD file to tell FrameMaker which system variable you want to use. Here is what I used in my EDD:

Which looks like this in structure view:

Finally, I had to modify my DTD to specify that this element is an empty element. If you don't do this, the date will get written to the XML file as an opening tag with no closing tag, which obviously causes a validation error when you save the file. What you want is an empty element .

My DTD now contains the following description of a date element:

<!ENTITY % date.element "INCLUDE">
<![%date.element;[
<!ELEMENT date EMPTY>
<!--end of date.element-->]]>

This now works nicely. When you add a Date element within a Revision element in FrameMaker, the Modification Date (Long) system variable is automatically added, and this survives round-tripping. I've modified this variable in my template so that it shows up as a code rather than a conventional date. If you enter a Date element elsewhere, you can select an option for the Role attribute value and this gives you one of the other available date variables.

What this means is that my source files are XML text files, rather than binary FrameMaker files. This gives me the potential benefits of XML source (e.g. CVS) plus the undoubted benefits of structured FrameMaker in a graphical interface that shows you more-or-less what you get when you print out the file or produce a PDF.

So far so good - except that getting to this state of play has meant travelling a long and tortuous road. The FrameMaker EDD that controls most of this process has taken me a huge amount of time over the past year or so to develop: a slow and protracted iterative process.

I would like to make this EDD freely available on the Web, which would immediately make structured FrameMaker a much more viable prospect than it is at present. Right now, if you buy FrameMaker 7.1, you're going to have to dedicate an awful lot of time to developing your structured application before it starts to save you time and make your documentation life easier. So, I'd like to offer some gain without pain. But it remains to be seen whether my company, in whose time this EDD has (mostly) been developed will allow me to release it. In reality it has cost my company a large chunk of my reasonably generous salary to create this EDD, so it's perhaps not something that should be given away for free. But then we're not going to make it available at a price either, so putting it on this web site wouldn't lose the company any money. As you can tell, I'm still mulling this over myself.

However, besides all that, the reason for this post was to gripe about Adobe's commitment to FrameMaker. Here we have a product that has undoubted XML capabilities now, but they just haven't worked the problem through and produced a 100% functional solution.

Last week I finally got to the end of the writing of the first manual I have written using FrameMaker 7.1 to roundtrip XML. The previous documents I wrote using structured FrameMaker and mxDocBook were saved as FrameMaker-format files, because of the problems in FrameMaker 7.0. But, right at the end of the process, when I came to pull the book together I discovered the following about FrameMaker 7.1.

You can only perform book-wide operations, such as automatic page numbering, if your book contains FrameMaker format files. My book contained XML files, which results in the Format > Document > Numbering option being greyed out.

The solution is, seemingly, simple. After you've finished writing all of the chapters and other book components, save the files in FrameMaker format and create a new book containing these documents. Solution? Not quite.

The problem with this workaround is that if you have external cross-references between different chapters in your manual, these cross-references contain a file name such as introduction.xml. When you save the files as FrameMaker-format (.fm) files, these cross-references still contain the same file names, resulting in unresolvable links, or links that point to the wrong file (i.e. an XML file rather than the FrameMaker version of it).

FrameMaker 7.1 should (according to its Structure Developer's Guide, pp. 326–7) allow you to add an ExternalXRef element to the appropriate XMLApplication element in your structapps.fm file and then insert a child element called TryAlternativeExtensions with the value Enable. This tells FrameMaker that if it can't find the file whatever.xml to look for the file whatever.fm and use that instead – and vice versa. The trouble is that it seems that someone has forgotten to update the in-built DTD for the structapps.fm file, and the result is there's no way to add an element called ExternalXRef. Presumably this will be fixed in FrameMaker 7.2.

The consequence of this is that you have to change all the cross-references to whatever.xml to whatever.fm before you save the files as FrameMaker-format files, otherwise you'll have broken links (or links to the .xml files rather than the .fm files in the book). I've written a shell script called changerefs that saves copies of the .xml files with all the .xml cross-references changed to point to .fm files. I'll post this script to this web site sometime soon, along with the methodology for using it.

To cut a long story short, I've come up with a usable workaround to this bug in FrameMaker, but it pisses me off that Adobe realised 7.0 was a crock of shit, but didn't manage to fix it properly.

Am I the only person using FrameMaker 7.1 to roundtrip to/from XML source files? I don't think so, but I'm absolutely sure you other people out there doing this have suffered pain at the bleeding edge of FrameMaker, just like I have.

If this happens, close the FrameMaker file and open the XML source file in a text editor. At the top of the file you will see entity declarations such as:

<!ENTITY imagedata25 SYSTEM "images/dependencies.eps" NDATA epsi>
<!ENTITY imagedata26 SYSTEM "images/directory-tree.eps" NDATA epsi>
<!ENTITY imagedata27 SYSTEM "images/progress-90.eps" NDATA epsi>
<!ENTITY imagedata1 SYSTEM "images/WinZip-SFU.gif" NDATA gif>
<!ENTITY imagedata2 SYSTEM "images/WinZip-SFU.gif" NDATA gif>
<!ENTITY imagedata3 SYSTEM "images/WinZip-SFU.gif" NDATA gif>

Each NDATA type ("epsi", "gif" etc.) should have a NOTATION declaration earlier in the file. For example:

<!NOTATION epsi PUBLIC "">
<!NOTATION gif PUBLIC "">
<!NOTATION png PUBLIC "">

If these lines are missing, add them back in and save the file. Open the file in FrameMaker and save it again. This time you should not see the message.

If you do, something a little more serious has occurred. Sometimes FrameMaker gets confused and adds hidden metadata to the file. If you follow the above instructions and you still get the "referenced but never declared" message, when you open the file in a text editor you will see that FrameMaker has removed the NOTATION lines you added.

The workaround to this problem is to copy everything from the opening <?xml version="1.0" encoding="UTF-8"?> to the end of the file and paste it into a new file. Remove the old file and save the new one in its place. Don't just copy the whole file and put everything in a new file as you may just transfer the hidden problem from the old file to the new file. Sometimes you'll notice that there are two or three weird characters at the start of the XML file. This is an indication that FrameMaker is having export problems and you should write the remainder of the document to a new file, without these junk characters.

Add the NOTATION lines back in, save the file, then try opening and saving it in FrameMaker again.

How this affects my work
The only hassle this causes is when I work on structured FrameMaker files from home. I need to copy the source XML files from the server at work to my own machine (using WinSCP) and then modify them the path to the DTD, using a text editor. Once I've finished working on them in FrameMaker and I want to copy them back to the work server, I need to change the DTD reference back to one that works on my work network.

For example, at work the FrameMaker XML files I work with reference a DTD called mxDocBook.dtd. Let's say the path to this is //networkserver/mxDocBook/mxDocBook-DTD/mxDocBook.dtd. So the start of each XML file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter SYSTEM "//networkserver/mxDocBook/mxDocBook-DTD/mxDocBook.dtd" [
...

If I tried to open this file in FrameMaker on a computer on my home network I'd get an error message, because FrameMaker wouldn't be able to find the DTD file. So I have to change the identifier to something like:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter SYSTEM "file:///D:/work/mxDocBook/DTDfiles/mxDocBook.dtd" [
...

Changing each file back and forwards could get very tedious, but there's a solution.

The solution: the changedtd shell script
I wrote a shell script that you can use to automate this process. The script (called changedtd) contains variables called FINDTHIS, CHANGETOTHIS and FNAMEPATTERN. It looks for files in the current working directory that match the FNAMEPATTERN (typically *.xml) and performs a search/replace, searching for FINDTHIS and replacing it will CHANGETOTHIS.

If you want to use the script, copy it and edit the FINDTHIS and CHANGETHIS values to appropriate paths.

To run the shell script you obviously need a shell. I'd recommend installing Windows Services for UNIX 3.5 as the easiest way of getting a UNIX-like shell on a Windows machine.

You can download SFU 3.5 free of charge from:
www.microsoft.com/windows/sfu

Once you've got a shell, all you need to do is put the changedtd file in a directory that's in your PATH, and then, in a UNIX/SFU shell, browse to the directory containing the files you want to change and run the command: changedtd

View/download the script

• View the script
• To download the script, right-click this link and choose Save Target As or Save Link As.

Notes:
You might think it's a very long-winded script to do such a simple operation, but most of the verbosity of it comes from:
a) The parsing of the command line arguments. This allows you to run the script on a directory other than the current working directory and to recurse into child directories (if you dare).
b) The usage instructions, which you can read by running changedtd -h.
c) You could of course very easily change this script to do a search/replace with any text you like on any type of file, just by changing the values of FINDTHIS, CHANGETOTHIS and FNAMEPATTERN.

However, a good solution is to install KatMouse by Eduard Hiti:

http://eduard.hiti.bei.t-online.de/

This changes the scrolling functionality, making the scroll wheel apply to whichever application happens to be under the mouse pointer - including FrameMaker windows. This sounds odd, but once you start using it it's really useful - especially in structured FrameMaker, where you can scroll the Structure View window without losing the focus in the document window. When I'm using FrameMaker I have the Structure View window permanently displayed on a second monitor, so I find this behaviour particularly useful.

I've had a look today for ways to remedy this. The reason for doing this is that the XML may need to be edited in its raw state occasionally, and this would be much easier if it was indented to display the element hierarchy.

I tried:

• Tidy and TidyUI - but these didn't recognize entities such as / and just deleted them. TidyUI also removed spacing from within a literallayout element, which is just plain dumb
• xmllint and xsltlint - but in researching possible tools I read warnings about xmllint and so I wasn't confident about using them
• xmlformat - I had most success with this. I tried the Perl version, which worked fine from a DOS command console in Windows. It produced nicely formatted XML, without the problems TidyUI had, but on import into FrameMaker, some of the formatting spaces showed up in the FrameMaker text (e.g. as spacing to the left of subheadings)

I suppose the solution, if you really wanted to do this, would be to format the XML with xmlformat, work on the formatted XML, then remove the formatting before opening the file in FrameMaker. xmlformat allows you to create a configuration file specifying how you want to format the XML, which would allow you to have a "prettyprinted" config file and a "noformatting" config file to remove the spacing.

One of the things I like about xmlformat is that it appears to be very well documented.

Get xmlformat from:
http://www.kitebird.com/software/xmlformat/

I never encountered this error in FrameMaker 7.0, but now, in 7.1, it has returned. For the third time this week, the dreaded error has appeared:

It occurs with no warning and with no apparent reason (i.e. it doesn't happen when you do something in particular). The FrameLog text file just contains a lot of stack information that sheds no light on the problem for a non-Frame-programmer. The error message suggests emailing the log file to Adobe. But do the handful of underpaid coders out in India really want to get emailed this information. From my own experience of software development, I doubt it.

   element "literallayout"
   {
      is fm element "LiteralLayout";
      preserve line breaks;
   }

didn't work.

Here's the rant I discovered in my read/write rules file from FrameMaker 7.0:

/*** Don't use "preserve line breaks;".
It doesn't work, because it inserts 'xml:space = "preserve"' in the XML, which is invalid DocBook. Also, it adds this attribute to any child elements, but, despite this, doesn't actually preserve the line breaks into the XML unless you add "preserve line breaks" to every element that might come within LiteralLayout (most elements). This would result in almost every tag in your XML having 'xml:space = "preserve"', which is nonsense!!! It also doesn't preserve FM carriage returns (which you'll have if you've copied text into an element within LiteralLayout. It only preserves forced line breaks (i.e. those you've added manually using Shift+Return). All in all, it's totally useless!!! ***/

It all now seems to work fine in 7.1. The comment about adding "preserve line breaks" to every element that might come within LiteralLayout was a red herring because LiteralLayout can only contain inline elements, and will rarely contain any of those anyway.

The only thing you need to remember is to use a line break (Shift+Return) not a new paragraph (Return) to start a new line, and if you want multiple spaces you should switch off smart spaces (Format > Document > Text Options) or use en spaces (Alt+Ctrl+space).

I did a great deal of work last year trying to get FrameMaker 7.0 to do three things:

a) Roundtrip without losing anything along the way.
b) Store documents as XML that validates against the xDocBook DTD.
c) Store documents as XML, that uses standard DocBook elements for things like index references and cross-references.

Frame 7.0 failed on all accounts, but now (from a brief tryout this afternoon) version 7.1 seems to do part a) successfully, and will, I'm pretty sure, do b) too.

I don't think it will ever do part c) successfully, because it uses processing instructions like for cross-references etc. However, I'm sure I could use XSLT to transform FrameMaker XML output into standard DocBook XML, should the need arise. More useful, probably, would be an XSL transformation to turn DocBook into FrameMaker XML for importing into FrameMaker, as this would allow programmers to write documentation in DocBook markup, including cross-refs and index refs, using standard DocBook elements, and I could (after transforming it) pull their work straight into Frame for editing, polishing and output to PDF.

Two bug-bears of mine with FrameMaker 7.0 were that I had to invent a very contrived way of doing conditional text, and I couldn't get literal text to output properly to XML at all.

Fixing conditional text was Adobe's main selling point of 7.1, and formed the bedrock of my case for spending company money on buying the upgrade. However, I still need to see whether literal text survives the roundtrip.

But I was very pleasantly surprised this afternoon when I took a chapter from the structured manual I wrote last year - created in FrameMaker 7.0 - saved it to XML, using the Save As option, then opened the resulting XML document and it came back looking just like it had when I opened the original .fm file.

Another good step closer to my goal of storing documenation as XML source, so that we can maintain it in a CVS repository, and so that non-FrameMaker users can make use of it and can contribute documentation that we can use within FrameMaker.

Frame founder Charles Corfield is now a director of, and investor in, several Silicon Valley startups.

Read a profile of Steve Kirsch at:
www.spectrum.ieee.org/publicfeature/aug00/prof.html

Seybold Report from 1996:
Adobe acquires Frame, plans full takeover
www.seyboldreports.com/SRPS/free/0ps24/P2421023.htm

XML Brawn

The new version also offers improved cross-referencing between XML documents. With Version 7.0, cross-referencing was supported only within the same document. With 7.1, cross-references between XML files now work across FrameMaker documents as well.

Read the whole article.

This sounds promising. I've put in my first tentative bid for an upgrade. We'll see how that goes. The promise of making conditional text round-trippable is attractive, but I'd like to know how it's implemented. Round tripping between FrameMaker and XML of some description is not the same thing as round tripping between Frame and DocBook, and my experience of trying to get this working in 7.0 leads me to be extremely cautious.

Improved XML handlingâ € ”When you open an XML document in FrameMaker
7.1, the software retains the original XML format and â € œ.xmlâ €  file extension when saving. Cross-references to external XML and FrameMaker documents are retained when saving as XML. FrameMaker now provides the ability to use conditional text functionality when working with XML documents.

Sounds promising. Conditional text was one of the things I had to give up on fairly early on when I was working on the DocBook round-tripping idea. There were lots of other things too, though, like links and the things that finally broke the camel's back: LiteralLayout elements not preserving line breaks!

I persuaded my employers to upgrade from Frame 5.5 to 7.0 at the end of last year. I don't think they're going to upgrade to 7.1 without some convincing arguments. My convincing arguments for buying 7.0 was that it would allow us to store all our documentation as DocBook XML source – allowing us to use CVS and enabling non-Frame DocBook-saavy developers to write documents and output them to look like the documents produced by the technical authors – while still allowing the technical authors all the benefits of writing in FrameMaker. Didn't work out though, and it cost me hours and hours of work.

I am, however, writing my documentation in Structured FrameMaker now, which is a big improvement on what I was doing in Frame 5.5, but I'm still waiting for the payback from all the time I spent writing read-write rules and learning all about DocBook.

I suspect Frame 7.1 has a few little tweaks that make its support for general XML a little bit better. Nothing in the little bit of information Adobe provide about the changes from 7.0 to 7.1 make me think this is the solution I was originally hoping 7.0 was going to deliver. I think I'll have to wait for 8.1 before I get that. And everything I hear about Adobe's attitude to FrameMaker suggests I shouldn't hold my breath. Apparently, FrameMaker only continues to be developed at all because Boeing are big Frame users and pay Adobe big bucks every year to keep it going and add enhancements to suit their way of working.