mark@mekon

Creating a master page, colour definition and background page colour in Adobe FrameMaker

Creating a master page, colour definition and background page colour in Adobe FrameMaker from Mark Poston on Vimeo.

This video provides an example of how to create a new master page and colour definition in Adobe FrameMaker, and to then apply that colour as a background to the new master page.
It was created in response to a customer who recently asked how to do this.
This video contains no audio.

FrameMaker Adapter for the DITA Open Toolkit (Part 1)

Back in 2006 I initiated a project to develop a plugin for the DITA Open Toolkit that allowed users to publish their content into Adobe FrameMaker. This project was co-developed by Paul Prescod, formerly from BlastRadius, and Deborah Pickett from MoldFlow. Deborah is still active in the DITA Open Toolkit development community.

The adapter was developed before Adobe or anyone else had a DITA publishing solution within FrameMaker. It was developed as a solution for publishing only and as such did not create valid DITA content if saved. Instead, the adapter created XML through the DITA Open Toolkit that was "FrameMaker-friendly" – that is, it made the XML more suitable for importing into FrameMaker in order to support the specific features of FrameMaker (like conditional text, cross references, markers etc.).

At the time of developing the adapter, i was seeing a lot of companies migrating to DITA and needing to also migrate to another authoring tool. Having invested, however, in licenses for FrameMaker, I saw a great opportunity to allow these user to keep that investment and publish using their existing FrameMaker templates.

The basic operation of the Adapter was to use the DITA Open Toolkit's PDF output to create a single XML file (topic-merged) and to then apply the adapter's transformations to prepare it for importing into FrameMaker.

One of the key aims of the adapter was that it could publish any DITA content, regardless of its specialisation – I definitely didn't want to have to build a solution that meant maintaining an EDD for all possible current and future element types!! So, to supporting all specializations was achieved by generalising all elements back to their base form and to redefine the class attributes to a simplified form that a FrameMaker EDD can handle via its EDD context rules.

So, the XML imported into FrameMaker would change a <b/> tag into <ph class="ph-b"/>. This gave the ability to have a general rule in the EDD for the <ph> element and a more specific context rule based on the class attribute. This is similar to the DITA Open Toolkit as this approach still allowed the EDD to fall back to a default context rule when the EDD didn't have a more specific rule defined.

The FrameMaker Adapter also provided parameters that allowed for a number of user-defined options. These included:

• presenting definition lists as paragraphs or tables,
• putting titles before or after a table
• inserting a chapter heading element to allow for paragraph numbering
• inserting <codeblock> into a table
• specifying the default column width in FrameMaker
• opening a map as a single file, book with single file, or book with separate files.

Some of the other things that the adapter also handled were:

• converting some attributes to conditional text (only two attributes were supported)
• removing whitespace in the XML (seeing as FrameMaker seems to like it so much)

The adapter was used to publish the first edition of "Introduction to DITA" book. This exposed a few issues that were not implemented in the adapter. These were:

• graphics did not import at the correct size
• tables needed to be resized
• table of content and indexes were not created automatically

The resizing problems were partly resolved by defining a parameter in the adapter for the default width of the text column in the FrameMaker template. This, however, was not always enough. I therefore made use of Mekon's JavaScript API for FrameMaker called FrameAC. This solved a lot of issues that would otherwise have been tedious to fix.

After the initial development of the adapter I presented it, along with the Introduction to DITA as a case study, at a couple of DITA conferences including DITA Europe 2006 and DITA 2006.

