FrameMaker 10, Windows 7 x64.
I have a document with a lot of external files inserted as text insets. I would like to have this file appear in a book only under certain conditions. I've created the appropriate conditions, selected the entire file, and applied the conditions. All of the insets are conditionalized, with the exception of a single inset. When I reselect that inset and attempt to reapply any of the conditions, I get a dialog, whose title is too long for its size, so you cannot fully comprehend the purpose. See below.
I do not wish to make the text unconditional, and I do not wish to delete the text. I wish to set a condition. There is nothing I can find in any FrameMaker resource that describes why I am getting this message, or what to do about it. All of the other insets are correctly conditionalized.
That's just the thing - It doesn't show any tags at all for that inset. The source file has no tags either. There must be something that FrameMaker sees there to behave differently for this one inset, but whatever it is, I'm not seeing it. Hm... maybe I should save a .mif and see if it shows anything there...
OK bear with me - I realized that I may have left out information that could be relevant.
I have a number of stand-alone procudures. All of these procedures share a number of text insets, so that I can update them all by updating the inset.
Now I want to create a book, and I want to place these procedures in a folder of the book. But the book needs to have conditions set. Since I cannot set a condition on a file, I have to select the entire document's contents and conditionalize that. It works fine when I do that on the first document, but I have this error when I get to the next one.
It almost seems as if FrameMaker objects to setting the condition in the using document if the inset is shared with another document. That doesn't even make sense, since all of the other insets are also shared, and they are correctly taking the conditions. But perhaps my description will jog someone's understanding enough to realize what I'm doing wrong here.
I would like to have this file appear in a book only under certain conditions.
... and I want to place these procedures in a folder of the book.
If the conditional content comprises an entire file (book component), why not set up separate books for each edition?
By the way, are the insets plaintext, .fm or some other format?
If .fm, do the conditions exist in the source files?
The conditional content does comprise an entire file.
The inset source files are .fm format, and they contain the same conditions as the using document, but no markers have been set on the text. In other words, the text is unconditional in the inset source.
OK ignore that. If I open one of the documents that I want to conditionalize, go just to the one that I'm having problems with, I still cannot conditionalize it, even outside of the context of the book.
I opened the inset source and removed all conditions from that file. It's still .fm, but there are no conditions in that file any longer. In the using document, I still get the error message above when trying to conditionalize it.
I started a brand new document that contains all of the conditions I need, and inserted the text inset. Still I get the error message above. Thus, I became convinced there is something about this one inset that is suspect. However, I created a brand new text inset source file, and substituted that, and I STILL get that error message when I insert it and try to conditionalize it.
I'm missing something here - all of the other insets conditionalize just fine. I see nothing specifically unique about this one - it has two numbered steps. Step 1 contains a URL. It couldn't be simpler...
I can open the inset source and edit it just fine. I can open the file where I'm placing the inset and edit that too. Apparently the only thing I cannot do is tag one of the insets with a condition.
While trying to debug this, FrameMaker has started crashing. So my frustration level is correspondingly increased.
I think it would help a lot if anyone knew the source of that error message. I suppose that's asking for a lot, since it could have been there since before dirt, and only comes out to play every millenium. Still, FrameMaker is trying to tell me something that I clearly am not understanding.
Update: I mif-washed the main doc with no apparent improvement. I converted the two-step procedure (my inset source file) into plain text and imported that as an inset, and I was able to tag it. Subsequent to that, I was then able to import the .fm version of the two step procedure and tag it. However, now a different inset is behaving in the same way (error message above).
My method is to tag as much as I'm able until I discover which inset is throwing the error (the message, as you can plainly see, gives no clue). These documents I'm working with have about 40 insets in them, so it is a real pain to discover which one is the culprit.
Anyway, working through like this, and restarting every time FrameMaker crashes, I made the discovery that the problem inset had migrated. How is that even possible? I don't know.
I am not sure that I understand correctly what you are doing. I think you are importing a text inset into the main document and then applying the condition there, from within the main document. I am not sure that one can do that. I think you should apply the conditions in the inset document itself, then import the file as an inset. Is there a reason why you are applying the conditions from within the main document?
I'll try to keep this short, but it is complex, so...
We have ten products fielded. They all have one feature in common, yet in some of them that feature operates on a different voltage.
They all have a PC in them. But over time that PC has evolved and been replaced.
Some have modems.
Some have routers.
Some have cellular aircards.
Some have other added features.
They are deployed in North America and Europe, so there are two voltages.
Essentially, across the ten models out there, we can write a book of 8 chapters to cover the most complex model, and the simplest model only takes 5 chapters to describe.
The tech writer here before me took the approach of not describing the models at all. He just described all of the systems and subsystems, and put a "used on" statment on page 1 of each Service Bulletin. It is a hopeless mess.
I have the unenviable task of making this into a real book, one for each model. But our products evolve rapidly and continuously. We will have to make a way to attach stand-alone service bulletins to each chapter in each book, on a continuing basis. In addition, the physical hardware is always evolving, gaining new part numbers along the way. That has to be captured and kept up to date for each model.
Since hundreds of these service bulletins exist already, and many are single-sourced using text insets as the source files, I'm trying to "attach" them to a chapter by adding a folder to the chapter and importing stand alone documents into that chapter's folder. Then I can use a cross reference to set up a menu to the service bulletins.
But as I said, some features require different treatment depending on the model. For example, we have a cellular network in some, but it requires a different aircard in the Canadian model. Thus the chapter that describes the cellular networking has to include both the US and Canadian descriptions. Since these service bulletins exist, I want to use them as is. But how to conditionalize them? I thought it would be best to open the service bulletin and select all in flow, then set the condition there. It worked on the first document, and then started throwing the error above on any others I tried to do that way.
I'm not sure I could manage to conditionalize at the inset's source files, because at that level it is never clear where it might be used. It's single-sourced - can be deployed to any of this set of documents. They are fragments.
OK, now you have most of it (although perhaps not as clearly as I would have liked) - have I made a wrong assumption about text insets here? Shouldn't I be able to do this manual in this way? Or is there a smarter way to approach the problem? And what the heck is that error trying to tell me?
Exactly how are you inserting your text insets? Do you have a custom paratag used to hold an inset and is it empty except for a space before the end-of-paragraph (pilcrow) mark?
Are you applying the conditional tag to the entire inset container paragraph or to just the inset within the container paragraph?
What strategy will you be using for your conditionals, e.g. a simple show/hide where you want to only hide features not found in the combined book? Or do you want to "show" features that are relevant (i.e. using relational expressions)? Each route requires different considerations for the conditional tags - besides the current issue that you're having.
I have not been using a custom paratag for insets. I've been inserting them in the flow where I need them, with consideration for the extra space etc. I take the formatting of the inset, since many of them have list numbering and that gets mangled if I use the container document's formatting.
Do you feel a paratag specific for insets would add value? I just checked my copy of Unstructured FrameMaker 8 (from Scriptorium) and it doesn't make such a recommendation, although there are cautions about an extra paragraph before and after, which I have been observing.
Conceptually, you are on the right path, but your implementation is using technology that is very old and hard to manage in a heavy-use environment. Some time in the future, I'd recommend that you consider a migration to structured FM, where you can start using structural metadata to denote and manage conditional/reusable content. The unstructured text inset and conditional text features are simply don't scale very well, especially when you attempt to combine the two.
Ouch. Well we will not be going structured here for a very long time - there is only one writer, and right now he's engaged in things other than creating content.
I've avoided the idea of going structured based on advice I've seen in a number of places that says there is no way to do it with a lone writer. I'd love to go that way, but it is not in the cards in our immediate future.
So if I'm to do this by myself, using the tools I have available (TCS 3.5), is there a design that allows me to single source without coming up against FrameMaker's creaky parts?
across the ten models out there
Maybe the better approach is to avoid conditional text altogether. Sometimes it is better to manage the different possibilities through the book rather than conditional text.
If I understand you situation, you have many documents. Some are used in one model and some are used in one or more but not all models. There is no rule against using a particular document in several books.
So, suppose you created a book file for each of the ten models. Doing each book (model) separately, import the documents needed for that model. You mentioned creating chapter folders. Are you talking about creating folders in the BOOK file, say one for each chapter? If so, then you can import the files into each folder as appropriate (caveat: I have never used folders in books, so I have no idea the implications downstream of doing this). I am inferring from you post that you then want to create cross-references to the documents in the folders, say from one or more of the chapters in the book. You can do this.
NOTE that any one document can be used in any number of folders in any number of books. FrameMaker does not care how often or where you use the documents.
NOTE that nothing is conditioned, at least not whole documents. IF PARTS of each single document has to be conditioned, you can do this. Just do not condition the whole document.
NOW create a PDF from the first book. Assuming nothing INSIDE the single documents is conditioned, you can simply update the book and create the PDF.
THEN repeat for EACH book, one for each document. HOWEVER, BE SURE to update the book before creating the PDF. When you use a document in book 1 and update book 1, FrameMaker leaves information about that update in the document, particularly page numbers. When you use the document in book 2, you need to update book 2 to redo the page numbering, for example. SO, always update the book before creating the PDF, even if you have made no edits in any of the documents in the book.
Note that using this approach, there are NO text insets and NO wholly conditioned single documents. The "conditioning" is managed through the books. Each book specifies which files are to be used in that book, NOT the conditions.
It is also possible to use conditioning within each single file. Suppose a particular file has content most of which applies to two models, but there is one sentence in the content that has to be written one way for model A and another way for model B. Simply create the one file. Write the A sentence and condition it A. Right after it write the B sentence and condition is B. This one file is added to both books, A and B. Before updating the A book, you need to show condition A and hide condition B; then update the book. For book B, show condition B and hide condition A; then update the book. For each PDF, always show/hide the conditions, update the book, then create the PDF.
I may not have resolved your problems, but maybe this gives you a better approach.
I understand your suggestion, and I can see that it would likely work. But it also introduces a lot of what we're trying to get away from here, which is when something changes, we have to go in search of all the places where that information resides and change it multiple times. Making separate books reintroduces that issue, at least partially negating the point of single sourcing. Unfortunately, I've stupidly championed the idea of single sourcing so effectively, the entire organization is now convinced. The first time we make a change and every instance isn't updated, I'm going to have some explaining to do.
Still, your suggestion has merit from the perspective of getting things to work. It may be that I can find a happy compromise design based on this. Thanks for the idea.
Meanwhile, I wonder if FrameMaker will EVER be a product that has had its creaky parts updated and producing error messages for humans.
Edit: The more I look at this idea, the better I like it. And I don't think I have to give up any single sourcing advantages to do it. Thanks to the responders here - it has been a useful discussion for me, and I hope helps others avoid this same pitfall. Many thanks!
You got my attention with that one!
Even if I weren't seeing FM10 crash frequently with conditional info, I would be interested in something more powerful than what unstructured FM offers.
My need is a more complex than what Van talks about. Currently I'm using unstructured FM to conditionalize content about product features, then using conditional expressions named for product releases or customers, to expose the required content and then publish. Few customers get all optional features, some get relatively few.
Where are some resources that address this relatively narrow point of structured FM as a substitute for managing content conditionally: case studies, practices, etc. ? The crash behavior, plus increasing complexity of content here, suggest that I consider alternatives, whether structured FM or products from other vendors.
Let me second Van's suggestion of using book-based editions, plus you can use Conditions.
We do this. Separate .book structures import common text. The common text is tagged, in the inset source, with various conditions. What appears in the importing document is controlled by what is inset and condition code settings in the importing document (which are basically set-and-forget).
But attempting to perform any mods on an inset, in the importing document, is risky. If you save out an importing.fm as a MIF and study it, you'll see that there are a some locking tags associated with insets:
<TextInsetLocked zzz>, <PgfLocked zzz>, <FLocked zzz>, <TblLocked zzz>, <VariableLocked zzz>, <XrefLocked zzz>
They are documented in the MIF Reference Manual, except for TextInsetLocked.
I have had problems in the past with <PgfLocked Yes>. After deleting the inset, that tag got transferred to the hosting para, and it required a MIF hack to fix it. The empty para could not be changed or even deleted.
I'm actually surprised that it appears possible to apply conditions to an inset in the importing document. I would be totally unsurprised to learn that sometimes it doesn't work, or has unpleasant side effects. Apply the conditions in the source of the inset. Set the Show/Hide conditions in the importer.
The more I look at this idea, the better I like it. And I don't think I have to give up any single sourcing advantages to do it.
You indicated you are using some prewritten service bulletins. These are your single sources. The books that use them are simply using them. Assuming there is not a lot of overlap among the service bulletins, then updating the content in the service bulletins is not a process of finding all the places where they are used. The usage is in the books, which link to the content where the changes are made. As time goes by, you will probably update/rewrite the service bulletins to look less like service bulletins and more like parts of books. Then you will have single sources used in several books. Write once, publish as many times as you need.
If you're not inserting your text insets (i.e. complete service bulletins) into separate paragraph containers of any kind, then what are you placing them into? The process is a step in the structured direction that Russ suggests. You're just using a paragraph container rather than an element container (when structured). You can then make the container conditional. When FM "hides" or removes conditional content, it drops in a marker at the location that the conditionalized content occurred and then moves the content to special hidden page along with a pointer back to the marker so it knows where to put the content back when unconditionalized. Conditionalizing entire paragraph containers (that include the insets) seems to be less error-prone that trying to conditionalize just the inset within the container, in my experience.
Also, using relational expressions on overlapping conditions can cause some interesting results. Have you checked for overlaps and are you certain of your condition boundaries?
You also didn't mention whether your FM10 version is fully patched to 10.0.2 or not.
I'm fully patched.
I appreciate the information, but we are fully unstructured here, and plan to stay so for the immediate future. We cannot spend any money, hire any help, or otherwise do what we should do for this complicated set of problems. Thus, I will muddle through, assuming FrameMaker does its part.
Unfortunately, I don't know of any great resources, except to start messing around with it and letting your mind wander. If you want to get some ideas of the possibilities, you could download my (free) structure-based conditional text and text inset plugins (AXCM and InsetPlus) and run through the sample files/tutorials:
However, I am somewhat loathe to start you out there, because I'm not here to promote myself or the business, even though the software is free. I just don't really know of many other good options for this particular subject.
My main point was just to make a suggestion about exploring solutions based on innovation and forward thinking, rather than still banging on that old typewriter, wondering why it doesn't work any better. By moving forward with technology, you improve your own situation, in addition to the general outlook of the industry in general. Too often, though, the response is some typical expression of pain or statements full of words like "can't" and "won't". I'm sure this is why so many employers now would rather hire an engineer that can sort of write, rather than a tech writer who can't engineer at all.
But before I get too philosophical, let me steer back to a couple of points that I know to be true:
- Structured FM is a technology and a concept, not just a tool. It is a path to making your content look like data to the computer, after which the computer can do more work for you. When you mess around with techniques like conditional text and text insets, you are asking the computer to do more work for you, which is good. That's what computers are for. But the more help you give the computer the better. Structure is a path in that direction, whether you use some plugin, write some scripts, ditch FM altogether, or whatever. If you refuse to provide the computer the input it needs, it will forever refuse to do the work that you want.
- It is a complete myth that a lone writer (or anybody) can't move to structured content, especially with a structured authoring tool as easy to use as FM. All it takes is one brain with a modest amount of technical competence and the will to learn. It also a myth that it has to be wildly complex or has to adhere to some buzzword or standard such as DITA. The movement can be incremental and methodical, and entirely customized for a particular situation. It does take time and motivation, sure... but so does anything that is worth anything in the end.
"It is a complete myth that a lone writer (or anybody) can't move to structured content, especially with a structured authoring tool as easy to use as FM. All it takes is one brain with a modest amount of technical competence and the will to learn. It also a myth that it has to be wildly complex or has to adhere to some buzzword or standard such as DITA. The movement can be incremental and methodical, and entirely customized for a particular situation. It does take time and motivation, sure... but so does anything that is worth anything in the end."
Hi Russ, I am really fascinated that you have said this. I am a lone tech writer that manages 3,500 pages of complex IT documentation that spans 40 books. I use text insets and conditional text heavily. I have looked into converting from unstructured to structured framemaker several times. I have never found the ROI to be worth it and the reason for that was cost. Everything I have read and the webinares i have attended indicate this would take many weeks if not months of effort to first design the EDD and then perform the conversion. Tom Aldous took 6 training sessions (or six hours of training) just to do a basic introduction. I have even talked to a consultant who said it would take hundreds of man hours to do this and potentially thousands of dollars of consulting work if one were go to that route. Are you saying this wouldn't take hundreds of man hours, is not complicated at all, a single person could do this while at the same time making documentation deliveries every three months, and not require the services of a consultant or special plugins? If so, I would love to hear your explanation on how this is possible. Thanks, Joe
"My main point was just to make a suggestion about exploring solutions based on innovation and forward thinking, rather than still banging on that old typewriter, wondering why it doesn't work any better. By moving forward with technology, you improve your own situation, in addition to the general outlook of the industry in general."
That depends entirely on the ROI and business case. There's a reason legacy systems stay around for 20 years or longer in some corporations. Sometimes it is inertia, laziness, and lack of creativity. However, other times people assess the pros and cons of sticking with what they currently have and decide its "good enough" to get the job done. That's why whenever someone says STRUCTURED FRAMEMAKER TO THE RESCUE, my first response is whats your business case and what is the ROI? My second response is considering the costs in going to a new approach, are those outweighed by the benefits with sticking with your unstructured framemaker approach? Personally, I would love to switch to XML authoring. I see the benefits to it and I love learning new technology. Plus, I am pretty familiar with XML already because of the product that I document. My problem has always been that unstructured framemaker always seems "good enough" to get the job done and that the ROI and business case in my particular situation is just not there yet. Now if the costs to switching over become greatly reduced OR my understanding of those costs are off based, I am totally willing to reconsider my position. Joe
PS I realized I might be accidentally hijacking this thread which was not my intention. Russ, please feel free to email at jaloren AT gmail.com or start a new thread if you'd like.
I am not saying that it is easy, nor that it is quick. It could take hundreds of hours and perhaps months or years, especially if you are starting from scratch. All I am saying is that it is possible if you want it and I will suggest that the ROI may be greater than you think. The journey of a thousand miles begins with a single step, but will never be completed without the will to take it.
I am a lone writer with responsibilities that sound similar to yours and I took many thousands of pages of unstructured content and moved them into a fully structured workflow. This has been a gradual process over several years and continues to evolve, as I continue to discover new possibilities. It is also interrupted by pesky annoyances like having to meet publication deadlines and such, but I make the time.
The reason I make the time is because the ROI pays me back many times over and quite frankly, I couldn't get my work done without my new toys. I produce the amount of output that used to require several technical writers, and it isn't because I type fast. It is because I have the computer doing the content management and publication busywork for me. So the further I get into this, the more I am rewarded with more time to explore it further. And, the real rewards come from company management, who for the first time can see tangible value that a tech writer has added to the organization.
Also, there is more to the ROI than just increased productivity at the day job. There is an invaluable professional growth as well. Every writer has the "wrote such and such for such and such" on their resume. When you walk into the interview with "Implemented cutting edge structured content technologies, reducing departmental costs by 75% while decreasing time to publication" on yours, I can say that you might get a little more attention.
Several years ago, a decision was made by my employers to move to structured authoring. The motivation was the fact that all writing was outsourced and had been worked on by many different writers over many years. The unstructured results were a mess. Moving to structured authoring provided a way to maintain consistency across the set of publications, no matter who did the authoring. It took about 6 months of my time to develop and test the EDD. From my point of view, it was a lot of fun.
Even after the conversion to structured authoring, I used conditional text to manage 8 user manuals from one master book. It was a headache. During crunch time, FrameMaker crashed probably once every other day, sometimes once or twice a day. I was using and still use FrameMaker 9. Even if the time spent recovering from crashes is less than the time to convert to structured, eliminating the recovery frustrations has to be worth a lot.
Then I switched to specifying the conditions through element attributes and then filtering the book by attribute. NO conditional text. Filtering by attribute is part of out-of-the-box FrameMaker, but I use Russ Ward's AXCM plugin instead. Filtering by attribute works very well and is more in line with the concepts of XML authoring.
The move to structured authoring was in our division alone. This year a larger part of the company decided to move to XML authoring using an XML-based CMS. Because we had already moved to structured FrameMaker, WE became the experts in helping the others make the move. I guess that was our ROI.
"Apply the conditions in the source of the inset. Set the Show/Hide conditions in the importer."
OK, I get that, but maybe i plucked it out of context.
What if I want the entire inset to vanish from the importer? With that, I want the "host" paragraph in the importer to vanish as well.
I've inherited a few chapters like this. They contain some all-versions unconditional content and some VersionX content that is inset-based. Most of those VersionX insets are procedure steps.
We're not willingly doctrinaire around here. Just looking for reliable, high-speed maintainabiltiy.
> What if I want the entire inset to vanish from the importer? With that, I want the "host" paragraph in the importer to vanish as well.
I think that circles us back to the problem that gave rise to this thread. You'd be applying a condition to the anchor for the inset, with the presumed intention of applying it to not just the anchor, but the entire inset, which might have ideas of its own as regards that condition.
And in any case, Frame may not be coded to handle this kind of condition overload. For extra credit, you can Xref that imported inset, and apply some other conditions to that .