Tregner Thomas - MADCAP FLARE FOR PROGRAMMERS : a guide to getting the most from flare

MadCap Flare for Programmers: A guide to getting the most from Flare

Thomas Tregner

Thank you for purchasing MadCap Flare for Programmers: A guide to getting the most from Flare.We hope you enjoy the book and find it useful.

Best Regards,
Tom Tregner and David Owens
June, 2015

MadCap Software is dedicated to providing leading-edge software that addresses the many ways people obtain their information, whether it is in print, on the Web, or on a mobile device. Technical communicators, marketing managers, clinical documentation specialists, user assistance managers, and policy specialists across a wide range of industry verticals use our software to create, manage, and publish content quickly and efficiently.

Flare for Programmers is a valuable resource for anyone looking to adapt and expand on the robust capabilities of MadCap Flare. Since Flares source files are all based on open standards such as XML, JavaScript, and CSS, the examples and techniques covered in this book are not only useful in the MadCap Flare environment, but can also be applied to web development best practices, file management, and XML manipulation.

With step-by-step examples for processes including dynamic content generation and plugin API development, this book offers the most thorough overview of advanced Flare development available to date.

Anthony Olivier,
CEO of MadCap Software

MadCap Flare).

Figure 1.1. Flare user interface

One of the main strengths of Flare is what goes on behind the scenes. Flare uses XML, which means you can manipulate, process, and merge content outside of the user interface (UI). The ability to manipulate XML-based Flare content outside the tool provides flexibility you cant get with a tool that uses a proprietary format. For example, you can easily automate your production process. In that build help files or PDFs. We show how to automate content builds and even how to automate creation of the files that define those builds.

You can create deliverables that blend content from different teams. In our workplace, we produce documentation for developers that combines author-created content with content automatically generated from a database. Perhaps you have similar deliverables. Maybe you write configuration manuals that incorporate information extracted from code comments such as permissions tables, or maybe you need to create database documentation that includes both authored content and generated entity-relationship diagrams. By working outside the UI, you can create processes that seamlessly blend this material, and you can automate those processes.

Because the project structure is open and many of the file types are XML-based, working outside of the Flare user interface can be as simple as editing an XML file.

Figure 1.2. Flare TOC (table of contents) viewed from Notepad++

This book is for programmers, programmer-technical writers, XML specialists, tech-savvy authors, information architects, and managers anyone who wants to go beyond what is achievable via the MadCap Flare user interface. Although this book contains code and markup, we dont show you how to code. Our goal is to explain how Flare projects work, describe the files (mostly XML) that make up Flare projects, and show you how those files can be manipulated.

If you are responsible for document automation or you need to connect an application to Flare-generated help output, this is the book for you. We describe Flare artifacts and how to create and manipulate those artifacts with technologies such as XSLT, JavaScript, and .NET LINQ to XML. We demonstrate how to programmatically create Flare content, automate documentation builds, connect help outputs to applications, and extend the Flare user interface with plugins.

If you are a technical writer interested in XML or coding, but arent quite at the point where you can write XSL transformations or automation programs, this book explains some of what is possible and some of the technologies that can be used. This book wont teach you how to write JavaScript or how to code an XSL transformation, but it contains examples you can build on even if you arent a coder.

For a technical writer with some programming experience, the examples help you begin customizing out-of-the-box Flare outputs. For example, we show you techniques for including JavaScript in your outputs that dont require deep scripting knowledge. Reading the more technical descriptions may help you target areas of interest that you can explore further.

If you manage a documentation team that uses Flare or plans to use Flare, this book will help you understand what you can do with Flare and how you can go beyond the capabilities of the user interface. You may want to implement some of these ideas to increase your teams efficiency or create new types of output. If you manage a team in a software development environment, you may be able to find a programmer or technically proficient tech writer who can help implement these techniques.

This book demonstrates how users can programmatically interact with Flare outside of the user interface. The book shows how content is managed and parsed by Flare, how to work with that content, and the advantages and benefits of doing so. Here are some things to keep in mind:

You can read this book from start to finish, and we considered that when we organized the chapters. However, if you have a particular interest or if you want to skip around, here is what each of the chapters covers: