Easy steps to convert your content to structured (frame maker and xml)

Easy Steps to Convert Your
Content to Structure
Bernard Aschwanden
www.publ ishingsmar ter.com
bernard@publ ishingsmar ter.com
11:48
1
@publishsmarter

About this session
2
 Using sample (unstructured) files, we’ll created
structured
 Touch on high level common pitfalls of content
conversion
 We convert content including:
 Character tags
 Paragraph tags
 Table tags
 Also discuss considerations when converting legacy
content
@publishsmarter 11:48
 MANY SLIDES, so it will feel quick. Review the video!

But wait... There’s more!
 Since this is about
converting to structure...
 I’ve included info on using
structured Frame as an
author
 It’s basic, but it’s enough
to get you to create a bit
of DITA content
 Early slides, covered
quickly as they are not
core (look for ‘thumbs up
guy’ to flag them)
3

Rule 1: Know your audience
4
 Hopefully you are generally familiar with
FrameMaker
 You can create unstructured content
 You use character, paragraph, and table tags
 You should be interested in the ideas related to
structure
 You do NOT need to know the tech (techniques or technology)
 Samples created and shared, but require FM12
 Contact info at the end (you can review the recorded
session, ask for files, and try all this yourself as well)

Housekeeping and note taking
 Not all slides (lots of them!)
or topics are equally
weighted
 Use some, discard others
 Slides speed varies
(reference)
 Questions? Ask along the
way!
 I’d love to claim
errors/typos is on
purpose… they isn’t,
weren’t never, and ain’t; I’ll
fix ‘em as I can…
5

About your speaker
 Publishing Smarter:
President
 Content strategist,
publishing technologies
expert, author, and geek-enough
 Certified Technical Trainer
 DITA
 Content management
 Topic-based writing
 Society for Technical
Communications
 Vice President
 STC Associate Fellow
6

Services
 We help clients:
 Create great content
 Manage content as an
asset
 Deliver content the right
way
 Socialize the message
 Listen to the consumer
 Improve experiences by
helping
 Create great content
 Manage content as an
asset
 Deliver content the right
way
 …
 By helping clients:
7

Standard disclaimer
 In the interest of brevity I
will make some blanket
statements to keep it
simple
 It’s not all 100% “the
truth”, but I’ll stay close
 Purists may complain
 And they are wrong!
 (except when they are
right)
8

Basics of Structured
FrameMaker
9
Setup of FrameMaker, creat ing a
sample f i le, and conf igur ing the
workspace, al l whi le using 100%
defaul ts

Select Edit > Preferences (to setup FM)
10
1
2
3

Relaunch, File > New > XML
11
1
2
3

By default you see this (or similar)
12

Change to a structured author mode
13
1
2

Structure View: Hierarchy of content
14

Element Catalog: Contextual list
15

Create (and Save) your own workspace
16
1

Click in <Enter title here> and do so
17
1

Content in doc and in Structure View
18

Inline: View > Element Boundaries (as Tags)
19

Continue to edit using the defined rules
20

Unstructure to structure
21
Pi t fal ls to know about and t ry to
avoid, and the workf lows to fol low

Be careful of some standard challenges
 Have a good idea of the
structure you want
 Understand what can
and cannot be supported
 DITA, for example:
 Frames can only have one
thing in them (one image,
no callouts, captions,
other Frame stuff)
 Ideally avoid inline linking
 Unique topic types
 The more you know, the
easier the conversion will
be
 Some source content
may cause corrupt
conversion without a
MIF-washing
 File > Save As > [mif and
then reopen and save as
FM]
 Other issues may exist
 For demo, samples are
used (and available by
22

About the sample files
 Samples are very basic
 Designed to allow you to
do the same thing and
learn
 We do NOT convert the
most complex content
 It’s important to have a
basic understanding of
structured authoring and
more (non-FrameMaker)
ideas if you consider
conversion
 Experts (including me)
can deliver formal
training
 Companies (including
mine) can provide
migration as a service
 Knowing what you need,
how to explore it, and
what is legit helps make
the right decision.
23

General list of samples
 001 files
 Used only to convert a set
of paragraphs
 No conversion table
provided
 You can create one based
on information in this
slideshow
 002 files
 Used to convert
paragraph and character
tags
 Basic starting point
conversion table provided
 003 files
 Convert nested content
 Convert a bullet list to
nested list items within a
specific type of list
 004 files
 Includes a very basic table
 BUT WAIT... There’s
more!
 Also including some EDD
to try to build on your own
24

Converting paragraphs
25
The 001 f i le set : Enough to get you
s t a r t e d , a n d t h a t ’ s a b o u t i t
A lot of images to reduce note taking!

Basic paragraph level formats
26
Title
Body

Structure Tools > Generate Conversion
Table
27
New

The most basic of conversion tables
28
Wrap this object or objects In this element With this
qualifier
P:Title Title
P:Body Body

A bit of detail on the columns
29
Wrap this object or objects In this element With this qualifier
P:Title Wrap this object or objects In this element Title
With this
qualifier
P:Body P:Title Title
Body
P:Body Body
When a paragraph
named Title or a
paragraph named Body
is found... ...take that tagged
content and wrap it
into a named
element

Files we are about to work with
 001_ParagraphsOnly.fm
 Contains three
paragraphs
 Title, two Body
 Goal is to convert it to a
structured file
 Default conversion will
be limited function
 The conversion table is
currently unnamed, but...
 001_ConversionTable.fm
 Not provide, create your
own and use File > Save
As.
 Basic table with 3 columns
 Column 1 has an ID for an
object type (P:, C:, E: etc.
for paragraph, character,
element, etc.)
 Column 2 is the name to
be assigned to the
element
 Column 3 does not matter
at this point in time 
30

Initial steps to take
31
 Ensure both files have been saved with logical
names
 Switch to the open, unstructured
001_ParagraphTags.fm
 Select Structure Tools > Utilities > Structure
Current Document and use the conversion table
 Review the resulting document

Resulting document is a bit short of the goal
32

Conversion tables are an iterative process
33
 Review the resulting doc and compare with your
goals
 If correct, then great. You are done.
 If incorrect
 Close the converted file, update the conversion table
 Switch to the source, select Structure Tools > Utilities >
Structure Current Document and use the conversion table
 Review the resulting document and compare with your goals
 If correct, then great. You are done.
 If incorrect
• Close the converted file, update the conver.... Easy pattern, right?
 This means you need to know some standard
syntax!!!

Standard syntax
34
 This syntax will serve you well to get started, and
also if working with developing additional things (like
an EDD)
Symbol Function Sample
, (Comma) In specific order Title, Intro, Section
| (Pipe) In any order Figure | Table | Map
* (Asterisk) Zero or more Title, Intro, Section*
+ (Plus) One or more Title, Intro, Section+
? (Question) Zero or One Title, Prolog?, Intro,
Section+
Parenthesis Grouping Title, Intro, (Section | Table)

Updated conversion table
35
Wrap this object or objects In this element With this
qualifier
P:Title title
P:Body P
E:title, E:p+ concept

Revisions to the conversion table
Change to the case
(from Title to title) Renamed from
Body to p
Wrap Wrap this this object or object objects or In objects this element In With this this
element With this qualifier
qualifier
P:P:Title Title title
title
P:Body P
P:Body p
36
IF the element title is followed
by (the comma) 1 or more (plus
sign) elements named p, then...
...take that combo
and wrap it into a
concept

We now have a valid highest level
37

Elements are giving the updated names as
well
38

Iterative process continues
39
Current Document and use the updated conversion
table
 NOTE: The conversion table does NOT have to be saved for
testing. This lets you experiment, mess it up, and File >
Revert to Saved.
goals
 If incorrect

Paragraph and character tags
40
The 002 f i le set : Updat ing what we do
wi th paragraphs, and adding
character tag conversion as wel l

Title and Body still here, but also Emphasis
41
Title
Body
}
Emphasis

Addition of 2 sections with Heading1 and
Body
42
Heading1
Body
}

Structure Tools > Generate Conversion
Table
43
Update

Resulting appearance after Update (added
info)
44

A bit of detail on the columns
45
P:Title title
P:Body p
P:Heading1 Heading1
C:Emphasis Emphasis

What we are about to work with
 002_ParaAndCharaTags.
fm
 Contains Title, Heading1,
Body, and Emphasis
 Goal is to convert it to a
structured file
 Default conversion based
on what’s already done
 002_ConversionTable.fm
 Basic table
 Column 1 has an ID for an
object type (P:, C:, E: etc.
for paragraph, character,
element, etc.)
 Column 2 is the name to
be assigned to the
element
 Column 3 does not matter
at this point in time 
46

Initial steps to take
47
 Ensure both files have been saved with logical
names
 Switch to the open, unstructured
002_ParagraphTags.fm
Current Document and use the conversion table
 Review the resulting document

NoName at the highest level AND Heading1
48

Conversion tables are an iterative process
49
goals
 If incorrect

Updated conversion table
50

