Previously, I discussed how the features of DoX CMS could be utilized with the oXygen XML editor when you edit content through the WebDav-based network drive for a copy of Dox CMS. This time, I will go through how the same can be done with the structured authoring mode for Adobe FrameMaker. The version to which this applies is FrameMaker 2020.
It is important to note how FrameMaker requirtes a stricter format than oXygen because of its dependency (sole) dependence on pre-determined structures (EDD) against which it is constantly validating your content. For example, despite how you can write the required identifiers directly in the raw XML editor view, this will cause an error message unless these attributes have been specified as part of the allowed format.
As a personal anecdote, I must also note how it was somewhat concerning when the trial version of FrameMaker could not finish installing before I closed Microsoft Outlook.
Tags and Element Classes
As before, you must add a separate attribute related to each tag category as well as element classes in order to add them to elements in the editor.
In FrameMaker, you must make possible additional attributes a part of the possible structures for the file. These possible structures in FrameMaker are specified by so-called EDD files (Element Definition Document) which correspond to the DTD files (Document Type Definition) used elsewhere. These EDD files share the same basic format with DTD files but may also include instructions specific to FrameMaker.
Because it us considerably more laborious to edit an EDD file than to do the adjustments required by other external editors, it is especially important that you specify all tags and element classes in advance in DoX CMS. If some of our customers insist on FrameMaker as their external editor of choice, we are open to negotiate innate support for EDD files in terms of the features of DoX CMS.
The steps to make EDD files with the tags and element classes in DoX CMS are provided below.
Download the DTD file for DoX CMS
Because you can base an EDD file on a DTD file, the DTD file that DoX CMS uses is a good way to import the majority of the required structure.
To have access to the DTD file, you must publish any content in the DITA format. Extract the contents of the .zip-file in some location. The ‘schema’ folder among them contains the .dtd and .mod-files for the publicaion. You will need the ‘topic.dtd’ file among them and you may copy or move it elsewhere from here.
Convert the DTD file to an EDD file
When you open FrameMaker, set it to structured authoring first. To do this use the Edit > Preferences command from the top toolbar and set the value of the ja Product Interface field to Structured FrameMaker. Then click the OK button.
After this, you must make the new EDD file. First, open ‘topic.dtd’ with FrameMaker and copy its contents. After you do this, use the Structure > EDD > New EDD command from the top toolbar. In principle, you can make a new empty file through other means but this ensures its suitability for the task.
Select all the contents of the new EDD file and replace them with the content that you copied from ‘topic.dtd’. Save this file as a .fm-file. It is not a functional EDD file but you must still specify your tags and element classes in it.
Specify Tags and Element Classes
Because you must specify the possible attributes separately for each type of element, you must repeat the these specifications for each type of element (on which they will be used). You can copy the specifications for one type of element and paste them for other types of elements, though. They need not be written separately each time.
Start from the top of the list to add new attributes. Select the end of the ‘Attribute List’ -row for an element and press the Enter key to add a new item to the list below it with a Name element in place. Write the identifier for a tag category or for element classes as the Name value. The identifier for a tag category is ‘data-doxattribute-category’ where ‘category’ must be replaced with the (hidden) identifier of the tag category in question. You must add a new attribute for each category of tags. The identifier for element classes is ‘doxelementclass’.
Once you hace written the name for the attribute, press the Enter key to specify its other details. First you must specify the input method for its values. If you prefer to always write the names of tags and element classes because you expect to regularly add new alternative values such as the identifiers for new models, you can use the value ‘String’ here. This is also ideal should you have need to use more than one tag from the same category on the same element. However, our recommendation is to go with ‘Choice’ instead. Next, add ‘Optional’ there.
If you opted for ‘Choice’, the system should add a ‘Choices’ field automatically when you press the Enter key. If this does not happen, add it yourself. The, write the (hidden) identifiers of the tags in the category as the possible values there. In the case of element classes, use the identifiers for element classes. Separate possible values with a vertical bar (|) with an empty space on both sides.
Repeat this process for each category of tags and element classes and copy the values for each type of element for which they may be needed. The easiest way is to start a new item for each element’s list of attributes and to remove its ‘Name’ field before you paste the copied information.
Apply the EDD to Files
Once the EDD file looks satisfactory, you must use it on the files for topics.
The first step is to validate the contents of the EDD file. It cannot be applied elsewhere otherwise. Use the Structure > Validate command from the top toolbar for this. If the system warns you of any part of the file, the likely reason is a missing necessary detail (such as an ‘Optional’ element).
After you successfully validate the EDD file, keep it open in FrameMaker. Then open content from DoX CMS through the WebDav network drive. The means to access it can be found in our user manual. Once the content has been opened in FrameMaker, use the command File > Import > Element Definitions. Select your EDD file for the ‘Import from Document’ field and then click the ‘Import’ button.
Add Identifiers to Elements
Once a correctly specified EDD file has been applied, tag categories and element classes become available attributes for different elements. When you select an element and use the ‘Attributes’ command from the vertical toolbar on the right, they are among the attributes on the list.
If you these attributes’ values are based on the ‘Choice’ alternative, you open a list of available values when you click the field for the value of one of them. If you they use the ‘String’ alternative, you must write the (hidden) identifiers of the exact tags and element classes that you must use in these fields.
Variables
The principle for adding variables remains the same as in oXygen. You can write them directly as part of the textual content by adding two sets of curly brackets ({}) around their names. If the name of the variable is ’email-support’, for example, you will have to write ‘{{email-support}}’ in the document to use it.
The same principle applies to system variables that are replaced with values retrieved from inside the system when you publish the content. A list of system variables is available in the user manual for DoX CMS.
Internal Links
Unfortunately, FrameMaker uses its own ‘fm-xref’ element for links other than external links. Although these elements act identical to standard xref elements when you publish content, they will not show in DoX CMS after you save the content. For this reason, you must first add the links as external links and then change them to local or peer links using their DITA attributes.
First, add an xref element with the Element > Insert Element command. You must click the ‘External Xref’ button in its ‘Cross-Reference’ menu which you can also open from the vertical toolbar to the right. In there, select ‘Xref Target(href)’ and then write write the address for a topic, element, or web address in this field. In the case of elements, the address must include the identifier for the topic that contains it before the element’s identifier, separated from it with a slash mark (/).
Add the link by clicking the OK button. When you are making an internal link, select it and open its ‘Attributes’ menu from the vertical toolbar to the right. Change the value of the ‘scope’ attribute to either ‘local’ or ‘peer’. ‘Local’ is used for links to position in the same topic and ‘peer’ for links to other topics or their elements.
In the case of images, you must first use the address for some actual file and then edit the href value directly through the XML editor. Once folders for attachments are added to the WeDav network drive, the associated addresses will also be added as acceptable values for the href field in terms of publishing content. Because FrameMaker attempts to add a prefix related to a file location in the href value, you may have to remove it in DoX CMS for the time being.
What You Cannot Do
FrameMaker contains fewer additional features than oXygen, for instance. As the challenges with xrefs discussed above demonstrate, though, the program occasionally adds its own identifiers to elements.
The most notable feature which is incompatible with the editor for DoX CMS and where the differences cannot be resolved with some editing is the inclusion of ‘Conditional Tags’. When you use this method of conditioning content, the editor in DoX CMS refuses to open the content at all.
Additional types of elements that are not (yet) supported in DoX CMS such as mathematical equations will only show as error messages in the internal editor for DoX CMS. If you must save content there, this error message will replace the actual elements in question. For thos reason, we cannot recommend using them despite how other parts of the publishing process are not limited only to the elements that the editor supports.