Can't get TOC to use right-align page numbers

Report · Jun 17, 2011

Hi,

I am using Framemaker 7.2 (I have used Framemaker 8 inthe past and will try to get company to upgrade) and am frustrated by Framemaker's clutzy method for creating a TOC. (Why haven't they copied Word's simple idea of field codes and detailed TOC dialog boxes?) My client uses one file for each manual but no one here knows how the previous tech writer built the TOC for each manual.

I used Special->Table of Contents from the single manual file and clicked No to create a standalone file. I imported all the heading TOC tags (I forget how I got them) into the TOC file, then did Update Book (I had to create a book file with the TOC file and the one file containing the manual). When I opened the TOC file it was formatted with the correct paragraph tags (font, point size, and indenting) but all entries failed to use the right aligned page number tab. I had to manually insert each tab.

Finally I copied the contents of the TOC file into the front of my single manual file.

This is tedious. And it's not going to help me convince the manager to upgrade Frame since I don't know if making a TOC is any easier with newer versions.

Can someone unscrable this TOC mess?

Michael F

Report · Jun 17, 2011

Sorry, why wouldn't you use the separate TOC doc within the book?

Report · Jun 17, 2011

Mchael F wrote:
Hi,
I am using Framemaker 7.2 (I have used Framemaker 8 inthe past and will try to get company to upgrade) and am frustrated by Framemaker's clutzy method for creating a TOC. (Why haven't they copied Word's simple idea of field codes and detailed TOC dialog boxes?) My client uses one file for each manual but no one here knows how the previous tech writer built the TOC for each manual.
I used Special->Table of Contents from the single manual file and clicked No to create a standalone file. I imported all the heading TOC tags (I forget how I got them) into the TOC file, then did Update Book (I had to create a book file with the TOC file and the one file containing the manual). When I opened the TOC file it was formatted with the correct paragraph tags (font, point size, and indenting) but all entries failed to use the right aligned page number tab. I had to manually insert each tab.
Finally I copied the contents of the TOC file into the front of my single manual file.
This is tedious. And it's not going to help me convince the manager to upgrade Frame since I don't know if making a TOC is any easier with newer versions.
Can someone unscrable this TOC mess?
Michael F

Search Google for terms like "FrameMaker generate toc tutorial" and similar phrases without quotes for useful info that clarifies the TOC setup process, and simplifies the ongoing regenerating of TOCs, as document contents change.

HTH

Regards,

Peter

_______________________

Peter Gold

KnowHow ProServices

Report · Jun 17, 2011

Firstly, unless there is some compelling reason to in-line the TOC, do it as a separate xyzzyTOC.fm file in the book.

I had to manually insert each tab.

In the TOC Reference page "openObjectId" of the xyzzyTOC.fm file, merely insert the tab in each line. These objects control TOC formatting.

Once set up, you almost never need to touch the TOC.fm file again. We clone new books from old without ever touching the TOC ref page.

We only edit ours for copyright date and history, although you might also need to edit for publication/edition history if you put that there.

Report · Jun 17, 2011

Jeff, it sounds like your manuals were originally set up as a single FM document that probably contains content divided by paragraph tags and headings to simulate having multiple "chapters", is that correct?

If so, that's the reason that the old "TOC" was created in what seems like a "clutzy" manner, because you're constrained by trying to contain everything (ordinary content and generated content such as the TOC) in a single file. The only way to have a TOC within a single file like you have is to use the convoluted process of creating the TOC as a separate file and then copy / pasting it back into the single chapter. The big downside is that when the manual content changes you have to re-do the entire process again, as you've found.

For most users this is indeed a roundabout, time-consuming, and error-prone way to get a TOC. And it's usually a sign that the files were created by somebody who didn't have time to learn any of the basics about how FM uses books and chapters, so they just put everything into a single file, similar to what most folks do with Word docs.

The result that you've achieved, getting as far as you did, is as good as it will get if the docs stay in their current single file incarnation (bravo for getting that far!)

The better way is to reconfigure your manuals so that you have multiple FM files, one for each chapter, one for the cover, one for the frontmatter, etc. Add each of the chapters to a new FM book file. Save the book file. Then with the book file and all the chapters open, use Add > Table of Contents to add a TOC to the book, placing it in the correct position within your book file. Then Edit > Update to generate the TOC content.

With a book file structure and the TOC correctly created this way, all you will need to do after editing will be to have the files open and do Edit > Update to refresh the TOC, automagically creating new entries if any are needed, refreshing the page numbers, etc.

All of these steps are covered in several online resources; there are many tutorials that go over these basics. Once you "get" how books work in FM you'll undoubtedly impress the manager by being able to add a new "list of figures" or an index to your manuals too 🙂

Sheila

Report · Jun 17, 2011

Sheila, you mean @Mchael F, not me, right?

Report · Jun 17, 2011

ooops, sorry Jeff, I did mean Michael F. Thx!

Report · Jun 20, 2011

