hooking up DITA structure and house style(s)

[Guest]

OK ... I've never yet managed to get a DITA project up and running to the point where I can work on it every day with a view to delivering something. But today I hope this has finally changed, so I'll start trying to post here and improve my grasp of the essentials. My thanks to all those, especially Rick Quatro, who have replied to earlier postings now sunk beneath the forum's event horizon never to be seen again <g>

First question, leaving myself wide open to correction:

I observe, on opening a DITA file in FM 9.0p237, that FrameMaker has thoughtfully provided a slew of styles related to elements and their position in the document structure. I am aware that really clever people can set up rules so that formatting is applied very cleanly, without using styles; but (certainly at this early stage) should I try updating the style-definitions based on what we're already used to?

"title.0", for instance: from the Element Context Format Rules, it looks as though that's equivalent to a chapter heading where my not-technically-speaking-structured documents would use the style ":h1".

Got to learn somehow! so thanks in advance for pointers along the path to enlightenment.

Niels Grundtvig Nielsen

[Van Kurtz]

Niels,

I have not worked with DITA but have taken a peak at it. On the other hand, I have created a structured application that applies formatting from the EDD and uses some styles. So these are some general hints but may not be the best approach. Others may have better ideas.

Formatting, including styles, is applied by the EDD. If you look at the DITA EDDs provided by Frame, you will see how and where they are applied. So, rather than guessing about where a style or other formatting is applied, look through the EDDs and see exactly which elements get which styles. The Frame version of DITA has lots of styles. You may find some cases in which the EDDs apply formatting that is NOT the simple application of a style.

I am sure you will back up all Frame provided EDDs and templates before changing them for your needs. Whether you can change the names of the EDDs and templates for your purposes and still have Frame treat them as DITA is out of my realm of expertise. If you can, it may make template management easier. Changing the standard DITA structure is whole other can of worms, which I have yet to figure out.

Good luck and I hope this helps even a little bit,

Van

[ScottPrentice]

Hi Niels...

As Van pointed out, the EDD does apply the styles that are defined in the template. In most cases it's just that simple .. the element definitions in the EDD contain context rules which apply a specified style to the current element based on the context. In some cases, the EDD will also apply some additional properties, so it's not always clear where some format or characteristic is coming from, but if you dig deep enough you'll find it.

Before messing with the default apps, I highly recommend cloning them to create your own. In the process of tweaking (even a simple tweak) you *will* break the app, and possibly be unable to open a file. When you do this it'll be difficult to know which of the last tweaks caused the problem. If you always have the default app to fall back on and to compare your custom app against, you'll be much better off. Once you get the hang of it, cloning an app is fairly easy, but there are a number of steps involved to do it properly. basically you'll end up with another set of structure applications (for FM9, just Topic and Map .. for FM8, there's Topic, Map, and Book) that have a new name. You can swotch between the default apps and your apps by changing the settings in the DITA Options dialog.

I've got some documentation on cloning apps that might help point you in the right direction. This is written specifically for use with DITA-FMx, so you can't follow the steps exactly, but it should give you an idea of the areas that you'll need to work ..

    http://docs.leximation.com/dita-fmx/1.1/ditafmx_customizingapps.html

Cheers!

...scott

Scott Prentice

Leximation, Inc.

www.leximation.com

[Guest]

Thanks, both – I'll go through my EDD reference material and see who much of it I remember from previous readings. Would I be right in suspecting that the "Show element context" tab is displaying a fragment of the EDD? And are read/write rules coming into play at some stage? I ask this because if I daringly change the definition of a style (for example, body or ul) in an open file, then save, close and re-open, all the changes are discarded.

I'll make frequent and abundant backups, and check the links about cloning.

N

[Van Kurtz]

Niels,

I have played only a little with DITA in FrameMaker, but my understanding is that your basic files are XML files, not FrameMaker files. So, yes, read/write rules are always present. They are needed to read the XML file into Frame and again to output the Frame file to XML. BUT read/write rules have to do with the structure, not the formatting. The formatting is in the styles embedded in the template AND in the application of formatting done by the EDD. When Frame reads the XML file, it applies the read/write rules to get certain things (such as tables) into Frame objects. It copies that structure into the template specified in the structure application. The EDD embedded in that template then applies the formatting. When you save the file to XML, only the structure is output, not the formatting. So, if you change a style in a DITA Frame document, it is lost when you save the file to XML. So, if you decide to change a style, then you should change it in the template and/or the EDD, not from within the Frame document itself. Of course, if you DO change the style in your Frame document, you can always import that style into the template; then it will be there the next time you open the XML file. If you want different types of documents to have different style sets, then you will have to create different templates, which of course, can have the same structure definitions, ie, DITA structure definitions.

I do not use the Show element context tab, but I took a look at it. It appears to be showing the formatting rules that will be applied to the element containing the insertion point. If you use it to change a formatting style, then the change is only in the Frame file, which will be lost when the file is saved as XML.

I suppose one could work entirely within a set of Frame files, saving your work as Frame files, not XML. Then your style changes will stay with the document, but that leads to maintenance issues, having different versions of one style in different documents. And I am not sure how that situation would play with the DITA structure application built into Frame.

Hope this helps,

Van

[ScottPrentice]

Hi Niels...

Some people do work with structured FM binary files that have the DITA model applied to them, but I don't recommend this approach. Some of the authoring features assume the files is XML and may not work properly, and it's also very easy to inadvertently add unstructured content (markers, etc.) that seem to be working but when you do save to XML they go away.Unless you have very specific reasons to work in this way it's best to use XML files as the source.

To expand on Van's points .. all of the formatting that's applied to your DITA (XML) files when you open them comes from the template and EDD of the structure application. You can test formatting changes by modifying the character or paragraph styles in the open document, but in order for them to be applied when opening an XML file, you need to make those same changes to the template. In some cases, the EDD is actually applying formatting (typically indents or applying prefix strings, but could be any formatting), so you should also have hte EDD open to check on what it is doing under the current context. You can make tweaks to the EDD and import that directly into your open document to test those changes, but in order for those changes to be permanent (part of the structure application), you must import the modified EDD into the template file. The template file contains both the formatting template (named styles and page layout data), and the structure/context-based formatting (from the EDD).

Cheers,

...scott