Revisions to the conversion table
51
Maybe going from Heading1 to
title will do the trick
(TIP: No. It won’t)
P:Title title
P:Body p
P:Heading1 title
C:Emphasis Emphasis

We end up with a LOT of concepts but not
valid
52

On the bright side, we have updated names
53

So let’s change the rules
54
 Remember that third column?
 Let’s put it to use
 Allows you to name elements the same, BUT to
provide a temporary unique value for conversion

The first (of many) paragraph rules
55
Qualifier column updated to allow
two elements to have the same
name, but for unique functions
P:Title title ConceptTitle
P:Body p
P:Heading1 title SectionTitle
C:Emphasis Emphasis

Update to the <concept> to use the qualifier
56
If the title has a ConceptTitle
qualifier, then use it
P:Body p
E:title[ConceptTitle], E:p+ concept
C:Emphasis Emphasis

Creating a <section> using SectionTitle
57
If the title has a SectionTitle
qualifier, then use it
P:Body p
E:title[ConceptTitle], E:p+ concept
C:Emphasis Emphasis
E:title[SectionTitle], E:p+ section

Calling the <section> to create a <concept>
58
If there is one or more complete
section after <title> and <p>...
P:Body p
E:title[ConceptTitle], E:p+,
concept
E:section+
C:Emphasis Emphasis

Working with character tags
59
 By default, they are neatly nested in most cases
 Renaming is done the same as with other samples
so far
P:Body p
E:title[ConceptTitle], E:p+, E:section+ concept
C:Emphasis em

Net result of the change
60
 Once applied, the content converts correctly
 Due to the longer/larger structure I turn off
boundaries
 Work with the Structure View (and get comfy there)

