Which template file is used for DITA 1.2 publishing?

Report · Apr 12, 2013

Hi all,

when I save a ditamap as composite document, which template file must I edit to change the layout?

So far I have modified the topic templates (task.template.fm etc.) but I have not found the template relevant for the output yet.

Update

-----------

The ditafm_output.ini file contains the line CompositeDocTemplate_1.2=ditabase.template.fm but exchanging all ditabase.template.fm files in the FM directory did not do the job.

This seems like is a very basic question so I wonder why it is not documented - or am I missing something? The only workaround I found was to manually import the EDD and formatting from my template into the FM document each time after publishing.

-----------

Robert

Report · Jul 10, 2013

Update: Now I am also working on DITA 1.1 and DITA 1.2 documents in parallel. The ini file mentioned above contains separate lines for the publishing templates, e.g.

CompositeDocTemplate_1.1=ditabase.template.fm

CompositeDocTemplate_1.2=ditabase.template.fm

What folders do these refer to? It seems possible to use separate output templates for both DITA versions but I have not been able to adjust the output by replacing the adequate template file.

This seems really basic, if this is documented anywhere then I would be happy to receive a link.

Robert

Report · Jul 10, 2013

Hi Robert...

I'm not 100% sure (hopefully someone who has done this will chime in), but I'd assume that the 1.2 composite template is here ..

FRAMEMAKER\Structure\xml\DITA_1.2\app\technicalContent\template\ditabase.template.fm

and would expect the 1.1 composite template to be here ..

FRAMEMAKER\Structure\xml\DITA\app\DITA-Composite-FM\composite.template.fm

(But the 1.1 template name is different than you're seeing in the INI, so something isn't right there.)

Hopefully you'll get more definitive info from someone else. I use DITA-FMx, which makes it very clear as to which apps do what, and doesn't (by default) force you to use separate apps for each topic type. Since you have to maintain the composite model for publishing, you might as well use that same model for authoring .. no?

However .. why would you maintain both 1.1 and 1.2 templates? You can easily work with 1.1 files in 1.2, and if you don't use the 1.2 features or elements in a 1.1 file, it should still be valid under a 1.1 model. It's enough effort to maintain one model, but why do both?

Cheers,

...scott

Scott Prentice

Leximation, Inc.

www.leximation.com

Report · Jul 10, 2013

After struggling to find the answer to the same question you are asking, we found, through extensive trial and error, that we had to make our changed to the ditabase.edd.fm file, and then import them into the ditabase template.

No, this is not documented anywhere that we could find. <sigh />

HTH,

Marsha

Report · Jul 10, 2013

Keep in mind that you only need to modify and import the EDD if you want to make changes to the underlying model or how formatting is applied (through context rules) to the elements. If you're just modifying the styles or page formatting, you should be able to just edit the template.

To determine the template for any structured file, you should be able to use the StructureTools > Set Structured Application command to determin the structured application that has been applied to that file. Then look in the structured application definition file (likely the "Global" file) to see where the template is that is applied by that app. It's a bit trickier to know for certain which EDD was imported into the template (because there's no definitive link or pointer to the file), if you open the EDD, it should have an ApplicationName node at the top of the file that indicates the structured application it is used for. You can also export the EDD from the template, but this will not generate the exactl same EDD that was imported to the template. The elements will be reordered (alphabetically) and any text insets (used heavliy in the DITA 1.2 apps) will be flattened.

...scott

Report · Jul 11, 2013

Hi all,

thanks for your help, it seems that for DITA 1.1 the folder DITA\app\DITA-Composite-FM is the right way to go (at least something happens when I make changes there..). However, after replacing the files in that folder by my own I receive the following error message when I save a ditamap as composite file. It says the document could only be saved as temporary file because it could not be renamed and that "the new version has an unknown extension" - very strange. A loneley .lck file remains in the destination location but the composite file is not saved there.

