HTML to MadCap Flare

HTML to MadCap Flare

Table of Contents

eBook Introduction

Foreword

Preface

1. Who needs this book?

2. How is this book organized?

2.1. Part I: Getting Started

2.2. Part II: Preparing for Import

2.3. Part III: Importing HTML

2.4. Part IV: Scripting

2.5. Part V: Template Projects with Global Project Linking

2.6. Appendices

I. Getting Started

1. Flare and HTML

1.1. Dynamic documentation

2. What You Need to Know About Flare

2.1. Flare project structure

3. The Tool Kit

3.1. tidy

3.2. Pandoc

3.2.1. Converting to HTML

3.2.1.1. The default HTML template

3.3. xmllint

3.4. Cygwin

3.5. unix2dos

3.6. XML editor

3.7. PHP

3.8. Browser

4. CSS and Flare

4.1. Flare-specific styles

4.2. CSS and print

4.2.1. Quirks of print styling

4.2.1.1. Spaces

4.2.1.2. Labeling and numbering

4.2.1.3. Numbering ordered lists

4.2.1.4. Fonts

II. Preparing for Import

5. Preprocessing

5.1. Avoiding class conflict

5.2. The HTML <title> tag

5.3. Styling <ol> tags

5.4. Removing links to resources

5.5. Adding bookmarks

6. Tables of Contents

6.1. The HTML ToC

6.2. Creating a Flare TOC from an HTML ToC

6.3. TOCs and System Variables in Flare 2017

6.3.1. Setting a TOC entry to a system variable

6.4. Validating your TOC file using xmllint

7. Glossaries

7.1. HTML glossaries

7.2. Creating glossary topics

7.3. Creating a Flare glossary

7.4. Creating a glossary for print output

7.5. Creating <MadCap:glossaryTerm> tags

III. Importing HTML

8. Importing HTML Files

8.1. Permanently importing HTML files

8.1.1. What happened?

8.1.1.1. The project file

8.1.1.2. Content files

8.1.1.3. Changes to HTML files

8.1.1.4. The Project directory

8.1.1.5. Permanent import summary

8.2. Synchronized documentation

9. After Importing HTML

9.1. Updating TOC files

9.1.1. Updating TOC files for synchronized files

9.2. Glossary files

9.2.1. Glossary files and skins

9.3. Resource files

9.4. Checking links

9.4.1. Checking and converting links

9.5. Converting internal links to cross-references

9.5.1. Styling cross-references

9.6. Troubleshooting

9.6.1. Using Project Analysis

9.6.1.1. Broken links

9.6.1.2. Broken bookmarks

9.6.1.3. Topics not in selected TOC

9.6.2. Building an HTML target

IV. Scripting

10. Dynamic Content in Flare

10.1. Including content

10.1.1. Flare snippets

10.1.2. Variables

10.1.2.1. Flare variables

10.1.3. Using XInclude

10.2. Other XML objects

10.2.1. Conditional text

10.2.1.1. Conditions and TOC files

10.2.2. Proxies

10.2.2.1. Mini-TOC

10.2.2.2. List-Of proxy

10.2.3. Master pages

10.2.3.1. Master pages and topics

10.2.3.2. Master pages and targets

10.2.4. Togglers and popups

11. Scripting Tasks

11.1. Removing empty <p> tags

11.2. Improving search results

11.3. Changing comments to annotations

11.4. Formatting JSON text

11.5. Setting a maximum line length

11.6. Automating the build process

11.7. Pre/Post Build Processes (Flare 2016 r2 and later)

12. Scripting Creation of Projects

12.1. Exporting a project

12.2. Reviewing the exported project

12.3. Creating PDF targets

12.4. Creating a document title

12.5. Creating a new project from a prototype

12.6. Creating custom documents

V. Template Projects with Global Project Linking

13. The Flare Solution

13.1. Terminology

13.2. Auto-sync

13.2.1. Linked file naming conventions

13.3. Creating a source project

13.3.1. Source projects versus prototype projects

13.3.2. Selecting content files for a source project

13.3.2.1. Topic files

13.3.2.2. Image files

13.3.2.3. Snippet files

