ITauthor

I use dual monitors. This is particularly good for Structured FrameMaker, where you can have the WYSIWYG view on the main monitor and the Structure View and the Element Catalog on the other monitor.

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.

This is just to remind myself how to do this - because it's not spelt out in any documentation I know about and it took me a while to figure it out from the FrameMaker Structure Application Developer's Guide. 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.

As I've mentioned before in this blog, I now write most of my documentation in structured FrameMaker 7.1 - roundtripping to/from XML, using a paired-down version of the xDocBook DTD. 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.

When you save an XML file in FrameMaker 7.1, you occasionally get a message that tells you that entities such as "epsi" or "gif" or "png" have been referenced but never declared. 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.

The problem I usually work at the office, but occasionally work from home. At the office I can browse to any networked server in Windows (e.g. in Windows Explorer) by entering an address like \\networkedserver. When I'm working from home, I log on to my work network via an SSH session. This works fine, but one drawback is that, because it's not a VPN session my home PC is not part of the work network, so although I can access machines from a command line, using SSH, or upload/download files using WinSCP, addresses like \\networkedserver don't work because (unless "networkedserver" happens to be one of my own machines on my own home network). 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.