I modified the EDD slightly (mainly by adding context rules) and the entire system works fine for editing DITA files. I use the templates such as concept.template in Structure\xml\DITA\app\DITA-Concept-FM, etc. I would have expected to replace the files in the DITA-Composite-FM folder in a similar way, but evidently something is still missing.

@Marsha In which folder did you edit these files? I tried the Structure\xml\DITA\outputTemplates folder but FM still uses it's default layout.

Robert

Report · Jul 11, 2013

Either I'm confused about dates, or there's a harmonic convergence going on. I am just now grappling with this problem myself and lo, here is a discussion that started yesterday!

So far I have tried altering the Struct Apps file to specify which template to use in the DITA_1.2_ditabase applicaton, and I have tried editing the template file stored in ...\AdobeFrameMaker11\Structure\xml\DITA_1.2\app\technicalContent\template\ditabase.template.fm... Neither of these activities makes a difference. So when Maker saves a DITA map as a composite document, does it use any of the applications in the App Definitions file? Or is it using hard-coded magic for some unexplicable reason? If the latter, that should be logged as a bug.

I'm getting convinced that Maker doesn't use the Struct Apps file at all when saving as a composite doc because I have deleted all app definitions from the file except DITA_1.2_ditabase. I still get the same results no matter how I define the template. Then when I use Scott's trick to check which app created the document, it shows DITA_1.2_ditabase -- BUT, the Set Application list shows the full set of apps that I could choose from the default struct apps file. (Yes, I have loaded my changed struct apps file -- and verified that it has only one app in it by restarting Maker and choosing EDIT struct apps file... It has a single app as expected.) So I don't believe I have reduced the set of defined struct apps at all, even though I have only one app in the loaded struct apps file! Where is this information coming from, and why can't I control it? In short, this area of the product is unpredictable for my feeble brain, and I can't afford to spend any more time on it. I have deadlines to meet.

Bottom line, I can't seem to do ANYTHING that will change Maker's behavior when saving a dita map as a composite document. This is a real problem, BTW. It means that my daily work flow always includes the stupid, manual steps of importing formats and EDD from another template after I create the file! Can this possibly be acceptable behavior? Note to Adobe... This is the sort of thing that drives a customer to use a different product.

Report · Jul 11, 2013

@Robert .. all I can suggest is that you go back through your modifications, and test each one to see where the problem lies. Even the most basic change, can break things