Thanks all for your helpful suggestions. The note from Error7103 was a little cryptic but I found the reference frame with the TOC keywords and saw how the paragraph tags mimicked the headings in the file (with TOC suffixes). I had searched the online help but don't remember coming across mention that Framemaker creates this frame and puts it in the TOC file to control formatting of TOC entries.

Since I was not confident with the TOC I had last week, I trashed it, went back to the main file, and used Special->Table of Contents to generate a new TOC file. After an Update Book, I opened the TOC file and voila it was formatted with the correct fonts, point sizes, and right justified page numbers (with leader lines).

I would also like to thank Sheila for the clear advice about structuring the manual into front matter, TOC, chapters, and such. I agree that my current method is tedious, since I have to generate an updated TOC and cut and paste it into the main file before creating the PDF file.

I used to use book files and multiple Frame files a few years ago at another company, but the current company stuffs their manuals into a database app. called Synergis Adept. You have to sign files in and out. I was told it was supposedly more difficult to manage multi-file books (not clear why), and they make it more confusing by requiring that each book be named with its part number and not the book title. (The part number file name and the book titles are searchable fields in the Adept UI.)

Does anyone have experience storing multiple file books in Synergis Adept (http://www.synergissoftware.com/)?

Also, is the UI for making a TOC and index any better in Frame V9 or 10?

I would like to have some talking points to convince the managers to allow me to use the multifile book method.

Thanks,

Michael F

Report · Jun 20, 2011

Michael,

I would like to have some talking points to convince the managers to allow me to use the multifile book method.

Would you be allowed to put all the files into a folder that is named with the part number and then zip the folder? This would result in a single file in the database.

The techniques for creating TOCs and indexes are the same in Fm 9 and, guessing, Fm 10.

Van

Report · Jun 20, 2011

You have to sign files in and out. I was told it was supposedly more difficult to manage multi-file books (not clear why), ...

This suggests that you have to check out/in the .book file, and all component .fm files, as separate objects. Since this would even nastier with a CAD model having a tree of subassemblies and components, I'm wondering if the CMS (content mgmt sys) doesn't have some way of doing batch check out, or if it might support directories as objects.

... requiring that each book be named with its part number and not the book title.

Pub numbers are generally easier to manage than titles, but not if you'll be obliged to pull a pub number for every book component file. Perhap's they'll let you use a -01.fm throught -99.fm pub number extension.

Van's suggestion of zipping would reduce the book to a single object, but it might break the search and index features of the CMS since a compressed .zip might be an impenetrable binary object to the CMS. Also, the auto-diff at check-in is likely to result in a huge difflog, as a single-character change could cause the entire zip file to be completely different than the previous one. This will annoy the admins when they have to keep adding disk space for you.

But I'm thinkin' that even in the CMS worst case, doing a book makes more sense.

Report · Jun 21, 2011

Hi,

I am going to develop a test case using the part number along with suffixes that makes sense like -fm, -toc, -ch1, so one book would look like

4500 Operator's Manual

50-1234-0.book

50-1234-0-FM.fm

50-1234-0-TOC.fm

.

50-1234-0-IX.fm

With Adept, I can search for either all or part of the book title (4500 operator*) or I can search for the part of the part number (50-1234*) and find all the files for that book. For sign out/sign in, I would have to select the range of files instead of one big file.

That might work. So I'll demonstrate it to my manager when he gets back from vacation.

Yours,

Michael F

Report · Jun 21, 2011

Do you use graphics in the books? If so, and based on your description of the checkout process, it sounds like they would be embedded into the FM document?

That can be a huge challenge to maintain if/when you need to replace graphics, as there is no longer any connection to the orig. graphic file name, no way to know where graphic xyz.jpg or logo.gif might have been used within that one book, let alone across multiple manuals.

If you were going to redesign your doc strategy you might want to consider having the graphics are referenced files rather than copied in, and maintaining a consistent location for the graphics (the most common being a subdirectory "/graphics" under where the .book and .fm files live). Having a consistent location like that means that the links to the graphics will continue to work no matter on what host or what directory structure the FM docs are being edited within.

Report · Jun 21, 2011

Do you use graphics in the books? If so, and based on your description of the checkout process, it sounds like they would be embedded into the FM document?

The CMS app supports batch publishing, so one solution might be to have it periodically (or on-demand) re-publish all images to read-only files in a common directory structure. Other apps, such as FM, would then import-by-ref from there. Only the CMS publisher would have write access to the tree.

That can be a huge challenge to maintain if/when you need to replace graphics, as there is no longer any connection to the orig. graphic file name, no way to know where graphic xyz.jpg or logo.gif might have been used ...

We put a visible image reference number below every called out image. A simple grep of *.pdf in our print shop dir finds every instance. If you take this approach, use a long or complex ID string. Our numbers are short, so the search gets a few false positives due to arbitrary binary data in PDF data structures appearing to be strings of 8-bit digit characters.

... within that one book, let alone across multiple manuals.

Worse, with copy-into, you are strongly motivated to update every where-used, even if it's an obsolete document. With import-by-reference, updating occurs only as it needs to (when the manual is intentionally updated due to the image change, or updated for any other reason).

Report · Jun 21, 2011

Error,

>We put a visible image reference number below every called out image. A simple grep of *.pdf in our print shop dir finds every instance. If you take this approach, use a long or complex ID string. Our numbers are short, so the search gets a few false positives due to arbitrary binary data in PDF data structures appearing to be strings of 8-bit digit characters.

That reminds me -- when I worked at DEC years ago, we had actual graphic designers to generate artwork. They used to put ID numbers in the lower right corner of their artwork (and probably used that number for the filename). When you needed a new copy, or needed them to modify one into something different, all you had to do was give them the ID number and a description of the graphic. That's another good idea to implement here.

Thanks.

Yours,

Michael F

Report · Jun 21, 2011

They used to put ID numbers in the lower right corner of their artwork (and probably used that number for the filename).

We sometimes do that as well. These numbers will only be searchable text if the imported object is EPS, PDF (or possibly SVG, haven't tried), and the text was left as text, and not converted to outlines (or raster).

When you needed a new copy, or needed them to modify one into something different, all you had to do was give them the ID number and a description of the graphic.

You will need at least a log file (with conflict locking) to track the numbers, descriptor, date, and contributor.

That's another good idea to implement here.

A caveat is that standard Frame has no means of capturing the filename of an imported object. You have to type the file name or number by hand when adding it to the caption or elsewhere nearby. So it can mismatch, particularly when cloning text with an anchored frame and then replacing the image. Don't worry, you'll only screw up when it matters.

_______

It would be nice have system variables or other means of automatically capturing import names, but a big problem is that a single anchor frame can contain an unlimited number of objects.

Report · Jun 21, 2011

Sheila,

Yes the book is full of graphics and -- with them all embedded -- the book is over 50 MB in size, which concerns me. I created several new graphics and placed them in a /graphics subfolder. I will have to see how they get stored in the library database. This is not the way I would like to work, but it will take some experimenting to see how it can be done so it's easily retrieved from the library. A few times I asked where an original graphic came from and could not get an answer other than it came from another manual.

And thanks for the tip about the TOC suffix. I removed the hyphen, updated the book, and checked a few headings. The TOC is in synch with the main file.

Yours,

Michael F

Report · Jun 21, 2011

Michael, in your proposed naming convention, the only issue I see might be the inclusion of the dash prior to the TOC name -- FM's default way to name a generated file being added to a book is to append the appropriate "xxx" to the book file name. Your book file ends in "0", so FM's default is "book name + extension", so your default would be 50-1234-0TOC.fm

While it's entirely possible for you to manually change the name and/or add the dash to the name when you create the TOC, it's a very easy thing to forget to do, as well, leading to nasty gotchas when trying to troubleshoot "stuff" such as why one type of link works and another one doesn't -- dashes are devilishly invisible at times.

Report · Jun 21, 2011

Mchael F wrote:
...
I used to use book files and multiple Frame files a few years ago at another company, but the current company stuffs their manuals into a database app. called Synergis Adept. You have to sign files in and out. I was told it was supposedly more difficult to manage multi-file books (not clear why), and they make it more confusing by requiring that each book be named with its part number and not the book title. (The part number file name and the book titles are searchable fields in the Adept UI.)
Does anyone have experience storing multiple file books in Synergis Adept (http://www.synergissoftware.com/)?
Also, is the UI for making a TOC and index any better in Frame V9 or 10?
I would like to have some talking points to convince the managers to allow me to use the multifile book method.
Thanks,
Michael F

Hi, Michael:

When I first trained and supported FrameMaker users, most were on UNIX systems. Technical writers at several large corporate clients taught me their strategies for working around content management tools that wouldn't accept FrameMaker books comprised of independent files. IIRC, the fundamental problem was that the systems couldn't cope with binary files, and the multiple-file books just intensified the difficulty. I recall from those days that they had the same problem you have - incorporating TOCs and chapter files into a single file for the CMS.

Two solutions I remember involved converting the book and all of its files into MIF, a pure text format, and/or outputting PostScript, also text, and manage them. This seems to be missing something; I think the undiscussed missing link might have been collecting the books .fm files into a compressed format that could be stored in the system, along with the text files. For revision, the MIF files were checked out, opened in FrameMaker, which restored them perfectly to binary files, and when editing was complete, the files were again converted to MIF. Probably new PostScript files were generated after each editing, and checked in, replacing the old ones, so that any print production (this was before Acrobat and PDF) was based on the latest blessed PostScript files.

The UNIX versions of FrameMaker included fmbatch, a command-line utility that could also be run with scripts, to manage the conversion of directories-full of FM files back and forth between .fm and .mif, and direct the outputs to specified locations, etc. The free utilities dobatch and dzbatcher emulate fmbatch on Windows. Search Google for terms like "Search Google for terms like "FrameMaker windows fmbatch free utilities like dobatch dzbatcher" without quotes for resources on these tools.

HTH

Regards,

Peter

_______________________

Peter Gold

KnowHow ProServices