Renamed (View > Element Boundaries (As
Tags)
61
Click + or – to expand/
collapse, or Shift+click to
do the same to siblings

Nested paragraph tags
62
The 003 f i le set : What about complex
nest ing, such as a l ist

Earlier sample updated to include Bulleted
63
Heading1
Bod
y
Bulleted

So what if I use an existing conversion table
64
 This is the previous conversion table
 No support at all for Bulleted
 Slight re-org to move concept/section together
P:Body p
C:Emphasis em

Impact of no rule for Bulleted
65
The Bulleted source has no
conversion rule, and defaults to
Structurally invalid! That’s bad.
With no rules on how
to handle Bulleted
content, it is just plain,
unstructured text
Body format

Making a bit of room for the list components
66
P:Body p
C:Emphasis em

Converting the source paragraph to item
67
P:Body p
P:Bulleted item
C:Emphasis em

Putting one or more item into a list
68
P:Body p
P:Bulleted item
E:item+ list
C:Emphasis em

Adding support for an optional list
69
P:Body, list? p
P:Bulleted item
E:item+ list
C:Emphasis em

Now the conversion table handles nested
lists
70
The rules are defined for Bulleted
Structurally valid! That’s good.
A properly nested list
element is inserted
and it contains one or
more item elements
and the formats are retained

Converting tables
71
The 004 f i le set : Al l that we have so
far THEN ADD a nested table!

Earlier sample updated to include Table
72
Table Title
Table Heading (1 row)
Table Body (Many rows)
Rows have Table
Cells
(with paragraph
tags)

An existing conversion table won’t work
73
 No support at all for Table or related content
P:Body, list? p
P:Bulleted item
E:item+ list
C:Emphasis em

Structure Tools > Generate > Update
 This generates the worst
conversion table update so
far
 It is so horrible, I don’t even
want to show you it
 At least, not in a slide (yet)
 Tables are complex
structures
 If you know HTML you will
agree
 If you don’t know HTML, you
will agree when we are done
 BUT THEY ADD SO MUCH
VALUE
 So, I’ll show you what
happens
 Conversion table will add
support for:
 Paragraph tags
 Table Title
 Cell Heading
 Cell Body
 Table tag
 Format A
 Table components
 Title
 Heading
 Body
 Footing
 Row
 Cell
74

I can’t fit all this on one slide, and have it
readable
75
P:Body, list* p
P:Bulleted item
E:item+ list
C:Emphasis em
P:TableTitle TableTitle
P:CellHeading CellHeading
P:CellBody CellBody
T:Format A FormatA
TT: TITLE

At 9 point I can show it all, but don’t read it!
76
P:Body, list* p
P:Bulleted item
E:item+ list
C:Emphasis em
P:CellBody CellBody
T:Format A FormatA
TT: TITLE
TH: HEADING
TB: BODY
TF: FOOTING
TR: ROW
TC: CELL

I’ll leave the Body content, and focus on
tables
77
P:Body, list* p
P:CellBody CellBody
T:Format A FormatA
TT: TITLE
TH: HEADING
TB: BODY
TF: FOOTING
TR: ROW
TC: CELL

Now the conversion table handles tables
78

Once you HAVE structure...
79
You st i l l need to consider how you
plan to manage templates, EDD,
roundt r ipping of content

Don’t let vendors fool you!
80
 It is work to set up ANY environment that is custom
 You need to plan and build, in ANY tool...
 Consider a custom home and what you need:
 Property (and surveyors, inspections, prep work)
 Permission (building permits, electric, sewer, water)
 Money (and that may mean a plan to the bank as well)
 Support (family, friends)
 Contractors (unless you can do electrical, paint, concrete,
plaster, plumbing, roofing, framing, etc...)
 It takes time. It takes money. So does custom XML.

Working with custom XML
81
 I have shown you conversion tables for legacy
content
 You would still need to work with
 Templates
 Element Definition Documents (EDD)
 Read/Write Rules
 Structured Applications
 Etc.
 Start with something easier
 Adobe includes a complete solution via DITA; start
there!

But if you really want to create an EDD
82
 Know the general rules you want to work with
 For demo, let’s assume a basic memo document
 The plan might start with Memo contains Open, Body
 Opening has Re, To, From
 Body may have unique rules
 Once you know the rules, you also need to create
supporting content
 Need to develop formatting for this as well
 Therefore a template is needed
 Remember that things may change as you
implement

Core EDD definition
 Structure Tools > New EDD
 File > Save As (mine is
EDD001)
 Populate as needed
 Element (Container): Memo
 Valid as the highest-level
element.
• General rule: Open, Body
 Element (Container): Open
• General rule: Re, To+, From
 Element (Container): Re
• General rule: <TEXT>
 Element (Container): To
 Element (Container): From
83

EDD002 modifications
 Added some more
content
 Element (Container): Body
• General rule: Para+
 Element (Container): Para
 Included format for Re
 Element (Container): Re
• Text format rules
1. In all contexts.
Use paragraph format:
Heading1
84

EDD003 and template testing
 EDD003.fm contains all
the rules and format info
 Import into template
 File > New > Portrait
 This doc has Heading1
and Body in it already
 File > Import > Element
Definitions (all check
boxes)
 Once imported, test it
 There are a lot of
additional things that
could be added
 To cover them is days of
training and hands-on
 A more involved sample
(and still really basic) is
provided with EDD004
 Try the same... Open the
EDD, then File > New...
Then File > Import >
Element Definitions...
Test
85

Where you are now
86
Giving a bi t of scope

What do you know about conversion
87
 Enough to be dangerous
 So go and try the samples, get a rough idea of how it
works
 To develop custom environments you also need to
know:
 How to create templates for unstructured use
 How to work with structured writing (DITA is a good starting
point)
 How to create a basic Element Definition Document (EDD)
 How to customize the EDD and attach formats
 How to work with read/write rules
 And a bunch of other stuff I’m not going to list... Why not?

If you really want to get started...
88
 Work with DITA first
 The tools are already in FrameMaker
 Get to know how to write structured content there
 Then review your materials and see what works for
you
 If DITA works, convert (or contract someone) to it
 If DITA does NOT work, then look to other options
 There are many that are predefined including S1000D, and
many that other companies support already... Sometimes it is
easier to buy your solution rather than to build it... After all,
who builds their own home, car, or even computer anymore?

Conclusion and contact
89
Summing up the discussion,
and opt ions to cont inue i t

About this session
90
 Intro to the basics of Structured FrameMaker
 Using sample (unstructured) files, we’ll created
structured
 Included is common pitfalls of content conversion
 We convert content including:
 Character tags
 Paragraph tags
 Table tags
 Also discuss ideas when converting any legacy
content

Follow up contact information
91
905 833 8448 (Eastern Time)
bernard@publishingsmarter.com
www.linkedin.com/in/bernardaschwand
en
@publishsmarter
www.publishingsmarter.com

Easy steps to convert your content to structured (frame maker and xml)

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Was ist angesagt?

Was ist angesagt? (15)

Andere mochten auch

Andere mochten auch (20)

Ähnlich wie Easy steps to convert your content to structured (frame maker and xml)

Ähnlich wie Easy steps to convert your content to structured (frame maker and xml) (20)

Mehr von Publishing Smarter

Mehr von Publishing Smarter (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Easy steps to convert your content to structured (frame maker and xml)