@cudspan .. you may know this, but there are two structure app definition files. It sounds like you've cleaned out your local file (accessed via StructureTools > Edit Application Definitions), but there's also the global file (StructureTools > Edit Global Application Definitions). The global file is where the "default" apps are defined. If you want to get rid of those, empty out that file as well (after making a backup of course). Don't just delete the file .. that has other strange results. Beyond that, I do think that FM does some "magic" on the back end that makes it very difficult to control this publishing process. I haven't taken the time to figure it out (since I use DITA-FMx which doesn't have these limitations), but it is rather disturbing. Some people (@Marsha for one) seem to have figured it out, so perhaps she can offer more advice. I do know that it can be very difficult to get FM to use templates/apps that aren't the default ones.

All the best!

...scott

Report · Jul 11, 2013

HA!!! That would explain things. But now the question is, why don't I see a menu choice to edit the global app definitions? (This is what I get for sticking with Maker 8 for so many years...)

Report · Jul 11, 2013

I believe that this menu item was added in the 11.0.1 update. You can manually just open the structapps.fm file in the Program Files area .. that's the "global" file. The "local" file is the one in your "app data" area (that's the one opened when you chose StructureTool > Edit Application Definitions.

Cheers!

...scott

Report · Jul 11, 2013

Well, thanks, Scott... Still no joy, however. I have narrowed the app definitions to:

* Global

* DITA_1.2_map

* LOCAL

* DITA_1.2_ditabase

* DITA_1.2_topic

The ditabase application specifies a custom template in a custom location... I'm using the same template as I use for the topic, except it has DITA as the highest-level element. When I open a topic, it displays the file using the correct template. When I generate a composite doc it uses some default template. But as far as I can tell, that generic template is not specified anywhere in the application definition files that I have. I restarted Maker, and got the same results.

When I check which application was used to generate the document, it shows DITA_1.2_ditabase. The list of available applications agrees with my global and lcal app def files.

So I believe this is a bug. It clearly isn't using the app definition to get the template file. Furthermore, I have no idea where it's getting the default file. In the DITA 1.2 app directory, I have saved a copy of my custom composite template as ditabase.template.fm. So even if it picks that file up from the application directory, it should have the custom look, and not the default look.

Baffled and confused as ever... cud

Report · Jul 11, 2013

What worked for us was to save our ditamap as "Book 11.0 with frame components (*.book)" rather than "Composite Document." I know these are two entirely different animals, but that worked for us.

HTH,

Marsha

Report · Jul 11, 2013

@Marsha... Doesn't that start every topic on a new page? I can't get away with that...

Report · Jul 11, 2013

No, it doesn't start every topic on a new page IF you set your ditafm-output.ini file properly. AFAIK, that isn't documented anywhere either. <sigh />

You can find the ditafm-output.ini file here: C:\Users\<userID>\AppData\Roaming\Adobe\FrameMaker\11 where <userID> is your computer userID. Of course, make a copy of the file before making any changes.

The section that hold the key to keeping your output from having a new page for every topic is BookWithFM-General and the specific line is GenerateFlatBook=1. If GenerateFlatBook is set to 0 you will get a new page for every topic - not generally desirable, IMNSHO.

For information about this file see http://help.adobe.com/en_US/framemaker/ini/WSab3dc8d98b7c993e-4e15a103138ec8407cc-8000.html

HTH,

Marsha

Report · Jul 11, 2013

By the way, there are a lot of other good settings in the ditafm-output.ini file.

Happy hunting.

Marsha

Report · Jul 12, 2013

Marscha,

thanks for the hint with the GenerateFlatBook setting! This works now and uses the layout in the bookmap.template file (DITA-Bookmap-FM folder).

Now what I need is a batch file that copies, renames and saves my template to all the required locations each time I make a change.

Robert

Report · Jul 12, 2013

@Marsha... Thanks loads for the tip! Actually, I got it to work with a composite doc simply by making this change in the ditafm-output.ini file:

;TemplateDir=$STRUCTDIR\xml\DITA\outputTemplates (the old setting)

TemplateDir=C:\VMTurbo\_Tools\MakerAppFiles

I have my modified version of the ditabase.template.fm file in there. When I save a ditamap as a composite Maker doc, it now uses the correct template. And so my tables are the right size and everything.

What I don't understand is why we need so many different template directories, and so many ini files to manage this. Why doesn't the app definitions file do it. It's as though different teams were involved in implementing these different features. There's no re-use of capabilities. I see no rason why the ditabas app definition can't specify the template to use for output.

Anyway, 'll take a close look at that ini file! Thanks again!

Report · Jul 11, 2013

An added problem. I couldn't figure out why my tables were always getting their column widths reset. Well, it's because they're getting stuffed into the wrong template. So I have to do all sorts of manual stuff with each PDF release I make:

* Open the correct template

* Import formats

* Import EDD

* Resize tables (maybe 50 or so)

Who knows what else I'll discover. I find this very disappointing.

Report · Jul 12, 2013

The issue with tables being resized to fit your main column is a know bug.

If you use side heads and tables that span over the size head, no matter what you do, the tables will be resized to fit the main column.

This has been one of the reasons why we threw DITA overboard after all.

If you need to stick with it, I'd suggest to use DITA-FMx. Scotts' doing some great work there and it nearly solves every freaking issue, that occurs with the native FM11 DITA stuff (from what I've heard).