(also posted to techshoret)
My apologies if I'm asking something trivial. I haven't used FrameMaker for a while and am not yet familiar with the most recent versions.
Problem statement: We have a User's Guide for a product that has multiple (~15) different flavors so we have that many guides. I would like to unify them into one guide with conditional text.
The basic format is the same for all flavors. The main difference lies in sections containing lists of parameters and their values; these change with each milestone of a flavor.
Whenever a product is built, the build process generates the relevant lists. These are then manually copied into the document for the specific flavor (a rather painful process). Each "flavor" requires several builds in the course of a year, so the tech writer needs to do all this around 50-60 times.
Engineering will provide me the information in whatever format I want (or so they say), and will place it in a drive that I can access. My plan is to import the data (File > Import > Object > Create from File) and link it so that when they change the data, it will be automatically updated in the Frame file.
What format should I ask for, and are there any tips on how to perform the import automatically?
I've tried importing from Word and Excel, but find it hard to implement the required fonts, sizes, etc. without having to edit the data afterwards.
I may be missing something significant about your process … but if it's a question of regularly updating text insets, and if these insets do not use tables or character-level formatting, have you considered mml? I've just run a very quick test that confirms I can use File > Insert file [by reference] to pull in an .mml file the same way as I'd usually pull in an .fm file. The tagged plain-text formatting ought to simple enough to generate, and because .mml includes style names you shouldn't need to do manual tweaking afterwards. [there's one limitation, though: .mml can only handle Bold and Italic. You can run find/replace on these afterwards, of course] And if you don't need to keep versions, you can just update each .mml file when required; next time you open the FrameMaker files, the insets will be updated.
Feel free to message me if you have questions. Big disclaimer, though – I'm still stuck on FM12, with no idea whether this old-style approach is available in more recent versions.
For things like parameter lists, etc., I prefer to get XML from the engineers. I create a structured FrameMaker template and possibly some XSLT stylesheets so I can ingest the content directly into FrameMaker. It doesn't matter if the rest of the FrameMaker content is unstructured; you can have a mix of structured and unstructured documents in your book. Or, you can simply remove the structure from the converted documents.
If you are interested in exploring this idea, please contact me offlist and I will be glad to take a look at what you have. There would be no cost to a first meeting. Thanks. rick at frameexpert dot com
Exactly. This sounds like a classic case for the import of XML-formatted data snippets. FrameMaker is built for this type of thing. It will require some customization, but it sounds like the return on investment would be quite rich.
Could I also assign paragraph formats for specific elements automatically? Or even tables?
How would I do this?
In structured templates, you use the EDD (Element Definition Document) to apply formats based on element/attribute combinations. The whole EDD feature is pretty powerful in my opinion.
OK. I did not know that I could use the EDD for this.
When I have an unstructured file into which I import the XML as text inset, where is the location of the EDD stored?
I assume not in the XML file.
I am not sure if it will work like this. Typically, my documents are either structured or unstructured. I don't know what happens if you import XML as a text inset into unstructured FrameMaker. I don't have time to try it right now.
Winfried, there are several variations that you could choose, all of which involve some complexity. You could import XML fragments, then include the content in your files as text insets. Or some other mechanism. When you import XML, the EDD and structure application files define all the formatting, so properly configured, it is all just automatic. But it is not simple to get there. You would need significant knowledge in several areas of advanced FrameMaker usage.
Another thing I thought of... if your engineering could provide content in *any* format you want, MIF fragments could also be an option. The syntax would be more complex, but it would avoid the overhead of XML.
In summary, it is a task with complexity which could involve several approaches. It is very possible and likely a worthy effort, but it is hard for us to get much more specific here. A qualified analysis process would be required. If you feel that it is beyond your time and/or current skillset, you may need to hire some expert help to get started.
Seems to me that there are two separate issues: what is the best format for engineers to use for the data and how to get that data into the FM document.
I certainly agree that XML may be an appropriate format for the engineers to use, especially if they are already familiar with XML and have used it to create data files in the past. You mention that you had tried Excel but it was difficult to obtain the necessary format from Excel. Excel can save documents as XML (use format XML Spreadsheet 2003). Thus, if it is most convenient for everyone involved, the engineers can use Excel and the FM representation can be derived from XML.
MIF may also be appropriate. Aside from the complexity that Russ mentioned, if the engineers deliver MIF, their MIF-generation process will need to be updated if you ever change the formatting or tagging. If you decide to go with MIF, consider having the engineers deliver XML, and using XSLT to convert the XML to MIF. That way, you control all the FM details.
Rick commented that he wasn't sure an XML flow could be imported into an unstructured document. I just tried it and it fails with an alert that XML cannot be imported into an unstructured flow.
All in all, I believe MIF is the only way for engineers to deliver the data in a way that will allow changes to be incorporated simply by updating text insets. Still, if I were designing a solution with similar requirements, I would ask the engineers for either XML or MIF. To update the text insets, I would preprocess the engineers' files either outside of FM or with a script or plugin to derive new MIF or structured FM files that would be used for the actual text insets.