(image of me at DITA 2006 from http://dita.xml.org/blog/don-day)

I am aware of a few companies that used the adapter, Moldflow being one, and a number of others who experimented more with it.

BlastRadius, being one of the developers of the adapter, were also including the plugin with their software for a while. They saw this as a way to let clients migrate to XMetaL whilst still letting them keep their investment in FrameMaker.

Mekon, too, use it now to publish our consultancy reports.

So, where are we now?

Mekon are now looking to further develop the FrameMaker Adapter to bring it up to the latest DITA standard and also to add some of the functionality that was missing in the original release. DITA 1.2 brings with it a lot more features that we also need to try and implement as some stage.

In Part 2 of this post I'll describe the work we are now doing to the adapter.

In the meantime, if there's anyone interested in knowing more about the adapter, it can be downloaded from the Open Toolkit site. Please also contact me directly if you like.

Converting to DITA using FrameMaker Conversion Tables and XSLT

Adobe FrameMaker has always had the ability to convert unstructured documents into structured files. This is a very powerful feature of FrameMaker but has some limitations that mean that getting a perfect conversion directly with this feature is not possible.

On a recent project to convert unstructured FrameMaker files into DITA I had the challenge of converting what looked, on the face of it, pretty well formatted documents. On closer inspection, however, the documents had a lot of overrides that would make any conversion a lot more problematic.

Apart from the usual non-sequential use of heading styles (i.e. Heading 1 > Heading 3 > Heading 4) nearly every use of character formatting was an override in either bold or italic. Lists too were heavily overridden. Definition lists were in tables. Figures had titles below the images.

So, I knew that FrameMaker’s conversion tables would not be able to do a complete job at converting these files. Conversion tables have no logic built into them so it makes it very difficult to decide how something should be structured. Therefore, I have a slightly different plan to get these files converted.

I used the conversion tables to tag up as much information as I could and to get the main DITA structures in place. I populated the outputclass attribute with information about the styles that were being converted. I also didn’t worry about the incorrect use of headings.

The result of these conversions tables was a fully structured XML document that didn’t conform exactly to DITA but at least was well formed.

The next steps are where valid DITA was created. I exported the FM structured files to XML without passing them through any FrameMaker Structured Application. I would use XSLT to get to work on the XML files and fix as many of the issues as I could this way.

Some things were easy to resolve – tables as definition lists were easy enough to map into the correct XML structures. Figures were easy enough to fiddle the ordering of elements. But lists and nested topics were more of a problem due to the original markup. And how would I make any sense out of the character overrides that were used throughout the content?

Having only a limited time to convert the documents I didn’t want to spend hours nad hours trying to fix issues that would ultimately be easier to do manually. So I did only a little work on lists and nested tables to ensure that they were atleast structured correctly. Users could then easily move things around in the FrameMaker structure view to fix them.

So this left the character formatting. Because the documents I was converting were for a computer user manual there were many instances of overrides that could map directly to tags in DITA. So instead of just mapping everything to tags I used a little more logic to do the job.

Using XSLT, I looked at the words before, after and within each tag to try and establish what the meaning actually was. Picking out words such as Window, Screen, Click, Button, Menu etc. I was able to identify the majority of these overrides and tag them with the correct DITA elements.

In summary, FrameMaker’s conversion tables are a very powerful tool when wanting to convert content into XML. This is especially the case if companies have already invested in FrameMaker, but even if not, a licence of FrameMaker to help with the conversion is well worth it. I have used them for a lot of projects, even when the source documents are in Word format. To think that they will do a perfect job out of the box, though, is a little optimistic in a lot of cases. Therefore, by using a combination of FrameMaker and XSLT a better result can be achieved.

from Space Invaders to Mekon

As the first post to my new work-related blog I thought it would be interesting to describe how I got to being a consultant at Mekon and how my previous education and interests have helped me along the way. I was not originally planning to work in the field that I am in now, but there were probably signs that I would be destined for something related to publishing for a long time before.

My earliest recollection of a computer are those that my father used to bring home from work in the 1980′s. We also had a ZX81, and not fully understanding what I needed to do to write my first Space Invaders game I wrote:

10 PRINT "SPACE INVADERS"

To my disappointment, when I ran this program, I didn’t end up shooting at little aliens moving back and forth across the screen. I soon realised that there was more to it! Still, it was the thought that counted!!

My main interest when younger was in writing music. Whilst at school, with my BBC Micro computer, I was already using it to compose music and also to produce sheet music. I had a sequencer program that also let me create scores and print on a dot matrix printer. I remember at the time my music teacher being impressed with how a computer could produce music scores.

My original aim was to have a career in music in some way – not as a performer but more on the writing, production and publishing side.

Having completed my ‘A’ levels I did not go straight to university. Instead, I ended up working for a civil engineering company in the Noise and Acoustics division. What attracted me to this job (my first “proper” job”) was the word “acoustics”. Somehow I thought it might have some bearing on my musical interests. It turned out to be a job mainly involving calculating the noise impact on local residents of new road schemes in the UK. But thee were some projects that dealt with acoustics in buildings too.

As part of this job I completed a post-graduate course in Acoustics and Noise Control. This was attended mostly by professionally qualified Environmental Health Officers (EHOs). During this course I used my interest of music to complete a project that measured the sound insulation of music rooms in a small school of music my friend worked at.

So after that, I ended up studying on a four-year degree course in Environmental Health in Cardiff and being sponsored by Portsmouth City Council. At the time I started the degree there was a shortage of EHOs and so I thought this was a good career move for me. Whilst I was at university I still kept my interest in music, and in fact, started to run a little music publishing business of my own. I provided music typesetting services to a number of music colleges and publishers in the UK and sold sheet music. This paid my way (and helped my friends out) through university. I used a combination of QuarkXpress, Ami Pro and Finale notation software to product music textbooks and sheet music. I also used a product called Score which at the time was a DOS-based music notation program. I even learnt the PostScript language and developed an application to create manuscript paper in all sorts of different ways!

On the music front I was still writing and arranging and worked on arrangements for a music college production of Guys & Dolls and some dance accompaniments for some friends. I also co-wrote a musical that was performed in Cardiff and at the Edinburgh Fringe Festival.

Having completed my degree I found that there was no longer a shortage of EHOs and found it difficult to find a job in local government. After going to a load of interviews only to find that I did not have enough experience or was over qualified for other jobs I decided to find a temporary job.

I ended up finding a contract position at BOC Edwards High Vacuum where I was responsible for providing a system that allowed product information to be delivered to their worldwide sales team. I introduced Adobe Acrobat to the company for this solution which ended up being far better than the Word-based files they had wanted me to create. I remember asking the documentation specialist what authoring tool I should use for technical writing – only to be told that they were not really suitable for me!

By then I was getting interested in becoming a technical author.

I ended up discovering FrameMaker and calling Adobe to find out more about it. I had been asked to develop a CDRom-based solution for an Environmental Health consultant who wanted to deliver Government leaflets on a searchable CDRom. I wanted to use FrameMaker and Acrobat for this. Adobe, put me in touch with Mekon, whom I finally purchased FrameMaker 5 from. I had also asked that they consider me for any out sourcing work that they might be able to give me. I got one project from them. I remember having to take out a loan to buy this software.

Since I had qualified as an Environmental Health Officer I was also still applying for work in that area and eventually was offered a job as a meat hygiene inspector at a slaughterhouse. I was very nervous about starting this job and on my way up to start my first day I had a change of mind. Instead, I decided to drive to Mekon’s office and with the intention of asking them for a job!!

Luckily, I think the timing was just right for me, and was offered a job. At the time I didn’t mind the 140 mile round trip every day as it was a job that I was really interested in doing.

So there you have it … I’d gone full circle … My introduction to computers was by trying to write a Space Invaders game nearly 30 years ago … and now I work for a company named after a little green space invader … the Mekon!

… and now I’ve been there nearly 14 years.