framemaker to xml conversion options - tekom

FrameMaker to XML Conversion Optionstekom tcworld 2013 Wiesbaden, Germany

1

Pleased

© S

crip

to b

vba

Pleased to meet you

■ Scott Prentice:

■ President of Leximation, Inc.

■ Specializing in FrameMaker plugin development as well as structured FrameMaker conversions, consulting, and development

■ FrameMaker user/developer since 1991

■ Developed DITA-FMx, a FrameMaker plugin for efficient DITA authoring and publishing

■ Offers consulting for custom Help systems, creative/functional web applications, and EPUB solutions

to meet you
385

Pleased

© S

crip

to b

vba

Pleased to meet you

■ Yves Barbion

■ Managing director of Scripto

■ FrameMaker user (not developer) since 1993

■ DITA coach/instructor

■ Adobe-Certified FrameMaker Instructor

to meet you
2

About Sc

© S

crip

to b

vba

About Scripto

■ Technical writing

■ Consulting

■ Training:

■ Structured authoring and information modeling (DITA)

■ Technical writing

■ Adobe FrameMaker

■ Content screening

■ Content (strategy) audit

■ See also: www.scripto.nu

ripto
3
http://www.scripto.nu

© S

crip

to b

vba

FrameMaker to XML via MIF2Go

1

Caution:

Caution: valid vs. well-structured DITA content

■ Valid DITA content is not necessarily well-structured DITA content

■ Conversion to valid DITA content: automated

■ Conversion to well-structured DITA content: human effort

✔ Demo: just valid vs. well-structured content

valid vs. well-structured DITA content
4

Conversio

Conversion vs. restructuring: example 1

■ Original:

■ Converted:

n vs. restructuring: example 1
5

Conversio


■ Original:

■ Restructured:

6

Conversio

Imth


■ Original:

■ Converted:

■ Restructured:

1 Click on Preview. You should see that this output creates a PDF of the 3D view only.


port graphics at 270 dpi. They appear 1:1 when displayed full screen in Acrobat, because e zoom factor is approx. 280 %. Thus: 96*2.8 = 268.8, rounded off to 270

7

About th

First sec

© S

crip

to b

vba

About the source file

■ Unstructured FrameMaker 11

■ Style-based DITA:

■ Content model: part > chapter > topic > section

■ Paragraph formats: parttitle <H1>, chaptertitle <H2>, topictitle <H3>, sectiontitle <H4>

■ Character formats: uicontrol, wintitle, filepath, codeph...

■ “Typical” FrameMaker content:

■ Variables

■ Conditional text

■ Table formats

■ Cross-references

■ Illustrations

e source file

tion title

■

Import graphics at 270 dpi. They appear 1:1 when displayed full screen in Acrobat, because the zoom factor is approx. 280 %. Thus: 96*2.8 = 268.8, rounded off to 270

385

DITA: you

© S

crip

to b

vba

DITA: your content’s “fil rouge”

© Scripto

Texteditors

Desktoppublishing programs

XMLeditors

Contentmanagement

systems

StructureROI

# Content# Authors

r content’s “fil rouge”
25

Conversio

Imth

Conversion to DITA: process

Unstructured FrameMaker

book

DITA (book)map

Generated FrameMaker

book

PDF

MIF2Go Framescript DITA-FMx

Acrobat DistillerAcrobat Distiller

n to DITA: process


8

Conversio

Conversion to DITA XML: toolset

■ Adobe FrameMaker

■ Scripts: Extendscript and/or Framescript

■ Optional, but handy: oXygen XML Author

■ MIF2Go:

■ FrameMaker plugin developed by Omni Systems Inc.

■ Jeremy Griffith

■ Converts Fm to HTML, XML, RTF and Help formats

■ $US 295 per seat

n to DITA XML: toolset
9

Establish

Imth

Establish a conversion environment1

■ Use a local copy (performance!)

■ Conversion project folders; keep source and target separated:

✔ Copy the original files over to the “optimized” folder