13.3.2.4. Linked CSS files

13.3.2.5. Layouts

13.3.2.6. Summary content table

13.3.3. Selecting project files for a source project

13.3.3.1. Conditions

13.3.3.2. Glossary files

13.3.3.3. Skins

13.3.3.4. Targets

13.3.3.5. Flare TOC files

13.3.3.6. Linked files and variables

13.3.3.7. Project files suitable for a source project

14. Creating the Template

14.1. Creating an empty project

14.2. Using the Import Flare Project Wizard

14.3. Saving as a template

15. Creating Derived Projects

15.1. First steps after creating a derived project

15.1.1. Removing links

15.1.2. The local.css file

15.2. Manually updating source files

15.3. Understanding imported projects

16. Linking Existing Projects

16.1. Preparation

16.2. Excluding files

16.2.1. Omitting files from the Include Files list

16.2.2. Adding files to the Exclude Files list

16.2.3. Excluding files using conditions

16.2.4. Excluding files by unlinking

16.2.5. Excluding files by manipulating XML

16.3. Running the Import Flare Project Wizard

17. Managing Linked Projects

17.1. Managing the source project

17.2. Managing derived projects

17.2.1. Changing settings in the Project Import Editor

17.2.2. Managing existing linked files

17.2.3. Auto-syncing all projects

17.3. Managing a template project

A. Using Apache Ant with Flare

A.1. Installing Ant

A.2. Using Ant

A.3. Build files

A.4. The Ant properties file (build.properties)

A.5. The Ant build file (build.xml)

A.6. Importing files into build.xml

A.7. Advanced Ant

A.7.1. Using macros

A.7.2. Including files

A.7.3. Applying XSLT

A.8. Targets and pre-build commands

B. Cheat Sheets

C. Glossary Scripts for Flare Version 11

C.1. Creating a Flare Glossary

C.2. Creating a Print Glossary

C.3. Creating <glossaryTerm> Tags

D. Sample Glossary Output File for Print

E. Importing DocBook

E.1. Output format

E.2. The chunking parameters

E.3. ToC parameters

E.4. Labels and numbering

E.5. CSS parameters

E.6. JavaScript parameter

E.7. Tables

E.8. Styling DocBook admonitions

E.9. Glossaries and indexes

E.10. Summary

Glossary

Bibliography

Index

F. Copyright and Legal Notices

HTML to MadCap Flare

Peter Lavin

Dedication

For Judith, Madeleine, and Alice

Acknowledgements

Many thanks to:

Richard Hamilton of XMLPress for his guidance and encouragement.

My employer, Moneris Solutions, for providing the opportunity to learn Flare and for

allowing me to use scripts developed on the job.

Neil Perlin for kindly writing a forward.

eBook Introduction

Thank you for purchasing HTML to MadCap Flare: A guide to automating content

migration and maintenance. I hope you enjoy the book and find it useful.

Best Regards,

Peter Lavin

February, 2017

Foreword

To drive a car, you don’t need to know how its transmission works, but you’ll be a

better driver if you do. Similarly, you don’t need to know how Flare works in order to

use it, but you’ll make better use of it if you do. That’s the gist of this book: it explains

how the parts of Flare that import HTMLfiles work under the hood and how to make

better use of those features.

Author Peter Lavin is a technical writer, former programming instructor, and web

developer with a background in XML, HTML, and CSS, along with DITA and Doxygen.

That background shows in this book. Peter explains how Flare’s HTML-related features

work at the interface level, then dives into the code behind those features. He discusses

the automation of HTMLimport and the use of scripts and third party tools to clean up

the incoming files. Those discussions provide tremendous value and are the heart of the

book. Here are just a few of the gems you’ll find:

Instructions for using third-party tools such as xmllint and tidy to clean up HTML

files.

Several dozen scripts for automating tasks such as removing references to

JavaScript resource files, removing empty <p> tags, and identifying mismatched

titles.

Pre-import processing steps to increase the efficiency of your HTMLfile import.

Tips on managing the <title> tag and controlling how page names appear in

search results.

Scripts that can help with little-known issues, such as getting Flare glossary terms

whose definitions come from topic links to appear in print output.

If you’re familiar with Flare and technologies like HTMLand CSS…

If you have to import large numbers of HTMLfiles from various sources into your

projects and are looking for ways to make the process more efficient…

If you understand how things work in Flare but not necessarily why they work that

way…

… You’ll find this book extremely useful.

Neil Perlin

Hyper/Word Services

Certified Flare Trainer and Consultant since 2005

Preface

Technical documentation often contains a mix of static documentation – content created

by technical writers – and dynamic content, which is generated from external elements

such as files extracted from databases or spreadsheets and, perhaps, source-code

comments and function signatures. When looking for a documentation tool, you want one

that handles both static and dynamic elements. You also want it to produce a variety of

different outputs, and, for ease of maintenance, it should be a single-sourcing tool. You

want a sophisticated tool but one that is intuitive and easy to use. You want to have your

cake and eat it too.

MadCap Flare is a single-source, open standards, XML-based documentation tool that

runs on Microsoft Windows. The Flare Key Features Guide (published by MadCap

software) describes Flare as “easy to integrate with other XMLor XHTML

applications” and claims that, because of its open XML architecture, “Flare projects are

completely open, transparent, and accessible.”

Do these claims stand up? Can you have your cake and eat it too? This book attempts to

answer these questions.

Note

All references to MadCap Flare in this book are to version 12. However, all of the

scripts used in this book will also work in Flare versions 11, 2016 r2 and 2017. The

scripts in Chapter 7, Glossaries, only work with version 12 and higher, but you can find

equivalent scripts for version 11 in Appendix C, Glossary Scripts for Flare Version 11.

Where appropriate, the differences between versions are noted.

1. Who needs this book?

This book focuses primarily on importing HTMLinto MadCap Flare. Flare can directly

import files in a variety of formats, including: Microsoft Word, FrameMaker, Darwin

Information Typing Architecture (DITA), and HTML. However, because Flare content

files are HTMLfiles, you will likely have better results if you first convert your files to

HTMLand then import them.

Although the primary focus is on importing HTMLinto Flare, this book can also help

you determine whether Flare is the appropriate tool for you. Most books about Flare

focus exclusively on the user interface (UI) and say very little about the underlying

HTML, CSS, (Cascading Style Sheets) or XMLstructures – one notable exception is

MadCap Flare for Programmers[Tregner, 2015]. Understanding the UI can help you

evaluate Flare, but you really need insight into the underlying structure to determine if it

is the tool for you. Depending upon the nature of your work force and how you plan to

use Flare, insight into the underlying structure can help determine the suitability of Flare

as a documentation tool in your environment.

For example, if you plan to generate portions of your documentation from external files,

such as database tables, knowledge of Flare internals can help you evaluate Flare’s

suitability for creating dynamic documentation. And if you currently use automation to

create documentation or portions of your documentation, you can evaluate whether Flare

will integrate with your current processes.

If only a segment of your writing team will use Flare as their primary tool, while others

will use another tool, this book will help you determine how well Flare functions in an

environment that uses mixed documentation tools and how readily external content can

be accommodated.

If you are choosing a documentation framework, this book can help you make that

decision. You will be able to answer questions such as: “Just how XML-compliant is

Flare?”, “Will Flare allow me to leverage my existing knowledge of XML, XSLT,

HTML, and CSS?”, or “Can I use existing CSS files in Flare projects?”

If you have a good grasp of CSS, HTML, and XML, you may find it frustrating to use a

GUI tool for a task that you could accomplish more quickly by directly manipulating a

source file. This book can help you understand how Flare uses these technologies, so

you can safely work with its source files.

When starting to use a new documentation tool, most people have an existing body of

documentation that needs to be adapted for that tool. If that content is already in HTML

format, this book will help you import it. But if your documents are in a variety of

different formats that are easily converted to HTML, this book can provide you with a

single path for migration to Flare. You may find that it is more efficient first to convert to

HTMLand only then import documentation; this work flow may prove superior to

directly importing a variety of different formats.

The scripts in this book can be downloaded from http://xmlpress.net/publications/flare￾html.

2. How is this book organized?

