Frequently asked questions about MiramoPDF, MiramoDesigner and the Miramo DITA-OT plugin
Feeling stuck? Schedule a quick 15 minute Zoom.
Miramo Designer FAQs
Click on the 'More' button in bottom right-hand corner of MiramoDesigner, in the 'Format Definitions' column. Select 'RunningTextDef'. Select the running text format that you wish to change. Place the cursor where you wish to insert the numbering and then right click and insert the paragraphNumber building block. Close Window.
Click on 'ContentsDef' and then the TOC formatting 'Edit' button. Click on the then apply a pre-defined fontDef with the required color specified.
This is done by setting the paragraph ListLabel 'showInPDFbookmarks' property to 'N' as shown below (for chapter_title):
In the properties column of a ParaDef, in the Background fill and borders section, check the box for paraFrame and then click Edit (Fig a). In the pop up window (Fig b) select the ruling required such as topRule:Thin etc..
Fig a
Fig b
Select the PageDef in the format definitions column, click on the foreground textframe, then in the properties column increase or decrease the number of columns as required.
To change the size of a note image, edit the label width in the listLabel of the note ParaDef to the size required.
To include a product-specific cover image, add a DITA <data> element to the DITA map metadata which includes an <image> element referring to the required product image, for example:
Then reference this 'cover-image' graphic in the .mfd template as follows:
Import a placeholder image of your choice onto the cover page.
Resize and position the image as desired (this may require that the Image keepAspectRatio checkbox is unchecked, i.e. set to 'N').
Check the Image 'active' checkbox to make it a 'replaceable image', i.e. set to 'Y'.
Set the Image 'locationName' to 'cover-image' or whatever DITA <data> element name you have assigned.
When the DITA content is published, the active image will be replaced by the graphic referred to by the element @href, if available. If no element of that name has been defined in the DITA content, the graphic referred to in the .mfd template (in this case, miramo_logo.png) will be imported.
Note that:
This active image may be copied, pasted and resized to the same PageDef, or any other PageDef in the .mfd template - this can be useful when including (for example) a product logo in every page header.
DITAVAL filtering may be applied to use different cover images for different products, described by the same DITA map.
To change the general formatting of a <hazardstatement> in MiramoDesigner, select the 'hazardstatement' TblDef in the Format Definitions column and amend properties as required.
The Miramo DITA-OT plugin applies a built-in mapping of DITA elements to document objects and corresponding format definitions, based on the inheritance class of each DITA element (the DITA architecture @class attribute) and the context of the element, e.g nest level in the hierarchy. So, for example, a title element may be mapped to a 'chapter_title' ParaDef, or a 'topic_title1', 'topic_title2', 'topic_title3' ParaDef, depending on the context and nesting level of the original DITA title element. Similarly, a table element will, by default, be mapped to a 'table' TblDef etc. A technical writer does not need to take this mapping into account when writing DITA as it happens automatically. To determine which Format Definitions need to be amended to give the output design required, run the MiramoPDF Dev transformation (mmpdf:showProperties ant build parameter set to Y) and the resultant PDF displays which Format Definitions are used and where, allowing the MiramoDesigner template to be amended as required. By exception, if required, this mapping may be modified using ant build parameters, @outputclass values and, if necessary, via a customization and this is detailed in the Miramo DITA-OT plugin Getting Started Guide
To import 'Format Definitions' from one .mfd template into another, open the template you wish to add the 'Format Definitions' to. Click on 'File' in the menu, select 'Import', browse to the .mfd template from which you wish to import the'Format Definitions. A window will appear listing all the 'Format Definitions' in the selected .mfd template, these can then be selected and imported into the open template. This process is detailed in the Miramo DITA-OT plugin Getting Started Guide
To do this, make a new FontDef (for example, 'noteimage') which has vertical offset set to (for example) 20%, (percentage of font size downward shift):
Then apply it to the hazardstatement (or note) ParaDef listLabel:
Table footnotes can either be in a table footer (@footnotePosition=atfoot) or gathered and placed at the end of a table (@footnotePosition=atend). For tables which are on a single page, the behaviour will appear to be the same in either case as the difference only occurs when a single table spans many pages. To set table footnote behaviour, double click on the TblDef name, scroll down to the TblDefFootnotes section and select the footnotePosition required i.e atEnd or atFoot as described.
In MiramoDesigner, in the 'Format Definitions' column, select the ParaDef 'chapter_title'. In the 'properties' column, in the 'List label and autonumbering section', check the 'listLabel' check-box (if not already checked) and then click on the 'Edit' button. In the window that opens, click into the 'Label Format' section, right click and insert the variable required - in this case it would be the '$lang-chapter' variable.
In MiramoDesigner, click on the 'More' button in the bottom right-hand corner, select 'RunningTextDef', click on the green 'Add running text format' button and give it a name. Define a)whether the type is a 'Marker' or a 'Paragraph' and b) whether it displays the first or last instance of that paragraph or Marker on the page. Then create a marker name or select the ParaDef name or names which you would like displayed. For example, if you select 'last' instance and select 5 ParaDefs, the last instance of the first on the list of the 5 ParaDefs that appears on the page will be displayed in the Header/Footer.
Start a console window and enter the commandline: miramodesigner -reset
Modify the menucascadeseparator <VarDef> as illustrated below.
You can create a new variable by first inserting something like the following in the bookmeta
<data name="test">test test test</data>
then generate a new VarDef in MiramoDesigner by clicking on the 'More' button in the bottom right-hand corner, select 'VarDef' and then click on the green button 'Add a new user variable'. Name the variable 'test' or however it is defined in the DITA and close the window.
There are several variables available to choose from in the default template supplied with the Miramo DITA-OT plugin. To insert one of these variables on the cover page, double click into the background TextFrame of the Cover PageDef, right click, select 'Insert Variable' from the menu and then select one of the variables from the list displayed.
Multiple ParaDefs can be changed in one go. To do this, 'Crtl Shift Select' the range of ParaDefs that you wish to make a group change to, right click, select 'modify' and then, in the pop-up window, change the properties as required and click 'ok'.
In the 'format definitions' column, select the ParaDef to which you want to apply justification, in the 'Horizontal alignment' section, select 'justify' from the dropdown menu for the 'textAlign' field.
To create multiple foreground TextFrames, create or open an existing PageDef. Select the existing foreground TextFrame, right click and from the menu select 'Add new foreground TextFrame before' or 'Add new foreground TextFrame after' depending on your requirements. The foreground TextFrames are automatically numbered and can be dragged and dropped to the required positions on the page.
The term feathering refers to the act of adding small amounts of leading to aid in vertical justification of a column. In MiramoDesigner, feathering can be applied to a SectionDef in the 'Numbering, language and text properties' section. Note: The maximum amount of space added between paragraphs may be controlled on a per-paragraph basis by setting the @deltaSpaceAbove value (defaults to zero, in which case no feathering will be applied).
Column balancing can be applied to a SectionDef in the Numbering, language and text properties section by checking the 'balanceColumns' check box.
Hyphenation can be set for the overall document in the 'DocDef', in the 'Numbering, language and text properties' section, it can be set in a 'SectionDef' to inherit 'Y' or 'N' in the 'Numbering, language and text properties' section or can be set for a specific ParaDef in the 'Line breaking' section.
Page breaks can be controlled for a ParaDef in the 'Paragraph placement' section where you can define the positioning of the paragraph as follows: normal (default), topOfColumn, topOfPage, topOfLeftPage, topOfRightPage.
Select the 'step' ParaDef. In the 'properties' column. In the 'listLabel and 'autonumbering' section, click on the 'Edit' button beside 'listLabel'. This brings up a window that displays the 'list Label properties for step'. In the 'Label format' section there is a window with a counter represented by <c> add whatever pre-fix of suffix you require in this window.
MiramoPDF FAQs
A single channel license only allows jobs to be queued in a single queue (channel) on a first come first served basis. A dual channel license allows two jobs to be run simultaneously in two separate queues (channels). Channels can be assigned to different groups - for example, higher volume publishing groups can be assigned a dedicated channel while all other groups can be assigned to a second channel. The choice of number of channel depends on the volume of publishing and whether users need to publish simultaneously.
Miramo DITA-OT plugin FAQs
There are two possible reasons why you are seeing this message:
1. The DITA-OT integrator tool needs to be run. Here is a link to how to run the DITA-OT integrator in oXygenXML.
2. The version of the DITA-OT Toolkit used by OxygenXML is different to the version folder in which the plug-in is installed.
To edit the images in a <note> or <hazardstatement>, copy the DITA-OT3.x\plugins\com.miramo.mmpdf\images folder to a location outside the DITA-OT folder and set the path in the mmpdf:images.dir ant build parameter to point to that location. Then replace the appropriate image in this folder with the image you require.
To change note text, copy \DITA-OT3.x\plugins\com.miramo.mmpdf\cfg\strings folder outside the DITA-OT folder and set the path of the mmpdf:localization-strings.dir to point to that location. Then amend the specific language.xml folder or commonstrings.xml as required.
Here is an example of a 'many-to-one' footnote indicators:
The small dita topic below illustrates how to achieve this, by using multiple <xref>'s which target the same instance:
Miramo detects the presence of an <xref> immediately after a <fn>, and in this case suppresses the footnote number from the source paragraph body. The footnote indicators are all displayed using the 'footnote1' cross reference format, which by default displays the footnote paragraph number (a '1' or '2' in this case):
The Miramo DITA-OT plugin allows non-standard formatting to be applied using one or more space separated 'mmpdf:' @outputclass values, as described in the Miramo DITA-OT plugin Getting Started Guide.
then apply a pre-defined fontDef with the required color specified.