1. Source: MIF2Go Help

a conversion environment


10

Prepare y

Prepare your documents for conversion

■ Read chapter 2 “Planning a conversion project”1

■ File and folder names:

■ No spaces or special characters in file or path names (graphics!)

■ Book name must not duplicate a chapter name

■ No duplicate chapter names in a Fm book

■ FrameMaker format names:

■ Do not use identical names for paragraph formats and character formats

■ Do not use format names that differ only in case (“Body” vs. “body”)

■ Do not use reserved (= , ; [ ) characters or wildcard (* ?) characters (Heading4;topictitle)

our documents for conversion

1. MIF2Go Help

11

Prepare y


■ Update your FrameMaker files

■ Check “unresolved cross-references”:

■ If unresolved xrefs in the same book: fix them now

■ If unresolved xrefs to other books: fix using <reltable>

■ Fix cross-references to and from text insets

■ Conditional text:

■ See 14.12 “Converting conditions to DITA attributes”

■ Show the conditions that you want to have in your DITA output

■ Content that remains hidden in Fm is not included

■ Avoid spaces in condition attribute values

■ Check text edits: enable, accept all/reject all

12

Prepare y


■ Content model

■ Section in the book paradigm:

■ Section in DITA:

■ Line breaks (“forced returns”, SHIFT+ENTER): converted to spaces

■ Custom ruling and shading in tables (requires PIs and/or @outputclass)

■ Icons using special fonts ( → 3 9 6)

■ Character-based formatting: artificial bold (CTRL+b), italics (CTRL+i) or underline (CTRL+u)

volume > part > chapter > section > topic

part > chapter > topic > section

13

Prepare y


■ “Disambiguate1” formats:

■ Same presentation but different usage

■ <b> can be <b>, but also <wintitle>, <uicontrol>, <keyword> etc.

■ Use dedicated formats or markers

■ Turn off hyphenation (Framescript!)

■ Check your content for context-specific references:

■ “in the following chapters”

■ “can be found later on in this Section”

■ “on the next page”

■ “as you can see in the red text”


14

Prepare y

Imth


■ Check the graphics:

■ No missing graphics

■ No spaces in file names

✔ Run the “Get Image Paths” Framescript

■ Graphic file format (EPS, PNG, GIF...) supported by the output format?

■ Avoid OLE objects!

■ Replace embedded graphics (“Copy Into Document”) with referenced graphics (“Import By Reference”), using MIF2Go or a Framescript

✔ Run the “Replace embedded graphics” Framescript

■ Scaling and Fm dpi (otherprops=”fmdpi:144”)

■ Graphics cropped by the anchored frame



15

Set up MI

Set up MIF2Go

■ The MIF2Go manual is (or should be) your friend

■ Enter the _m2dita.ini

■ Let’s go:

1 Convert a FrameMaker source file to DITA XML.

2 Check the conversion results in oXygen XML Author

3 Take a closer look at the details

F2Go
16

Let’s chec

Imth

Let’s check the conversion results

■ Graphics: embedded vs. referenced

■ Structure of the ditamap

■ Typographics (underline, italics...)

■ Nested lists (search for “representation characteristics”)

■ Conditional text (search for “restrictive sub-attribute”)

k the conversion results


17

DITA top

First sec

© S

crip

to b

vba

DITA topic types: assignment precedence

■ Default type = concept

■ Precedence1

Precedence Method

Highest DITAtopic marker

Intermediate FrameMaker paragraph format

Lowest Default topic type


ic types: assignment precedence

tion title

■


385

Remove

First sec

© S

crip

to b

vba

Remove content during the conversion

■ Stem sentences:

■ “Proceed as follows...”

■ “Follow these instructions to...”

■ Discussed on Yahoo dita-users and dita.xml.org

■ In _m2dita.ini: stem=Delete

content during the conversion

tion title

■


385

http://groups.yahoo.com/neo/groups/dita-users/conversations/topics/9662

http://dita.xml.org/wiki/stem-sentences

Converti

First sec

© S

crip

to b

vba

Converting FrameMaker variables to conrefs

■ VariableType = Conref converts Fm variables to conrefs

■ Each variable is a definition term <dt>

■ Definition term <dt> = variable name

■ Definition description <dd> = variable definition

■ All conrefs are saved in a single “warehouse” topic: conref library file

ng FrameMaker variables to conrefs

tion title

■


385

tcworld conference 2013 - Wiesbaden, GermanyScott Prentice, Leximation, Inc.

FM XML

Converting FrameMaker Content to XML

IntroductionScott Prentice, President of Leximation, Inc.

Specializing in FrameMaker plugin development as well as structured FrameMaker conversions, consulting, and development. FrameMaker user/developer since 1991.

Developed DITA‐FMx, a FrameMaker plugin for efficient DITA authoring and publishing.

Offers consulting for custom Help systems, creative/functional web applications, and EPUB solutions.

Conversion tables vs. Mif2GoFrameMaker conversion tables

Allows for manual “adjustments” before XML export

Easier to get started (IMHO)

Mif2Go

Good if your documents are rock-solid consistent

Offers more features “out of the box”

Conversion “tools”FrameMaker (from FM7.1 on up)

DTD files (XML model)

Structured application

Conversion table

Scripting and/or plugins (FrameSLT, FM2DITA, or ?)

Structured Application Developer’s Guide/Reference (they are your friend!)

Structured applicationInstructs FM how to apply formatting to elements and provides validation rules

DTDTemplate (with embedded EDD)Read/write rulesOptional XSLT processing

May need separate structured app for conversion/authoring

Conversion table basicsMap styles and objects to elements, optionally set attributes

Wrap elements in other elements

(1/2)

Conversion table basicsMake effective use of qualifiers

Add a “Notes“ column and formatting

Can apply to single file or entire book

Creates structured FM binary file

(2/2)

Creating a conversion tableAnalyze styles and objects in FM files

Create document with examples of all tags and objects

Start with .. StructureTools > Generate Conversion Table

Rearrange rows into logical groups

Map objects to elements

Wrap elements in other elements

Test, then add more mappings and wrappings (repeat)

Potential issuesConversion table only maps “named” styles and objects; overstyled tagging is lost

Consistent use of tags is very important

Only the “main flow” exports to XML

Multiple graphics or objects in a frame “may” merge into CGM file; better to clean up graphics, remove callouts

(1/4)

Potential issues Tabs and forced line breaks are lost unless specialarrangements are made

Conditional text can be difficult (especially inline)

Cross-references will require scripting to re-link

User variables turn into entities (typically not useful in XML)

Text insets may not convert properly (depends on content)

(2/4)

Potential issuesFor DITA, tables with titles end up in the wrong place

Custom table shading and rules can be difficult to convert

Table layout is based on table format properties

Don't use tables for formatting (like fancy “note” paragraphs)

(3/4)

Potential issuesOrder of source content may not match the data model

Each “topic” needs an ID

If naming topics based on titles, collisions are possible

Typically shouldn't convert title page and generated files (toc, index, etc)

Certain element types have restrictions on content, cross-ref and marker must be empty

(4/4)

Typical conversion processCleanup FM files (retag, rewrite, ?)Apply conversion table to bookImport EDD and template into structured FM filesCleanup and validate structured FM files (FrameSLT helps!)Export to XMLPossible additional cleanup via XSL or other scriptingOpen XML in Frame using structured application to validate

DEMO TIME!Walk through conversion table

Apply conversion table, show problems and how to fix

Convert entire book

Perform cleanup

Export XML files

If time allows .. generate FM book from DITA map then save to PDF!

Thanks!Resources:

Structure Application Developer’s GuideFrameSLT from West Street Consulting

Questions?

Scott Prentice <scott AT leximation.com>Leximation, Inc. - www.leximation.comTwitter @saprentice and @leximation

framemaker to xml conversion options - tekom

Documents