This book contains seventeen chapters in five parts plus five appendices, a glossary, a

bibliography, and an index.

2.1. Part I: Getting Started

Chapter 1, Flare and HTML, describes how Flare topic files differ from standard

(X)HTMLfiles and the different ways that HTMLfiles are imported into Flare.

Chapter 2, What You Need to Know About Flare, outlines the file structure of a Flare

project.

Chapter 3, The Tool Kit, describes the tools you will need. This includes tools to

convert files to HTML, convert HTMLto XHTML, and perform other tasks. With the

exception of an XMLeditor, all of the tools are open-source software that you can

download and use freely.

Chapter 4, CSS and Flare, describes how Flare handles CSS and how Flare’s handling

differs from standard CSS.

2.2. Part II: Preparing for Import

Chapter 5, Preprocessing, shows how to prepare HTML for import. You can often script

these tasks and reduce the time it takes to convert an existing project to a Flare project.

Chapter 6, Tables of Contents, covers tables of contents. It compares a Flare table of

contents (TOC) with a typical HTMLToC, showing the similarity of structure and

revealing how to convert an HTMLToC to a Flare TOC using a script.

Chapter 7, Glossaries, covers glossary files, comparing a Flare glossary file with its

HTMLequivalent. This comparison reveals how to script the conversion of an HTML

glossary to a Flare glossary and, in the process, provides best practices for using Flare

glossaries.

2.3. Part III: Importing HTML

Chapter 8, Importing HTMLFiles, guides you through the import process using the Flare

interface. The emphasis is on permanently importing a project, but you also learn how to

import files that will be maintained outside of Flare and kept up to date by auto-syncing.

Chapter 9, After Importing HTML, identifies tasks that must be performed after import.

You learn how to make changes using the UI and see what effect these changes have on

XML files. This chapter provides scripts that automate some tasks and describes

techniques for evaluating the success of your import.

2.4. Part IV: Scripting

Chapter 10, Dynamic Content in Flare, shows how the architecture of Flare supports

dynamic content. Understanding Flare XMLfiles enables you to create items outside of

Flare, including dynamic documentation that is created or updated at build time.

Chapter 11, Scripting Tasks, provides scripts for automating tasks such as formatting text

within <pre> tags and, more importantly, creating documentation from the command line

using the madbuild.exe command.

Chapter 12, Scripting Creation of Projects, describes a project prototype that can serve

as the basis for future projects. You can begin a new project by copying some or all of

the files in this prototype. By using this prototype and the command line executable

provided by Flare, you can create and build a complete project without opening the

Flare application.

2.5. Part V: Template Projects with Global Project Linking

The last five chapters show how to maximize file reuse and reduce document

maintenance by implementing global project linking.

Chapter 13, The Flare Solution, explains global project linking and the kinds of files you

need to include in a linked project.

Chapter 14, Creating the Template, shows how to use a template to simplify the creation

of a new linked project.

Chapter 15, Creating Derived Projects, deals with the tasks you should perform after

creating a new project from a template, specifically how to unlink files and how to

update them.

Chapter 16, Linking Existing Projects, shows how to associate an existing project with a

linked project.

Chapter 17, Managing Linked Projects, discusses best practices for maintaining source

projects, derived projects, and linked project templates.

2.6. Appendices

Appendix A, Using Apache Ant with Flare, describes how to use Apache Ant with

Flare.

Appendix B, Cheat Sheets, lists the Flare XMLfile types used in this book

alphabetically by the file extension. It describes where files of each type are located and

provides a brief description.

Appendix C, Glossary Scripts for Flare Version 11, contains scripts for glossary

processing in Flare 11. These are the only scripts that differ between Flare 11 and Flare

12.

Appendix D, Sample Glossary Output File for Print, contains an output glossary file.

Appendix E, Importing DocBook, describes how to import DocBook XMLfiles into

Flare.

The book also contains a glossary of common terms, a bibliography, and an index.

Getting Started

This section contains an overview of how Flare works with HTML, details the structure

of a Flare project, and discusses how Flare implements CSS. It also contains a chapter

on tools that will make your life easier as you work with Flare.